Statify

Statify is a compact static-site authoring toolkit for documentation, product pages, and landing sites. Write content as Markdown or structured JSON, keep ordinary assets beside the site, and generate a complete deployable website with one command.

Statify is designed for work that should remain simple:

documentation trees with nested sections and responsive navigation;
quick landing pages assembled from reusable widgets;
richer product sites with cards, FAQs, carousels, local video, and YouTube;
repeatable, agent-assisted website generation from readable source files;
static output that can be hosted by any ordinary web server or CDN.

The generated website has no server-side runtime. Statify performs the build, copies the selected browser application and assets, and leaves the result in .build/ by default.

Why use Statify?

Many websites are not applications. They are small, recurring publishing jobs: a product needs a landing page, a project needs documentation, or an organization needs a permanent home for policies and support information. These sites should be quick to create, easy to revise, pleasant to use, and simple to deploy. Statify is built for exactly that middle ground.

Launch landing pages quickly. Start from a working template, replace the example identity and content, adjust the accent colors, and publish a focused product, service, event, campaign, or project page without assembling a new frontend stack.
Build maintainable documentation systems. Organize Markdown files into ordinary folders and let that structure become the website. Adding a guide, moving a section, or reviewing a change remains as straightforward as editing a text file in version control.
Publish the pages every site needs. Privacy policies, cookie notices, terms of service, FAQs, contact information, release notes, and support pages recur across projects. Statify provides a consistent place for them without requiring a CMS or server application. Template legal text remains an example and should always be replaced and appropriately reviewed.
Create product and project microsites. A repository, downloadable tool, prototype, open-source project, internal initiative, or small business can have a clear public home without inheriting the maintenance burden of a larger framework.
Reuse a tried-and-tested responsive shell. The supplied application handles the shared page structure, navigation, light and dark presentation, and responsive behavior, producing output suited to phones, tablets, and desktop displays. Authors can concentrate on content and local styling instead of rebuilding those foundations for every site.
Mix prose with richer presentation. Markdown pages can include YouTube videos and image carousels through the bundled Showdown extensions. Use structured JSON when a page benefits from widget-driven cards, calls to action, FAQs, or local video. A site can use both formats wherever each is most appropriate.
Keep content portable and reviewable. Pages, metadata, and assets remain ordinary files. They can be searched, diffed, backed up, generated by tools, reviewed in pull requests, and moved between hosting providers without exporting content from a database.
Automate repetitive publishing. The predictable source format and small command set work well in npm scripts, CI jobs, and agent-assisted workflows. The same process can initialize, customize, build, and verify many related sites while keeping their individual branding and content separate.
Deploy almost anywhere. The result is a directory of static HTML, CSS, JavaScript, fonts, and media. It can be served by an ordinary web server, object storage, a CDN, or a static hosting platform, with no Statify or Node.js process required in production.

Statify is particularly useful when the alternative is copying an old website yet again, rebuilding the same navigation and policy pages, or introducing a full application framework for content that ultimately needs to become a set of reliable static files.

Requirements

Node.js 18 or newer
npm, or another package manager capable of installing npm packages

Installation

Install globally

A global installation makes statify available from any directory and is a convenient choice when creating and maintaining several sites:

npm install --global @nebularstreams/statify

Confirm the installation:

statify --help

Install in a project

Install Statify as a development dependency when the website should pin its own tool version and remain reproducible for other contributors or CI:

npm install --save-dev @nebularstreams/statify

Project-local commands can be used from npm scripts, or directly through:

npx --no-install statify --help

Statify is a build-time dependency. It is not needed by the generated website after deployment.

Quick start

Create a documentation website, build it, and open the result:

statify init my-documentation documentation
cd my-documentation
npm run build
npm run open

Every bundled template includes a package.json with these useful scripts:

{
  "scripts": {
    "build": "statify folder .",
    "open": "statify open",
    "stub": "statify app simple assets/app/",
    "start": "npm run build && npm run open"
  }
}

With Statify installed globally, those scripts work immediately. To pin Statify to the generated project, run npm install --save-dev @nebularstreams/statify inside it.

npm start performs the common preview workflow:

npm start

Command overview

statify init <destination> <template>
statify folder <source> [destination]
statify file <file> [destination] <source>
statify list <list-file> <source> [destination] [filter-id]
statify app <stub> <destination>
statify open [target]
statify skill install [--force]

folder, file, and list write to .build/ when their destination is omitted. open consequently opens .build/index.html by default.

Creating a new site

From your projects folder, type

statify init <destination> <template>

init copies a complete template into a new directory. It refuses to replace an existing destination.

Ask the installed package which templates it provides by running init without arguments:

$ statify init
statify: Usage: statify init <destination> <template>
Available templates: documentation, landing, landing-rich

The current templates are:

documentation — a straightforward Markdown documentation tree with responsive navigation, legal-page examples, and light/dark presentation;
landing — a concise JSON-authored landing page using the standard widget set;
landing-rich — a larger syntax reference demonstrating richer cards, FAQs, carousels, local video, YouTube embeds, and nested content.

Examples:

statify init product-manual documentation
statify init product-site landing
statify init showcase landing-rich

Template companies, people, URLs, policies, and media are examples. Replace them before publishing a real site.

Building the site

Using `statify` directly

From your initialized website, type

statify folder .

or for your convenience,

npm run build

This generates the site in .build/.

You can also provide a custom source or destination folder:

statify folder . public
statify folder website build/site

During the build, Statify:

