Stark's

Customize Theme

import { Aside, Spoiler, Steps } from 'astro-pure/user'

You Should Know

This theme is designed to "NPM Package" for the following reasons:

The code written in package may be frequently changed. If users change them at will, it will significantly increase the cost of subsequent updates and merging (various conflicts for code)
Roll back and switch between different versions easily, to maintain user stability
Reduce system coupling & increase reuse ability
The NPM Package mode can be used as a "Astro plugin" to append additional operations that enhance user experience during the build phase
Support some built-in commands like new, check, info, etc.
Use as component library for other Astro projects (yes, this project can be broken down into the UI component library): Package details.

Before you customize it, you should check site.config.ts to make sure there is no option that satisfy your need.

Swizzling

This theme chose an elegant method called 'Swizzling', which is inspired by the design from Docusaurus.

Use an IDE to quickly view the source code corresponding to a certain component (In VSCode, it is to click the component with Ctrl).
Copy to src/components/<your prefer directory>.
After modification, change the corresponding reference to your own file path.

Let's make an example to customize the Footer component:

---
import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic'
import type { SiteMeta } from 'astro-pure/types'
// ...
---

Find it in theme source code:

export { default as Footer } from './Footer.astro'
export { default as Header } from './Header.astro'
export { default as ThemeProvider } from './ThemeProvider.astro'

Then you get the Footer component source code at node_modules/astro-theme-pure/components/basic/Footer.astro.

Copy the Footer.astro file to your project:

cp node_modules/astro-theme-pure/components/basic/Footer.astro src/components/custom/Footer.astro

Solve the sub-dependencies problem:

---
import config from 'virtual:config'

import { Icon } from '../user' // [!code --]
import { Icon } from 'astro-pure/user' // [!code ++]
// ...
---

Change the reference in BaseLayout.astro:

 ---
 import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic' // [!code --]
 import { Header, ThemeProvider } from 'astro-pure/components/basic' // [!code ++]
 import { Footer } from '@/components/custom/Footer.astro' // [!code ++]
 // ...
 ---

Then you've done a "localization" of the component.

Package Mode

If you want to make some breaking changes or just make a test, this method may follow "what you see is what you get".

Making sure you have the original theme code (./packages/pure). If yo've deleted it, download it from the Releases.
Link it to your project using your package manager (Example: Bun, NPM, PNPM).
Then change the theme code as it is a part of your code!

About

import { GithubCard } from 'astro-pure/advanced' import { Button, Aside } from 'astro-pure/user'

The astro-theme-pure theme is open source under the Apache 2.0 license. Please abide by this license for any further development.

Contribute Code

A big thank you to everyone who has contributed to the astro-theme-pure. The open-source community is amazing because of you.

All changes for astro-pure package should enable Customize Theme#Package Mode first. PR test will also run in that mode. This requests you test your changes locally using bun run yijiansilian command first.

And for contributing docs, you can simply click the "Edit on GitHub" link at the bottom of each doc page to change the docs content.

Sponsorship

We would like to express our gratitude to all the sponsors.

Open Source References

This theme uses/references/derives content from the following projects:

Framework:

astro
unocss

Content rendering:

Integrations:

Code block: Shiki
Image lightbox: Medium Zoom
Comment: Waline
Search: Pagefind

Others:

Compress: playform/compress
Image compress: sharp

Optimize Your Site

import { Aside } from 'astro-pure/user'

Integrations

This theme has integrated with:

sharp: image optimization
@playform/compress: HTML, CSS, JS, images minify (has problems for a while; see GitHub Issue #55)

CDN

Some light-weighted libraries are using js static links. You can configure CDN links to improve your site performance.

export const theme: ThemeUserConfig = {
  // ...
  npmCDN: 'https://cdn.jsdelivr.net/npm'
  // Recommend:
  // - https://cdn.jsdelivr.net/npm
  // - https://cdn.smartcis.cn/npm
  // - https://unkpg.com
  // - https://cdn.cbd.int
}

Coding

It is a good way to use "Typescript-like" syntax comment in your .astro files. It can ensure your comment will not be rendered in the final production HTML file.

---
// Here is a safe place to put your comment
import { AstroComponent } from '@/components'
---

<div>
  <!-- This is a bad comment style which will still in the production -->
  {/* This is a better comment style */}
  <AstroComponent>Hello, Astro!</AstroComponent>
</div>

Pictures

Use optimized component

Display optimized images with the <Image /> component: Use the built-in <Image /> Astro component to display optimized versions of:

your local images located within the src/ folder
configured remote images from authorized sources

<Image /> can transform a local or authorized remote image’s dimensions, file type, and quality for control over your displayed image. The resulting <img> tag includes alt, loading, and decoding attributes and infers image dimensions to avoid Cumulative Layout Shift (CLS).

You can use loading="lazy" to enable lazy loading for images.

---
// import the Image component and the image
import { Image } from 'astro:assets'

import myImage from '../assets/my_image.png' // Image is 1600x900
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt='A description of my image.' />

<!-- Output -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

Using this, it will transform your images to a WebP format. .md and .mdx files are enabled default.

Change Image Size

Although this theme has integrated with some known image optimization plugins, you way still need to optimize your images for some key pages like homepage.

A easy way is using online tools like TinyPNG to manually compress your images.

Adapt External Images

If you are using external images, excepting the lazy-load tag, you can also add Astro pre-optimize service for it. This will change external images to local optimized ones.

export default defineConfig({
  // ...
  image: {
    // ...
    domains: ['<specific site domain>'] // [!code ++]
  }
})

File Size Analysis

Install npm package rollup-plugin-visualizer. Then append the following code to your astro.config.ts:

export default defineConfig({
  // ...
  vite: {
    plugins: [
      visualizer({
        emitFile: true,
        filename: 'stats.html'
      })
    ]
  }
})

Build your project and open the generated stats.html file to analyze your bundle size. After that finish, you can remove the above code and package to keep your project clean.

Update Theme

import { Aside } from 'astro-pure/user'

Breaking Changes

v4.1.2

Move src/pages/terms/list.astro to src/pages/terms/index.astro.

v4.1.1

Move shiki custom transformers to src/plugins/shiki-custom-transformers.ts.
Move shiki official transformers to src/plugins/shiki-offical/transformers.ts.
Improve config file with new order and comments. This will affect both src/site.config.ts and astro.config.ts (09dc44d).
Add collapse code function with default (7281077, 22b8847)
Refactor palette and border radius styles. If you use color like --primary-foreground, update it to --card.

v4.1.0

Moved custom css file global.css to src/assets/styles/global.css.
Changed the font loader to Astro built-in font loader.

v4.0.9

Support caching links avatar (Arthals)

v4.0.8

No breaking changes.

v4.0.7

Changed the Button component to use variant prop instead of style prop. This can help you add custom styles without conflicts. You should change your code like this:
```
<Button title='My Button' style='primary' /> // [!code --]
<Button title='My Button' variant='primary' /> // [!code ++]
```

Changed the ExternalLinks configuration in src/site.config.ts. You should change your config like this:

export const theme: ThemeUserConfig = {
  content: {
    externalLinksContent: ' ↗', // [!code --]
    /** External links configuration */ // [!code ++]
    externalLinks: { // [!code ++]
      content: ' ↗', // [!code ++]
      /** Properties for the external links element */ // [!code ++]
      properties: { // [!code ++]
        style: 'user-select:none' // [!code ++]
      } // [!code ++]
    }, // [!code ++]
    /** Blog page size for pagination (optional) */
    blogPageSize: 8,
    externalLinkArrow: true // show external link arrow // [!code --]
  }
}

Changed the Waline files out of package! Checkout Commit 5119694 to see how to change your existing pages & layouts. Don't forget to copy files at src/components/waline to your project.

v4.0.6

Changed the project card var name to projects instead of project.

v4.0.5

Changed the UnoCSS preset from Wind3 to Mini. Some features are removed, like gradient, animation, container, etc.

v4.0.3

Changed footer registration config to links. This will give you more flexibility to add more links or other information:

export const theme: ThemeUserConfig = {
  footer: {
    links: [ // [!code highlight:12]
      {
        title: 'Moe ICP 114514',
        link: 'https://icp.gov.moe/?keyword=114514',
        style: 'text-sm' // Uno/TW CSS class
      },
      {
        title: 'Site Policy',
        link: '/terms/list',
        pos: 2 // position set to 2 will be appended to copyright line
      }
    ]
  }
}

v4.0.2-beta

Consider moving tool icons to a new path such as src/assets/tools/; this may help users know which ones are relevant to tools.

Changed links applyTip to a custom array style:

export const integ: IntegrationUserConfig = {
  links: {
    applyTip: [
      { name: 'Name', val: theme.title }, // [!code highlight:4]
      { name: 'Desc', val: theme.description || 'Null' },
      { name: 'Link', val: 'https://astro-pure.js.org/' },
      { name: 'Avatar', val: 'https://astro-pure.js.org/favicon/favicon.ico' }
      // You can also add more fields
    ]
  }
}

Add the env variable BUN_LINK_PKG. Set this to true to automatically refer to the package astro-pure in the path packages/pure instead of node_modules/astro-pure. This may help users develop the theme or change code for themselves (not recommended for production).
Changed the CSS framework to UnoCSS. This will affect unocss.config.ts and typography class name settings.

v4.0.1-beta

Changed svg deliver import to custom import svg element. This will affect using component for ToolSelection. You should change:

(Optional) Move icons to new path like src/assets/icons/

Then change using code (default at src/pages/about/index.astro)

<ToolSection
  tools={[
    {
      name: 'Arch Linux',
      description: 'Linux Distribution',
      href: 'https://archlinux.org/',
      iconPath: 'archlinux' // [!code --]
      icon: import('@/assets/icons/archlinux.svg?raw') // [!code ++]
    }
  ]},
/>

This changes import a new component Svg. See User Components #Svg Loader for usage.

v4.0.0-alpha

Move all components, types and utils that are reused to new npm packages astro-pure. Affected components are included in . Import method is also changed:
```
import { Button } from '@/components/user' // [!code --]
import { Button } from 'astro-pure/user' // [!code ++]
```

New format config file src/site.config.ts. There will be zod schema to validate the config file, and use of config will be changed to:

import { siteConfig } from '@/site-config' // [!code --]
import config from '@/site-config' // [!code ++]
// Or if you want to use the config that is after processed or transformed
import config from 'virtual:config' // [!code ++]

Built-in astro config supported. package astro-pure will automatically config some integrations like unocss/astro, @astrojs/mdx, @astrojs/sitemap, also with some rehypePlugins and remarkPlugins.
Changed search engine to pagefind, mainly because Astro v5 will not allow getting collection data directly from client (that is core working mode of Fuse.js search engine).
Changed some BaseHead tags config to src/site.config.ts.

v3.1.4

Move config siteConfig.content.typographyProse to integrationConfig.typography.class in src/site.config.ts.

Move advanced components to src/components/advanced. Affected components are included in Advanced Components. Import method is also changed:

import LinkPreview from '@/components/LinkPreview.astro' // [!code --]
import { LinkPreview } from 'astro-pure/advanced' // [!code ++]

<LinkPreview href='https://www.cloudflare.com/' />

Move Substats config to related page src/pages/about/index.astro.
Changed Github Card component to GithubCard in src/components/advanced. See Advanced Components #Github Card for usage.
Move Links Logbook to src/site.config.ts. See Friend Links #Basic Configurations.

v3.1.3

Move user components to src/components/user. Affected components are included in User Components. Import method is also changed:
```
import Button from '@/components/Button' // [!code --]
import { Button } from 'astro-pure/user' // [!code ++]
```
Replace remark-github-blockquote-alert plugin to component Aside. Check User Components #Aside to know how to migrate.

v3.1.2 (pre-release)

Move some configuration items like telegram, walineServerURL to new structure in src/site.config.ts.

v3.1.1

Move the internal parts in the src/utils to src/plugins.
Modify the configuration file astro.config.ts to astro.config.mjs.
Update ESLint to latest version and migrate configuration file .eslintrc.js to eslint.config.mjs.
Modify the prettier.config.js to prettier.config.mjs.

v3.1.0 (pre-release)

Changed common content markdown formatter coverImage to heroImage. You need to modify all your markdown files to replace coverImage with heroImage.

v3.0.9

A stable version.

Pending update...

Update Method

Rebase

If you create a new project using fork, you can just rebase the theme repository to the latest version.

Merge Manually

As the git histories are not the same, you might need to merge the theme repository into your project manually.

A practical way for Windows users is to use the tool WinMerge.

A filter list may be helpful:

## This is a directory/file filter template for WinMerge
name: Astro Theme Pure
desc: Diff for Blog v.s. Astro Theme Pure

## Select if filter is inclusive or exclusive
## Inclusive (loose) filter lets through all items not matching rules
## Exclusive filter lets through only items that match to rule
## include or exclude
def: include

## Filters for filenames begin with f:
## Filters for directories begin with d:
## To exclude some of the files that match the f: pattern, specify f!:
## To exclude some of the folders that match the d: pattern, specify d!:
## (Inline comments begin with " ##" and extend to the end of the line)

### Front-end files ###
d: \\\.git$
d: \\node_modules$

# Astro cache
d: \\\.vercel
d: \\\.astro

### Theme dev ###
d: ^\\packages$
d: ^\\preset$
d: ^\\test$
f: ^LICENSE$
f: ^README\.md$
f: ^README-zh-CN\.md$
f: ^CODE_OF_CONDUCT\.md$

# Project
f: ^bun\.lockb$
f: \.code-workspace$
f: ^ignore\.md$

### Astro theme pure ###
# Static
d: ^\\public\\favicon$
f: ^public\\links\.json$
f: ^public\\images\\social-card\.png$

# Assets
f: ^src\\assets\\avatar\.png$
d: ^\\src\\assets\\projects$
d: ^\\src\\assets\\tools$

# Content
d: ^\\src\\content\\blog$
d: ^\\src\\content\\docs$
d: ^\\src\\pages\\docs$
f: ^src\\pages\\terms\\.*\.md$

### Blog ###
# Your own files

Authoring Content

import { Aside } from 'astro-pure/user'

Astro helps you author and present your content. You can write a blog post directly in Astro using Markdown/MDX, or fetch your content from a headless CMS. Astro lets you build a site around your content: you can add a layout to your pages, create an index of posts, and set up an RSS feed to allow readers to subscribe.

Writing Content

In Astro, you can author your content in a variety of ways:

In Markdown files (.md or alternative extensions), designed to make it easy to write rich text content.
In MDX (.mdx) or Markdoc (.mdoc) files with an official integration, which can include components and dynamic expressions in your document.
Using a third-party content management system (CMS), then pulling that content into a .astro page.
Other options (less commonly used for content-heavy pages) include .astro files and .html files.

For this theme, .md and .mdx is supported by default.

Markdown Authoring

Markdown is a convenient syntax for writing rich text with basic formatting and common elements like headers, lists, and images. Astro has built-in support for Markdown files in your project.

Create and write a new .md file in your code editor or bring in an existing file written in your favorite Markdown editor. Some online Markdown editors like StackEdit and Dillinger will even allow you to edit and sync your work with your Astro repository stored on GitHub.

Let's give you example of writing Markdown content in Astro:

---
title: 'First Article' # (Required, max 60)
description: 'I like writing articles.' # (Required, 10 to 160)
publishDate: '2024-11-30 00:08:00' # (Required, Date)
tags:
  - Markdown # (Also can write format like next line)
heroImage: { src: './thumbnail.jpg', alt: 'an image targeting my article', color: '#B4C6DA' }
# thumbnail.jpg should be in the same folder as the article
draft: false # (set true will only show in development)
language: 'English' # (String as you like)
comment: true # (set false will disable comment, even if you've enabled it in site-config)
---

## This is a title

This is a paragraph.

If you have a lot of assets, you can create a folder for title like src/content/blog/first-article/ and put all your assets in there. Of course, your content should be renamed to index.md or index.mdx and also be contained in this folder.

If you want to use remote image for heroImage, please add inferSize: true or specified width and height to the object heroImage. Example:

heroImage:
  { src: 'https://img.tukuppt.com/ad_preview/00/15/09/5e715a320b68e.jpg!/fw/980', inferSize: true }
# Or specified width and height
heroImage:
  { src: 'https://img.tukuppt.com/ad_preview/00/15/09/5e715a320b68e.jpg!/fw/980', width: 980, height: 551 }

Too complex? Simple example just need these:

---
title: Simple Article
description: Just another simple article.
publishDate: 2024-07-26
---

I like writing simple articles.

MDX Authoring

This allows you to include UI elements such as a banner or an interactive carousel along with your text content.

Write and edit .mdx files directly in your code editor, alongside your project files. MDX files are a supported page file type in Astro, and may also be used as content collection entries.

For integrated components, checkout User Components and Advanced Components.

Connect a CMS

See Astro: Use a CMS with Astro

Pages

Astro uses file-based routing to generate your build URLs based on the file layout of your project src/pages/ directory.

Routes

.astro page components as well as Markdown and MDX Files (.md, .mdx) within the src/pages/ directory automatically become pages on your website. Each page’s route corresponds to its path and filename within the src/pages/ directory.

# Example: Static routes
src/pages/index.astro        -> mysite.com/
src/pages/about.astro        -> mysite.com/about
src/pages/about/index.astro  -> mysite.com/about
src/pages/about/me.astro     -> mysite.com/about/me
src/pages/posts/1.md         -> mysite.com/posts/1

There is no separate "routing config" to maintain in an Astro project! When you add a file to the src/pages/ directory, a new route is automatically created for you. In static builds, you can customize the file output format using the build.format configuration option.

Astro Pages

Astro pages use the .astro file extension and support the same features as Astro components.

---

---

<html lang='en'>
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

A page must produce a full HTML document. If not explicitly included, Astro will add the necessary <!DOCTYPE html> declaration and <head> content to any .astro component located within src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.

To avoid repeating the same HTML elements on every page, you can move common <head> and <body> elements into your own layout components. You can use as many or as few layout components as you'd like.

And in this theme, luckily you can use BaseLayout.astro as your layout component.

---
import PageLayout from '@/layouts/BaseLayout.astro' // [!code highlight]

const meta = {
  title: 'My Page',
  description: 'My fav page'
}
const highlightColor = '#44AEF6' // Optional
---

<PageLayout {meta} {highlightColor}>
  <!-- [!code highlight] -->
  <p>My page content, wrapped in a layout!</p>
</PageLayout>
<!-- [!code highlight] -->

Markdown/MDX Pages

While .astro pages have some flexible features and be friendly to inline / module scripts, .md and .mdx pages are more suitable for content-focused pages.

Astro also treats any Markdown (.md) files inside of src/pages/ as pages in your final website. If you have the MDX Integration installed, it also treats MDX (.mdx) files the same way.

Consider creating content collections instead of pages for directories of related Markdown files that share a similar structure, such as blog posts or product items.

Markdown files can use the special layout frontmatter property to specify a layout component that will wrap their Markdown content in a full <html>...</html> page document.

This theme supports a good layout for .md and .mdx files:

---
layout: '@/layouts/IndividualPage.astro'

title: 'Privacy Policy'
description: 'Effective date: 2024-11-26'
language: 'En' # optional
back: '/terms/list' # optional, default to '/'
heroImage: { src: './thumbnail.jpg' } # will used to social-image
---

## Privacy Policy 1

This is the first section of the privacy policy.

HTML Pages

Files with the .html file extension can be placed in the src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components.

Getting Started

import { Steps, Aside, Tabs, TabItem } from 'astro-pure/user'

Installation

Two way to install. "Template" way is lightweight and simple, but hard to update; while "Fork" way is easy to update but needs some skills for git.

Install Using Template

Install the theme

Execute the following command in the your user directory to install the theme:
```
[install]
registry = "<npm mirror site>"
```
For details about other PM mirror configs, you may need to see their official documents.

By default, this command will use the template repository’s main branch. To use a different branch name, pass it as part of the --template argument: cworld1/astro-theme-pure#<branch>.
Answer the questions and follow the instructions of the CLI wizard.
VOILA!

You can now start the Astro dev server and see a live preview of your project while you make it your own!

Install Using Fork

You only need to click fork button at theme repository to create your project; then clone the forked repository to your local machine.

git clone https://github.com/<your-username>/astro-theme-pure.git

Then, you can start the Astro dev server and see a live preview of your project while you make it your own!

Start the Dev Server

Go to your project directory:

cd ./<your-project>

Next, please read the configuration notes first and continue configuring the theme.

Migrate to Astro

See Astro: Migrate an existing project to Astro.

Theme File Structure

The theme file structure is as follows:

public: Static resources that will be copied to the root directory
src:
- assets: Static resources
- components: Components used in the theme, also include user-like components, like Card, Collapse, Spoiler, etc.
- layouts: Basic site layouts
- pages: Pages like 404, about, blog, docs, index, etc.
- plugins: Extended plugins used in the theme
- types: Typescript type definitions
- utils: Utilities
- site.config.ts: Theme configuration file
astro.config.ts: Astro configuration file
eslint.config.mjs: ESLint configuration file
prettier.config.mjs: Prettier configuration file
uno.config.ts: UnoCSS configuration file
tsconfig.json: Typescript configuration file
package.json: Package information

Simple Setup

Remove docs files

Remove the src/pages/docs directory
Remove the menu declaration in src/site.config.ts:

export const theme: ThemeUserConfig = {
   // ...
   /** Configure the header of your site. */
   header: {
      menu: [
         { title: 'Blog', link: '/blog' },
         { title: 'Docs', link: '/docs' }, // [!code --]
         // ...
      ],
   },
}

Remove the Content Collection for docs in src/content.config.ts:

const docs = defineCollection({ // [!code --]
loader: glob({ base: './src/content/docs', pattern: '**/*.{md,mdx}' }), // [!code --]
schema: ({ image }) => // [!code --]
   z.object({ // [!code --]
      ... // [!code --]
   }) // [!code --]
}) // [!code --]
export const collections = { blog, docs } // [!code --]
export const collections = { blog } // [!code ++]

Remove packages directory (this will be imported by our NPM package).

And remember to change the workspaces field in package.json:

{
  "name": "astro-theme-pure",
  "workspaces": [ // [!code --]
    "packages/*" // [!code --]
  ], // [!code --]
  // ...
}

Change the site favicon.

Replace the public/favicon/* files with your own favicon.
Replace your avatar image.

Replace the src/assets/avatar.png file with your own avatar image.

Configure the site

You can configure your project inside the src/site.config.ts configuration file:

export const theme: ThemeUserConfig = {
   author: 'CWorld',
   title: 'Astro Theme Pure',
   site: 'https://astro-pure.js.org',
   description: 'Stay hungry, stay foolish',
   // ...
}

export const integ: IntegrationUserConfig = { /* ... */ }
// ...

