cargo install cargo-fission
fission init field-journal --template website
cd field-journal
cargo add serde_yaml
fission site serve --project-dir .
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"fission.toml","value":"fission-toml"},{"index":1,"label":"src/lib.rs","value":"src-lib-rs"},{"index":2,"label":"src/home.rs","value":"src-home-rs"},{"index":3,"label":"src/translations.rs","value":"src-translations-rs"},{"index":4,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":5,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"},{"index":6,"label":"content/blog/2026-09-18-markdown-to-pages.mdx","value":"content-blog-2026-09-18-markdown-to-pages-mdx"},{"index":7,"label":"content/blog/2026-09-15-useful-search.mdx","value":"content-blog-2026-09-15-useful-search-mdx"},{"index":8,"label":"content/blog/2026-09-11-corrections.mdx","value":"content-blog-2026-09-11-corrections-mdx"}]}
{"id":"fission-tabs-1","index":0,"label":"fission.toml","value":"fission-toml"}
targets = ["static-site"]
[app]
name = "field-journal"
app_id = "rs.example.field.journal"
[site]
entry = "crate::site_app"
title = "Field Journal"
description = "Practical notes about building and maintaining small software projects."
base_url = "https://field-journal.example.com"
out_dir = "dist/site"
default_locale = "en-US"
locales = ["en-US", "es-ES"]
generate_sitemap = true
generate_robots = true
[site.code_highlighting]
enabled = true
[[site.nav]]
title = "Journal"
href = "/blog/"
[[site.routes]]
path = "/blog"
source = "content/blog"
template = "fission::site::blog"
{"id":"fission-tabs-1","index":1,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod home;
mod translations;
pub fn site_app() -> fission::site::FissionSite {
fission::site::FissionSite::new().with_env(translations::create_env())
.route_widget::<(), _>("/", "Field Journal",
Some("Practical notes about building and maintaining small software projects.".into()),
home::JournalHome::new())
}
pub fn build_site() -> anyhow::Result<()> {
fission::site::build_from_cli(site_app())
}
{"id":"fission-tabs-1","index":2,"label":"src/home.rs","value":"src-home-rs"}
use fission::prelude::*;
fission_component! {
pub JournalHome<()> {}
view(_home, _state, cx) {
let tokens = &cx.view.env().theme.tokens;
} =>
Container(Column(gap: tokens.spacing.l, children: [
SemanticsRegion(identifier: Some("site-heading-1:field-journal".into()), child:
Text(cx.tr("home.title")).size(tokens.typography.heading1_size)),
Text(cx.tr("home.description")),
Link::to(cx.tr("home.read"), "blog/"),
])).padding_all(tokens.spacing.l).bg(tokens.colors.background)
}
{"id":"fission-tabs-1","index":3,"label":"src/translations.rs","value":"src-translations-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use std::collections::HashMap;
pub fn create_env() -> Env {
let mut env = Env::default();
env.locale = Locale::from("en-US");
for (locale, source) in [
("en-US", include_str!("../i18n/en-US.yaml")),
("es-ES", include_str!("../i18n/es-ES.yaml")),
] {
let messages: HashMap<String, String> =
serde_yaml::from_str(source).expect("checked-in translations must be valid YAML");
env.i18n.add_bundle(TranslationBundle { locale: Locale::from(locale), messages });
}
env
}
{"id":"fission-tabs-1","index":4,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
home.title: "Field Journal"
home.description: "Practical notes about building, explaining and maintaining small software projects."
home.read: "Read the journal"
{"id":"fission-tabs-1","index":5,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
home.title: "Field Journal"
home.description: "Notas prácticas sobre crear, explicar y mantener pequeños proyectos de software."
home.read: "Leer la revista"
{"id":"fission-tabs-1","index":6,"label":"content/blog/2026-09-18-markdown-to-pages.mdx","value":"content-blog-2026-09-18-markdown-to-pages-mdx"}
---
title: Keep an article at a stable address
description: How source files, metadata and links identify the same article.
categories: [Rust guides]
tags: [markdown, static sites]
show_adjacent_posts: true
---
# Keep an article at a stable address
An article can be reached through a shared link, a search result or its archive. Those routes should identify the same piece of writing. A title copied into a separate Rust record becomes another value an editor has to remember to change.
## Keep content together
Put the title, description and body in one Markdown file. Use the description to state the question the article answers, not a second unrelated marketing claim. Its public URL then gives another writer a stable place to link.
## Change the structure carefully
A filename-based route can change when the file is renamed. Before reorganising a published archive, record the old URL and arrange an explicit redirect. A fresh sitemap is useful discovery information, but it does not repair someone else's saved link.
[The revision note](../2026-09-11-corrections/) explains what to record when the advice itself changes.
{"id":"fission-tabs-1","index":7,"label":"content/blog/2026-09-15-useful-search.mdx","value":"content-blog-2026-09-15-useful-search-mdx"}
---
title: Search the words a reader can remember
description: Why a search index needs meaningful article content and an honest no-result path.
categories: [Product design]
tags: [search, navigation]
show_adjacent_posts: true
---
# Search the words a reader can remember
A reader may remember a problem without remembering its headline. Search needs enough meaningful content to connect that question to the article. Filling descriptions with repeated terms makes the result harder to judge.
## Try more than the headline
Search for a term from the explanation, then one from a heading. Open the returned route and check that it contains the answer, rather than merely repeating the query.
## Keep the article reachable
Search is one way into the archive. Category links, article links and direct URLs should remain usable when the search script cannot run. That separates the reading path from an optional discovery enhancement.
{"id":"fission-tabs-1","index":8,"label":"content/blog/2026-09-11-corrections.mdx","value":"content-blog-2026-09-11-corrections-mdx"}
---
title: Record what changed in a correction
description: Keep original publication facts distinct from a later review.
categories: [Field notes]
tags: [maintenance, publishing]
show_adjacent_posts: true
---
# Record what changed in a correction
Publication starts an article's maintenance period. Dependencies change and an example that once worked can become misleading. Replacing the text without an explanation leaves a returning reader unable to distinguish a correction from their own mistake.
## State the correction
Name the behaviour that was wrong, what now happens and whether readers need to act. Keep the original publication date distinct from a later review date.
## Preserve the route
A correction is normally still the same article. Keep its address and link to a replacement when advice has been retired. [Stable article addresses](../2026-09-18-markdown-to-pages/) explain the navigation consequence.
{"id":"fission-tabs-1"}
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"fission.toml","value":"fission-toml"},{"index":1,"label":"content/blog/2026-09-08-reviewable-plan.mdx","value":"content-blog-2026-09-08-reviewable-plan-mdx"},{"index":2,"label":"content/blog/2026-09-04-error-outcomes.mdx","value":"content-blog-2026-09-04-error-outcomes-mdx"},{"index":3,"label":"content/blog/2026-09-01-release-notes.mdx","value":"content-blog-2026-09-01-release-notes-mdx"},{"index":4,"label":"content/blog/2026-08-28-state-ownership.mdx","value":"content-blog-2026-08-28-state-ownership-mdx"}]}
{"id":"fission-tabs-1","index":0,"label":"fission.toml","value":"fission-toml"}
targets = ["static-site"]
[app]
name = "field-journal"
app_id = "rs.example.field.journal"
[site]
entry = "crate::site_app"
title = "Field Journal"
description = "Practical notes about building and maintaining small software projects."
base_url = "https://field-journal.example.com"
out_dir = "dist/site"
default_locale = "en-US"
locales = ["en-US", "es-ES"]
generate_sitemap = true
generate_robots = true
[site.code_highlighting]
enabled = true
[[site.nav]]
title = "Journal"
href = "/blog/"
[[site.routes]]
path = "/blog"
source = "content/blog"
template = "fission::site::blog"
[site.search]
enabled = true
output_path = "search"
min_token_len = 2
{"id":"fission-tabs-1","index":1,"label":"content/blog/2026-09-08-reviewable-plan.mdx","value":"content-blog-2026-09-08-reviewable-plan-mdx"}
---
title: Write a plan someone can review
description: Make the outcome, owner and next action observable.
categories: [Product design]
tags: [planning, teams]
show_adjacent_posts: true
---
# Write a plan someone can review
A plan is useful when another person can tell what should happen next. A broad ambition such as “improve support” may be reasonable, but it is not enough to coordinate today's work.
## Name the result
Write “publish the handover guide reviewed by support”. That identifies an output and a reviewer. It does not prescribe every implementation detail.
## Identify the next action
Ask support which questions are missing. When that action is complete, replace it with the next decision rather than allowing this small record to become another backlog.
{"id":"fission-tabs-1","index":2,"label":"content/blog/2026-09-04-error-outcomes.mdx","value":"content-blog-2026-09-04-error-outcomes-mdx"}
---
title: Distinguish a failed request from a rejected write
description: An interrupted response does not always prove that a server changed nothing.
categories: [Rust guides]
tags: [errors, network]
show_adjacent_posts: true
---
# Distinguish a failed request from a rejected write
A client can lose a response after a server has committed a change. Showing “nothing was saved” in that case claims knowledge the client does not have. Automatically repeating the request may create a duplicate.
## Preserve the user's input
Keep the draft while explaining that the outcome is uncertain. Reload the authoritative record before deciding whether another write is needed.
## Design a retry contract
If an operation needs safe automatic retries, define its identity and deduplication behaviour on the server. A spinner or retry button cannot establish that guarantee by itself.
{"id":"fission-tabs-1","index":3,"label":"content/blog/2026-09-01-release-notes.mdx","value":"content-blog-2026-09-01-release-notes-mdx"}
---
title: Write release notes for an upgrade decision
description: Explain changed behaviour and required actions rather than publishing an unexplained commit list.
categories: [Field notes]
tags: [releases, maintenance]
show_adjacent_posts: true
---
# Write release notes for an upgrade decision
Someone reading release notes is usually deciding whether to upgrade and what the upgrade will require. A list of internal changes forces them to reconstruct the consequence.
## Put required actions first
Name a changed default, renamed setting or migration next to the command or edit needed. Separate those changes from improvements that require no action.
## Describe the result
A fix should identify the behaviour that changed and who encountered it. Avoid calling a release “more reliable” when the evidence only establishes one corrected failure path.
{"id":"fission-tabs-1","index":4,"label":"content/blog/2026-08-28-state-ownership.mdx","value":"content-blog-2026-08-28-state-ownership-mdx"}
---
title: Put a draft where its lifetime belongs
description: Why an edit that must survive filtering cannot depend only on a mounted row.
categories: [Rust guides]
tags: [state, identity]
show_adjacent_posts: true
---
# Put a draft where its lifetime belongs
A row's local state is useful while that row remains mounted. Filtering can remove the row entirely. Giving it a stable key does not, by itself, promise to preserve state after unmounting.
## Decide what must survive
If the user expects an unfinished note to return after clearing a filter, store the draft with the record ID in application state. Let the row observe and edit that value through reducers.
## Keep the boundary small
Hover state or an isolated open disclosure can remain local. The choice follows the information's lifetime and ownership, rather than a rule that all mutable values belong in one global structure.
{"id":"fission-tabs-1"}
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"fission.toml","value":"fission-toml"},{"index":1,"label":"assets/feed.xml","value":"assets-feed-xml"},{"index":2,"label":"src/home.rs","value":"src-home-rs"}]}
{"id":"fission-tabs-1","index":0,"label":"fission.toml","value":"fission-toml"}
targets = ["static-site"]
[app]
name = "field-journal"
app_id = "rs.example.field.journal"
[site]
entry = "crate::site_app"
title = "Field Journal"
description = "Practical notes about building and maintaining small software projects."
base_url = "https://field-journal.example.com"
out_dir = "dist/site"
default_locale = "en-US"
locales = ["en-US", "es-ES"]
generate_sitemap = true
generate_robots = true
asset_dirs = ["assets"]
[site.code_highlighting]
enabled = true
[[site.nav]]
title = "Journal"
href = "/blog/"
[[site.routes]]
path = "/blog"
source = "content/blog"
template = "fission::site::blog"
[site.search]
enabled = true
output_path = "search"
min_token_len = 2
{"id":"fission-tabs-1","index":1,"label":"assets/feed.xml","value":"assets-feed-xml"}
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
<title>Field Journal</title>
<link>https://field-journal.example.com/blog/</link>
<description>Practical notes about building and maintaining small software projects.</description>
<item>
<title>Keep an article at a stable address</title>
<link>https://field-journal.example.com/blog/2026-09-18-markdown-to-pages/</link>
<guid>https://field-journal.example.com/blog/2026-09-18-markdown-to-pages/</guid>
<description>How source files, metadata and links identify the same article.</description>
</item>
</channel>
</rss>
{"id":"fission-tabs-1","index":2,"label":"src/home.rs","value":"src-home-rs"}
use fission::prelude::*;
fission_component! {
pub JournalHome<()> {}
view(_home, _state, cx) {
let tokens = &cx.view.env().theme.tokens;
} =>
Container(Column(gap: tokens.spacing.l, children: [
SemanticsRegion(identifier: Some("site-heading-1:field-journal".into()), child:
Text(cx.tr("home.title")).size(tokens.typography.heading1_size)),
Text(cx.tr("home.description")),
Link::to(cx.tr("home.read"), "blog/"),
Link::to("RSS", "feed.xml"),
])).padding_all(tokens.spacing.l).bg(tokens.colors.background)
}
{"id":"fission-tabs-1"}
fission site build --project-dir .
fission site check --project-dir .
fission site routes --project-dir .
fission site serve --project-dir . --port 8123
curl http://127.0.0.1:8123/blog/2026-09-18-markdown-to-pages/