A first build

Module progress100%

Lesson 3 of 3 — the last one of this module.

Three commands

Build

npx docpensieve build writes the site into dist/.

Serve

npx docpensieve dev serves it, and rebuilds on every save.

Check

npx docpensieve check reads it back for dead links.

What comes out

dist
- index.html — sends the reader to the current version
- versions.json — the versions, for the switcher
- versions
  - v1.0
    index.html — the home page
    guide — one folder per page, each with its index.html
    assets — the stylesheet, the images, the search index
    search — the only page carrying a script

Each page is a complete file, served as it is. A page is a folder holding an index.html, which is what gives it an address ending in a slash and needs no rule on the server. The stylesheet comes along; no script does.

When something is wrong

build stops on what it cannot do — a missing file, a component used wrongly — and names it. It says nothing about a link pointing at a page you renamed: that page compiled perfectly, it simply is not there any more.

npx docpensieve check

Run it every time

check reads the built site back and exits with an error if a link leads nowhere. It costs a second, and it is the difference between finding a dead link yourself and having a reader find it.

While you write

npx docpensieve dev

It serves the site and rebuilds on every save — including when you change the configuration or a file of the theme/ folder. Leave it running in a second terminal: the loop between writing a sentence and seeing it is what makes a documentation get written.

Well done

You have finished First steps. The next module shows how to organise pages and use components.

Next module: Writing well

Structure, series, and components in a real page.