Skip to content
πŸ“– Additions to Markdown for writing specification documents
HTML JavaScript CSS
Branch: master
Clone or download
Latest commit f139294 Jul 30, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Snapshot testing! Jul 4, 2019
spec Link to any highlighted section of a document. (#24) Jul 29, 2019
src Link to any highlighted section of a document. (#24) Jul 29, 2019
static Checksum selection links (#25) Jul 30, 2019
test Checksum selection links (#25) Jul 30, 2019
.gitignore
.travis.yml Attempt to fix Travis CI deploys Jul 4, 2019
CONTRIBUTING.md contributing Apr 16, 2015
LICENSE Initial commit Apr 1, 2015
README.md Fix anchor tag section links in Getting Started (#23) Jul 29, 2019
package.json 1.1.1 Jul 30, 2019
yarn.lock minify JS while writing executable sections Jul 29, 2019

README.md

Spec Markdown

Renders Markdown with some additions into an HTML format commonly used for writing technical specification documents. Markdown additions include code syntax highlighting, edit annotations, and the definition of algorithms and grammar productions.

Philosophy

Spec Markdown is first and foremost Markdown. As such, it follows Markdown's philosophy of intending to be as easy to read and easy to write as is feasible.

In order to interoperate with other tools which use Markdown, Spec Markdown tries to add as little additional syntax as possible, instead preferring conventions. This means any documents written with Spec Markdown in mind should render adequately by other Markdown renderers.

To support the rendering additions of Spec Markdown, some features of Markdown may be limited or removed. As an example, Spec Markdown is strict about the order and locations of headers in a document.

Note: This is not a normative spec for Spec Markdown, but just documentation of this tool. Of course, written in Spec Markdown!

Getting Started

To use Spec Markdown, just write Markdown files. There are some conventions used by Spec Markdown which you can read about in Spec additions.

To convert your Markdown files into an HTML spec document, use the spec-md utility.

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.

npm install --save-dev spec-md
var fs = require('fs');
var specMarkdown = require('spec-md');
specMarkdown.html('./path/to/markdown.md').then(function (html) {
  fs.writeFile('./path/to/output.html', html);
});

Spec Markdown also provides utilities for generating and operating on an intermediate representation of the markdown, which you can explore in Using Spec Markdown.

Markdown

Spec additions

Using Spec Markdown

Contributing

You can’t perform that action at this time.