Pattern

Documentation sites.

Documentation is a natural fit for Nift: many pages share navigation, layout and browser helpers, while each page remains an ordinary readable source file. The useful part is not merely templating—it is knowing exactly which pages a shared change affects.

A complete documentation project

content/docs/
  index.html
  getting-started.html
  configuration.html
  commands.html
templates/
  docs.html
  partials/
    docs-sidebar.html
    docs-search.html
    header.html
    footer.html
public/assets/
  docs.js
  docs.css
.nift/
  config.json
  tracked.json

Track each document by its stable public identity:

nift track docs/index "Documentation" templates/docs.html
nift track docs/getting-started "Getting started" templates/docs.html
nift track docs/configuration "Configuration" templates/docs.html
nift track docs/commands "CLI commands" templates/docs.html
nift build --all

One template owns the document shell

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>$[title] · Product docs</title>
  <link rel="stylesheet" href="@pathto('public/assets/docs.css')">
</head>
<body>
  @input('templates/partials/header.html')
  <div class="docs-layout">
    @input('templates/partials/docs-sidebar.html')
    <main id="main" class="docs-content">@content</main>
  </div>
  @input('templates/partials/footer.html')
  <script src="@pathto('public/assets/docs.js')" defer></script>
</body>
</html>

The template owns global document structure. Individual content files start at their page heading and remain free of repeated navigation, metadata and asset tags.

<nav aria-label="Documentation">
  <a href="@pathto('docs/index')">Overview</a>
  <a href="@pathto('docs/getting-started')">Getting started</a>
  <a href="@pathto('docs/configuration')">Configuration</a>
  <a href="@pathto('docs/commands')">CLI commands</a>
</nav>

The same sidebar works from every nesting depth. @pathto calculates the correct output-relative URL and fails the build if a named destination disappears instead of shipping a known broken local link.

See the impact of a change before building

# Change one page
$ nift status
docs/configuration
  content changed

# Change templates/partials/docs-sidebar.html
$ nift status
docs/index
  dependency changed: templates/partials/docs-sidebar.html
docs/getting-started
  dependency changed: templates/partials/docs-sidebar.html
# ...every page that actually uses the sidebar

An edit to one content file stays local. An edit to shared documentation UI correctly invalidates its consumers. Use nift status -p when a large fan-out is summarized and you need every affected name.

Search, copy buttons and playgrounds remain browser features

Nift can generate the search form, result container, code blocks and playground mount points. Ordinary JavaScript or a specialist search indexer owns the interactive behaviour:

<form role="search" data-docs-search>
  <label for="docs-query">Search documentation</label>
  <input id="docs-query" type="search" autocomplete="off">
  <div data-docs-results aria-live="polite"></div>
</form>

A TypeScript/Vite build may write public/assets/docs.js before Nift runs. Nift does not need to become a search engine or browser-component framework to place and check that asset.

Versioned documentation

content/docs/
  v4/
    getting-started.html
    commands.html
  v3/
    commands.html
  migration/
    v3-to-v4.html

Give every maintained version a distinct tracked name such as docs/v4/commands. A shared template can display a version selector, while @pathto keeps cross-version and migration links explicit. Do not overwrite historical documentation with current semantics if users still operate an older release.

Markdown is an optional authoring layer

If a team prefers Markdown, run a Markdown converter before Nift and make its output an explicit input to the Nift build. Keep the ordering visible in a Makefile or package script:

docs:
	./scripts/render-markdown
	nift build

docs-clean:
	./scripts/render-markdown
	nift build --all

Nift does not require a special documentation content format. The important contract is that the preprocessing step finishes successfully before Nift consumes its output.

Build and verification checklist

Run any asset, Markdown, search-index or playground build first.
Run nift build during development and nift build --all for a clean release check.
Inspect nift status; it should be clean immediately after the build.
Crawl generated local links and fragments, including nested and versioned pages.
Exercise keyboard navigation, narrow layouts, code overflow, search and copy controls.
Deploy the generated directory—not source content or .nift/ build state.

Keep authoring simple; make relationships explicit.

The strongest Nift documentation project is not the one with the most generator features. It is the one where shared UI, paths, preprocessing and interactive assets have obvious owners and can be verified independently.