astro-theme-ink

astro-theme-ink is a fully static, paper-feel personal blog theme for Astro that pairs serif headings and quiet grays with a single accent hue for long-form writing.

What is astro-theme-ink?

astro-theme-ink is a personal blog theme built on Astro and UnoCSS that ships a complete static site, not just a visual layer over an existing blog. It takes Markdown posts in src/content/blog plus typed settings in src/site-config.ts and outputs a static dist directory you can serve from any static host. Its design is an independent implementation inspired by astro-theme-pure (Apache-2.0); the repository is MIT licensed.

What makes astro-theme-ink stand out?

• Astro + UnoCSS stack — content collection schema in src/content.config.ts, UnoCSS presets and typography in uno.config.ts, design tokens in src/assets/styles/tokens.css.
• Two switchable palettes — warm ink and cool fresh palettes can be switched independently, alongside light, dark and system themes applied before first paint.
• Build-time search — a small search index generated at build and queried in the browser, with no third-party search service.
• Markdown extras — KaTeX math, Mermaid diagrams (fetched only for posts containing a Mermaid fence), Shiki highlighting with line highlights/diffs, code titles, copy buttons and automatic folding after 15 lines.
• Reading aids — sticky desktop table of contents, mobile table of contents, reading progress, reading-time estimates and previous/next links.
• Blog structure — pagination, tags, yearly archives, RSS full text and sitemap, plus folder posts (a file at notes/index.md publishes at /blog/notes).
• Optional Waline integration — comments, per-post page views and a footer-wide visit counter configured as separate endpoints, with comments lazy-loaded near the viewport.
• SEO metadata — canonical URLs, Open Graph and Twitter metadata, and JSON-LD BlogPosting data.

Who is it for?

Long-form writers: authors who want serif headings, generous whitespace and a calm palette that keeps attention on prose rather than chrome.

Astro developers: developers who prefer typed configuration in a single site-config.ts file over a theme-specific config language, while keeping pages as normal Astro files.

Theme maintainers: people running a theme repo and a real blog repo separately, using the included theme:sync CLI or local visual panel (http://127.0.0.1:4175) to preview and apply updates while preserving posts and assets.

Use cases

• Personal blogs: publish Markdown posts with tags, archives, RSS and reading-time estimates without adding a search backend.
• Technical writing: embed KaTeX formulas, Mermaid flowcharts and Shiki-highlighted code blocks with copy buttons.
• Static deployment: build once and deploy dist to GitHub Pages, Vercel, Netlify or Cloudflare Pages, setting SITE_URL and BASE_PATH as needed.

How does it work?

Install with pnpm, run pnpm dev to serve on port 4321, then pnpm build runs diagnostics and produces the static site in dist. Node.js 22.12.0 or newer is required, and the repository is pinned to pnpm 10.20.0. The theme:sync command previews changes first; add --apply to write them.

FAQ

Is astro-theme-ink free?

Yes. The repository is released under the MIT License, though the Shiki code-block pipeline is ported from astro-theme-pure under Apache-2.0. Some features are optional: comments and counters require pointing endpoints at a Waline server, and they are disabled when the endpoint is left empty.

How many categories or tags does it support?

Tags are defined per post in Markdown frontmatter and aggregated into tag pages and a tag cloud. The home page displays at most 5 recent posts by default; set home.recentPosts to 0 to hide that section.

Can comments and page views be configured separately?

Yes. Comment and pageview settings are deliberately separate Waline endpoints. Point both at the same server to use both, or leave either empty to disable that feature.