Skip to content

Commit 014b123

Browse files
vrasparCopilot
vraspar
and
Copilot
committed
feat(website): add blog infrastructure with markdown-to-HTML build
Add a lightweight blog system that converts markdown posts to styled HTML matching the site's dark theme. No frameworks added, just a build script. New files: - scripts/build-blog.js: Converts md posts to HTML using marked + gray-matter - website/blog-src/posts/: Markdown source directory for blog posts - website/blog/blog.css: Blog-specific styles (nav, prose, index listing) - website/blog/: Generated HTML output directory Changes: - package.json: Add build:blog script + marked devDependency - .github/workflows/pages.yml: Run build:blog before GitHub Pages deploy First post: Building Brain migrated from docs/blog/ with frontmatter. Workflow: write md in blog-src/posts/ -> npm run build:blog -> push Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent b37fe54 commit 014b123

8 files changed

Lines changed: 629 additions & 3 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,14 @@ jobs:
2424
steps:
2525
- uses: actions/checkout@v4
2626

27+
- name: Setup Node.js
28+
uses: actions/setup-node@v4
29+
with:
30+
node-version: 20
31+
32+
- name: Build blog
33+
run: npm ci && npm run build:blog
34+
2735
- name: Setup Pages
2836
uses: actions/configure-pages@v5
2937

‎package-lock.json‎

