mark-static

mark-static turns a folder of Markdown files into a static SvelteKit documentation site.

It is built for file-structure CMS style authoring: scaffold a site, choose a starter content preset, then add or move Markdown files in static/content.

Demo site

Create a Site

Use the published package CLI to scaffold into the current empty directory:

pnpm dlx mark-static@latest init

Or create a new directory in one command:

pnpm dlx mark-static@latest my-docs

The CLI downloads the generator, guides you through a short setup, shows a project summary, writes a complete SvelteKit static documentation project, and then exits. The generated project is yours: it is private by default, includes a lockfile, and can be developed without keeping this repository around.

For a non-interactive run:

pnpm dlx mark-static@latest my-docs --yes --name "Acme Docs" --preset basic --theme forest --background aurora --deploy github-pages

Add --install --git --git-commit when you want the scaffold to install dependencies, initialize a local Git repository, and create the first commit before it exits:

pnpm dlx mark-static@latest my-docs --yes --install --git --git-commit

Then start the generated project:

cd my-docs
pnpm install
pnpm dev

From this repository checkout, use the local scaffold command:

pnpm install
pnpm create-site ../my-docs

The scaffold asks for:

• site name and description
• content preset: minimal, basic, or api
• theme preset: default, forest, or mono
• background: aurora, grid, or none
• deployment target: github-pages, netlify, vercel, or static
• whether to install dependencies
• whether to initialize Git
• whether to create an initial commit

Useful package CLI helpers:

pnpm dlx mark-static@latest --help
pnpm dlx mark-static@latest --list-presets

Local non-interactive run:

pnpm create-site ../acme-docs --yes --name "Acme Docs" --preset basic --theme forest --background aurora --deploy github-pages --install --git --git-commit

To scaffold into the current empty directory:

pnpm create-site init --name "Acme Docs"

Useful CLI helpers:

pnpm create-site --help
pnpm create-site --list-presets

Generated Projects

Scaffolded sites include:

• markstatic.config.js for site identity, content directory, base path, and theme choices.
• static/content for Markdown pages and assets.
• src/custom-theme.css for project-specific CSS variable overrides.
• pnpm-lock.yaml and .npmrc for reproducible pnpm installs.
• Provider config for the selected deployment target.

The scaffold removes generator-only files, so the new project does not keep the mark-static CLI, test suite, demo content, or package publishing metadata.

Add Content

Content lives in static/content.

Use plain Markdown files for simple pages:

static/content/
  01.Getting Started.md
  02.Guides/
    01.Installation.md
    02.Configuration.md

Use index.md for folder landing pages:

static/content/
  02.Guides/
    index.md
    01.Installation.md

The older folder page model is still supported when a page needs local assets grouped beside it:

static/content/
  03.Reference/
    API/
      content.md
      diagram.png

Numeric prefixes are used for sorting and removed from URLs. Folder and file names can contain spaces, dots, mixed case, and punctuation; the generator normalizes them into URL-safe slugs and fails if sibling routes collide.

Frontmatter

Frontmatter is optional. When present, it overrides file or folder derived metadata:

---
title: OAuth Flow
description: Configure API authentication.
order: 30
slug: auth-flow
tags: [auth, api]
draft: false
---

# Auth Flow

Markdown content goes here.

Supported fields:

• title: navigation and page title.
• description: page metadata and search text.
• order: sort order within sibling files and folders.
• slug: URL segment override.
• tags: search metadata.
• draft: exclude from generated pages unless INCLUDE_DRAFTS=true.

Configure

Site-level settings live in markstatic.config.js:

export default {
	site: {
		name: 'Acme Docs',
		description: 'Acme product documentation.',
		docsLabel: 'Documentation',
		repositoryUrl: '',
		basePath: '/acme-docs',
		language: 'en'
	},
	content: {
		dir: 'static/content'
	},
	theme: {
		skeleton: 'wintry',
		preset: 'default',
		background: 'aurora'
	}
};

Use basePath for GitHub Pages project sites. Keep it empty for root-hosted targets like Netlify, Vercel, or a custom domain.

Theme Overrides

The default design tokens are defined in src/theme.css. Project-level overrides belong in src/custom-theme.css so users can change only what they need.

Common tokens:

• --ms-page-bg
• --ms-text
• --ms-surface
• --ms-border
• --ms-accent
• --ms-focus-ring
• --ms-header-bg
• --ms-sidebar-bg

Example:

body {
	--ms-accent: oklch(58% 0.18 250deg);
	--ms-page-bg: oklch(99% 0.01 250deg);
}

Scripts

pnpm dev
pnpm generate
pnpm docs:check
pnpm build
pnpm preview
pnpm lint
pnpm test
pnpm check:generated

pnpm generate writes src/lib/generated/content.js from the Markdown tree.

pnpm docs:check validates documentation pages for missing titles, duplicate headings, missing image alt text, broken local assets, and broken internal links.

pnpm check:generated regenerates content data and fails if the committed generated manifest is stale.

Deployment

The included GitHub Pages workflow installs with pnpm, builds the static site, uploads build as a Pages artifact, and deploys it with GitHub's first-party Pages deployment action.

For GitHub Pages project sites, set site.basePath in markstatic.config.js to the repository path, for example /my-docs.

For Netlify, Vercel, or other root-hosted static targets, keep site.basePath empty.

Release

mark-static is published on npm. Before publishing a new version, update package.json and CHANGELOG.md, then run the full release gate:

pnpm release:check

This runs package metadata validation, unit tests, the packed-package scaffold smoke test, linting, documentation validation, generated-manifest drift detection, a production build, and a package dry run. The same command runs automatically through prepublishOnly.

To create an inspectable local tarball without publishing:

pnpm release:dry-run

This writes the packed archive to the ignored package directory after the full release gate passes.

The prepack lifecycle also runs the package metadata check, documentation check, and generated-manifest drift check whenever the package is packed or published.

When the dry run looks right, verify the npm account and publish:

npm whoami
pnpm publish --access public

After publishing, verify the public scaffold path:

pnpm dlx mark-static@latest init

Maintainer Development

This repository also serves as the demo site. Install dependencies and run:

pnpm dev

Before committing changes:

pnpm release:check

The CI workflow runs the same release check on pushes to main and on pull requests.

License

MIT