Typescript Syntax

The configuration file site.config.ts uses Typescript syntax. If you are not familiar with TS syntax, please read about it here first.

Advanced Components

import { MdxRepl } from 'astro-pure/user'

Web Content Render

Quote

The Quote component is a simple component that displays a random quote.

Config:

export const integ: IntegrationUserConfig = {
  // Add a random quote to the footer (default on homepage footer)
  quote: {
    // https://github.com/lukePeavey/quotable
    server: 'https://api.quotable.io/quotes/random?maxLength=60', // [!code highlight:2]
    target: `(data) => data[0].content || 'Error'`
  }
}

Quotable is a open-source API that provides random English quotes.

For Chinese quotes, you can use Hitokoto.

export const integ: IntegrationUserConfig = {
  quote: {
    // https://developer.hitokoto.cn/sentence/#%E8%AF%B7%E6%B1%82%E5%9C%B0%E5%9D%80
    server: 'https://v1.hitokoto.cn/?c=i', // [!code highlight:2]
    target: `(data) => data.hitokoto || 'Error'`
  }
}

GitHub Card

The GithubCard component is a simple component that displays a GitHub user card.

Link Preview

Preview any link inserted in the content.

Data Transformer

QRCode

// // default to render current page link

</Fragment>
</MdxRepl>

