
Getting started with Sahb: your own research site from a folder of Markdown
Sahb is a personal research site that publishes itself from a folder of Markdown files. No CMS, no database, no admin panel. You write a note, set publish: true, and the next build puts it on the site with a cover, a table of contents, syntax-highlighted code, tags, a feed entry and a sitemap URL.
This guide takes a fresh checkout to a live site.
What it is built on
Astro 7 static output, zero server runtime
TypeScript strict, typed content collections
Tailwind CSS 4 the monochrome design system
remark-obsidian-md wikilinks, callouts, inline tags
Shiki syntax highlighting at build time
Playwright renders Mermaid diagrams to SVG at build time
The site ships no JavaScript by default. The only scripts are the home page filter, the mobile menu and the image lightbox, and they are a few hundred bytes of inline vanilla JS each.
Install and run
git clone https://github.com/ShulkwiSEC/shulkwisec.github.io.git
cd shulkwisec.github.io
npm install
npm run dev
The dev server prints a local URL. It is hot-reloading, so a saved note is on the page before you switch back to the editor.
The first build needs a headless browser, because Mermaid diagrams are rendered to SVG at build time instead of shipping a diagram runtime to the reader:
npx playwright install chromium
npm run build
If you do not need diagrams, the build still works without the browser. It is the diagram path that needs it.
Point it at your vault
Content lives in vault/. Every note is a Markdown file with YAML frontmatter:
---
title: "Reading an ELF header"
slug: "reading-an-elf-header"
date: 2026-11-13
category: "Reverse engineering"
tags:
- "elf"
- "linux"
excerpt: "What the first 64 bytes of a binary actually tell you."
publish: false
---
The body starts here. Section headings begin at `##`.
The fields that matter:
| Field | Required | Notes |
|---|---|---|
title |
yes | Shown as the page title. The body must not repeat it. |
date |
yes | YYYY-MM-DD. Used for ordering and for the sitemap. |
category |
yes | One category per note. Drives the category pages. |
tags |
no | A list. Drives the tag pages. |
slug |
no | Defaults to the file name, slugified. |
excerpt |
no | Generated from the first paragraph when missing. |
updated |
no | Used for lastmod in the sitemap. |
banner |
no | Vault-relative path to a cover image. |
type |
no | post (default) or nav for a header navigation page. |
publish |
yes | true publishes the note. Everything else stays private. |
publish: false is the default state of a draft, and it is enforced in both directions: the content loader never reads a private note, and the wikilink resolver will not link to one. A [[wikilink]] to a note that is not published renders as plain text, so a private title can never leak into the built site, the feed, the sitemap or the search index.
Write and publish
Create a note in vault/notes/, or use the helper that ships with the skill:
node .opencode/skills/sahb-skill/scripts/new-note.mjs "My first finding" --category "Reverse engineering" --tags "elf,linux"
The note lands with publish: false. Write it, read it on the dev server, then flip the flag:
publish: true
The things it handles for you
Wikilinks. [[note-slug]] and [[note-slug|the alias]] resolve to /posts/<slug>/. Unresolved links stay as plain text.
Images. Put the image next to the note and reference it relatively. The build copies it into the output and rewrites the path, so the vault stays the only source of truth.
Cover art. A note with banner: "00-Meta/covers/<slug>.jpg" gets a 1200x630 cover in the grid, in the related posts and in the social preview. There are two scripts for this: scripts/fetch-covers.mjs reuses a real image from the post, scripts/make-covers.mjs draws an abstract monochrome one.
Diagrams. A fenced mermaid block becomes inline SVG:
```mermaid
classDiagram
Note --> Reader : published
```
Feeds and discovery. /rss.xml, /sitemap.xml and /robots.txt are generated from the published notes only.
Related posts. Every article gets three related articles, scored on shared tags and wikilinks in either direction, falling back to the newest posts in the same category.
Checks before you publish
npm test
The test builds the site and asserts the things that are expensive to get wrong: a published note appears, a private note appears nowhere in the output, and a note with broken frontmatter fails the build with the offending file named. It is the same gate that runs in CI, so a note that passes locally passes on the server.
npx astro check runs the type checker over the whole project.
Deploy
The repository ships a GitHub Actions workflow that builds on every push to main and publishes to GitHub Pages:
- run: npm ci
- run: npx playwright install --with-deps --only-shell
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: './dist'
If you keep the vault in a submodule, add submodules: recursive to the checkout step, which the workflow already does.
For Cloudflare Pages instead, point the build command at npm run build, the output directory at dist, and add a _headers file for the security headers GitHub Pages cannot set.
Make it yours
Everything personal lives in one file, site.config.ts:
export const site: SiteConfig = {
name: 'Your Name',
handle: 'yourhandle',
role: 'Security Researcher',
bio: 'One paragraph about what you work on.',
email: 'you@example.com',
url: 'https://example.com',
socials: [
{ label: 'GitHub', url: 'https://github.com/you' },
],
features: {
showGraph: false,
showActivity: true,
},
vaultPath: process.env.VAULT_PATH ?? './vault',
};
No other file contains your name, your email or your links. Change that file and the header, the footer, the metadata, the structured data and the social preview all follow.
Keep the vault usable
Two things make the difference between a vault you write in and a vault you abandon.
First, the house style. Title in the frontmatter only, sections from ##, the body opening with content rather than an introduction, code blocks tagged and trimmed. node scripts/normalize-headings.mjs --dry reports any note that breaks the heading rules.
Second, the skill. .opencode/skills/sahb-skill teaches an assistant the vault layout, the frontmatter, the house style and the publishing rules, and it ships scripts for scaffolding notes, capturing screenshots and checking what is currently live. It lives in your global skills directory so it follows you into every project:
ls ~/.opencode/skills/sahb-skill
If you would rather not use it, the whole site still works from the vault alone. Nothing in the build depends on the skill.
Where to go next
- Add a standing page:
type: navputs it in the header navigation instead of the writing grid. - Point
VAULT_PATHat a directory outside the repo if you keep your notes elsewhere. - Turn on the optional graph view in
site.config.tswhen you want a wikilink map; it stays out of the navigation until you enable it.
Questions and issues are welcome in the repository: open an issue.
https://shulkwisec.github.io/01-Articles/getting-started-useing-sahb-template-by-shulkwisec/
Printed 2026-11-15