knowm.ai

Deployment runbook: See DEPLOYMENT.md.

The Knowm Inc. research blog. Long-form technical notes on running modern LLMs and other neural workloads on memristor crossbar architectures combined with personal narratives. Static site, deployed to GitHub Pages by GitHub Actions.

Stack

Astro + MDX, React (for interactive components), Tailwind CSS v4 + @tailwindcss/typography, Expressive Code (Shiki), KaTeX with mhchem, remark-directive callouts, RSS, sitemap, automatic OpenGraph image generation.

Local development

Requires Node.js 20 or newer.

npm install
npm run dev        # http://localhost:4321
npm run build      # static build into ./dist
npm run preview    # serve the built site locally

Authoring a new article

1. Draft the article as plain markdown in drafts/<slug>.md. Don't worry about MDX syntax, components, or frontmatter — write prose, drop in [plot: ...] / [fig: ...] / [sweep: ...] shorthand markers wherever you want interactive content.
2. Hand the draft to an LLM (Claude works well) along with CONVERSION_GUIDE.md. Ask it to convert the draft to MDX and place the result at src/content/blog/<slug>/index.mdx, with any images / CSVs as siblings of index.mdx.
3. Preview locally with npm run dev.
4. Commit the article work to develop. Merge develop into main when it is ready for production.

Working on unpublished drafts

Draft posts live in src/content/blog/ like normal posts but with two differences that keep them out of the public site and repo:

• Folder name starts with _, e.g. src/content/blog/_my-new-post/. The _-prefix pattern is in .gitignore, so the folder is never committed to the public repository.
• draft: true in the frontmatter. The site filters draft posts out of production builds (npm run build) but shows them during local development (npm run dev).

Workflow:

# 1. Create the draft folder (won't be committed)
mkdir src/content/blog/_my-new-post

# 2. Add index.mdx with draft: true in frontmatter
# 3. View it at http://localhost:4321 while running npm run dev
# 4. When ready to publish: rename the folder (drop the _) and set draft: false

The content collection schema lives in src/content/config.ts. The build will fail loudly if frontmatter is missing required fields.

Reusable components (importable from MDX)

Component	Use
<Figure>	Image with caption (use wide for full-bleed).
<VideoEmbed>	Responsive embedded video (src, title, optional caption).
<Callout>	Auto-generated from :::note / :::tip etc.
<PlotlyChart>	Lazy-loaded interactive Plotly chart.
<ScopeTrace>	CSV-driven oscilloscope-style time series viewer.
<ParameterSweep>	Sliders + live-updating plot of compute(params).

Article-specific components belong in the article's own folder.

Embedding YouTube videos in MDX

Use the shared VideoEmbed component instead of raw iframe markup.

import VideoEmbed from '@/components/article/VideoEmbed.astro';

<VideoEmbed
   src="https://www.youtube.com/embed/WttNSyo-XHk"
   title="Knowm and Thermodynamic RAM"
   caption="Optional caption text"
   wide
/>

Environment variables

Name	Purpose	Required?
PUBLIC_POSTHOG_KEY	PostHog project key (phc_...).	No — analytics is silently disabled if unset.
PUBLIC_POSTHOG_HOST	PostHog ingest host. Defaults to US.	No

Copy .env.example to .env for local development. Set the same values as GitHub repository or environment secrets if production analytics is enabled.

Project layout

src/
├── components/
│   ├── article/       Figure, Callout, PostHog
│   ├── charts/        PlotlyChart, ScopeTrace, ParameterSweep
│   └── layout/        Header, Footer, ThemeToggle
├── content/
│   ├── config.ts      Content collection schema (Zod)
│   └── blog/<slug>/   One folder per article (index.mdx + assets)
├── layouts/           BaseLayout, ArticleLayout
├── lib/               remark-callouts plugin
├── pages/             Routes (index, about, blog/[...slug], rss, og)
└── styles/global.css  Tailwind entry + design tokens
drafts/                Plain-markdown drafts before conversion

Deployment

The production release path is:

feature work -> develop -> main -> GitHub Actions -> GitHub Pages

Pushes and pull requests involving develop run a build check. Pushes to main build and deploy the static site to GitHub Pages at https://knowm.ai. See DEPLOYMENT.md for Pages setup, DNS cutover, and rollback notes.