Build & deployment

Applies to DevSikt 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.

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.

Author and link articles

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. Your download contains editable source and a compiled preview. Your permitted use, support period and access to releases are governed by the licence associated with your purchase. A successful local build does not authorize redistributing DevSikt as a template or source product.

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.