# astro-theme-pure is an Astro blog theme that also publishes a component package > astro-theme-pure is an Apache-2.0 Astro theme for blogs and documentation sites, with full site search through pagefind, RSS and sitemap output, a table of contents and dynamic Open Graph images. Its components are also published separately as the astro-pure npm package, and the whole project is built around Bun rather than npm. **cworld1/astro-theme-pure** — ⭐ A simple, fast and powerful blog & document theme built by Astro - Repository: https://github.com/cworld1/astro-theme-pure - Website: https://astro-pure.js.org - Stars: 1,111 · Forks: 278 - Language: Astro - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/cworld1-astro-theme-pure ## A theme that publishes its components as a package astro-theme-pure describes itself as a simple, fast blog and document theme built by Astro, and the feature list is short enough to read in one pass. Fast and high performance, a simple and clean design, responsive design, full-site search built with pagefind, a sitemap and RSS feed, SEO-friendly output, a table of contents, dynamic open graph generation for posts, and a mediumzoom lightbox for images. The distinctive part is the Package section and the Components section. The theme includes a lot of components which can not only be used in the theme, but also in other astro projects. The basic ones are named in the README: Aside, Tabs, Timeline, Steps, Spoiler. The advanced ones are GithubCard, LinkPreview, Quote, QRCode. Those are published as the astro-pure npm package, and the package.json pins it as a dependency at 1.4.9 alongside the theme version of 4.1.6, so the two release lines move independently. The README adds a condition for using the components outside the theme, which is that UnoCSS is required, and points to the package README for details. That arrangement matters more than it first appears. A theme that keeps its components locked inside its own templates is useful only to people who adopt the whole theme. A theme whose components are a separate package with its own version is usable as a component library, and the repository layout reflects that with a packages/ directory alongside src/ and preset/. The theme itself is aimed at two content shapes. The documentation site at astro-pure.js.org/docs exists alongside the demo blog, and the thanks section credits Astro Cactus, Astro Resume and Starlight, which are the reference points in the Astro theme ecosystem. ## The build runs three checks before astro build The package.json scripts show a project that treats verification as part of the build rather than as a separate step. ```json "build": "astro-pure check && astro check && astro build", "dev": "astro dev", "dev:check": "astro check --watch & astro dev", "check": "astro check", "sync": "astro sync", "pure": "astro-pure", ``` The build script is astro-pure check, then astro check, then astro build. The first of those is the package's own check, so the theme validates itself through the package it publishes. The second is the Astro type and template check, which is what catches a malformed.astro file or a TypeScript error. The result is that a broken build fails before it produces output, which is a good default for a theme whose users are non-experts copying a template. The dev:check script runs astro check in watch mode alongside astro dev, so type errors surface while you are editing rather than at build time. There are also separate lint and format scripts, with the lint script scoped to src and targeting js, ts, jsx, tsx and astro files, and the format script using Prettier across the same set plus md and mdx. The Prettier setup uses the sort-imports plugin from @ianvs, and the ESLint setup uses eslint-plugin-astro with a flat config file. One script stands out because it is not a normal theme script. There is a cache:avatars script that runs tsx preset/scripts/cacheAvatars.ts. Avatars are fetched at build time and cached, which is the mechanism behind the avatar rendering in a blog listing without a runtime request to a third party image host. There is also a convenience script named yijiansilian, which chains lint, sync, check and format into one command. The name is a Chinese internet phrase for running four steps in one go, and it is a small sign of where the maintainer and much of the audience are. The repository ships a Chinese README at README-zh-CN.md. ## Site configuration lives in one TypeScript file The getting started instructions are short, and the customisation step is a single file. After cloning the repository and entering the directory, you edit src/site.config.ts to customise the site. ```shell git clone https://github.com/cworld1/astro-theme-pure.git cd astro-theme-pure ``` A TypeScript configuration file rather than a JSON one is the notable choice, because it means the site configuration is type checked against the shape the theme expects. The astro.config.ts file at the root is the Astro configuration, and the README warns that depending on the deployment platform you choose you may need to modify it, which is the usual Astro caveat around adapters and output modes. The runtime requirements are stated with a warning attached. Astro 6.0 and later requires Node.js 22.12.0 or newer, and odd-numbered Node.js versions such as 23 are not supported by Astro. The project dependencies confirm the Astro 6 line, with astro at 6.4.8 and the @astrojs/compiler-rs at ^0.1.10. For the environment you can pick Bun or Node.js, and the README is explicit that Bun is the first choice in every command it gives. Installing dependencies is bun install, starting the server is bun dev, and the dev server runs at localhost:4321 by default. ```shell bun install bun dev ``` The same script names work with the other package managers, and the README lists the alternatives explicitly. ```shell pnpm dev yarn run dev npm run dev ``` A notable detail is the lockfile. The repository has bun.lock and no package-lock.json, and the Docker build uses bun install --frozen-lockfile. So while the commands accept npm or pnpm, the reproducible install is the Bun one, and a team whose CI only installs with npm will not get a frozen dependency set. ## A CLI for writing articles, and a compose file built around profiles Creating a post is a command, not a file copy. ```shell bun pure new ``` The pure script maps to the astro-pure binary, so the theme's own CLI is what scaffolds an article. The same binary provides the check command the build depends on, so a user who installs the package gets both. The Docker workflow is unusually carefully organised, and the comments in compose.yml explain the design before the YAML begins. The services are profile-based so you can choose the workflow you need, and there are four named workflows. ```shell docker compose --profile build up --build docker compose --profile preview up --build docker compose --profile dev up --build docker compose --profile new run --rm new ``` The build workflow builds the site and exports the generated dist/ to the host. The preview workflow runs the build service first and starts the Astro preview server only after the build completes successfully, which the compose file enforces with a service_completed_successfully condition on the dependency. The dev workflow mounts the repository into the container so source changes are reflected immediately without rebuilding the image each time. The new workflow mounts src/ and runs astro-pure new without leaving a long-running container behind, and the --rm flag in the example reflects that. The Dockerfile is a Bun image with the fontconfig package installed, which is the dependency the image processing needs, the lockfile installed with --frozen-lockfile for a reproducible dependency set, the repository copied in, ASTRO_TELEMETRY_DISABLED set, and port 4321 exposed. The build service then copies the built dist/ out to the host with a find and delete followed by a copy, so the export step is explicit about removing stale files rather than merging over them. ## The build script installs more than you might expect The dependency list is where a theme reveals what it actually does, and this one is heavier than a minimal blog theme. The Astro side is conventional: @astrojs/check at 0.9.9 for the type checking, @astrojs/rss at 4.0.18 for the feed, and @astrojs/vercel at 10.0.6 for the Vercel adapter, which means the project can output a server rendered build rather than purely static pages if you want that. The rendering extras are more interesting. katex at ^0.16.47 with rehype-katex at ^7.0.1 and remark-math at ^6.0.0 is a full mathematical typesetting pipeline, so LaTeX in Markdown renders to typeset equations. sharp at ^0.34.5 is the image processing library, which is what the dynamic open graph image generation and any image optimisation run on. The @waline/client at ^3.15.2 is a comment system client, so comments are supported through Waline rather than through a self-hosted backend in this project. Search is not in the dependency list, and that is consistent with how the feature is described. Full-site search is built with pagefind, which is a separate static search indexer that runs over the built output, so the index is generated after the site is built and no server is involved. That is why the search works on a static host with no backend, and it is also why the search index has to be rebuilt every time the content changes. UnoCSS is required for the components to work outside the theme, and the configuration lives in uno.config.ts at the root, with the preset/ directory holding the theme's own preset and the cacheAvatars script. ## What the theme still has not finished The README carries a note about known issues, and it is worth reading before you commit. Header and customize options is still under development, with template exposed still. In other words, the header and the customisation surface are incomplete, and some of that configuration is still exposed as a template rather than as a finished options system. For a theme whose main selling point is that you edit one configuration file, that is a real gap rather than a cosmetic one. The second limitation is the project shape. This is a theme repository with a packages/ directory and a preset/ directory, which means it is a monorepo. The published astro-pure package and the theme itself are versioned separately, and the theme pins the package at a specific version. When you copy the template, you inherit that pin, and you get theme updates only by taking the whole repository again, because there is no theme release that upgrades only the component package. The third limitation is the toolchain. Astro 6 requires Node.js 22.12.0 or newer, and the lockfile is a bun.lock, so a team on an older Node, or one that has standardised on npm or pnpm, will hit friction at the install step even though the README lists those alternatives. The Docker path sidesteps this since the image pins the runtime for you. The fourth limitation is the platform surface. The theme ships a Vercel adapter as a dependency and the deployment buttons target Vercel and Netlify, and the README points at the official Astro deployment guide for anything else. A deployment to an unusual host will need the astro.config.ts adjusted, and the README does not enumerate the platforms that work without changes. The project itself is in good health by the stated facts. The tags are v4.1.3 on 2026-03-05, v4.1.4 on 2026-04-06 and v4.1.6 on 2026-08-30, and the last push was on 2026-09-26, so the maintenance is continuous rather than abandoned. The licence is Apache 2.0 with a LICENSE file at the root, and there is a CODE_OF_CONDUCT.md. ## Conclusion astro-theme-pure fits a writer who wants a static blog with real search, a table of contents and a documentation structure without assembling an Astro integration list by hand, and it fits a developer building an Astro site of their own who wants the Aside, Tabs, Timeline, Steps and Spoiler components without copying them. It does not fit a team that needs a server rendered application, and it does not fit a team whose pipeline is built around npm, since the documented workflow assumes Bun or one of the other package managers it lists and the lockfile is a bun.lock. Before adopting it, edit src/site.config.ts as the README instructs, note the known issue that the header and customize options are still under development, and pin the release, since the latest tag is v4.1.6 from 2026-08-30 and the last push was on 2026-09-26. ## FAQ ### How do I run astro-theme-pure locally? Clone the repository, edit src/site.config.ts to customise the site, install dependencies with bun install, and start the development server with bun dev. The dev server runs at http://localhost:4321 by default, and the same script names work with pnpm dev, yarn run dev or npm run dev. ### How do I create a new article in astro-theme-pure? Run the pure command, which maps to the astro-pure binary: bun pure new. The same binary is used by the build script, where astro-pure check runs before astro check and astro build. There is also a Docker profile called new that runs astro-pure new with src/ mounted. ### What are the Node.js requirements for astro-theme-pure? Astro 6.0 and later requires Node.js 22.12.0 or newer, and odd-numbered Node.js versions such as 23 are not supported by Astro. The project dependencies pin astro at 6.4.8, and the lockfile is a bun.lock, so bun install --frozen-lockfile is the reproducible install path. ### Can I use the astro-theme-pure components in another Astro project? Yes. The components are published as the astro-pure npm package, and the README states they can be used in other astro projects, not only in the theme. UnoCSS is required for that use, and details are in the package README. ### How does astro-theme-pure implement full-site search? Search is built with pagefind, a static search indexer that runs over the built output, so no server is required. The theme also ships a sitemap and RSS feed, a table of contents, dynamic open graph image generation for posts, and a mediumzoom lightbox for images. ## Sources - [cworld1/astro-theme-pure on GitHub](https://github.com/cworld1/astro-theme-pure) - [License: Apache-2.0](https://github.com/cworld1/astro-theme-pure/blob/main/LICENSE) - [Project website](https://astro-pure.js.org) - [README](https://github.com/cworld1/astro-theme-pure/blob/main/README.md) - [Releases](https://github.com/cworld1/astro-theme-pure/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cworld1-astro-theme-pure