### Toast

<MdxRepl>
import { Button } from 'astro-pure/user'

<Button
  title='Click Me'
  onClick={`document.dispatchEvent(
    new CustomEvent('toast', {
      detail: {
        message: 'Hello from toast!',
        time: 5000
      }
    })
  )`} /> 
<Fragment slot='desc'>
```jsx
import { Button } from 'astro-pure/basic'

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

Medium Zoom

Try click the following image.

See Other Integrations#medium-zoom.

Deployment

import { Aside, Steps } from 'astro-pure/user'

Package Mode

This theme which >= v4.0.0 has integrated NPM package mode. Recommended way is remove local package file, and install the theme integration from NPM. If there's some reason you want to change the package content, you should link local package to your theme template. A bun method is integrated. You should:

Add environment variable BUN_LINK_PKG=true.
Run bun pure check to link the package automatically.

This method can also work on Deployment for other platforms like 'Vercel'. All you need is to add the environment variable to build options on your platform control settings. The build command astro-pure check && astro check && astro build will automatically link the package.

Deployment Mode

Astro had a very fantastic support for deployment. Check Deploy your Astro Site for more.

Vercel

This theme supports Vercel by default:

Push your code to your online Git repository (GitHub, GitLab, BitBucket).
Import your project into Vercel.
Vercel will automatically detect Astro and configure the right settings.
Your application is deployed! (e.g. astro.vercel.app)

And vercel also support static method:

import vercelServerless from '@astrojs/vercel/serverless' // [!code --]
import vercelStatic from '@astrojs/vercel/static'; // [!code ++]

export default defineConfig({
  //   ...
  adapter: vercelServerless() // [!code --]
  adapter: vercelStatic(), // [!code ++]
})

Node server

If you are deploying with Node.js locally, you need to install @astrojs/node first:

bun add '@astrojs/node'

Then follow the comments in astro.config.ts and modify like:

import node from '@astrojs/node' // [!code ++]
import vercelServerless from '@astrojs/vercel/serverless' // [!code --]

export default defineConfig({
  //   ...
  adapter: vercelServerless(), // [!code --]
  adapter: node({ mode: 'standalone' }), // [!code ++]

  integrations: [
    // prettier-ignore
    outputCopier({ // [!code --]
      integ: ['sitemap', 'pagefind'] // [!code --]
    }) // [!code --]
  ]
})

Bun server

Bun also support static method.

Check @nurodev/astro-bun for more.

Static

Remove all server adapter configuration in astro.config.ts:

import vercelServerless from '@astrojs/vercel/serverless' // [!code --]

export default defineConfig({
  //   ...
  adapter: vercelServerless(), // [!code --]
  output: 'server' // [!code --]
})

GitHub Pages

See Astro: Configure Astro for GitHub Pages.

For ones deploying on GitHub Pages with a base path, like username.github.io/repo-name, please read Deployment#Platform with Base Path. carefully.

Platform with Base Path

Astro provides basic support for a base path — see the "base" option in the configuration reference Astro: base for more.
This theme will not support the base path, as it seriously break down the experience of remote developments. In general, deploying the template with a base path is not recommended because the homepage integrates lists, resume elements, and other features that rely on the template’s source structure.
If you follow the guide and modify the code, you can deploy with a base path, but you cannot use the same project copy to deploy both with and without a base path simultaneously. Proceed at your own risk; do not open issues about this unless you plan to contribute improvements to the docs.

Set the base option in astro.config.ts to your base path, for example:

export default defineConfig({
  //   ...
  base: '/repo-name/' // Replace with your repository name
})

Update all internal links in Dynamic script files:
- src/components/BaseHead.astro
- src/pages/docs/DocsContent.astro
- src/pages/rss.xml.ts
- packages/pure/components/pages/PostPreview.astro (Customize Theme is required to make the change)
Update all static resource paths:
- Add base paths in src/site.config.ts. Especially the menu configs.
- Add base paths in src/plugins/shiki-transformers.ts for all /icons/code.svg.
- Add base paths in src/assets/styles/app.css for all url in @font-face property.

Comment System

import { Aside } from 'astro-pure/user'

Waline Comment System

The theme's comment, read statistics, likes, and other functionalities are all provided by Waline.

Remove

If you have some reasons to remove the comment system, or just learn how to change to other comment systems, this section might help you. But if you want to know how to configure it, you can skip this section.

Remove it by the following steps:

set enable to false in src/site.config.ts.

export const integ: IntegrationUserConfig = {
  // ...
  waline: {
    enable: false // [!code highlight]
  }
}

Remove dependency @waline/client:
```
bun remove @waline/client
```
Remove folder src/components/waline.
Remove relative code in these layouts:
- src/layouts/CommonPage.astro
- src/layouts/BlogPost.astro
Remove relative config like comment or view configuring for the earlier edited layouts in these files:
- src/pages/about/index.astro
- src/pages/links/index.astro
- src/pages/projects/index.astro
- Other blog post frontmatter config if exists

Deploy

You can refer to its documentation for configuration, and it is recommended to use the Vercel + Supabase combination.

Configuration

Then you can configure the Waline comment system in the integrationConfig.server.

export const integ: IntegrationUserConfig = {
  // ...
  waline: {
    enable: true,
    // Server service link
    server: 'https://astro-theme-pure-waline.arthals.ink/', // [!code highlight]
    // Refer https://waline.js.org/en/guide/features/emoji.html
    emoji: ['bmoji', 'weibo'],
    // Refer https://waline.js.org/en/reference/client/props.html
    additionalConfigs: {
      pageview: true,
      comment: true
      // ...
    }
  }
}

Usage

You can call it manually in .astro or .mdx files.

import { Comment } from '@/components/waline'

// prettier-ignore
<Comment />

Render:

import { Comment } from '@/components/waline'

Content Presentation

import { MdxRepl } from 'astro-pure/user'

Shiki Code

You can change transformer at defineConfig.markdown.shikiConfig in config file astro.config.ts.

Basic Usage

For .astro file:

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

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

For .mdx and .md file:

```shell
git log --oneline
```

Add Title

bun check & bun dev


<Fragment slot='desc'>
````markdown
```shell title="start.sh"
#!/bin/bash

