PlainBlog

PlainBlog is a black-on-white (switchable to light) Astro static blog template with breadcrumb navigation instead of a navbar, per-year article archives, and dense Markdown typography. It is a text-first theme inspired by hyoban.cc and is built on Astro with Node.js 22.12+ and pnpm 12.6 (versions recorded in package.json). The repository ships a GitHub Pages demo, and the content included is replaceable demo material.

What is PlainBlog?

PlainBlog is an Astro-based static blog template that generates a minimalist, text-first blog where the homepage lists posts grouped by year. It takes Markdown posts and page files as input and outputs a static dist/ folder you deploy to any static host. Navigation uses an unframed breadcrumb trail plus an on-demand table of contents rather than a standard navbar, and the color scheme can be toggled between near-black and white.

Key Features

• Astro framework — static site generation with no server, database, or runtime environment variables required.
• Dual color themes — near-black default with a white-background toggle; the color button remembers your choice, and without JavaScript it follows the system setting.
• Per-year archives — the homepage lists articles grouped by year.
• Breadcrumb navigation — a background-free breadcrumb trail instead of a conventional navbar.
• Collapsible table of contents — a TOC that expands on demand, with its native toggle working without JavaScript.
• Compact Markdown layout — dense typography with a markdown-field-guide.md file that doubles as a rendering sample.
• RSS feed at /rss.xml — rebuilt on every build from all public posts; drafts are excluded automatically.
• Draft support — set draft: true in frontmatter to exclude a post from the homepage and output; unpublished by default.

Who is it for?

• Writers who want a distraction-free blog: publish plain Markdown posts in src/content/posts/ without touching layout code.
• Developers deploying to static hosts: run pnpm build and publish dist/ to any static root, optionally with a BASE_PATH for sub-path hosting such as GitHub project pages.
• Minimalists customizing branding: edit src/config.ts for site name, description, TOC entries, and social icons.

What can you do with PlainBlog?

• Publish dated posts: create a single-level, lowercase kebab-case .md file with a non-empty title and a quoted YYYY-MM-DD date, starting the body at ##.
• Add standalone pages: create a src/pages/*.astro file and add its entry to the navigation array; Home is fixed in the breadcrumb.
• Attach post images: place images under src/assets/posts/<post-name>/ and reference them with a relative path; a missing relative image fails the build.
• Deploy with canonical URLs: set SITE_URL to an absolute HTTP(S) address at build time to output canonical links and absolute RSS/image URLs.

Pros and cons

• Pro: no server, database, or runtime environment variables needed.
• Pro: the TOC toggle works without JavaScript, and the theme falls back to the system setting.
• Pro: tests build HTML without a site URL and validate rules against real output using temporary project copies.
• Con: there is no /blog/ index page and no automatic redirect for it.
• Con: future-dated posts are not automatically hidden.
• Con: lint and check both just run Astro diagnostics — not a standalone ESLint.

FAQ

Does PlainBlog need a server or database?

No. PlainBlog is fully static: run pnpm build and publish dist/ to a static host. No server, database, or runtime environment variables are required.

How do I hide a post from PlainBlog?

Add draft: true to the post's frontmatter. Drafts are excluded from the homepage, body output, and the RSS feed. Posts without a draft field are public by default.

Does PlainBlog support hosting on a sub-path?

Yes. Set BASE_PATH=/your-sub-path without a trailing slash, and pages, static assets, canonical URLs, and feed addresses all carry the prefix. SITE_URL still contains only the source domain.

Is PlainBlog free to use?

Yes. PlainBlog is released under the MIT license, with copyright held by the repository author. The homepage social icons come from Simple Icons (CC0 1.0), and their brand marks belong to their respective owners.