wiki setup • sooriya

what is this?

the wiki section of the site is a digital garden. inspired by starlight but stripped down to the essentials. recursive sidebar, status badges, relative markdown links.

content structure

wiki content lives in src/content/wiki/ with nested folders for categories:

wiki/
├── index.mdx           # landing page
├── arch/
│   ├── index.md        # category intro
│   ├── riscv.md
│   └── avr.md
├── hw/
│   ├── fpga/
│   │   ├── index.md
│   │   └── ice40.md
│   └── protocols/
└── ...

frontmatter schema

title: note title
description: optional description
status: seed # seed | growing | evergreen
template: doc # doc | splash
tags: []
updated: 2026-01-02
sidebar:
  order: 10 # lower = higher in list
  label: custom label # overrides title in sidebar
  hidden: false # exclude from sidebar

status maps to visual indicators:

seed: yellow striped bar (wip, rough notes)
growing: blue bar (developing, needs work)
evergreen: green bar (mature, stable)

the recursive sidebar lives in src/components/wiki/Sidebar.astro. key parts:

tree building

entries get parsed into a tree structure. index.md files become the parent node of their folder:

function buildTree(entries: WikiEntry[]): DirNode {
  // splits entry.id by "/" and builds nested object
  // index files become __index__ of their parent
}

ordering

sidebar order comes from sidebar.order in frontmatter. if not set, defaults to 999. groups inherit the minimum order of their children if no index exists.

expand/collapse state

server renders based on current path (auto-expands ancestors)
client restores from localStorage for manually expanded groups
both states merge: if either says expand, it expands

const serverExpanded = btn.dataset.expanded === "true";
const shouldExpand = serverExpanded || expandedSet.has(groupId);

mobile behavior

on screens < 1024px, sidebar becomes a slide-in drawer with a floating toggle button. closes on outside click or escape key.

link resolution

using astro-rehype-relative-markdown-links for link processing.

write standard markdown links:

[some page](./relative/path.md)
[parent section](../other/index.md)

gets transformed to:

<a href="/wiki/relative/path">some page</a>
<a href="/wiki/other">parent section</a>

config in astro.config.ts:

rehypePlugins: [[rehypeAstroRelativeMarkdownLinks, { collectionBase: "name" }]];

the collectionBase: "name" option uses collection name as the base path. /index gets auto-stripped.

layout

wiki pages use a two-column layout on desktop:

sidebar: 14rem fixed width, sticky
content: max 48rem

defined in src/styles/pages/layout.css:

--layout-sidebar-width: 14rem;
--layout-article-max-width: 48rem;

pages

src/pages/wiki/index.astro - renders wiki/index.mdx
src/pages/wiki/[...slug].astro - dynamic route for all wiki pages

the slug handling strips /index for folder index files:

export function getStaticPaths() {
  // filters out index.mdx, maps to clean slugs
}

adding new wiki pages

create .md file in appropriate folder under src/content/wiki/
add frontmatter with at least title and status
optionally set sidebar.order for positioning
for new categories, create folder + index.md

the sidebar auto-discovers and builds the tree. no manual registration needed.