Lines changed: 23 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
"test": "vitest run",
2222
"test:watch": "vitest",
2323
"lint": "eslint src/ test/",
24+
"build:blog": "node scripts/build-blog.js",
2425
"prepublishOnly": "npm run build"
2526
},
2627
"keywords": [
@@ -56,6 +57,7 @@
5657
"@types/better-sqlite3": "^7.6.13",
5758
"@types/node": "^25.5.0",
5859
"eslint": "^10.1.0",
60+
"marked": "^17.0.5",
5961
"tsx": "^4.21.0",
6062
"typescript": "^5.9.3",
6163
"vitest": "^4.1.0"

‎scripts/build-blog.js‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Blog build script for brain.vraspar.com
5+
*
6+
* Converts markdown posts in website/blog-src/posts/ to HTML in website/blog/.
7+
* Uses gray-matter for frontmatter + marked for markdown-to-HTML.
8+
*
9+
* Usage: node scripts/build-blog.js
10+
*/
11+
12+
import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from 'node:fs';
13+
import { join, basename, dirname } from 'node:path';
14+
import { fileURLToPath } from 'node:url';
15+
import matter from 'gray-matter';
16+
import { marked } from 'marked';
17+
18+
const __dirname = dirname(fileURLToPath(import.meta.url));
19+
const ROOT = join(__dirname, '..');
20+
const POSTS_DIR = join(ROOT, 'website', 'blog-src', 'posts');
21+
const OUTPUT_DIR = join(ROOT, 'website', 'blog');
22+
const SITE_URL = 'https://brain.vraspar.com';
23+
24+
function loadPosts() {
25+
if (!existsSync(POSTS_DIR)) return [];
26+
return readdirSync(POSTS_DIR)
27+
.filter(f => f.endsWith('.md'))
28+
.map(file => {
29+
const raw = readFileSync(join(POSTS_DIR, file), 'utf8');
30+
const { data, content } = matter(raw);
31+
const slug = basename(file, '.md');
32+
const html = marked.parse(content);
33+
return { slug, html, ...data };
34+
})
35+
.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
36+
}
37+
38+
function formatDate(date) {
39+
return new Date(date).toLocaleDateString('en-US', {
40+
year: 'numeric', month: 'long', day: 'numeric',
41+
});
42+
}
43+
44+
function esc(str) {
45+
return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
46+
}
47+
48+
const HEAD = ` <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='80' font-family='monospace' fill='%234ade80'>b</text></svg>">
49+
<link rel="preconnect" href="https://fonts.googleapis.com">
50+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
51+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500&family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet">`;
52+
53+
function renderPost(post) {
54+
return `<!DOCTYPE html>
55+
<html lang="en">
56+
<head>
57+
<meta charset="UTF-8">
58+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
59+
<title>${esc(post.title)} \u2014 Brain CLI Blog</title>
60+
<meta name="description" content="${esc(post.summary || '')}">
61+
<meta property="og:title" content="${esc(post.title)}">
62+
<meta property="og:description" content="${esc(post.summary || '')}">
63+
<meta property="og:type" content="article">
64+
<meta property="og:url" content="${SITE_URL}/blog/${post.slug}/">
65+
<meta name="twitter:card" content="summary">
66+
${HEAD}
67+
<link rel="stylesheet" href="../../style.css">
68+
<link rel="stylesheet" href="../blog.css">
69+
</head>
70+
<body>
71+
<nav class="blog-nav">
72+
<div class="container">
73+
<a href="/" class="blog-nav-brand">brain</a>
74+
<a href="/blog/">Blog</a>
75+
</div>
76+
</nav>
77+
<main class="blog-main">
78+
<article class="blog-post">
79+
<header class="blog-post-header">
80+
<h1>${esc(post.title)}</h1>
81+
<div class="blog-post-meta">
82+
<time datetime="${new Date(post.date).toISOString()}">${formatDate(post.date)}</time>
83+
${post.author ? `<span class="blog-post-author">by ${esc(post.author)}</span>` : ''}
84+
</div>
85+
</header>
86+
<div class="blog-post-content">
87+
${post.html}
88+
</div>
89+
</article>
90+
<div class="blog-post-footer">
91+
<a href="/blog/">&larr; All posts</a>
92+
<a href="https://github.com/vraspar/brain">GitHub &rarr;</a>
93+
</div>
94+
</main>
95+
<footer class="site-footer">
96+
<div class="container">
97+
<div>brain &middot; MIT License</div>
98+
</div>
99+
</footer>
100+
</body>
101+
</html>`;
102+
}
103+
104+
function renderIndex(posts) {
105+
const list = posts.map(p => `
106+
<article class="blog-index-post">
107+
<a href="/blog/${p.slug}/">
108+
<h2>${esc(p.title)}</h2>
109+
<time datetime="${new Date(p.date).toISOString()}">${formatDate(p.date)}</time>
110+
${p.summary ? `<p>${esc(p.summary)}</p>` : ''}
111+
</a>
112+
</article>`).join('\n');
113+
114+
return `<!DOCTYPE html>
115+
<html lang="en">
116+
<head>
117+
<meta charset="UTF-8">
118+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
119+
<title>Blog \u2014 Brain CLI</title>
120+
<meta name="description" content="Blog posts about building Brain CLI.">
121+
<meta property="og:title" content="Blog \u2014 Brain CLI">
122+
<meta property="og:type" content="website">
123+
<meta property="og:url" content="${SITE_URL}/blog/">
124+
<meta name="twitter:card" content="summary">
125+
${HEAD}
126+
<link rel="stylesheet" href="../style.css">
127+
<link rel="stylesheet" href="blog.css">
128+
</head>
129+
<body>
130+
<nav class="blog-nav">
131+
<div class="container">
132+
<a href="/" class="blog-nav-brand">brain</a>
133+
<a href="/blog/">Blog</a>
134+
</div>
135+
</nav>
136+
<main class="blog-main">
137+
<header class="blog-index-header">
138+
<h1>Blog</h1>
139+
<p>Notes on building Brain CLI.</p>
140+
</header>
141+
<div class="blog-index-list">
142+
${list}
143+
</div>
144+
</main>
145+
<footer class="site-footer">
146+
<div class="container">
147+
<div>brain &middot; MIT License</div>
148+
</div>
149+
</footer>
150+
</body>
151+
</html>`;
152+
}
153+
154+
const posts = loadPosts();
155+
if (posts.length === 0) {
156+
console.log('No blog posts found in website/blog-src/posts/');
157+
process.exit(0);
158+
}
159+
160+
for (const post of posts) {
161+
const postDir = join(OUTPUT_DIR, post.slug);
162+
mkdirSync(postDir, { recursive: true });
163+
writeFileSync(join(postDir, 'index.html'), renderPost(post));
164+
console.log(` Built: blog/${post.slug}/`);
165+
}
166+
167+
writeFileSync(join(OUTPUT_DIR, 'index.html'), renderIndex(posts));
168+
console.log(` Built: blog/index.html (${posts.length} post${posts.length === 1 ? '' : 's'})`);

‎website/blog-src/posts/building-brain.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: "Building Brain: A CLI for Team Knowledge Sharing"
3+
date: 2026-03-28
4+
author: Vivek Parikh
5+
summary: "How I built a CLI tool that stores team knowledge in git, searches it with FTS5, and exposes it to AI agents through MCP."
6+
---
7+
8+
## The problem
9+
10+
I use AI agents for most of my development work. They produce a lot of markdown: guides, runbooks, patterns, context files. Over months, this accumulates into a personal knowledge base that's genuinely useful.
11+
12+
The problem is sharing it. I tried Obsidian, which works well for personal use but doesn't solve team knowledge sharing. There's no good way for a teammate's agent to access what my agent has already figured out. The pattern I kept seeing: I'd ask a teammate a question, they'd ask their agent, the agent would answer from scratch. That knowledge existed somewhere, but nobody could find it.
13+
14+
Wikis don't solve this either. They require manual curation, they rot without maintenance, and AI agents can't interact with them programmatically. I wanted something that fits how developers already work: command line, git, markdown.
15+
16+
## Architecture
17+
18+
Brain is a CLI tool that stores knowledge as markdown files in a git repository. Three design decisions define the architecture:
19+
20+
**Git as storage.** Entries are markdown files with YAML frontmatter, committed to a shared repo. No server to run, no database to manage, no accounts to create. Version history and access control come from git. A team joins by cloning the repo.
21+
22+
**SQLite FTS5 for search.** Each machine maintains a local search index using SQLite's FTS5 virtual table with BM25 ranking. The index is a disposable cache, rebuilt from git on every sync. This gives sub-millisecond full-text search with prefix matching and contextual snippets, without requiring any external service.
23+
24+
**MCP as the agent interface.** Brain exposes 10 tools and 2 resources via the Model Context Protocol over stdio. An AI agent connected to Brain can search team knowledge, read entries, publish findings, and check what's new. The agent doesn't need the CLI; it talks MCP directly. This is the key differentiator: the agent is a first-class user, not an afterthought.
25+
26+
The rest follows from these three decisions. Read receipts are JSON files in the repo (so they sync with git). Freshness scoring uses a multiplicative formula over recency and read frequency. Pruning moves stale entries to `_archive/` (reversible). Everything runs locally, everything syncs through git.
27+
28+
## The tagging problem
29+
30+
Brain's first auto-tagger was a 56-term hardcoded dictionary. It matched words like "docker" and "kubernetes" in entry content and used them as tags. This works for the obvious cases but misses everything else. A guide about "payment service deployment patterns" gets tagged `docker` but not `payments`, `deployment-pipeline`, or `microservices`. The dictionary doesn't know your domain.
31+
32+
The relationship system had the same issue: four heuristic signals (shared tags, title overlap, same author, content cross-references) that miss connections between entries with different vocabulary. Two entries about Redis timeouts and connection pooling aren't linked because they happen to use different words.
33+
34+
We're replacing this with a two-algorithm approach, both zero-dependency:
35+
36+
**RAKE (Rapid Automatic Keyword Extraction)** extracts multi-word keyphrases per document. Instead of matching "docker" from a dictionary, it extracts "multi-stage docker builds" as a meaningful phrase. About 60 lines of TypeScript, no corpus needed.
37+
38+
**TF-IDF with zone weighting** scores terms by how distinctive they are within the corpus. A term that appears in one entry but rarely across the brain scores high. A term that appears everywhere (like "the" or even "guide") scores low. Markdown structure matters: title tokens get 3x weight, headings get 2x, code blocks 1.5x. The corpus index lives in SQLite and improves as the brain grows.
39+
40+
For relationships, TF-IDF cosine similarity replaces the heuristic linker. Two entries with high overlap in distinctive terms are related, regardless of whether they share tags or title words. This catches the Redis timeout / connection pooling case: both score high on `redis`, `connection`, `timeout`, `pool` relative to the rest of the corpus.
41+
42+
## Obsidian compatibility
43+
44+
Every brain works as an Obsidian vault. The directory structure (`guides/`, `skills/`) maps to folders. Entries are standard markdown with YAML frontmatter. Open `~/.brain/repo` in Obsidian and you get a visual graph of your team's knowledge for free.
45+
46+
This matters because it meets people where they are. Some team members prefer a visual editor. Some want a graph view. Brain doesn't force a choice between CLI and GUI; the same data works in both.
47+
48+
## What's next
49+
50+
The intelligent tagging system is the next major feature. After that:
51+
52+
- Better auto-linking via TF-IDF cosine similarity and entity extraction (CLI commands, file paths, URLs as link signals)
53+
- Louvain clustering for auto-discovered topic groups
54+
- Multi-brain support (multiple knowledge bases per machine)
55+
- Auto-archive for entries that stay stale for 30+ days
56+
57+
Brain is open source and in alpha. If you're interested, the repo is at [github.com/vraspar/brain](https://github.com/vraspar/brain) and the project site is at [brain.vraspar.com](https://brain.vraspar.com).

0 commit comments

Comments
 (0)