Updated docs builder

Author: Vitaly Puzrin

.ndocrc

@@ -4,10 +4,10 @@
 
 --index         "./support/api_header.md"
 --package       "./package.json"
---gh-ribbon     "{package.homepage}"
+--gh-ribbon     "https://github.com/{package.repository}"
 --output        "apidoc"
 --render        "html"
---link-format   "{package.homepage}/blob/master/{file}#L{line}"
+--link-format   "https://github.com/{package.repository}/blob/master/{file}#L{line}"
 --broken-links  "show"
 
 

Makefile

@@ -53,13 +53,8 @@ report-coverage:
 	-istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage
 
 doc:
-	@if test ! `which ndoc` ; then \
-		echo "You need 'ndoc' installed in order to generate docs." >&2 ; \
-		echo "  $ npm install -g ndoc" >&2 ; \
-		exit 128 ; \
-		fi
 	rm -rf ./apidoc
-	ndoc --link-format "{package.homepage}/blob/${CURR_HEAD}/{file}#L{line}"
+	ndoc --link-format "https://github.com/{package.repository}/blob/${CURR_HEAD}/{file}#L{line}"
 
 gh-doc: doc
 	touch ./apidoc/.nojekyll

package.json

@@ -9,7 +9,6 @@
     "markdown-it",
     "markdown-it-plugin"
   ],
-  "homepage": "https://github.com/markdown-it/markdown-it",
   "repository": "markdown-it/markdown-it",
   "license": "MIT",
   "main": "index.js",
@@ -59,6 +58,7 @@
     "markdown-it-testgen": "~0.1.3",
     "marked": "0.3.5",
     "mocha": "*",
+    "ndoc": "^4.0.0",
     "stylus": "~0.53.0",
     "uglify-js": "*"
   }

support/api_header.md

@@ -1,67 +1,199 @@
-<!-- styles hack until ndoc updated -->
-<style>
-header .name_prefix { font-weight: normal; }
-</style>
+# markdown-it
 
-# markdown-it API
+## Install
 
