Examples
Before/after snippets for common customizations, starting from the generated starter site. Each example names the file it touches; for the full file map, see Layout.
Configuration only — riebeckite.config.ts
Set the site identity
The site block controls the name, description, canonical URL, language, and the fallback link-preview image:
site: {
title: "My Blog",
description: "Notes on static sites",
baseUrl: "https://example.com",
locale: "en",
defaultOgImage: "/ogp.png",
},
Put a 1200×630 image at public/ogp.png so it is served at /ogp.png. baseUrl must be the real public URL — canonical URLs and Open Graph metadata are built from it.
See Branding your site and Configuration.
Switch the theme
Install a theme package, import its factory, and replace theme: defaultTheme():
npm install @riebeckite/theme-sakura
import { sakuraTheme } from "@riebeckite/theme-sakura";
export default defineConfig({
// ...
theme: sakuraTheme(),
});
Theme factories also take options — every theme accepts colorMode, layout, preset, settings, and stylesheets:
import { gardenTheme } from "@riebeckite/theme-garden";
theme: gardenTheme({
colorMode: "system",
preset: "reading",
settings: { typography: "serif" },
}),
Restart the dev server after changing the config. See Change Your Theme and Themes.
Curate the navigation
Before — the default navigation derives links from the vault:
plugins: [navigation()],
After — pass explicit items (with children for nested entries) and secondary for supplementary links:
plugins: [
navigation({
items: [
{ label: "Guide", href: "/guide" },
{
label: "Notes",
href: "/notes/planning",
children: [
{ label: "Planning", href: "/notes/planning" },
{ label: "Writing", href: "/notes/writing" },
],
},
],
secondary: [{ label: "GitHub", href: "https://github.com/example/site" }],
}),
],
See Pages and navigation and the navigation reference.
Turn on SEO outputs
Before — the starter registers the plugin with sitemap and robots only:
seo({ sitemap: true, robots: true }),
After — also emit RSS / Atom / JSON feeds:
seo({
sitemap: true,
robots: true,
feed: { rss: true, atom: true, json: true, limit: 30 },
}),
This renders /sitemap.xml, /robots.txt, and the feeds at build time. See the SEO plugin.
Tune code blocks
Before — the starter enables line numbers, copy button, filename, and highlights:
codeEnhance({ lineNumbers: true, copyButton: true, filename: true, lineHighlight: true, diffHighlight: true }),
After — pick Shiki themes and add a collapse button:
codeEnhance({
theme: { light: "github-light", dark: "tokyo-night" },
lineNumbers: true,
copyButton: true,
filename: true,
lineHighlight: true,
diffHighlight: true,
wrapToggle: true,
collapsible: true,
}),
See the Code Enhance plugin.
Tune related posts
relatedPosts({
limit: 8,
minScore: 2,
headingText: "Related notes",
}),
limit caps the list, minScore drops weak matches, and headingText renames the heading. See the Related Posts plugin.
Redirect old URLs with aliases
If a note has aliases in its frontmatter:
---
title: Old Note
aliases:
- legacy-note
---
the alias plugin serves /legacy-note as a redirect to the canonical permalink. Choose the HTTP status:
alias({ status: 301 }),
See the Alias plugin.
Tune hover previews
Before — the starter's settings:
hoverPreview({ delay: 120, excerptLength: 160, selector: 'a[href^="/"]' }),
After — a slower, longer preview:
hoverPreview({ delay: 300, excerptLength: 240 }),
See the Hover Preview plugin.
Make the site multilingual
Add the l10n plugin and declare the languages:
import { l10n } from "@riebeckite/plugin-l10n";
plugins: [
l10n({ defaultLang: "ja", languages: ["ja", "en", "zh-CN"] }),
],
defaultLang must appear in languages. Non-default languages get URL prefixes, a language switcher, and hreflang links. See Localization.
Read notes from an existing vault
Point content.directory at the vault — it may sit outside the site directory:
content: {
directory: "../vault",
exclude: [".obsidian/**", "Templates/**"],
},
exclude uses globs over logical paths and runs before publishing, so excluded notes are not linkable. See Publishing Obsidian notes and Content selection.
Enable SPA navigation
spa: {
prefetch: "intent",
viewTransitions: true,
},
After the first load, eligible internal links fetch the next page and replace the main content; the header and footer stay in place. Scaffolded sites already depend on @riebeckite/spa. See SPA navigation.
Generate Open Graph images
Install the plugin and pick a preset:
npm install @riebeckite/plugin-og-image
import { ogImage } from "@riebeckite/plugin-og-image";
plugins: [ogImage({ preset: "card" })],
card, minimal, and editorial are available. Images are generated at build time under /_og/; an ogImage or image value in frontmatter takes precedence. See the OG Image plugin.
Pages and layout — app/
Add a custom page
Create app/routes/about.tsx. HonoX file-based routing serves it at /about:
// app/routes/about.tsx
export default function About() {
return (
<main>
<h1>About</h1>
<p>This page is mine.</p>
</main>
);
}
See Pages and navigation.
Customize the 404 page
app/routes/_404.tsx is an ordinary site file:
// app/routes/_404.tsx
import type { Context } from "hono";
const handler = (c: Context) => {
c.status(404);
return c.render(
<div class="not-found">
<p class="not-found__status">404</p>
<h1>Not here</h1>
<p>
<a href="/">Back to home</a>
</p>
</div>,
);
};
export default handler;
Keep c.status(404) — a pretty screen served as 200 would be wrong. See Pages and navigation.
Add custom head tags
In app/routes/_renderer.tsx, keep RiebeckiteHead (it renders the standard head contents) and add your own tags next to it:
<head>
<RiebeckiteHead
faviconHref="/favicon.svg"
seo={c.get("seo")}
themeStyle={themeStyle}
themeStylesheets={getThemeStylesheets(config.theme.stylesheets)}
/>
<meta name="theme-color" content="#0f172a" />
</head>
faviconHref swaps the site icon; put the file under public/. See Layout and Branding your site.
Rearrange the article page
Before — the starter assembles the article in app/components/article.tsx:
<ArticleContent>
<Breadcrumbs />
<Properties />
<ArticleBody />
<PoweredByRiebeckite />
<RecentPosts />
<ArticleFooter class="site-article__footer">
<Backlinks />
<RelatedPosts />
</ArticleFooter>
</ArticleContent>
<aside class="site-article__aside">
<TableOfContents className="rr-table-of-contents--desktop" />
</aside>
After — move the property panel below the body and move recent posts to the aside:
<ArticleContent>
<Breadcrumbs />
<ArticleBody />
<Properties />
<PoweredByRiebeckite />
<ArticleFooter class="site-article__footer">
<Backlinks />
<RelatedPosts />
</ArticleFooter>
</ArticleContent>
<aside class="site-article__aside">
<TableOfContents className="rr-table-of-contents--desktop" />
<RecentPosts />
</aside>
SiteArticle is a site component built on the Article primitive, so you can edit it freely. See Layout.
Place plugin UI beside an article
Before — the article page uses only the generated app/components/article.tsx.
After — render plugin components in your own aside component, then use it from article.tsx:
// app/components/article-aside.tsx
import { Backlinks } from "@riebeckite/plugin-backlinks";
import { TableOfContents } from "@riebeckite/plugin-toc";
export function ArticleAside() {
return (
<aside>
<TableOfContents />
<Backlinks />
</aside>
);
}
Context-aware components read the current page from context, so no props are needed; explicit props override the context:
// app/components/article.tsx
import { ArticleAside } from "./article-aside";
// ...inside the layout:
<ArticleAside />;
See Plugins and CSS.
Show a local graph on articles
Install the plugin and register it:
npm install @riebeckite/plugin-local-graph
import { localGraph } from "@riebeckite/plugin-local-graph";
plugins: [localGraph()],
Then place the component once after the article body:
// app/components/article.tsx
import { LocalGraph } from "@riebeckite/plugin-local-graph";
// ...inside ArticleFooter:
<ArticleFooter class="site-article__footer">
<LocalGraph />
<Backlinks />
<RelatedPosts />
</ArticleFooter>
The page embeds up to three hops and 320 nodes; a truncated neighborhood says so, and the depth slider stops at three. See the Local Graph plugin.
Replace the header logo
The header renders the logo in app/components/site-header.tsx:
<img src="/riebeckite-logo.png" alt="" class="site-header__logo" width="28" height="28" />
The simplest change is to overwrite public/riebeckite-logo.png with your own square PNG — no code change needed. If you rename the file, update src to match. See Branding your site.
Create your own component
// app/components/callout.tsx
export function Callout({ children }: { children?: unknown }) {
return <aside class="callout">{children}</aside>;
}
Use it from any route or component:
// app/routes/about.tsx
import { Callout } from "../components/callout";
export default function About() {
return (
<main>
<h1>About</h1>
<Callout>Restart the dev server after config changes.</Callout>
</main>
);
}
See Layout.
Build an interactive island
UI that needs browser behavior goes in app/islands/ as a normal HonoX island:
// app/islands/counter.tsx
import { useState } from "hono/jsx";
export default function Counter() {
const [count, setCount] = useState(0);
return (
<button type="button" onClick={() => setCount((c) => c + 1)}>
Clicked {count} times
</button>
);
}
Import it from a route or component like any other component:
// app/routes/about.tsx
import Counter from "../islands/counter";
export default function About() {
return (
<main>
<h1>About</h1>
<Counter />
</main>
);
}
app/client.ts already calls createClient(), so islands hydrate without further setup. See Plugins and CSS.
Styling — CSS
Add site-wide CSS
Before — app/style.css imports the generated styles, the preset styles, and the starter's own styles:
@import "./.riebeckite/framework-styles.css";
@import "./.riebeckite/plugin-styles.css";
@import "./.riebeckite/theme-styles.css";
@import "./styles/page.css";
@import "./styles/site-header.css";
@import "./styles/site-explorer.css";
@import "./styles/site-footer.css";
@import "./styles/article.css";
@import "./styles/not-found.css";
After — keep the generated imports first and append your own stylesheet:
@import "./.riebeckite/framework-styles.css";
@import "./.riebeckite/plugin-styles.css";
@import "./.riebeckite/theme-styles.css";
@import "./styles/page.css";
@import "./styles/site-header.css";
@import "./styles/site-explorer.css";
@import "./styles/site-footer.css";
@import "./styles/article.css";
@import "./styles/not-found.css";
@import "./styles/custom.css";
Never edit files under app/.riebeckite/; they are regenerated on every build. See Plugins and CSS.
Restyle plugin UI with CSS hooks
Plugins expose stable root hooks: rr-<feature> for plugin UI (for example rr-code, rr-search) and rb-* for framework structure. Unlayered site CSS wins over framework, plugin, and theme declarations:
/* app/styles/custom.css */
.rr-code {
border-radius: 8px;
}
.rr-code__header {
font-size: 0.75rem;
}
See CSS hooks.
Write dark-mode-aware CSS
Use the semantic --rb-* tokens (such as --rb-color-accent, --rb-color-border, --rb-rule-width) so colors resolve correctly in light, dark, and system mode:
.my-banner {
border-bottom: var(--rb-rule-width) solid var(--rb-color-border);
color: var(--rb-color-accent);
}
Only when you must branch on the mode itself, scope the override to the theme root so it also works inside an embedded .rb-theme-root:
:is(:root, .rb-theme-root)[data-rb-mode="dark"] .my-banner {
background: #0f172a;
}
See Stable CSS hooks.
Override a theme token
Semantic tokens are the stable vocabulary themes and plugins read. Override them in unlayered site CSS:
/* app/styles/custom.css */
:is(:root, .rb-theme-root) {
--rb-color-accent: #c2410c;
--rb-font-heading: "Newsreader", serif;
}
Unlayered declarations win over the framework, plugin, and theme layers, so no !important is needed. See Design tokens.
Content — Markdown, MDX, frontmatter
Embed a site component in MDX
Register the plugin once with mdx({ trusted: true }) (trusted is required — MDX evaluates authored JavaScript at build time), then write an .mdx page:
---
title: Release notes
publish: true
---
import { MdxNote } from "../app/components/mdx-note";
# Release notes
<MdxNote />
See the MDX plugin.
Use Obsidian syntax
The starter registers obsidianMarkdown(), so callouts, wikilinks, embeds, inline tags, and block references work without configuration:
> [!warning]- Back up before you migrate
> Keep the vault under version control.
See [[Notes/planning]] for the schedule.
![[Notes/writing#Checklist]]
![[diagram.png|480]]
Note embeds render recursively up to three levels, and unresolved targets keep a link with rr-obsidian-wikilink--broken. See the Obsidian Markdown plugin.
Show frontmatter as properties
Frontmatter:
---
title: My note
tags: [riebeckite, docs]
status: active
publish: true
---
The properties() config decides how each key is rendered:
properties({
include: ["tags", "status"],
fields: {
tags: { type: "tags", variant: "chips" },
status: {
type: "badge",
variants: { active: "success", draft: "warning", archived: "danger" },
},
},
}),
See the Properties plugin.
Give a note a fixed URL
permalink builds URLs from frontmatter instead of the file path. Install and register it:
npm install @riebeckite/plugin-permalink
import { permalink } from "@riebeckite/plugin-permalink";
plugins: [permalink()],
Then set permalink for a one-off URL and redirect_from for the old one:
---
title: About
publish: true
permalink: /about
redirect_from: /about-us
---
Enabling this plugin changes every URL: notes without an id get a path-derived hash. Decide the URL shape before the first deployment. See the Permalink plugin.
Control publishing from frontmatter
A note without publish: true is not built — it is simply absent, and requests to its URL get the 404 page. The same applies to future-dated notes:
---
title: Draft post
# no publish: true → stays private
---
See Content setup.
Unlist or schedule a page
visibility: unlisted serves the page at its URL but keeps it out of navigation, search, feeds, the sitemap, taxonomy, graphs, backlinks, and related lists:
---
title: Share link
publish: true
visibility: unlisted
---
publishAt hides a page until the first build after the timestamp:
---
title: Launch post
publish: true
publishAt: 2026-12-01T00:00:00.000Z
---
Scheduling is build-time only — run a scheduled build for the page to appear. See Content selection.
Group notes into a series
Install and register series:
npm install @riebeckite/plugin-series
import { series } from "@riebeckite/plugin-series";
plugins: [series()],
Add the series name and position to each note:
---
title: Part 1
publish: true
series: Build a thing
series_order: 1
---
Render the navigation once per article:
// app/components/article.tsx
import { SeriesNavigation } from "@riebeckite/plugin-series";
// ...after ArticleBody:
<ArticleBody />
<SeriesNavigation />
The plugin also publishes /series and /series/<name> pages. Notes without series_order still appear, after the numbered parts. See the Series plugin.
Where to look next
- Discovery recipes — featured lists, all-posts indexes, tags, folders, series, and archive pages
- Deployment — static hosts, Cloudflare Workers, and GitHub Actions
- CLI reference —
check,doctor,build, andinspect - Presets — what each preset already registers
Powered by Riebeckite