markdown-to-html

Version:

Converts markdown text to HTML. A readable stream plus utilities and web demo.

96 lines (88 loc) • 11.5 kB

HTML

<!DOCTYPE html> <html> <head> <title>README.md</title> <link rel="stylesheet" href="test/style.css"> </head> <body> <h1 id="markdown-to-html">markdown-to-html</h1> Command-line utility to convert Github Flavored Markdown to HTML. Output may be to stdout or to your default browser. Also, the underlying Markdown and GithubMarkdown classes are readable stream classes and may be used however you like (e.g., pipe to an http response or to stdout). Includes a demo of a web server app that uses both the classes. <h2 id="installation">Installation</h2> <h4 id="to-use-the-command-line-utilities">To use the command line utilities</h4> <pre><code><div class="highlight"><pre>npm install markdown-to-html -g </pre></div> </code></pre><h4 id="to-use-the-markdown-or-githubmarkdown-classes-in-your-project">To use the Markdown or GithubMarkdown classes in your project</h4> <pre><code><div class="highlight"><pre>npm install markdown-to-html --save </pre></div> </code></pre><h2 id="example-usage">Example Usage</h2> <h4 id="command-line-utility-to-output-html-to-stdout">Command line utility to output HTML to stdout</h4> <pre><code><div class="highlight"><pre>markdown myfile.md [<options>] </pre></div> </code></pre><h4 id="command-line-utility-to-output-html-to-default-browser">Command line utility to output HTML to default browser</h4> <pre><code><div class="highlight"><pre>markdownb myfile.md [<options>] </pre></div> </code></pre><h4 id="command-line-utility-to-output-the-github-api-results-to-stdout">Command line utility to output the Github API results to stdout</h4> <pre><code><div class="highlight"><pre>github-markdown myfile.md [<options>] </pre></div> </code></pre><h4 id="command-line-utility-to-output-the-github-api-results-to-default-browser">Command line utility to output the Github API results to default browser</h4> <pre><code><div class="highlight"><pre>github-markdownb myfile.md [<options>] </pre></div> </code></pre><h4 id="run-the-web-demo">Run the web demo</h4> <ol> <li>Run <code>git clone https://github.com/cwjohan/markdown-to-html.git</code> to create a markdown-to-html directory.</li> <li>Run <code>cd markdown-to-html</code></li> <li>Run <code>npm install</code></li> <li>Run <code>npm start</code>.</li> <li>In a web browser address field type <a href="http://localhost:3000">localhost:3000</a>.</li> </ol> <h3 id="use-the-markdown-class-to-render-markdown-text">Use the Markdown class to render markdown text</h3> <pre><code class="lang-js"><div class="highlight"><pre>var Markdown = require('markdown-to-html').Markdown; var md = new Markdown(); md.bufmax = 2048; var fileName = 'test/test.md'; var opts = {title: 'File $BASENAME in $DIRNAME', stylesheet: 'test/style.css'}; ... // Write a header. console.log('==============================='); // Write a trailer at eof. md.once('end', function() { console.log('==============================='); }); md.render(fileName, opts, function(err) { if (err) { console.error('>>>' + err); process.exit(); } md.pipe(process.stdout); }); </pre></div> </code></pre> <h2 id="options-for-markdown-and-markdownb">Options for markdown and markdownb</h2> <h4 id="-flavor-type-"><code>--flavor <type></code></h4> Format as type 'gfm' or just plain 'markdown'. May be abbreviated <code>-f</code> on the command line. Note that for the <code>github-markdown</code> utility or the <code>GithubMarkdown</code> class it is the 'markdown' flavor that gives you something resembling the README.md format on Github. Whereas, the 'gfm' flavor gives you something resembling the the format of comments and issues on Github. This is due to how the Github Markdown API works. On the other hand, for the <code>markdown</code> utility or the <code>Markdown</code> class it is virtually the opposite. For example, fenced code blocks don't work when using the <code>markdown</code> utility or the <code>Markdown</code> class with the <code>--flavor markdown</code> option. This is due to how the <code>marked</code> markdown parser works. The default value for this option is whichever flavor results in something more like README.md format. <h4 id="-highlight-"><code>--highlight</code></h4> Highlight code blocks with style info. Highlight has no effect in github-markdown. May be abbreviated <code>-h</code> on the command line. Defaults to <code>false</code>. <h4 id="-stylesheet-stylesheet-"><code>--stylesheet <stylesheet></code></h4> Outputs HTML header with link element referring to the given stylesheet. May be abbreviated <code>-s</code> on the command line. <h4 id="-title-title-"><code>--title <title></code></h4> Outputs HTML header with given title. Title string may include special values <code>$FILENAME</code>, <code>$DIRNAME</code>, <code>$BASENAME</code>, or <code>$PATHNAME</code> variables which are replaced by the corresponding .md filename, directory name, base name, or full path, respectively. Alternatively, the title may be any text you wish. May be abbreviated <code>-t</code> on the command line. <h4 id="-context-context-"><code>--context <context></code></h4> Suupply the relevant Github user/project to use with #<n> issue number references. Typically, these are not used in README.md files but, rather, in comments and issue text on Github. May be abbreviated <code>-c</code> on the command line. <h4 id="-verbose-"><code>--verbose</code></h4> Verbose output. May be abbreviated <code>-v</code> on the command line. Defaults to <code>false</code> unless debug has been specified, in which case it is set to <code>true</code>. Only used by the command line utilities. <h4 id="-debug-"><code>--debug</code></h4> Debug output to stderr. For example, outputs the individual chunks of data pushed to output. May be abbreviated <code>-d</code> on the command line. Defaults to <code>false</code>. Used only by the command line utilities. However, the Markdown and GithubMarkdown classes both have a <code>debug</code> property. <h4 id="-help-"><code>--help</code></h4> Output usage info. Only used by the command line utilities. <h2 id="markdown-and-githubmarkdown-class-properties">Markdown and GithubMarkdown class properties</h2> <h4 id="-bufmax-"><code>bufmax</code></h4> The chunk size for streaming -- that is, the maximum amout of data to push to the read operation at any given time. Defaults to 1024. <h4 id="-debug-"><code>debug</code></h4> Debug output to stderr. For example, outputs the individual chunks of data pushed to output. Defaults to <code>false</code>. <h2 id="markdown-and-githubmarkdown-class-methods">Markdown and GithubMarkdown class methods</h2> <h4 id="-render-filename-opts-ondone-"><code>render(fileName, opts, onDone)</code></h4> Renders the markdown text in the given file using the given options. Calls the onDone callback function when rendering is finished, if specified. If you are going to pipe the output to another stream, this is best done in the callback function. The <code>onDone</code> callback takes a single error parameter, which ought to be tested before performing any other operations on the Markdown or GithubMarkdown stream. Before calling <code>render</code>, you can set up a test for end of file with <code>on('end', cb)</code>, which is a good place to write any output that should follow the streamed HTML. See the above code example for how to do that. </body> <html>