Static site content routes
Content routes are the part of the static-site target that let a site grow without registering every page in Rust. You put Markdown or MDX files in a folder, describe that folder in fission.toml, and the site shell turns each file into a generated route.
Use this model for documentation, reference pages, release notes, blogs, policy pages, and other pages where the main content is text with occasional code, tables, images, and links. Use custom Fission route widgets when the page needs a designed product layout rather than an article layout.
1. Enable the site target
Start with a Fission project that has the static-site target enabled.
targets = ["static-site"]
[app]
name = "my-docs"
app_id = "com.example.my_docs"
What you should have working
After this guide, you should be able to explain where Static site content routes fits in the Fission lifecycle, identify the file or component you changed, run the relevant fission command, and verify the result in a real target or test.
Common mistakes to check
Symptom | What to check first |
|---|---|
The app compiles but nothing changes | Confirm the component is actually used by the route or shell target you are running. |
An action fires but state does not update | Confirm the reducer is registered with the same action value that the UI dispatches. |
A platform feature reports unsupported | Confirm the target has the capability in fission.toml and the shell registered the provider. |
The page works on one target but not another | Run fission doctor, then inspect target-specific configuration and feature flags. |
Tests are hard to write | Split the product rule into a reducer test first, then add a UI or shell smoke test for the integration. |
If the project already exists, this is the safe command path:
fission init .
fission add-target site --project-dir .
fission init . is idempotent. It writes missing project metadata and preserves existing source files.
2. Create a content folder
Create a folder for the section you want to publish. This example uses content/docs.
my-docs/
content/
docs/
intro.mdx
learn/
quickstart.mdx
A page uses front matter for route metadata and Markdown for the body.
---
title: Quickstart
description: Build and run your first app.
---
# Quickstart
This page becomes a generated HTML route.
The title is used in the article heading, browser title, search index, and generated metadata. The description is used for SEO and social previews. Keep both specific to the page.
3. Register the content route
Add a [[site.routes]] block. The path is the public URL prefix. The source is the project-relative folder containing Markdown files.
[site]
entry = "crate::site_app"
title = "My Docs"
description = "Documentation for my product."
base_url = "https://docs.example.com"
out_dir = "dist/site"
asset_dirs = ["static"]
generate_sitemap = true
generate_robots = true
[[site.routes]]
kind = "content"
path = "/docs"
source = "content/docs"
template = "fission::site::documentation"
sidebar = "site/docs-sidebar.toml"
With that config, content/docs/learn/quickstart.mdx becomes /docs/learn/quickstart/. The built-in documentation template renders a header, collapsible left sidebar, article body, right table of contents, and footer.
4. Write the sidebar explicitly
Sidebars are explicit TOML files because generated alphabetical navigation is rarely good product documentation. A small sidebar looks like this:
[[items]]
title = "Start"
href = "/docs/intro/"
level = 1
group = true
[[items]]
title = "Introduction"
href = "/docs/intro/"
level = 2
[[items]]
title = "Quickstart"
href = "/docs/learn/quickstart/"
level = 2
The static shell progressively enhances the sidebar. Top-level groups are shown first, nested groups can expand, and the current page's ancestors open automatically. Without JavaScript, the sidebar remains plain links.
5. Add assets, code highlighting, and search
Static assets are copied from the directories listed in asset_dirs.
[site]
asset_dirs = ["static"]
logo = "/img/logo.svg"
favicon = "/img/favicon.svg"
Code highlighting is opt-in. The generated page only loads highlighting assets on pages that contain code blocks.
[site.code_highlighting]
enabled = true
Client-side search is also opt-in. It writes a local index into the generated site, so no hosted search service is required.
[site.search]
enabled = true
output_path = "search"
min_token_len = 2
6. Check, build, and serve
Use check while writing content because it renders all routes and validates internal links.
fission site check --project-dir .
Use serve when you need to review the generated site in a browser.
fission site serve --project-dir . --host 127.0.0.1 --port 8123
Use build in release workflows.
fission site build --project-dir . --release
The output directory contains ordinary HTML, CSS, JavaScript, search files, sitemap, robots file, and copied assets. It can be hosted on any static host or packaged into a Docker image.
Fission
A cross-platform, GPU-accelerated user interface framework for Rust. MIT licensed.
Copyright (c) 2026 Fission
Ready to use today. Widget APIs are expected to remain stable; some runtime and shell APIs may change before 1.0.0.
Fission 0.7.0