The same content can be published without running anything. tobar-segais build renders every page to a file and writes them, with the search index and the assets, into an output directory:

$ tobar-segais build --content ./content --out ./site
level=INFO msg="site generated" out=./site pages=42 assets=7 documents=42

The result is plain files. Upload them to GitHub Pages, an S3 bucket, or any web server, and there is nothing left to run or keep alive.

What you get, and what you lose

Pages are rendered with the same templates the server uses, so a generated site looks and behaves like a served one. Navigation, the version picker and the table of contents are all there, and search still works: the index is written alongside the pages as search-index.json and queried in the browser.

What a static site cannot do is notice a new archive. A served catalogue picks up a change to the content directory within moments; a generated one is a snapshot, and publishing a new version means running build again. That is the trade, and for documentation that changes when a release is cut it is usually the right one — the build already exists, and it can write the site.

Options

Flag Default Meaning

--content

./content

Directory of .zip and .jar archives to publish.

--out, -o

./site

Directory to write the generated site into.

--site

(none)

Path the site is rooted at, if it is not the root of the domain.

--default

(none)

Slug to publish at / instead of the catalogue index.

--copyright

(none)

Notice about the documentation itself, shown in the footer. A bundle declaring tobar-segais.copyright overrides it for its own pages.

--debug

false

Verbose logging.

publish is accepted as an alias for build.

A generated page says it was published by Tobar Segais where a served one says it was served by it. The difference is worth having: a served page is as current as the content directory, and a published one is as current as the last build.

Sites below the root of a domain

A GitHub Pages project site is served from https://user.github.io/repo/, not from the root. Every absolute link the site writes has to carry that prefix, so give it:

$ tobar-segais build --content ./content --out ./site --site /repo

Get this wrong and the pages render but the stylesheet, the search index and every link between pages point one directory too high. Serving the output locally is the quickest way to be sure — but serve it from the same depth it will be published at, or the mistake will not show.

In a release pipeline

The two commands compose: build the bundles from source, then build the site from the bundles.

$ tobar-segais bundle ./docs --out ./content
$ tobar-segais build --content ./content --out ./site --site /handbook

Keeping the archives — rather than generating the site straight from source — is what makes the version picker work. build publishes every archive it finds, so a content directory holding handbook-1.0.0.zip and handbook-1.1.0.zip produces a site with both versions and a picker that moves between them. Add each release to the directory and keep it there.