Skip to documentation

Documentation / Build & deployment

HTML-first Tailwind theme

Build & deployment

Applies to Pro source candidate 1.0.0. Prerequisites: editable source, matching lockfile, a supported Node version and a destination you are authorized to publish to. These instructions do not provision hosting. Free uses npm run build too, but supplies documentation.html rather than a documentation/ directory and has no build:docs command. Follow the Free local guide for that edition.

DevSikt release-site layout

The product site uses one host: marketing at /, documentation at /docs/, and immutable compiled previews at /demo/VERSION/ (for example /demo/1.0.0/). A later latest redirect may point to an approved immutable version, but it must never replace the versioned directory.

Maintainers can stage this layout locally after both builds by running node scripts/hostinger-deploy.mjs --version VERSION --demo /absolute/path/to/approved/compiled/demo. The command is dry-run only by default, validates the version and regular-file trees, refuses internal candidate paths, and prints a temporary staged directory. It stores no credentials. Its apply mode performs only a remote rsync dry run and deliberately stops; promotion stays gated until the final release process is approved.

Customer theme builds do not depend on this maintainer-only Hostinger workflow.

Build artifacts contain ordinary HTML, CSS and JavaScript. The host does not need a runtime framework, Node application server or Markdown service. Source files still require the build toolchain before publishing.

Build the theme

From the project folder, install locked dependencies if needed, then build and inspect:

npm ci
npm run build
npm run preview

The build first type-checks TypeScript, then writes the theme to dist/. Open the preview URL printed by Vite. Visit a workflow page directly as well as through navigation; verify its scripts, images and local fixture downloads load.

Publish the contents of dist/, including its assets/ and documentation/ directories, to the static host's document root. Do not publish only the top-level HTML files. Do not upload node_modules/, source TypeScript, local test artifacts or private customer material merely because they are in the project folder.

The full build copies public/ into the output. Review that directory before building: anything placed there is intended to be publicly downloadable, even if no visible page links to it. Do not put credentials, customer uploads or internal-only files there. The distribution validator checks several prohibited paths and extensions, but it cannot determine whether arbitrary content is confidential.

The full build includes documentation under documentation/. Keep source and generated output separate: edit source, rebuild and replace the published output together. Avoid combining new HTML with assets from an older build. npm run preview is a local inspection server, not a production hosting setup.

Build documentation separately

npm run build:docs
npm run preview:docs

The dedicated output is dist-docs/. It contains the registered documentation pages and their bundled assets, not the demo collection or files from public/. Its root index.html redirects to documentation/index.html and includes a normal fallback link.

Upload the complete contents of dist-docs/. Relative build URLs support a domain root or a path prefix. For a host prefix of /devsikt/, the getting-started article is /devsikt/documentation/index.html; keep the documentation/ directory rather than flattening its files.

The same relative-path convention applies to the full theme: /devsikt/work-queue.html must resolve to that page, not the dashboard. Preserve explicit .html links and filename case. This is a multipage site; do not enable a catch-all single-page-app rewrite to index.html. Newly authored links, images and runtime fetch URLs must also work under the prefix, so test them on the intended host rather than assuming the existing build setting fixes every URL.

The theme's Help page remains a UI example, while these articles explain how to use and customize the actual theme. When you choose a public documentation URL, update the intended theme documentation links deliberately and test both bundles again.

Deploy to GitHub Pages

No Pages workflow or remote deployment is configured by the preview. In the target repository, configure Pages publishing to install dependencies, run npm run build:docs and publish dist-docs/ as the artifact. Repository permissions and host configuration are deployment decisions, not theme features.

Before sharing the public URL, verify:

  1. The root redirect and a directly opened nested article both work.
  2. CSS and JavaScript load under the actual repository path prefix.
  3. The topics sidebar, mobile navigation, appearance toggle and Jump to search work.
  4. A copied heading link opens the intended section on a fresh visit.
  5. No demo-only or private files were accidentally included.

Use the same checks for another static host. Keep a known-good prior deployment so a bad release can be rolled back using the host's normal process.

Edit docs/content/*.md; the page title is supplied by the template, so start article sections at ##. Markdown is rendered at build time with raw HTML disabled. Fenced examples display code rather than running it.

To introduce an article, add all three source records:

  1. docs/content/your-topic.md containing the article.
  2. { slug: "your-topic", title: "Your topic" } in docPages inside scripts/documentation.mjs.
  3. documentation/your-topic.html containing {{documentation}}.

The Vite configuration derives documentation build entries from docPages. Titles and headings populate the topic sidebar and Jump to search automatically. Heading anchors are lower-case slugs; repeated headings receive numbered suffixes.

Use relative article links, for example customization.html#edit-pages-and-navigation. Keep filenames and public heading text stable, and test links after renaming either. When adding images, account for the standalone build's exclusion of public/ rather than relying on a full-theme asset accidentally being present.

Release checks

The current package version is 1.0.0, an unreleased full development source. Free and Pro archives, public documentation hosting, support contacts, licence terms and update entitlements have not been finalized. A successful local build does not establish those commercial or deployment decisions. Do not upload source or premium sample files merely because the documentation is intended to be public.

Automated development checks cover Chromium plus a smaller representative Firefox/WebKit suite. This is not a blanket supported-browser or accessibility-conformance promise. Consult the release's actual environment record when available; manual assistive-technology, real zoom and physical-device review remain separate checks. Working browser-local storage is optional for sidebar preferences; the rest of the demo state generally resets on reload.

Shared theme and project CSS are inserted as render-blocking stylesheet links in the document head by the render-blocking-page-styles Vite transform. Invoice print CSS is added only to the invoice page. This runs after Markdown documentation rendering and before Vite processes assets, so both development and compiled pages receive styles without waiting for page JavaScript. When changing the build pipeline, preserve this order and head-based loading; importing base styles only from a deferred JavaScript module can cause a flash of unstyled HTML.

For a reproducibility check, use a fresh copy of the editable source in a separate folder, with its matching lockfile and without an existing dependency installation or generated output. Do not delete your working project to simulate a clean machine. From that copy, run:

node --version
npm --version
npm ci
npx playwright install chromium
npm run check

This is a checklist to perform before release, not a claim that your machine or download has already passed it. Keep the command output and record the Node/npm versions with the result. A prebuilt preview working in a browser does not establish that the source can be installed and rebuilt independently.

Run npm run check before packaging. It tests the distribution validator, builds both outputs, checks local references/output boundaries, and then runs browser tests. After building, npm run validate:distribution can repeat the read-only output scan. It checks static references, not every runtime-generated URL, external service or asset licence. Review the generated directories and confirm that each new root page is registered in the non-documentation Vite input list. A successful development URL alone is not evidence that the page is in the release.

Test light/dark, keyboard operation and the reference viewports against the built preview. Deployment does not turn the sample 403/404/500 pages into server response handlers, or the login and billing pages into real services; configure those concerns separately in an actual application.

Jump to documentation

↑ ↓ to move · Enter to open · Esc to close