readme.md

Markdown » Spec-Up

Spec-Up is a technical specification development tool that enables you to create rich specification documents for standards bodies and engineering projects by writing in an extended version of markdown that features all the bells and whistles - for example: advanced syntax highlighting, notice blocks, complex tables, charts, UML diagrams, and more.

Using Spec-Up is easy peasy lemon squeezy:

1. npm install spec-up

2. Create a specs.json file at the root of your project to specify configuration values used in the generation of your spec documents. The values in your specs.json file include things like where your spec's markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the specs.json config file:

   • public_root (PATH STRING, optional) - For some platforms and services where you may want to output your rendered spec, the pathing may differ from the directory structure of your local project. To account for this, you can use the public_root property to specify the insertion of a path segment to account for the different in pathing between your local renders and wherever you publish your spec to.
   • specs (ARRAY, required) - the specs array contains descriptor objects for each of the specs you are generating in your project, and are composed of the following required and optional properties:

     • spec_directory (STRING, required) - You must specify the project root relative location of your spec's markdown file directory. You MUST name your spec's markdown file spec.md and locate it in your spec_directory for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optionalmarkdown_paths field described below.

     • title (STRING, required) - You must add a title for your spec, which will be rendered in the generated document's H1 text and page title.

     • logo (PATH/URI STRING, optional) - You may add a reference to a logo asset, either via a path to the asset or a URI

     • logo_link (URI STRING, optional) - The URI you want your logo to point to in the rendered page.

     • markdown_paths (ARRAY, optional) - If you want to name your spec's markdown file something other than spec.md, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the spec_directory you specified, so DO NOT repeat the full root relative path.

     • output_path (STRING, optional) - If you want the generated spec document to be output to a different location than the spec_directory you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use ./ for root), and the tool will write the document file there instead.

     • source (OBJECT, optional) - this object allows you to configure where repo-specific data is pulled from to power some of the more advanced repo-related features. To do this, specify the code hosting service by adding a service ID string to host (currently Spec-Up only supports "github", but this is extensible), add the account/org the repo is located within via the account property, and add the repo name under the repo property. Here is an example configuration:

       {
           "host": "github",
           "account": "decentralized-identity",
           "repo": "sidetree"
       }
       

3. In your main node.js file, or as a package.json script entry, use this invocation call: require('spec-up')()

Boom! That's it. Spec-Up will auto-detect modifications to files in your spec_directory and auto-generate your spec's updated HTML document every time you save a change.