-### Simple use
+**node.js** & **bower**:
+
+```bash
+npm install markdown-it --save
+bower install markdown-it --save
+```
+
+**browser (CDN):**
+
+- [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
+- [cdnjs.com CDN](https://cdnjs.com/libraries/markdown-it "cdnjs.com")
+
+
+## Usage examples
+
+See also:
+
+- [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
+  for plugins writers.
 
-In most cases you will use `markdown-it` in very simple way:
 
-```javascript
+### Simple
+
+```js
+// node.js, "classic" way:
+var MarkdownIt = require('markdown-it'),
+    md = new MarkdownIt();
+var result = md.render('# markdown-it rulezz!');
+
+// node.js, the same, but with sugar:
 var md = require('markdown-it')();
+var result = md.render('# markdown-it rulezz!');
+
+// browser without AMD, added to "window" on script load
+// Note, there is no dash in "markdownit".
+var md = window.markdownit();
+var result = md.render('# markdown-it rulezz!');
+```
 
-var result = md.render('your_markdown_string');
+Single line rendering, without paragraph wrap:
 
-// Or for inline (without paragraths & blocks)
-var resultInline = md.renderInline('your_markdown_inline_string');
+```js
+var md = require('markdown-it')();
+var result = md.renderInline('__markdown-it__ rulezz!');
 ```
 
-### Advanced use
 
-Advanced use consist of this steps:
+### Init with presets and options
 
-1. Create instance with desired preset & options.
-2. Add plugins.
-3. Enable/Disable additional rules.
-4. Rewrite renderer functions.
-5. Use result to call `.render()` or `.renderInline()` method.
+(*) presets define combinations of active rules and options. Can be
+`"commonmark"`, `"zero"` or `"default"` (if skipped). See
+[API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
 
-Of cause, you can skip not needed steps, or change sequense.
+```js
+// commonmark mode
+var md = require('markdown-it')('commonmark');
 
+// default mode
+var md = require('markdown-it')();
 
-__Example 1.__ Minimalistic mode with bold, italic and line breaks:
+// enable everything
+var md = require('markdown-it')({
+  html: true,
+  linkify: true,
+  typographer: true
+});
+
+// full options list (defaults)
+var md = require('markdown-it')({
+  html:         false,        // Enable HTML tags in source
+  xhtmlOut:     false,        // Use '/' to close single tags (<br />).
+                              // This is only for full CommonMark compatibility.
+  breaks:       false,        // Convert '\n' in paragraphs into <br>
+  langPrefix:   'language-',  // CSS language prefix for fenced blocks. Can be
+                              // useful for external highlighters.
+  linkify:      false,        // Autoconvert URL-like text to links
+
+  // Enable some language-neutral replacement + quotes beautification
+  typographer:  false,
+
+  // Double + single quotes replacement pairs, when typographer enabled,
+  // and smartquotes on. Could be either a String or an Array.
+  //
+  // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
+  // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
+  quotes: '“”‘’',
+
+  // Highlighter function. Should return escaped HTML,
+  // or '' if the source string is not changed and should be escaped externaly.
+  // If result starts with <pre... internal wrapper is skipped.
+  highlight: function (/*str, lang*/) { return ''; }
+});
+```
 
-```javascript
-var md = require('markdown-it')('zero', { breaks: true })
-            .enable([ 'newline', 'emphasis' ]);
+### Plugins load
 
-var result = md.renderInline(...);
+```js
+var md = require('markdown-it')()
+            .use(plugin1)
+            .use(plugin2, opts, ...)
+            .use(plugin3);
 ```
 
 
-__Example 2.__ Load plugin and disable tables:
+### Syntax highlighting
 
-```javascript
-var md = require('markdown-it')()
-            .use(require('markdown-it-emoji'))
-            .disable('table');
+Apply syntax highlighting to fenced code blocks with the `highlight` option:
 
-var result = md.render(...);
-```
+```js
+var hljs = require('highlight.js') // https://highlightjs.org/
 
+// Actual default values
+var md = require('markdown-it')({
+  highlight: function (str, lang) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return hljs.highlight(lang, str).value;
+      } catch (__) {}
+    }
 
-__Example 3.__ Replace `<strong>` with `<b>` in rendered result:
+    return ''; // use external default escaping
+  }
+});
+```
 
-```javascript
-var md = require('markdown-it')();
+Or with full wrapper override (if you need assign class to `<pre>`):
+
+```js
+var hljs = require('highlight.js') // https://highlightjs.org/
+
+// Actual default values
+var md = require('markdown-it')({
+  highlight: function (str, lang) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return '<pre class="hljs"><code>' +
+               hljs.highlight(lang, str, true).value +
+               '</code></pre>';
+      } catch (__) {}
+    }
+
+    return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
+  }
+});
+```
+
+### Linkify
 
-md.renderer.rules.strong_open  = function () { return '<b>'; };
-md.renderer.rules.strong_close = function () { return '</b>'; };
+`linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To
+configure linkify-it, access the linkify instance through `md.linkify`:
 
-var result = md.renderInline(...);
+```js
+md.linkify.tlds('.py', false);  // disables .py as top level domain
 ```
 
+## Syntax extensions
+
+Embedded (enabled by default):
+
+- [Tables](https://help.github.com/articles/github-flavored-markdown/#tables) (GFM)
+- [Strikethrough](https://help.github.com/articles/github-flavored-markdown/#strikethrough) (GFM)
 
-See classes doc for all available features and more examples.
+Via plugins:
+
+- [subscript](https://github.com/markdown-it/markdown-it-sub)
+- [superscript](https://github.com/markdown-it/markdown-it-sup)
+- [footnote](https://github.com/markdown-it/markdown-it-footnote)
+- [definition list](https://github.com/markdown-it/markdown-it-deflist)
+- [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
+- [emoji](https://github.com/markdown-it/markdown-it-emoji)
+- [custom container](https://github.com/markdown-it/markdown-it-container)
+- [insert](https://github.com/markdown-it/markdown-it-ins)
+- [mark](https://github.com/markdown-it/markdown-it-mark)
+- ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
+
+
+### Manage rules
+
+By default all rules are enabled, but can be restricted by options. On plugin
+load all its rules are enabled automatically.
+
+```js
+// Activate/deactivate rules, with curring
+var md = require('markdown-it')()
+            .disable([ 'link', 'image' ])
+            .enable([ 'link' ])
+            .enable('image');
+
+// Enable everything
+md = require('markdown-it')('full', {
+  html: true,
+  linkify: true,
+  typographer: true,
+});
+```