Volks-Typo

Volks-Typo is a free, MIT-licensed Astro blog theme that combines Bauhaus modernism with WW2-era monumental design in a zero-JavaScript, dark-mode-ready static site.

What is Volks-Typo?

Volks-Typo is an open-source blog theme built on the Astro framework with MDX integration. It takes Markdown and MDX files from the src/content/blog directory and generates a fully static blog with automatic reading time, table of contents, categories, tags, archives, and responsive dark mode. Created by GitHub user jdrhyne, the theme is designed around a "dissonant harmony" of Bauhaus functionalism and monumental aesthetics, and it deploys with one click to Netlify, Vercel, or Render, or to GitHub Pages using a BASE_PATH environment variable.

Key Features

• Dark Mode Toggle — One-click theme switching with localStorage persistence, FOUC prevention, and optimized contrast for all UI elements in both light and dark themes.
• MDX and Markdown Support — Write posts as .md or .mdx files in src/content/blog; MDX enables embedding JSX components inside normal Markdown syntax.
• Reading Time & Table of Contents — Reading time is auto-calculated at roughly 200 words per minute; the TOC is generated from H2-H4 headings and includes scroll-spy navigation.
• Zero JavaScript Output — Built pages ship pure HTML and CSS; the only JavaScript is the theme toggle initialization and scroll-spy logic, keeping total CSS around 20KB gzipped.
• Self-Hosted Typography — Oswald, Roboto Condensed, Work Sans, and JetBrains Mono are loaded via @fontsource with no external requests, protecting reader privacy.
• Full Blog Organization — Categories, tags, archives, recent posts, and a configurable frontmatter schema (title, date, author, excerpt, categories, tags, image, draft) are built in.
• SEO and Accessibility — Includes built-in meta tags, structured data, semantic HTML, and ARIA attributes, plus a Playwright test suite with visual regression baselines.

Who should use Volks-Typo?

• Design-focused bloggers who want an editorial, typographically strong look without JavaScript bloat or third-party font requests.
• Astro developers who need a typed, single-config (src/config.ts) starter with documented commands for dev, build, preview, lint, and Playwright testing.
• Self-hosters and open-source contributors who want a free MIT-licensed theme they can customize via CSS variables in src/styles/global.css and deploy to any static host.

What can you do with Volks-Typo?

• Publish a personal blog: Drop Markdown or MDX files into src/content/blog and get a responsive blog with dark mode, reading time, TOC, categories, and RSS-ready structure.
• Create a design archive or journal: Use the Bauhaus-inspired layout and monotone-plus-red color palette (accent #dc2626) to showcase typography and design history content.
• Deploy anywhere: Use the built-in one-click buttons for Netlify, Vercel, or Render, or configure SITE and BASE_PATH for GitHub Pages subdirectory deployment.
• Contribute to the theme: Run the Playwright feature tests with npm run test:features to verify dark mode, MDX rendering, reading time, TOC navigation, and visual regression snapshots.

How does Volks-Typo work?

To get started, run npm create astro@latest -- --template jdrhyne/volks-typo (or the pnpm/yarn equivalent), then install dependencies and run npm run dev to preview at localhost:4321. All site settings live in src/config.ts; content is added as Markdown or MDX posts; and npm run build outputs a static site to ./dist/ ready for any host.

Pricing

Volks-Typo is free and open source under the MIT License, so there are no licensing fees for personal or commercial use.

FAQ

Is Volks-Typo free?

Yes, Volks-Typo is released under the MIT License and can be used, modified, and deployed freely, including for commercial projects.

Does Volks-Typo support dark mode?

Yes, it includes a dark mode toggle with localStorage persistence and FOUC prevention. The default palette is a monotone scale (white, #f5f5f5, #888888, #333333, black) with a red accent (#dc2626) optimized for contrast in both themes.

What are the Node.js requirements?

You need Node.js 18.14.1 or higher and Git to install the theme. The dev server runs on localhost:4321 by default.

How do I customize the theme colors and fonts?

Edit the CSS variables in src/styles/global.css. Font families are defined as --font-heading-primary (Oswald), --font-heading-secondary (Roboto Condensed), --font-body (Work Sans), and --font-mono (JetBrains Mono), all self-hosted via @fontsource.

How do I deploy to GitHub Pages?

Set SITE=https://yourusername.github.io and BASE_PATH=/your-repo-name/ as environment variables (or in .env), then run npm run build. For root-domain deployments on Netlify or Vercel, no BASE_PATH configuration is required.