JuniorTree

CardLink 组件使用示例

import CardLink from '@/components/mdx/CardLink.astro'

CardLink 组件使用示例

CardLink 是一个用于在 MDX 中创建可点击卡片链接的组件。

基础用法

带图标

不同样式变体

Primary 变体

Minimal 变体

网格布局

使用 CSS Grid 可以创建多列布局:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose">
  <CardLink
    title="链接 1"
    description="第一个链接的描述"
    href="https://example1.com"
  />
  <CardLink
    title="链接 2"
    description="第二个链接的描述"
    href="https://example2.com"
  />
</div>

Props 说明

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | (必需) | 卡片标题 | | description | string | (必需) | 卡片描述文本 | | href | string | (必需) | 跳转链接 | | icon | string | undefined | 可选 SVG path 字符串 | | variant | 'default' \| 'primary' \| 'minimal' | 'default' | 样式变体 | | external | boolean | true | 是否在新标签页打开 | | class | string | '' | 自定义类名 |

CardLink 组件使用指南

import CardLink from '@/components/mdx/CardLink.astro'

CardLink 组件使用指南

CardLink 是一个智能卡片链接组件，支持在构建时自动爬取链接的 Open Graph 元数据（标题、描述、图标等）。

✨ 特性

🤖 自动爬取元数据：从目标页面自动获取标题和描述
⚡ 构建时处理：在构建时完成所有爬取，不影响运行时性能
🎨 多种样式变体：default、primary、minimal 三种风格
🔗 智能后备：爬取失败时自动使用域名作为标题
🌐 外部链接标识：自动添加外部链接图标

📖 基础用法

自动爬取（推荐）

只需提供链接，组件会自动爬取标题和描述：

<CardLink href="https://github.com/facebook/react" />

效果示例：

手动指定内容

如果自动爬取的内容不理想，可以手动指定：

<CardLink
  href="https://example.com"
  title="自定义标题"
  description="这是自定义的描述文本，可以覆盖自动爬取的内容"
/>

效果示例：

🎨 样式变体

Default（默认）

<CardLink href="https://astro.build" />

Primary（强调）

<CardLink href="https://astro.build" variant="primary" />

Minimal（简约）

<CardLink href="https://astro.build" variant="minimal" />

🔧 高级用法

使用自定义图标

<CardLink
  href="https://github.com"
  icon="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387..."
/>

内部链接

对于站内链接，可以设置 external={false}：

<CardLink
  href="/blog/my-post"
  title="我的文章"
  description="这是一篇内部文章"
  external={false}
/>

📦 多列布局

结合 Tailwind CSS 创建多列卡片网格：

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 not-prose">
  <CardLink href="https://astro.build" />
  <CardLink href="https://react.dev" />
  <CardLink href="https://vuejs.org" />
  <CardLink href="https://svelte.dev" />
</div>

效果：

📋 Props 参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | href | string | (必需) | 跳转链接 | | title | string | undefined | 手动指定标题（不指定则自动爬取） | | description | string | undefined | 手动指定描述（不指定则自动爬取） | | icon | string | undefined | SVG path 字符串 | | variant | 'default' \| 'primary' \| 'minimal' | 'default' | 样式变体 | | external | boolean | true | 是否在新标签页打开 | | class | string | undefined | 自定义类名 |

🚀 性能说明

构建时爬取：所有元数据在项目构建时获取，不增加运行时负担
智能缓存：内置 LRU 缓存机制，避免重复请求同一 URL
错误处理：爬取失败时优雅降级，使用域名作为后备标题
只爬取 HTTPS：出于安全考虑，只爬取 HTTPS 链接

💡 最佳实践

优先使用自动爬取：让组件自动获取标题和描述，保持内容新鲜
重要链接手动指定：对于特别重要的链接，建议手动指定标题和描述
合理使用变体：使用 primary 突出重点链接，minimal 用于次要链接
批量布局：使用 grid 布局展示多个链接时，记得添加 not-prose 类

🔍 与 LinkPreview 的区别

