Pudding

Pudding is a static Markdown blog theme built with Astro 7 and Svelte 5, designed as a personal blog starter that ships working light/dark themes, search, backlinks, and RSS from a single Markdown source folder. It is an open-source, MIT-licensed project (repository huamurui/pudding) that publishes to any static host, including GitHub Pages through an included workflow.

What is Pudding?

Pudding is a Markdown blog theme: you add .md files under src/posts/ and the theme compiles them into a static blog with directory listing pages, tag pages, RSS, a sitemap, and structured metadata. It runs on Astro 7 with Svelte 5 components, requires Node.js 22.12.0 or newer and pnpm 12.8.1, and builds its output into dist/ via pnpm build. MDX is not configured — only plain Markdown is supported.

What makes Pudding stand out?

• Astro 7 + Svelte 5 stack — Markdown posts are rendered with Expressive Code for syntax highlighting, editor/terminal frames, copy buttons, titles, and line/text markers.
• Light and dark themes with responsive post lists, a timeline view, directory navigation, and an interface locale toggle between en-US and zh-CN.
• Hover previews and backlinks — published article links get hover previews, and pnpm generate creates .cache/backlinks.json from the Markdown links between published posts.
• Math rendering via remark-math and KaTeX, with inline $...$ and block math supported.
• Spoilers and link cards — inline ||text|| blur and |||text||| blackout spoilers, plus metadata-fetching link cards for standalone URLs cached in .cache/link-previews.json.
• Optional comments through giscus, disabled by default and configured in siteConfig.giscus.
• Auto-generated RSS, sitemap, and robots at /rss.xml, /sitemap.xml, and /robots.txt under the configured base path.
• Base-aware URL helpers (buildUrl, getPostUrl, getTagUrl) in src/utils/helpers.ts for project-page hosting under a path prefix.

What can you do with Pudding?

• Technical bloggers: write posts in Markdown with code frames, KaTeX math, and custom front matter fields like pinned, draft, slug, updated, and image banners.
• GitHub Pages publishers: set site and base in src/config/site.config.ts and let the included workflow in .github/workflows/ run lint, type checks, tests, and deployment to main.
• Documentation-style writers: rely on nested directories — src/posts/tech/my-post.md becomes tech/my-post — with listing pages generated for every containing folder and directory index.md representing its own folder.

Who is it for?

• Developers who want a Markdown-first blog without a CMS or database.
• Writers hosting under a subpath such as /pudding/, who need base-aware URLs and tag URLs.
• Authors who want interactivity in posts, since full articles allow trusted raw HTML and scripts with data-astro-rerun lifecycle hooks.

How does Pudding work?

Clone the repository, run pnpm install --frozen-lockfile, then pnpm dev and open http://localhost:4321/pudding/. Edit src/config/site.config.ts for site name, description, author, social links, colors, locale, and comments, then replace the sample posts. Run pnpm generate and restart the dev server after changing article links to refresh backlinks.

FAQ

Is Pudding free to use?

Pudding is released under the MIT license, so you can use, modify, and redistribute it. Attribution is not contractually required by MIT beyond keeping the license notice.

Does Pudding support comments?

Comments are disabled by default. To enable them, create a public GitHub repository with Discussions, install the giscus app, generate repository and category IDs at giscus.app, and set enabled: true in the giscus config.

Can Pudding render code with line numbers?

No. Line numbers and collapsible code sections require additional Expressive Code plugins and are not enabled in this template.

What Node.js version does Pudding need?

Pudding requires Node.js 22.12.0 or newer, as pinned in the repository's .nvmrc, along with pnpm 12.8.1 set in packageManager.