Astro Theme Pure

Astro Theme Pure is a simple, fast, and powerful blog and documentation theme built with Astro. It features a clean, responsive design optimized for high performance and SEO.

Key Features:

• Performance: Fast and high-performance with high Lighthouse scores.
• Search: Full-site search powered by pagefind.
• Navigation & SEO: Includes Sitemap, RSS feed, Table of Contents (TOC), and SEO-friendly structures.
• Media: Dynamic Open Graph generation for posts and Mediumzoom lightbox for images.

Components: The theme provides a variety of components that can be used within the theme or imported into other Astro projects. Note that using these components in external Astro projects requires UnoCSS.

• Basic components: Aside, Tabs, Timeline, Steps, Spoiler, etc.
• Advanced components: GithubCard, LinkPreview, Quote, QRCode, etc.

The following directory structure defines the theme's organization:

• public: Static resources copied to the root.
• src/assets: Static resources (images, etc.).
• src/components: UI components (e.g., Card, Collapse, Spoiler).
• src/layouts: Basic site layouts.
• src/pages: Route definitions (e.g., 404, about, blog, docs, index).
• src/plugins: Extended theme plugins.
• src/types: TypeScript definitions.
• src/utils: Utility functions.
• src/site.config.ts: Main theme configuration file.
• astro.config.ts: Astro configuration.
• eslint.config.mjs: ESLint configuration.
• prettier.config.mjs: Prettier configuration.
• uno.config.ts: UnoCSS configuration.
• tsconfig.json: TypeScript configuration.
• package.json: Package information.

Astro uses the file structure within the src/pages/ directory to generate website routes. Every file in this directory automatically becomes a page.

Route Mapping Examples

• src/pages/index.astro $\rightarrow$ /
• src/pages/about.astro $\rightarrow$ /about
• src/pages/about/index.astro $\rightarrow$ /about
• src/pages/about/me.astro $\rightarrow$ /about/me
• src/pages/posts/1.md $\rightarrow$ /posts/1

Toast notifications are triggered by dispatching a custom browser event named 'toast'. You can trigger this from any component (like a Button) using document.dispatchEvent.

Event Detail Shape:

• message: The text content of the toast.
• time: Duration in milliseconds.

// Example: Triggering a toast via a button click
<Button
  title='Click Me'
  onClick={`document.dispatchEvent(
    new CustomEvent('toast', {
      detail: {
        message: 'Hello from toast!',
        time: 5000
      }
    })
  )`}
/>

Updating the theme can be complex due to frequent updates and breaking changes. Depending on how you initialized your project, use one of the following methods:

Rebase

If you created your project by forking the theme repository, you can simply rebase your fork onto the latest version of the theme repository.

Manual Merge

If your git histories have diverged, you must merge the theme repository into your project manually. For Windows users, WinMerge is recommended. Use a filter list to manage which files to include/exclude during the diff process to avoid conflicts with your own content (like src/content/blog).

To use external web images for the heroImage property in your content, you must include inferSize: true in the configuration object. This allows the theme to correctly determine the image dimensions for layout purposes.

heroImage:
  { src: 'https://img.tukuppt.com/ad_preview/00/15/09/5e715a320b68e.jpg!/fw/980', inferSize: true }

If you need to make fundamental, breaking changes to the theme's underlying logic, you can use 'Package Mode'. This involves linking a local version of the theme source code to your project using your package manager's linking command. This allows you to treat the theme as part of your own source code.

Warning: This method increases project complexity and makes future theme updates more difficult. Use it only when necessary.

Steps:

1. Ensure you have the original theme source code locally.
2. Use a package manager to link the local source to your project (e.g., npm link, pnpm link, or bun link).

# Example linking commands

# Using Bun
bun link

# Using NPM
npm link

# Using PNPM
pnpm link

You can render code blocks using the built-in Astro Code component or standard Markdown syntax.

In .astro files

Import Code from astro:components and use it as a component:

---
import { Code } from 'astro:components'
---

<Code lang='shell' code={`git log --oneline`} />

In .md and .mdx files

Use standard Markdown fenced code blocks:

```shell
git log --oneline