Skip to content

Latest commit

 

History

History
72 lines (55 loc) · 2.91 KB

Usage.md

File metadata and controls

72 lines (55 loc) · 2.91 KB
Raw

A. Using Spec Markdown

If installed globally, using spec-md as a shell executable is the easiest way to use Spec Markdown. The spec-md executable expects a filepath to a Markdown document as input and outputs HTML on stdout. Use > to write stdout to a file.

npm install -g spec-md
spec-md ./path/to/markdown.md > ./path/to/output.html

You can also require spec-md as a node module, after which you might add the spec-md command as a node script.

npm install --save-dev spec-md
const fs = require('fs');
const specMarkdown = require('spec-md');
const html = specMarkdown.html('./path/to/markdown.md');
fs.writeFileSync('./path/to/output.html', html);

The spec-md node module provides a few functions:

  • {html(filePath, options)} takes a {filepath} to a Markdown file and returns an HTML string. This function is the primary usage of the spec-md module.
  • {parse(filePath)} takes a filepath and returns an AST (Abstract Syntax Tree) representing the contents of the Spec Markdown file, with all imports already inlined.
  • {print(ast, options)} takes an {ast} produced by parse() and returns an HTML string.
  • {visit(ast, visitor)} takes an {ast} and a {visitor}. It walks over the {ast} in a depth-first-traversal calling the {visitor} along the way.

Print Options

The {html(filePath, options)} and {print(filePath)} functions both take {options} as an optional second argument. These options allow for customization control over the returned HTML, more options may be added in the future.

  • githubSource - a base URL, that if provided will be used to construct Github source links to the original Markdown files throughout the returned HTML. (example: "https://github.com/leebyron/spec-md/blame/main/")

  • includeComments - If true, any HTML style comments that occur within the original markdown files will be included in the returned HTML.

  • highlight - a function which is called when blocks of code are encountered, with the first argument as the string of code, the second argument being the language specified. This function should return well formed HTML, complete with escaped special characters.

  • head - a string which is inserted in the <head> tag in the returned HTML. Use this to introduce additional meta tags and scripts.

Note: When using githubSource take note that normal Github view (eg. "blob" instead of "blame") show rendered instead of source markdown and cannot link to specific lines.

Hot rebuilding with nodemon

The spec-md shell executable follows the Unix Philosophy of doing one thing and doing it well. Try out nodemon to continuously rebuild the HTML output as you edit the markdown specification:

npm install -g nodemon
nodemon --exec "spec-md > ./path/to/output.html" ./path/to/markdown.md