bun check &
bun dev

</Fragment>
</MdxRepl>

### Show Diff

Supports add and del lines.

<MdxRepl width='80%'>
```shell title="deploy.sh"
#!/bin/bash

bun check
bun lint
bun format # [!code ++]
# No need for vercel or other ci/cd
bun run build # [!code --]
git push
```

<Fragment slot='desc'>
````markdown
```shell title="deploy.sh"
#!/bin/bash

bun check
bun lint
bun format # [\!code ++]
# No need for vercel or other ci/cd
bun run build # [\!code --]
git push
```

Show Highlight

Content Obsolete Warning

Add a warning message if the article is old enough.

---
// ...
---
  <Hero {data} {remarkPluginFrontmatter} slot='header'>
    <Fragment slot='description'>
      {!isDraft && enableComment && <PageInfo comment class='mt-1' />}
      { // [!code ++]
        Math.floor((Date.now() - new Date(articleDate).getTime()) / 86400000) > 365 && ( // [!code ++]
          <p class='mt-1 text-sm italic text-primary' style='--primary:41 90% 50%'> <!-- [!code ++] -->
            This article was last updated over a year ago. Some information may be outdated. <!-- [!code ++] -->
          </p> /* [!code ++] */
        ) // [!code ++]
      } <!-- [!code ++] -->
    </Fragment>
  </Hero>

