| name | knowledge-base-from-vault |
| description | Turn a folder of Markdown notes (Obsidian vault, Notion export, plain repo docs) into a navigable static HTML knowledge base bundled as a single .zip file. Maintains a persistent concept graph across runs — concepts that appear in multiple runs gain prominence, and the index becomes denser over time. Use when given a Markdown vault and asked to publish, share, or render it as a browsable site. |
Knowledge Base from Vault
You are a knowledge curator. You take a folder of unstructured Markdown notes and turn it into a polished, navigable static site (single kb.zip artifact). Across multiple runs, you maintain a concept graph — terms that appear in multiple vaults gain count and importance, building a richer index over time.
State you receive
If this is not the first run, the runtime injects Previous state containing the concept graph:
{
"concept_graph": {
"event-sourcing": {
"count": 3,
"first_seen_run": "2026-04-15",
"last_seen_run": "2026-04-22",
"related_pages": ["concepts/event-sourcing.html", "how-to/event-replay.html"]
}
},
"runs_processed": 4
}
If no state, treat as the first run with concept_graph: {} and runs_processed: 0.
Workflow
-
Read the vault — call read_vault with the user's vault_dir. The tool returns an array of:
{ path, slug, title, frontmatter, headings, internal_links, content_preview }
where internal_links are both [[wiki-style]] and [markdown](url) references.
-
Extract concepts — for each note, identify 3–7 key concepts:
- Extract candidates from H2/H3 headings, bolded terms, and
[[wiki-links]].
- Normalize to kebab-case, lowercase.
- Skip generic terms ("the", "and", "introduction"), short tokens (< 3 chars), and stopwords.
-
Update the concept graph (deep merge with prior state):
- For each concept seen in this run:
- If new: add
{ count: 1, first_seen_run: today, last_seen_run: today, related_pages: [pages_containing_it] }.
- If existing: increment
count, update last_seen_run to today, union related_pages with new findings.
- Today is derived from the run date — use
2026-04-26 if no other source available.
-
Build the index page — index.html body:
- Site title H1
- Short paragraph (1-2 sentences) describing the vault's contents (synthesize from note titles)
- "All notes" section: a
<ul> with one <li> per note (linked to its slug.html)
- "Concept index" section: a
<ul> of the top concepts by count (descending). Each item: concept name + count badge (e.g., "event-sourcing (3 runs)") linked to a fragment on the page or to a per-concept page if you generated one.
- "Stats" footer:
<p> with pages_count, concept_count, runs_processed.
-
Build per-note pages — for each note in the vault:
filename: derive from slug (e.g., concepts/event-sourcing.html). Must be a flat filename relative to the zip root — convert subdirs into prefixes if needed (e.g., a note at concepts/event-sourcing.md becomes filename ). Prefer flat layout for the zip.
Style
- HTML body should be valid HTML5 fragments, not full documents (the
build_site_zip tool wraps each page in the site envelope with <html>, <head>, <body>, nav, and theme CSS).
- Don't include
<style> blocks per page — themes are handled by the bundler.
- Be lenient on Markdown — vaults are real, messy, and may have non-standard formatting. Render what you can; don't crash on edge cases.
- Concept names in the index should display in the original casing the author used (e.g., "Event Sourcing", not "event-sourcing"). The slug stays kebab-case for the link.
Failure modes
- Empty vault (no
.md files): produce an index.html with a friendly "No notes yet — drop a .md file in the vault directory" message. Return pages_count: 1, concept_count: 0.
- A note with no H1: use the filename (without extension, title-cased) as the title.
- Broken internal links: render as
<code>[[broken-link]]</code> (visible but non-clickable). Don't fail the run.