walks the source pages/ tree recursively;
converts .md and .json pages to matching .html files;
copies other files found beneath pages/ unchanged;
copies the contents of optional assets/ into the output root.

The folder hierarchy is preserved. For example:

pages/index.md                  → .build/index.html
pages/guide/install.md          → .build/guide/install.html
pages/res/diagram.webp          → .build/res/diagram.webp
assets/res/custom.css           → .build/res/custom.css
assets/app/website.min.js       → .build/app/website.min.js

Both pages/res/ and assets/res/ map to res/ in the output. Use pages/res/ for resources owned by nearby content and assets/res/ for shared site resources. Avoid defining the same output path in both locations.

Preview the generated site

To automatically open a browser with the locally generated site type:

statify open [target]

With no target, Statify opens .build/index.html in the operating system's default browser:

statify open

npm run open

Files and URLs can also be opened explicitly:

statify open public/index.html
statify open https://example.com

Statify uses the platform-native launcher: open on macOS, xdg-open on Linux, and explorer.exe on Windows.

Advanced commands

Generate data-backed pages with `list`

statify list <list-file> <source> [destination] [filter-id]

list reads a list-page definition from the source site's lists/ directory, retrieves its configured JSON feed, and renders one static page per item. Output defaults to .build/.

statify list products.json .
statify list products.json . .build featured-product

The optional filter-id builds only the matching item, which is useful while editing or previewing a single entry. Treat remote list feeds as trusted build input and validate their schema before publishing.

Select a browser application with `app`

statify app <stub> <destination>

Statify provided different browser application stubs that provide the shared responsive runtime, styles, skins, and client-side widgets. app copies an already compiled stub; users do not need Rollup or the Statify source tree.

List the stubs included by the installed version:

statify --help

The final help line is generated from the package's dist/ directory:

Available application stubs: simple, software

Copy a selected stub into the conventional template location:

statify app simple assets/app/

Matching files are replaced, while unrelated files in the destination are preserved. Stub names are discovered dynamically, so future releases may add, rename, or remove flavours without changing the command syntax.

Source-site structure

A typical source site looks like this:

website/
  package.json
  metadata.json
  images.json
  pages/
    index.md or index.json
    guide/
      index.md
    res/
  assets/
    app/
      website.css
      website.min.js
      webfonts/
    res/
      custom.css

Metadata files

At your site root there are two important files that define basic variables for the site:

metadata.json

Site-wide metadata defines the title, description, canonical origin, domain, publisher, browser head resources, navigation, breadcrumbs, footer behavior, and light/dark controls. Begin with a template and preserve its established shape while replacing its example identity.

site.domain and navigation links are required by the renderer. Keep canonical URLs, site URLs, navigation targets, and social metadata consistent.

images.json

images.json supplies decorative images for the documentation pages. These images are displayed at the right of the page if the screen is big enough.

Each time you open a documemtation page, a random image will be picked
Format of the file is compatible with unsplash playlists, so you can export a playlist directly from unsplash instead of adding images manually.

Markdown pages

Markdown is the natural format for documentation. Headings produce the page outline, and nested folders can represent arbitrary documentation trees. Tables, fenced code, task lists, images, ordinary inline Markdown, YouTube embeds, and image carousels are supported.

See Creating websites with Statify for the Markdown media syntax and complete page-construction examples.

Prefer one H1 followed by meaningful H2 and H3 sections. Keep internal links relative to the source page when possible:

[Installation](guide/install.md)

JSON pages and widgets

JSON pages select a widget and provide structured content. Landing templates demonstrate headings, text, images, links, cards, FAQs, carousels, video, and YouTube content. Start with the smallest template that suits the site and use landing-rich as a syntax reference for advanced patterns.

See Constructing pages with Statify for the complete authoring manual, including page examples and skin variables.

assets

Page-local resources may live anywhere under pages/; shared styles, logos, scripts, and media can be put under assets/.

Styling and skins

assets/app/website.css is the compiled shared application stylesheet. Ordinary branding belongs in the template-local stylesheet, normally assets/res/custom.css.

At minimum, a site can personalize its accents:

:root {
  --accent: #ff8800;
  --accent-tx: rgba(255, 136, 0, 0.5);
}

Use .skinroot.light and .skinroot.dark for mode-specific colors. Prefer the existing skin variables over one-off hard-coded colors, and verify text, controls, cards, borders, and navigation in both modes and at mobile widths.

Codex website-authoring skill

The npm package includes an optional Codex skill that teaches Codex how to author and verify Statify websites.

Install it from a global or project-local Statify command:

statify skill install

Or install directly without keeping a global package:

npx @nebularstreams/statify@latest skill install

The skill is copied to $CODEX_HOME/skills/statify-site, falling back to ~/.codex/skills/statify-site. Existing installations are protected by default. Replace one deliberately with:

statify skill install --force

Restart or refresh Codex, then invoke the skill with $statify-site.

Deployment

The output directory is an ordinary static website. Upload .build/ to a web server, object-storage bucket, CDN, static hosting provider, or an existing application's public directory. No Statify package or Node.js process is required in production.

Before deployment:

build the complete site with statify folder or npm run build;
replace template identities, example URLs, legal text, and placeholder contact information;
verify local images, stylesheets, scripts, and page links;
preview representative pages at desktop and narrow widths;
check both light and dark skins when the theme control is enabled.

Content trust

Statify is an authoring and build tool. It treats Markdown, JSON, metadata, remote list feeds, templates, and embedded HTML as trusted project input. Do not build untrusted content without validating and sanitizing it first.

License

Statify is distributed under the MIT license