It will render like this:

{

User Components

import { Aside, Tabs, TabItem, MdxRepl } from 'astro-pure/user'

Components let you easily reuse a piece of UI or styling consistently. You can use them not just in .astro files, but also in .mdx files.

For .astro, you can directly import and use components and use. An example will also shown in the first section.

Containers

Card

<Card as='a' href='#card' heading='Lorem ipsum' subheading='Lorem ipsum dolor sit amet, vidit suscipit at mei.' date='August 2021'

You can even contain a list here

<Card as='a' href='#card' heading='Lorem ipsum' subheading='Lorem ipsum dolor sit amet, vidit suscipit at mei.' date='August 2021'

You can even contain a list here

</TabItem>
<TabItem label='Astro'>
```astro
---
import { Card } from 'astro-pure/user'
---
<!-- ... -->
<Card
  as='a'
  href='#card'
  heading='Lorem ipsum'
  subheading='Lorem ipsum dolor sit amet, vidit suscipit at mei.'
  date='August 2021'
>
  You can even contain a list here
</Card>

Collapse

Lorem ipsum dolor sit amet, vidit suscipit at mei.

Aside

// A code snippet, for example.

// js // A code snippet, for example. //

This component also has a remark support version (which can directly use in .md), but not integrated in this theme. You can check packages/starlight/integrations/asides.ts for reference code.

:::tip
This theme author is a good guy.
:::

Tabs

MDX Repl

// Width is optional; using width parameter to set // all elements inside the MDX Repl component. // (slot desc is not included this parameter)

You can combine any other components for the sclot desc. And <Fragment> will not be rendered as a parent html container tag.

List

CardList

</Fragment>
</MdxRepl>

### Timeline

<MdxRepl>
import { Timeline } from 'astro-pure/user'

<Timeline events={
[
  { date: 'August 2021', content: 'Hello' },
  { date: 'August 2022', content: '<i>World!</i>' },
]
} />

<Fragment slot='desc'>
```jsx
import { Timeline } from 'astro-pure/user'

<Timeline events={
  [
    { date: 'August 2021', content: 'Hello' },
    { date: 'August 2022', content: '<i>World!</i>' },
  ]
} />

Steps

How to Yi Jian San Lian:

Or GuanZhu sometimes.

How to Yi Jian San Lian:

Or GuanZhu sometimes.

Simple Text Render

Button

Spoiler

No one can find me. But I am exposed here.

</Fragment>
</MdxRepl>

### Formatted Date

<MdxRepl>
import { FormattedDate } from 'astro-pure/user'

<FormattedDate date={new Date('2077-01-01')} dateTimeOptions={{ month: 'short' }} />

<Fragment slot='desc'>
```jsx
import { FormattedDate } from 'astro-pure/user'

<FormattedDate date={new Date('2077-01-01')} dateTimeOptions={{ month: 'short' }} />

Label

SVG Loader

</Fragment>
</MdxRepl>

## Resources

### Icon

<MdxRepl width='100%'>
<div>
import { Icon } from 'astro-pure/user'

Single use: <Icon name='rss' class='inline' />

Preview all icons available (click button to copy):

import { Icons as allIcons } from 'astro-pure/libs'

<div class='flex flex-wrap gap-2'>
{
Object.keys(allIcons).map(icon => {
  const script = `navigator.clipboard.writeText('${icon}');document.dispatchEvent(new CustomEvent('toast',{detail:{message:'Copied "${icon}" to clipboard!'}}))`
  return (
    <Button as='button' type='button' class='cursor-pointer' onClick={script}>
      <Icon slot='before' name={icon} />
      <span>{icon}</span>
    </Button>
  )
})
}
</div>
</div>

<Fragment slot='desc'>
```jsx
import { Icon } from 'astro-pure/user'

Single use: <Icon name='rss' class='inline' />

Preview all icons available (click button to copy):

import { Icons as allIcons } from 'astro-pure/libs'
import { Button } from 'astro-pure/user'

<div class='flex flex-wrap gap-2'>
{
  Object.keys(allIcons).map(icon => {
    const script = `navigator.clipboard.writeText('${icon}');document.dispatchEvent(new CustomEvent('toast',{detail:{message:'Copied "${icon}" to clipboard!'}}))`
    return (
      <Button as='button' type='button' class='cursor-pointer' onclick={script}>
        <Icon slot='before' name={icon} />
        <span>{icon}</span>
      </Button>
    )
  })
}
</div>

There's also some Advanced Components, which may suit for you. Hope you enjoy using these components!

Friend Links

import { Steps } from 'astro-pure/user'

Remove Links Page

Links page is a page for showing your friend blog links, which is enabled by default.

If you want to remove the links page for any reason, follow the steps in this section. Otherwise, you can skip ahead to the next chapter.

Set links.enable to false in src/site.config.ts:

export const integ: IntegrationUserConfig = {
  // ...
  links: {
    enable: false // [!code highlight]
  }
}

And also, remember to delete the following folders & files:

src/components/links/
src/pages/links/
public/links.json

Basic Configurations

A basic configuration for friend links is in src/site.config.ts. You can add your friend's logbook or your own link info.

export const integ: IntegrationUserConfig = {
  links: {
    // Friend logbook
    logbook: [
      { date: '2025-03-16', content: 'Is there a leakage?' },
      { date: '2025-03-16', content: 'A leakage of what?' },
      { date: '2025-03-16', content: 'I have a full seat of water, like, full of water!' },
      { date: '2025-03-16', content: 'Must be the water.' },
      { date: '2025-03-16', content: 'Let\'s add that to the words of wisdom.' },
    ],
    // Yourself link info
    applyTip: {
      name: theme.title,
      desc: theme.description || 'Null',
      url: 'https://astro-pure.js.org/',
      avatar: 'https://astro-pure.js.org/favicon/favicon.ico'
    }
  },
}

Friend Links

The friend links configurations are at public/links.json.

{
  "friends": [
    {
      "id_name": "cf-links",
      "desc": "Common links included in circle friends",
      "link_list": [
        { // [!code highlight:6]
          "name": "Elysia",
          "intro": "Hi, did you miss me? Anywhere and anytime, Elysia will return all your expectations.",
          "link": "https://honkaiimpact3.fandom.com/wiki/Elysia",
          "avatar": "https://0.gravatar.com/avatar/"
          // Here you can also leave some other fields as notes
        },
      ]
    },
    {
      "id_name": "inactive-links",
      "desc": "Inactive or rule-breaking friends",
      "link_list": [] // you can temporarily leave some bad links here
    },
    {
      "id_name": "special-links",
      "desc": "Other special links",
      "link_list": [] // special links which are note your friends
    }
  ]
}

Integrated with `Friend-Circle-Lite`

Friend-Circle-Lite is a stripped-down friend-link app with no backend and running only using github action.

It requires:

A github repository with github actions enabled by cron.
A static site server like Vercel, Netlify, GitHub Pages, etc.

This theme has not integrated it and will not provide support for it in the future. But don't worry, this doc will guide you to integrate it.

Fork the Friend-Circle-Lite.

Modify the config.yaml in your forked repository:

spider_settings:
   enable: true
   json_url: "<your-site>/links.json" # [!code highlight]
   article_count: 4

Go to "Actions" page and run workflow "Friend Circle Lite" manually to check if it works. This will also generate server files in "page" branch.
Checkout docs to deploy the server files to your static site server.
Add fetching script file friendCircle.ts to your project at path src/plugins.
Add style file fc.css to your project at path src/assets/styles.

Add initialize code in src/components/pages/links/index.astro:

---
const headings = [
   // ...
   { depth: 2, slug: 'small-circle', text: 'Small Circle' }, // [!code highlight]
]
---

<PageLayout>
   {/* ... */}
   <!-- [!code highlight:16] -->
   <h2 id='small-circle'>Small Circle</h2>
   <div id='friend-circle-lite-root' class='not-prose'>Loading...</div>
   <script>
      import '@/assets/styles/fc.css'

      import { FriendCircle } from '@/plugins/friendCircle'

      const fc = new FriendCircle()
      fc.init({
         private_api_url: '<your-fc-lite-server>',
         page_turning_number: 10,
         error_img: 'https://gravatar.loli.net/avatar/57d8260dfb55501c37dde588e7c3852c'
      })
      fc.load()
   </script>
</PageLayout>

Other Integrations

import { Aside, Tabs, TabItem, Steps } from 'astro-pure/user'

`medium-zoom`

Checkout medium-zoom for more.

export const integ: IntegrationUserConfig = {
  // ...
  // A lightbox library that can add zoom effect
  mediumZoom: {
    enable: true, // disable it will not load the whole library
    selector: '.prose .zoomable',
    options: {
      className: 'zoomable'
    }
  }
}

This theme has integrated it in BlogPost.astro by default, which means any content in src/content/blog doesn't need to import. If you want to use it in any other layout or page, you can use the following code:

// .zoomable class will automatically added using remark plugin

`@playform/compress`

Checkout playform/compress for more.

Friend-Circle-Lite

See Friend Links #Integrated with Friend-Circle-Lite.

LateX support

In case any time in the future this theme removes default support for LateX, there's a tutorial to help you add support for it.

Rendering LaTeX in Astro.js enriches your markdown files with mathematical expressions, making your content both engaging and informative. The following steps outline the necessary steps to integrate LaTeX into Astro.js and addresses potential pitfalls along with their solutions.

Install Necessary Packages

Begin by installing remark-math and rehype-katex. These packages parse and render LaTeX respectively. Use the install commands:
```
bun install remark-math rehype-katex
```

Configure Astro

Modify your Astro configuration to use these plugins. Add the plugins to the markdown configuration section in your astro.config.ts:

import { defineConfig } from 'astro/config';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
   // ...
   markdown: {
      remarkPlugins: [remarkMath],
      rehypePlugins: [rehypeKatex],
   },
});

