Liquidsoap website

The source of www.liquidsoap.info, built with Docusaurus.

How it fits together

Documentation for released versions is committed here under versioned_docs/, so a build needs no network beyond npm and cannot be broken by Docker Hub or a tag going away. Each version is added once, by scripts/sync-docs.mjs, and then frozen.

The in-development version cannot be produced here. Five of its files — reference.md, reference-extras.md, reference-deprecated.md, protocols.md and settings.md — are generated by running the Liquidsoap binary itself. So production is built and published by savonet/liquidsoap, in .github/workflows/doc.yml: that job already builds Liquidsoap, so it has both the prose and the binary, clones this repository, and publishes the result to savonet.github.io.

That repository is therefore where you go to confirm the site was built, and where a build failure shows up. This repository publishes nothing; its workflow only proves the tree still builds. Review changes here with npm start.

Local development

npm ci
npm start

That serves the released versions only.

Working on the documentation itself

If you are editing pages in doc/content of a Liquidsoap checkout, drive it from there instead — that is where the reference can be generated:

# in a liquidsoap checkout
LIQUIDSOAP_WEBSITE=/path/to/this/repo dune build @doc/serve-website

That builds the reference, syncs it here, and starts this dev server with the documentation live: editing a page under doc/content re-syncs and reloads it. Without LIQUIDSOAP_WEBSITE it clones its own copy of this repository, which is what someone working only on the documentation wants.

By hand

The same thing without the dune target, if you have already run dune build @doc:

mkdir -p /tmp/bundle
cp -RL <liquidsoap>/doc/content /tmp/bundle/content        # -L: images is a symlink
cp <liquidsoap>/_build/default/doc/{reference,reference-extras,reference-deprecated,protocols,settings}.md /tmp/bundle/
sed -n 's/^(version \(.*\))$/\1/p' <liquidsoap>/dune-project > /tmp/bundle/version

npm run sync -- --version dev --bundle /tmp/bundle   # add --watch to re-sync on edits
npm start

The version file is what labels the version in the dropdown: 2.5.0 becomes 2.5.x (dev), and it follows the series on its own.

Adding a released version

npm run sync -- --version 2.4.6      # runs savonet/liquidsoap:v2.4.6 to generate the reference

Then add it to versions.json (newest first) and commit versioned_docs/, versioned_sidebars/ and static/doc-2.4.6/.

Navigation

sidebars/base.json is the single curated navigation for every version. sync-docs filters it against the pages each version actually has, so an entry that does not exist there drops out with a warning rather than breaking the build. Adding a page means editing that one file; sync-docs prints any page that ends up in no sidebar.

Checks

npm run typecheck
npm run test:prism      # the Liquidsoap Prism grammar, incl. every code block in the docs
npm run build

The build also fails if the landing page links to a page that does not exist, or if the favicon or share image named in the config was never emitted.

Layout

Path	What
versioned_docs/, versioned_sidebars/	released documentation, committed
docs/	the in-development version, generated and gitignored
sidebars/base.json	the one curated navigation
scripts/sync-docs.mjs	turns a Liquidsoap release or build into a doc tree
vendor/prism-liquidsoap/	the Prism grammar, framework-free so it can be published
src/components/ApiSearch/	the navbar API search