ermaozi

ermaozi is an Astro static site theme for blogs, knowledge bases, and product documentation, installed through the npm package create-astro-theme-ermaozi and heavily customized from VuePress Theme Plume.

What is ermaozi?

ermaozi is an Astro static theme that turns Markdown files plus one site.config.mjs file into a deployable static site written to a dist/ directory. It handles three content types in a single project — blog posts, regular pages, and documentation — and ships bilingual Chinese and English routing with hreflang tags. The theme is maintained by ermaozi and published to npm, where npm create astro-theme-ermaozi resolves to the stable release of the generator package. It requires Node.js 22.12 or newer and works with npm, pnpm, or Yarn, with a live demo running at astro.ermao.net.

What makes ermaozi stand out?

• Three content types in one project — the frontmatter value type accepts post, doc, or page; doc pages automatically get grouped sidebars, previous/next links, and mobile documentation navigation.
• Bilingual routing — Chinese content lives in content/blog/category/ and English content in content/en/blog/category/; a translationOf field points English entries at the Chinese route and the theme emits hreflang tags.
• Pagefind full-text search — search ships built in, but the index is produced at build time only, so development mode has no index and search must be verified with npm run build followed by npm run preview.
• Styling and theme internals — the page names no CSS framework; presentation and global variables live in theme/styles/ (global variables, theme styles, and Plume compatibility styles) with UI components in theme/components/ and shared logic in theme/lib/.
• Sidebar control through frontmatter — group, order, and badge fields set documentation sidebar grouping, sorting, and badges, and permalink pins stable URLs while file paths otherwise generate routes with leading numeric prefixes such as 1. stripped.
• Markdown extensions — Shiki syntax highlighting with light and dark themes, code titles, line numbers, line highlighting, copy buttons, footnotes, callouts, task lists, highlighting syntax, file trees, code trees, steps, windows, table copying, collapsible panels, tabs, and Mermaid diagrams.
• Build-time content encryption — PBKDF2 plus AES-GCM encryption can protect whole pages or selected content, alongside QR codes and npm/GitHub status badges, plus click-to-preview images and YouTube, Bilibili, audio, video, and PDF embeds.
• SEO and machine-readable output — canonical URLs, Open Graph, JSON-LD, sitemaps, robots directives, and an llms.txt file are generated, and the theme supports light, dark, and system colour schemes with categories, tags, archives, and client-side pagination.
• Optional comments and interactions — Giscus comments and a self-hosted interaction API can be enabled, but comments, view counts, likes, and popular posts are disabled by default and require configured service URLs in site.config.mjs.

Who should use ermaozi?

• Bilingual bloggers — writers publishing the same article in Simplified Chinese and English, using the content directory split plus translationOf and hreflang output to keep both routes connected.
• Documentation maintainers — teams that want Markdown docs with automatic grouped sidebars, ordering and badge frontmatter, mobile navigation, and Markdown source export.
• Developers who prefer static hosting — anyone deploying to GitHub Pages, GitLab Pages, Netlify, Vercel, Firebase Hosting, or custom hosting, using the wizard-generated config and the shared dist/ output.
• Theme contributors and forkers — developers working in theme/components/, theme/lib/, and theme/scripts/audit.mjs, since the theme directory is shared between the generator template and regular sites.

What can you do with ermaozi?

• Bloggers: replace the sample posts in content/ with Markdown files, set tags and createTime in frontmatter, and get categories, tag pages, archives, and client-side pagination without touching theme code.
• Product teams: put user guides in content/docs/ and content/en/docs/, control sidebar grouping with group, order, and badge, and keep day-to-day edits limited to site.config.mjs and Markdown so theme updates stay easy.
• Privacy-minded publishers: encrypt a whole page or selected passages at build time with PBKDF2 and AES-GCM before shipping the static output.
• Site operators: run the pre-release script set — check, build, test, test:visual, audit, and validate — to catch configuration, SEO, privacy, unsafe markup, and responsive layout problems before deploying.

How does ermaozi work?

1. Run npm create astro-theme-ermaozi my-site; an interactive wizard asks for Simplified Chinese or English as the root language and whether to show the language switcher. For automated setup, append the flags -- --yes --lang=en-US --multilingual.
2. Edit site.config.mjs for domain, site name, author, navigation, and optional services, replace public/img/logo.svg, and swap the sample content for your own Markdown.
3. Run the validate script, then build with npm run build and check the output with npm run preview; npm run deploy produces a deployable dist/ without uploading it, and pnpm users need pnpm run deploy to avoid a conflict with pnpm's built-in deploy command.

Pricing

ermaozi is free and open source: the project code is released under the MIT License, and the bundled VuePress Theme Plume compatibility styles keep their own preserved MIT license in theme/styles/vendor/LICENSE. The code license does not automatically cover articles, images, or third-party materials you add to a site.

Alternatives

• Astro Starlight — Astro's official documentation theme, aimed at docs rather than a combined blog and docs site.
• VuePress Theme Plume — the VuePress theme ermaozi is customized from and whose compatibility styles it still vendors.

FAQ

Is ermaozi free to use?

Yes. Project code is licensed under the MIT License, and the Plume compatibility styles in theme/styles/vendor/ keep their original MIT license. The code license does not automatically cover the articles, images, or third-party materials you add to your own site.

What are the system requirements for ermaozi?

ermaozi needs Node.js 22.12 or newer plus npm, pnpm, or Yarn. The dev script starts the Astro development server with hot reloading, and dev:fast remains available as a legacy alias for it.

Does Pagefind search work during development?

No. Development mode does not generate a Pagefind index, so search returns nothing until you run a full build. Verify search and the production output by running the build command followed by the preview command.

Is the 0.2 series stable?

No. The 0.2 series is still in beta: features and configuration are not yet fully stable and future releases may introduce breaking changes, so pin your version during the beta period and read the release notes before upgrading.

Can ermaozi run without any backend?

Yes for static content, since comments, view counts, likes, and popular posts are disabled by default and a purely static deployment needs no server. Enabling those features requires configured service URLs, and Algolia, Waline, Twikoo, and Artalk still need connections to real services. Static content encryption is not a substitute for server-side access control, so passwords and genuinely confidential content should not be committed to a public repository.