})
```
+## GitHub-flavored Alerts
+
+VitePress also supports [GitHub-flavored alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) to render as callouts. They will be rendered the same as the [custom containers](#custom-containers).
+
+```md
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+```
+
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+
## Syntax Highlighting in Code Blocks
-VitePress uses [Shikiji](https://github.com/antfu/shikiji) (an improved version of [Shiki](https://shiki.matsu.io/)) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
+VitePress uses [Shiki](https://github.com/shikijs/shiki) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
**Input**
@@ -305,7 +341,7 @@ export default {
```
-A [list of valid languages](https://github.com/antfu/shikiji/blob/main/docs/languages.md) is available on Shikiji's repository.
+A [list of valid languages](https://shiki.style/languages) is available on Shiki's repository.
You may also customize syntax highlight theme in app config. Please see [`markdown` options](../reference/site-config#markdown) for more details.
diff --git a/docs/lunaria.config.json b/docs/lunaria.config.json
index 0a4c5077..93eb6010 100644
--- a/docs/lunaria.config.json
+++ b/docs/lunaria.config.json
@@ -26,5 +26,6 @@
"lang": "zh"
}
],
- "outDir": ".vitepress/dist/_translations"
+ "outDir": ".vitepress/dist/_translations",
+ "ignoreKeywords": ["lunaria-ignore"]
}
diff --git a/docs/package.json b/docs/package.json
index 119d8def..162e4e72 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -10,7 +10,7 @@
"lunaria:open": "open-cli .vitepress/dist/_translations/index.html"
},
"devDependencies": {
- "@lunariajs/core": "npm:@brc-dd/lunaria-core@latest",
+ "@lunariajs/core": "^0.0.28",
"markdown-it-mathjax3": "^4.3.2",
"open-cli": "^8.0.0",
"vitepress": "workspace:*"
diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md
index fb6d30b5..f41fb7ad 100644
--- a/docs/reference/default-theme-config.md
+++ b/docs/reference/default-theme-config.md
@@ -244,8 +244,10 @@ type SocialLinkIcon =
| 'instagram'
| 'linkedin'
| 'mastodon'
+ | 'npm'
| 'slack'
| 'twitter'
+ | 'x'
| 'youtube'
| { svg: string }
```
diff --git a/docs/reference/default-theme-home-page.md b/docs/reference/default-theme-home-page.md
index 765c585e..f7baecca 100644
--- a/docs/reference/default-theme-home-page.md
+++ b/docs/reference/default-theme-home-page.md
@@ -69,6 +69,12 @@ interface HeroAction {
// Destination link of the button.
link: string
+
+ // Link target attribute.
+ target?: string
+
+ // Link rel attribute.
+ rel?: string
}
```
@@ -144,6 +150,9 @@ interface Feature {
//
// e.g. `external`
rel?: string
+
+ // Link target attribute for the `link` option.
+ target?: string
}
type FeatureIcon =
@@ -157,3 +166,30 @@ type FeatureIcon =
height: string
}
```
+
+## Markdown Content
+
+You can add additional content to your site's homepage just by adding Markdown below the `---` frontmatter divider.
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+---
+
+## Getting Started
+
+You can get started using VitePress right away using `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info
+VitePress didn't always auto-style the extra content of the `layout: home` page. To revert to older behavior, you can add `markdownStyles: false` to the frontmatter.
+:::
diff --git a/docs/reference/site-config.md b/docs/reference/site-config.md
index 1cf9d726..ec853063 100644
--- a/docs/reference/site-config.md
+++ b/docs/reference/site-config.md
@@ -31,10 +31,10 @@ If you need to dynamically generate the config, you can also default export a fu
```ts
import { defineConfig } from 'vitepress'
-export default async () => defineConfig({
+export default async () => {
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
- return {
+ return defineConfig({
// app level config options
lang: 'en-US',
title: 'VitePress',
@@ -49,8 +49,8 @@ export default async () => defineConfig({
}))
]
}
- }
-})
+ })
+}
```
You can also use top-level `await`. For example:
@@ -510,7 +510,7 @@ When using the default theme, enabling this option will display each page's last
- Type: `MarkdownOption`
-Configure Markdown parser options. VitePress uses [Markdown-it](https://github.com/markdown-it/markdown-it) as the parser, and [Shikiji](https://github.com/antfu/shikiji) (an improved version of [Shiki](https://shiki.matsu.io/)) to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs.
+Configure Markdown parser options. VitePress uses [Markdown-it](https://github.com/markdown-it/markdown-it) as the parser, and [Shiki](https://github.com/shikijs/shiki) to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs.
```js
export default {
@@ -645,6 +645,24 @@ export default {
}
```
+#### Example: Adding a canonical URL `
`
+
+```ts
+export default {
+ transformPageData(pageData) {
+ const canonicalUrl = `https://example.com/${pageData.relativePath}`
+ .replace(/index\.md$/, '')
+ .replace(/\.md$/, '.html')
+
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'link',
+ { rel: 'canonical', href: canonicalUrl }
+ ])
+ }
+}
+```
+
### transformHtml
- Type: `(code: string, id: string, context: TransformContext) => Awaitable
`
diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md
index fa6478ca..69259a6a 100644
--- a/docs/zh/guide/asset-handling.md
+++ b/docs/zh/guide/asset-handling.md
@@ -2,7 +2,7 @@
## 引用静态资源 {#referencing-static-assets}
-所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://vitejs.dev/guide/assets.html) 处理。可以**并且应该**使用相对路径来引用资源：
+所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://cn.vitejs.dev/guide/assets.html) 处理。可以**并且应该**使用相对路径来引用资源：
```md
@@ -12,6 +12,10 @@
常见的图像，媒体和字体文件会被自动检测并视作资源。
+::: tip 通过链接引用的文件不会视作资源
+在 Markdown 内，通过链接引用的 PDF 或者其他文档不会被自动视作资源。要使这些文件可用，你必须手动将其放在项目的 [`public`](#the-public-directory) 目录内。
+:::
+
所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并使用哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会采用 base64 内联——这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。
所有**静态**路径引用，包括绝对路径，都应基于你的工作目录的结构。
diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md
index 4a78185f..e5eb760b 100644
--- a/docs/zh/guide/custom-theme.md
+++ b/docs/zh/guide/custom-theme.md
@@ -196,7 +196,7 @@ export default {
如果主题需要特殊的 VitePress 配置，也需要在配置中扩展：
```ts
-// .vitepress/theme/config.ts
+// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
export default {
@@ -208,7 +208,7 @@ export default {
最后，如果主题为其主题配置提供了类型：
```ts
-// .vitepress/theme/config.ts
+// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'
diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md
index 17525cd4..d8ac6cca 100644
--- a/docs/zh/guide/deploy.md
+++ b/docs/zh/guide/deploy.md
@@ -153,26 +153,24 @@ Cache-Control: max-age=31536000,immutable
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v3
+ uses: actions/checkout@v4
with:
fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
# - uses: pnpm/action-setup@v2 # 如果使用 pnpm，请取消注释
# - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
- name: Setup Node
- uses: actions/setup-node@v3
+ uses: actions/setup-node@v4
with:
- node-version: 18
+ node-version: 20
cache: npm # 或 pnpm / yarn
- name: Setup Pages
- uses: actions/configure-pages@v3
+ uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci # 或 pnpm install / yarn install / bun install
- name: Build with VitePress
- run: |
- npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
- touch docs/.vitepress/dist/.nojekyll
+ run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
- name: Upload artifact
- uses: actions/upload-pages-artifact@v2
+ uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
@@ -187,7 +185,7 @@ Cache-Control: max-age=31536000,immutable
steps:
- name: Deploy to GitHub Pages
id: deployment
- uses: actions/deploy-pages@v2
+ uses: actions/deploy-pages@v4
```
::: warning
diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md
index a58e35f4..4bb495fa 100644
--- a/docs/zh/guide/extending-default-theme.md
+++ b/docs/zh/guide/extending-default-theme.md
@@ -194,7 +194,10 @@ export default {
- `aside-ads-after`
- 当 `layout: 'home'` 在 frontmatter 中被启用时:
- `home-hero-before`
+ - `home-hero-info-before`
- `home-hero-info`
+ - `home-hero-info-after`
+ - `home-hero-actions-after`
- `home-hero-image`
- `home-hero-after`
- `home-features-before`
diff --git a/docs/zh/guide/frontmatter.md b/docs/zh/guide/frontmatter.md
index 778b8111..4bcec7ea 100644
--- a/docs/zh/guide/frontmatter.md
+++ b/docs/zh/guide/frontmatter.md
@@ -2,7 +2,7 @@
## 用法 {#usage}
-VitePress 支持在所有 Markdown 文件中使用 YAML frontmatter，并使用 [gray-matter](https://github.com/jonschlinkert/gray-matter) 解析。frontmatter 必须位于 Markdown 文件的顶部 (在任何元素之前，包括 `
+
+
+
@@ -16,23 +23,21 @@ import VPHomeFeatures from './VPHomeFeatures.vue'
-
+
+
+
+
diff --git a/src/client/theme-default/components/VPHomeContent.vue b/src/client/theme-default/components/VPHomeContent.vue
new file mode 100644
index 00000000..fe689b6e
--- /dev/null
+++ b/src/client/theme-default/components/VPHomeContent.vue
@@ -0,0 +1,52 @@
+
+
+
+
+
+
+
+
+
diff --git a/src/client/theme-default/components/VPHomeHero.vue b/src/client/theme-default/components/VPHomeHero.vue
index 5d482944..972a1f61 100644
--- a/src/client/theme-default/components/VPHomeHero.vue
+++ b/src/client/theme-default/components/VPHomeHero.vue
@@ -15,7 +15,10 @@ const { frontmatter: fm } = useData()
:image="fm.hero.image"
:actions="fm.hero.actions"
>
+
+
+
diff --git a/src/client/theme-default/components/VPHomeSponsors.vue b/src/client/theme-default/components/VPHomeSponsors.vue
index 7847ac96..1343e776 100644
--- a/src/client/theme-default/components/VPHomeSponsors.vue
+++ b/src/client/theme-default/components/VPHomeSponsors.vue
@@ -1,5 +1,4 @@
-