Include KaTeX CSS

To ensure that LaTeX formulas are styled correctly, include the KaTeX CSS in your HTML layout (in this theme it would be in the BlogPost.astro file). Add the following css resources:
```
---
import 'katex/dist/katex.min.css'
---
```
Or use CDN to fasten speed:
```
---
import config from '@/site-config'
---
<link rel="stylesheet" href={`${config.npmCDN}/katex@0.16.15/dist/katex.min.css`}>
```

Some CSS code is recommended:

To ensure that the LaTeX formulas are displayed better, you may need to add the following code to public/styles/global.css:

span.katex-display {
  overflow-y: scroll;
  padding: 0.5rem;
}
.katex-html {
  overflow: auto hidden;
  padding: 3px;
}
.katex-html .base {
  margin-block: 0;
  margin-inline: auto;
}
.katex-html .tag {
  position: relative !important;
  display: inline-block;
  padding-inline-start: 0.5rem;
}

Common Pitfalls and Solutions:

CSS Styling Issues

Problem: LaTeX formulas might not render with the correct styles if the KaTeX CSS isn’t loaded.

Solution: Confirm the KaTeX stylesheet link is correctly placed in the HTML head and is loading without issues. Check for network errors or restrictions that might prevent the CSS from loading.
Build Errors

Problem: Errors during build time when processing LaTeX syntax.

