First site

Building

npx docpensieve build

Every declared version is built. To build just one, pass its slug:

npx docpensieve build v1.0

Looking at the result

npx docpensieve serve

The output folder is served statically on port 4000. It is exactly what a host will do: no difference between this server and going live.

Working

npx docpensieve dev

The development server watches the sources and rebuilds on every save. It listens on port 3000; --port changes that.

The difference with serve is this: dev rebuilds, serve only serves. To check what will really be published, chain build then serve.

What was produced

dist/
├── index.html              redirect to the current version
├── versions.json           the versions and their URLs
└── versions/
    └── v1.0/
        ├── index.html      the home page of the version
        ├── assets/
        │   └── docpensieve.css
        └── guide/
            └── installation/
                └── index.html

Three things are worth noticing.

Each page is a folder with an index.html. That is what gives URLs without an extension — /guide/installation/ rather than /guide/installation.html — without asking anything of the host.

A single stylesheet for the whole version. It is compiled last, once the pages are written, because a utility theme needs to know which classes were actually used in order to emit only those.

The versions.json at the root describes the available versions. It is what lets versions built long ago stay online without ever rebuilding them.

Reading the output back

A successful build says nothing of a dead link: nothing in the chain looks at them. A command takes care of it:

npx docpensieve build
npx docpensieve check

It walks the produced pages, removes the deployment prefix from every internal target and checks that the file exists. It also reports the targets that ignore that prefix — the file is there, but the link will lead nowhere once online.

  index.html
    /guide/installation/
    → ignores the deployment prefix "/my-project/"

It is the check to run after any change of baseUrl, of folder structure or of URL.

Searching the site

Every page carries a search field in its header. It leads to the search page of the version, at /search/, which the build writes with the site: the list of every page, that a small script filters as the reader types — best matches first, each with an excerpt. It is the only page to load a script of its own, and without it, it stays the list of every page.

It works the same under both themes. search: false in the configuration removes the field and the page.