Build a documentation site

Fission

Product

▾

Setup

›

›

Build a documentation site

This cookbook builds a small site with the same architecture as the Fission documentation: a custom home page, Markdown-driven docs, an explicit sidebar, static assets, search, code highlighting, sitemap, robots file, and a generated static output directory.

1. Create the project

fission init docs-site
cd docs-site
fission add-target site --project-dir .

Finished state and checks

By the end of Build a documentation site, you should have a runnable change, not just a set of snippets. Run the command shown in the page, exercise the feature once manually, and add or update the smallest test that protects the behavior.

Check	Expected result
Build	cargo check or the relevant fission command finishes without target-specific configuration errors.
Behavior	The screen, package, server route, or test flow described by the recipe is visible and responds to input.
Failure path	At least one denied, missing, invalid, or empty case renders a useful message instead of silently doing nothing.
Next link	The reference page linked from the recipe explains the exact fields, commands, or types used here.

Set the site fields in fission.toml:

targets = ["static-site"]

[app]
name = "docs-site"
app_id = "com.example.docs_site"

[site]
entry = "crate::site_app"
title = "Docs Site"
description = "Documentation for the product."
base_url = "https://docs.example.com"
out_dir = "dist/site"
asset_dirs = ["static"]
logo = "/img/logo.svg"
favicon = "/img/favicon.svg"
generate_sitemap = true
generate_robots = true

[site.code_highlighting]
enabled = true

[site.search]
enabled = true

[[site.routes]]
kind = "content"
path = "/docs"
source = "content/docs"
template = "fission::site::documentation"
sidebar = "site/docs-sidebar.toml"

2. Add content and sidebar

content/docs/intro.mdx
content/docs/learn/quickstart.mdx
site/docs-sidebar.toml
static/img/logo.svg

content/docs/intro.mdx:

---
title: Introduction
description: Learn what the product does.
---

# Introduction

Start here.

site/docs-sidebar.toml:

[[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

3. Add a custom home page

use anyhow::Result;
use fission::prelude::*;
use fission::site::{build_from_cli, FissionSite};

#[derive(Default)]
struct SiteState;
impl GlobalState for SiteState {}

#[derive(Clone)]
struct HomePage;

impl From<HomePage> for Widget {
    fn from(component: HomePage) -> Self {
        Column {
            gap: Some(18.0),
            children: vec![
                Text::new("Documentation people can actually use")
                    .size(48.0)
                    .weight(FontWeight::Bold)
                    .into(),
                Text::new("A custom Fission page rendered to static HTML.").into(),
            ],
            ..Default::default()
        }
        .into()
    }
}

pub fn site_app() -> FissionSite {
    FissionSite::new().route_widget::<SiteState, _>(
        "/",
        "Docs Site",
        Some("A Fission static documentation site.".to_string()),
        HomePage,
    )
}

fn main() -> Result<()> {
    build_from_cli(site_app())
}

4. Check and build

fission site check --project-dir .
fission site build --project-dir . --release

Review dist/site/index.html, dist/site/docs/intro/index.html, dist/site/site.css, dist/site/search/, dist/site/sitemap.xml, and dist/site/robots.txt.

5. Package and publish

fission package --project-dir . --target static-site --format static --release
fission publish --project-dir . --provider github-pages --artifact target/fission/release/static-site/static/artifact-manifest.json --site production

That is the same lifecycle used by the Fission documentation site: source-controlled content and widgets in the project, generated static output in the build, and provider upload from a package manifest.

1. Create the project

Finished state and checks

2. Add content and sidebar

3. Add a custom home page

4. Check and build

5. Package and publish

Fission

A cross-platform, GPU-accelerated user interface framework for Rust. MIT licensed.

Ready to use today. Widget APIs are expected to remain stable; some runtime and shell APIs may change before 1.0.0.

GitHub

Quickstart

Reference

Fission 0.7.0