Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change markdown parser from 'marked' to 'markdown-it' #398

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cakefile
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ task 'install', 'install the `docco` command into /usr/local (or --prefix)', (op
lib = base + '/lib/docco'
exec([
'mkdir -p ' + lib + ' ' + base + '/bin'
'cp -rf bin README resources ' + lib
'cp -rf bin README resources docco.js node_modules ' + lib
'ln -sf ' + lib + '/bin/docco ' + base + '/bin/docco'
].join(' && '), (err, stdout, stderr) ->
if err then console.error stderr
Expand Down
1 change: 0 additions & 1 deletion README
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,3 @@ Usage: docco [options] FILES
-t, --template [file] use a custom .jst template
-e, --extension [ext] use the given file extension for all inputs
-L, --languages [file] use a custom languages.json
-m, --marked [file] use custom marked options
94 changes: 50 additions & 44 deletions docco.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

96 changes: 57 additions & 39 deletions docco.litcoffee
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Docco can be used to process code written in any programming language. If it
doesn't handle your favorite yet, feel free to
[add it to the list](https://github.com/jashkenas/docco/blob/master/resources/languages.json).
Finally, the ["literate" style](http://coffeescript.org/#literate) of *any*
language listed in [languages.json](https://github.com/jashkenas/docco/blob/master/resources/languages.json)
language listed in [languages.json](https://github.com/jashkenas/docco/blob/master/resources/languages.json)
is also supported — just tack an `.md` extension on the end:
`.coffee.md`, `.py.md`, and so on.

Expand Down Expand Up @@ -153,48 +153,27 @@ normal below.

To **format** and highlight the now-parsed sections of code, we use **Highlight.js**
over stdio, and run the text of their corresponding comments through
**Markdown**, using [Marked](https://github.com/chjj/marked).
**Markdown**, using [markdown-it](https://github.com/markdown-it/markdown-it).

format = (source, sections, config) ->
language = getLanguage source, config

Pass any user defined options to Marked if specified via command line option

markedOptions =
smartypants: true

if config.marked
markedOptions = config.marked

marked.setOptions markedOptions
console.log('language', language)

Tell Marked how to highlight code blocks within comments, treating that code
as either the language specified in the code block or the language of the file
if not specified.

marked.setOptions {
highlight: (code, lang) ->
lang or= language.name

if highlightjs.getLanguage(lang)
highlightjs.highlight(lang, code).value
else
console.warn "docco: couldn't highlight code block with unknown language '#{lang}' in #{source}"
code
}

for section, i in sections
code = highlightjs.highlight(language.name, section.codeText).value
code = hljs.highlight(language.name, section.codeText).value
code = code.replace(/\s+$/, '')
section.codeHtml = "<div class='highlight'><pre>#{code}</pre></div>"
section.docsHtml = marked(section.docsText)
section.docsHtml = md.render(section.docsText)

Once all of the code has finished highlighting, we can **write** the resulting
documentation file by passing the completed HTML sections into the template,
and rendering it to the specified output path.

write = (source, sections, config) ->

destination = (file) ->
path.join(config.output, path.dirname(file), path.basename(file, path.extname(file)) + '.html')

Expand All @@ -203,18 +182,14 @@ and rendering it to the specified output path.
from = path.dirname(path.resolve(destination(source)))
path.join(path.relative(from, to), path.basename(file))

The **title** of the file is either the first heading in the prose, or the
name of the source file.
The **title** of the file is the name of the source file.

firstSection = _.find sections, (section) ->
section.docsText.length > 0
first = marked.lexer(firstSection.docsText)[0] if firstSection
hasTitle = first and first.type is 'heading' and first.depth is 1
title = if hasTitle then first.text else path.basename source
title = path.basename source
css = relative path.join(config.output, path.basename(config.css))

html = config.template {sources: config.sources, css,
title, hasTitle, sections, path, destination, relative}
html = config.template {
sources: config.sources, css, title, hasTitle:true , sections, path, destination, relative
}

console.log "docco: #{source} -> #{destination source}"
fs.outputFileSync destination(source), html
Expand Down Expand Up @@ -280,9 +255,53 @@ Require our external dependencies.
_ = require 'underscore'
fs = require 'fs-extra'
path = require 'path'
marked = require 'marked'
MarkdownIt = require 'markdown-it'
commander = require 'commander'
highlightjs = require 'highlight.js'
hljs = require 'highlight.js'

md = MarkdownIt({
highlight: (str, lang) =>
console.log 'lang', lang

if lang && hljs.getLanguage(lang)
try
return hljs.highlight(lang, str).value
catch __

return '';
})

uml support
```puml
@startuml
a -> b
@enduml
```

@startuml
a -> b
@enduml

.use(require('markdown-it-plantuml'),{imageFormat:'png'})

math support
```
\begin{equation}
e^{\pi i} + 1 = 0
\end{equation}
```

\begin{equation}
e^{\pi i} + 1 = 0
\end{equation}


.use(require('markdown-it-mathjax')())






Languages are stored in JSON in the file `resources/languages.json`.
Each item maps the file extension to the name of the language and the
Expand Down Expand Up @@ -339,7 +358,6 @@ Parse options using [Commander](https://github.com/visionmedia/commander.js).
.option('-c, --css [file]', 'use a custom css file', c.css)
.option('-t, --template [file]', 'use a custom .jst template', c.template)
.option('-e, --extension [ext]', 'assume a file extension for all inputs', c.extension)
.option('-m, --marked [file]', 'use custom marked options', c.marked)
.parse(args)
.name = "docco"
if commander.args.length
Expand All @@ -351,4 +369,4 @@ Parse options using [Commander](https://github.com/visionmedia/commander.js).
Public API
----------

Docco = module.exports = {run, document, parse, format, version}
Docco = module.exports = {run, document, parse, format, version}
Loading