Solution: Ensure that your LaTeX is correctly formatted and that there are no syntax errors in your markdown files. LaTeX syntax errors can break the parser and cause build failures.

Configuration

Theme Configuration

File: src/site.config.ts

pending update...

Astro Configuration

File: astro.config.ts

You can configure it to change deployment methods, add rehype & remark plugins, and more.

Read more about Astro configuration here.

ESLint Configuration

File: eslint.config.mjs

You can configure ESLint to change rules and security checks.

Read more about ESLint configuration here.

Prettier Configuration

File: prettier.config.mjs

You can configure Prettier to change code formatting rules, this can change your experience using package command format and extension support for your favorite IDE.

Options are available here.

UnoCSS Configuration

File: uno.config.ts

It is a utility-first CSS framework building custom designs. Theme also uses its preset typography to make type settings.

Checkout UnoCSS & Styles for more info.

Typescript Configuration

File: tsconfig.json

FAQs

Path

Blog specific path

Routing blogs format like /blog/:year/:id

See 4.0.2-beta如何使文章链接中包含年份.

Content

Support web images for `heroImage`

It should be used with inferSize: true to get the image size. Example:

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

Build

Vite Block Request

Blocked request. This host ("xxx")is not allowed.
To allow this host, add "xxx" to `preview.allowedHosts` in vite.config.js.

See option server.allowedHosts doesn't take into account "true"

Problem with `BUN_LINK_PKG`

See BUN_LINK_PKG 环境变量无法设置成功

Build No "Exports" Main Defined

07:39:23 [ERROR] [@astrojs/vercel] An unhandled error occurred while running the "astro:build:done" hook
No "exports" main defined in /vercel/path0/node_modules/estree-walker/package.json
  Stack trace:
    ...

Try redeploy your project without existing build cache.

Detail: oven-sh/bun/issues: error No "exports" main defined in /vercel/path0/node_modules/estree-walker/package.json

UnoCSS & Styles

UnoCSS Change Appearance

You can customize the theme default UnoCSS palette by modifying the CSS file at src/assets/styles/app.css. For example, if you want to change the default theme color, you can modify the following code:

:root {
  /* ... */
  --primary: 200 29% 45%; /* [!code --] */
  --primary: <Your favorite color using raw hsl>; /* [!code ++] */
}

And the same way to change the default font family, you can modify the following code:

:root {
  /* ... */
  font-family: 'Satoshi'; /* [!code --] */
  src: url('/fonts/Satoshi-Variable.ttf'); /* [!code --] */
  font-family: '<Your favorite font family>'; /* [!code ++] */
  src: url('/fonts/<Your favorite font>.ttf'); /* [!code ++] */
}

Make sure to put your custom font file in the public/fonts directory.

UnoCSS Configuration

File: uno.config.ts

Get to know more:

`@unocss/preset-typography`

Typography config can be modified in uno.config.ts:

const typographyConfig = {
  // prettier-ignore
  cssExtend: { // [!code highlight:3]
    // ...
  }
}

But if you want to customize the typography by UnoCSS, or just change the preset typography theme, you can do it in src/site.config.ts:

export const integ: IntegrationUserConfig = {
  // ...
  typography: {
    class: 'prose text-base text-muted-foreground' // [!code highlight]
  }
}

Checkout Typography preset for more.