This is the specification generator for IPFS and other friends in the Interplanetary stack. You can enjoy its output online at https://specs.ipfs.tech/.
It is essentially a batteries-included, unobtrusive static site generator. What it will do is:
unicorn.md
in the input tree to /unicorn/index.html
in the output tree with:
In watch mode it will auto-update the spec in your browser as you edit it.
The usual:
npm install -g spec-generator
This will make a spec-generator
command available. (It is also available under the name
ipseity
.)
In order to set up a spec site, you need:
source
directory that will contain your MD spec source and whatever static files yououtput
directory where the generated output will go. These two directories can beconfig
file, that is a simple piece of JSON.template
file that is a basic piece of HTML.That's a fair bit of setup, but you only need to do it once for a whole spec site, which hopefully shouldn't be too often.
The config
file have the following format:
{
"input": "./src/",
"output": "./out/",
"template": "./template.html",
"baseURL": "https://specs.ipfs.tech",
"github": {
"repository": "ipfs/specs",
"defaultBranch": "main"
}
}
The fields are simple:
input
: the source directory, relative to the config file.output
: the published directory, relative to the config file.template
: the template file, relative to the config file.baseURL
: the base URL at which the specs are published. This is used to generated thegithub
: optional settings to generate commit history and feedback links forAll fields are required except baseURL
, and baseURL
is highly recommended.
The Markdown spec just generate the body of the spec, but you need some HTML to wrap around it from which to specify some metadata, hook up some styles, etc.
An example template file might look like this:
<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title></title>
<link rel="stylesheet" href="/css/ipseity.min.css">
<link rel="stylesheet" href="/css/your-spec-style.css">
<link rel="icon" href="/img/my-standards-logo.svg">
</head>
<body>
<nav id="ipseity-back-to-root">
<a href="/">Standards Home</a>
</nav>
<ipseity-header></ipseity-header>
${body}
</body>
</html>
The ${body}
gets replaced by the Markdown output. Optionally the ipseity-header
element
can be used to mark the injection point for the spec metadata if you don't intend it to be
the first thing in the body.
Apart from these conventions you can have whatever you want in there.
If your template includes /css/ipseity.min.css
, that will load styles for the spec body.
You can roll your own, of course, but this will have you covered. This doesn't include styling
the wrapper your way.
There are two ways of running the command. The first is in regular batch mode:
ipseity -c /path/to/config.json
The -c
option is always required. This will run once, generate the specs, and exit.
Or you can run in watch mode. This is most useful while you're editing a spec:
ipseity -c /path/to/config.json -w
This will start up a local server and watch your files in the input
directory. It will hot
reload specs you have open in a browser.