spec-up

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.

Setup

Installing Spec-Up is easy peasy lemon squeezy:

1. Run npm install spec-up in the root directory of the repo to install all dependencies.

2. Create a specs.json file in the root folder of your repository 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 repo-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. See the "multi-file" example in the spec-up repo.

     • 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. You're ready to start rendering specs as HTML sites locally and/or pushing them to github pages however you see fit to automate.

Usage

If your spec.json and package.json and package-lock.json files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes:

command	behavior
npm run edit	after rendering, this will stay running and the gulp library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.
npm run render	this renders the site once and does not keep a gulpy watch on the underlying files.
npm run dev	this enables debugging features.