shulkwisec
01 Articles/Guides//4 min read

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: nav puts it in the header navigation instead of the writing grid.
  • Point VAULT_PATH at a directory outside the repo if you keep your notes elsewhere.
  • Turn on the optional graph view in site.config.ts when 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.