项目中还有一个 LinkPreview 组件（来自 astro-pure），它们的区别：

| 特性 | CardLink | LinkPreview | |------|----------|-------------| | 布局 | 紧凑卡片 | 大型卡片（带图片） | | 用途 | 快速链接跳转 | 内容预览展示 | | 图片 | 不支持 | 支持 Open Graph 图片 | | 推荐场景 | 参考资料列表 | 文章开头展示引用 |

根据你的需求选择合适的组件！

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.
Then change the theme code as it is a part of your code!

This can also help you correctly build your project on cloud CI/CD.

FAQs

Routes

Blog specific route

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 }

Vite

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"

Packages

Problem with `BUN_LINK_PKG`

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

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.

Acknowledgements

import { GithubCard } from 'astro-pure/advanced' import { Button } 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.

Contributions

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

Acknowledgements

We would like to express our gratitude to all users and contributors who have supported this project.

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

Update Theme

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

Breaking Changes

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

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>

### Medium Zoom

Try click the following image.

![img](https://github.com/user-attachments/assets/6c42b061-df7e-4696-a29b-bff07fe17d88)

See [Other Integrations#medium-zoom](/docs/integrations/others#medium-zoom).

Shiki Code

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

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
<!-- You need to delete `\` during the use -->

```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

<!doctype html><html><head><meta name="color-scheme" content="dark"></head><body style='overflow:hidden'> 
<!-- Highlight a single line -->
<p style='text-align:center'>君指先跃动の光は、私の一生不変の信仰に、唯私の超电磁炮永生き！</p> <!-- [\!code highlight] -->

<!-- You can also highlight multiple lines with a single comment: -->
<canvas id="can" width="400" height="400" style="background:Black;display:block;margin:20px auto;"></canvas> 
<script> // [\!code highlight:11]
var sn=[42,41], dz=43, fx=1, n, score=-1, ctx=document.getElementById("can").getContext("2d"), sz=20;
onkeydown = e => fx = sn[1]-sn[0]==(n=[-1,-20,1,20][(e||event).keyCode-37]||fx) ? fx : n;
function draw(t,c) { ctx.fillStyle=c; ctx.fillRect(t%sz*sz+1,~~(t/sz)*sz+1,sz-2,sz-2); }
!function() { sn.unshift(n=sn[0]+fx);
  if (sn.indexOf(n,1)>0||n<0||n>399||fx==1&&n%sz==0||fx==-1&&n%sz==sz-1) return alert("GAME OVER. Score: "+score);
  draw(n,"Lime");
  if (n==dz) { score++; do{dz=~~(Math.random()*400)}while(sn.indexOf(dz)>=0); draw(dz,"Yellow"); }
  else draw(sn.pop(),"Black");
  setTimeout(arguments.callee,130);
}(); </script> 
</body></html>

</Fragment>
</MdxRepl>

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'

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('2021-08-01')} dateTimeOptions={{ month: 'short' }} />

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

<FormattedDate date={new Date('2021-08-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!

ImageSets 组件

import ImageSets from '@/components/mdx/ImageSets.astro'

ImageSets 用于在文章中把多组图片压缩到同一段落位置展示。每一组可以包含一张或多张图片，读者通过右下角按钮切换组。

import ImageSets from '@/components/mdx/ImageSets.astro'

<ImageSets
  columns={2}
  sets={[
    {
      label: '第一组',
      images: [
        { src: 'https://example.com/one.webp', alt: '第一张图' },
        { src: 'https://example.com/two.webp', alt: '第二张图' }
      ]
    },
    {
      label: '第二组',
      images: [
        { src: 'https://example.com/three.webp', alt: '第三张图' },
        { src: 'https://example.com/four.webp', alt: '第四张图' }
      ]
    }
  ]}
/>

可选参数：

columns：桌面端每组显示几列，默认 2，最大 4。
ratio：图片框比例，默认 16 / 10；如果希望图片保持原始高度，可以传 ratio="auto"。
fit：图片填充方式，默认 cover；如果是截图或图表，可以传 fit="contain"。
maxWidth：组件最大宽度，默认 58rem。
initial：默认显示第几组，从 1 开始。

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: [
    ],
    // Yourself link info
    applyTip: {
      name: theme.title,
      desc: theme.description || 'Null',
      url: 'https://www.juniortree.com/',
      avatar: 'https://s3.juniortree.com/pic/2025/11/c93639947bdf6f3bc87bd18ed6b283ea.webp'
    }
  },
}

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://cravatar.cn/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.mjs:

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.

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.

YouTube 视频卡片

import YouTube from '@/components/mdx/YouTube.astro' import { Aside } from 'astro-pure/user'

YouTube 组件用于在文章中插入一张 YouTube 视频卡片：展示封面、标题与作者，点击后在新标签页打开 YouTube 观看。

封面图与标题在构建时自动抓取并缓存到本地（public/youtube/），因此国内读者无需依赖 YouTube CDN 也能看到封面。

用法

只需要传入视频 ID（即 watch?v= 后面那一段）：

import YouTube from '@/components/mdx/YouTube.astro'

<YouTube id='dQw4w9WgXcQ' />

属性

| 属性 | 类型 | 说明 | | ------- | -------- | ---------------------------------------------------------- | | id | string | 必填。YouTube 视频 ID。 | | title | string | 可选。构建时未能抓到标题时的兜底文本。 | | class | string | 可选。自定义类名。 |

工作原理

构建脚本 scripts/cacheYoutube.mjs 扫描 src/content/** 下所有 <YouTube /> 用法，收集视频 ID。
对每个 ID 下载缩略图到 public/youtube/<id>.jpg（优先 maxresdefault，失败回退 hqdefault），并通过 oEmbed 抓取标题与作者。
抓取结果写入 src/data/youtube-metadata.json，组件在渲染时读取该文件取本地封面与标题。

该脚本已挂在 dev、build、check 流程前自动执行（与 paper:sync 并列）。如需强制刷新所有封面与元数据：

npm run youtube:sync -- --refresh

Configuration

Theme Configuration

File: src/site.config.ts

pending update...

Astro Configuration

File: astro.config.mjs

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

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 suopported 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 targetting 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 specificed 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 specificed 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, luckly 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 flexsible 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.

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.

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.mjs: 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)
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.

JuniorTree

CardLink 组件使用示例

CardLink 组件使用示例

基础用法

带图标

不同样式变体

Primary 变体

Minimal 变体

网格布局

Props 说明

CardLink 组件使用指南

CardLink 组件使用指南

✨ 特性

📖 基础用法

自动爬取（推荐）

手动指定内容

🎨 样式变体

Default（默认）

Primary（强调）

Minimal（简约）

🔧 高级用法

使用自定义图标

内部链接

📦 多列布局

📋 Props 参数

🚀 性能说明

💡 最佳实践

🔍 与 LinkPreview 的区别

Customize Theme

You Should Know

Swizzling

Package mode

FAQs

Routes

Blog specific route

Content

Support web images for heroImage

Vite

Vite Block Request

Packages

Problem with BUN_LINK_PKG

Optimize Your Site

Integrations

CDN

Coding

Pictures

Use optimized component

Change Image Size

Adapt External Images

File Size Analysis

Acknowledgements

Contributions

Acknowledgements

Open Source References

Update Theme

Breaking Changes

v4.0.8

v4.0.7

v4.0.6

v4.0.5

v4.0.3

v4.0.2-beta

v4.0.1-beta

v4.0.0-alpha

v3.1.4

v3.1.3

v3.1.2 (pre-release)

v3.1.1

v3.1.0 (pre-release)

v3.0.9

Update Method

Rebase

Merge Manually

Advanced Components

Web Content Render

Quote

GitHub Card

Link Preview

Data Transformer

QRCode

Support web images for `heroImage`

Problem with `BUN_LINK_PKG`

Integrated with `Friend-Circle-Lite`

`medium-zoom`

`@playform/compress`

`@unocss/preset-typography`