gitea-yuany3721/vuepress-theme-plume
1
0
Fork 1
mirror of https://github.com/pengzhanbo/vuepress-theme-plume.git synced 2026-04-23 10:58:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add en-US docs (#514)

Browse Source 
* docs: translate README to English in homepage

* feat(docs): update hero-text in README

* docs: add readme_en

* feat(docs): add language jump in readme

* docs: update readme layout

* feat(docs): add CONTRIBUTION_EN and jump link

* docs: translate theme introduction

* docs: upgrade version to 135 , create 2 file

* docs: add icon, fix translation errors in intro, translate quick-start

* docs: translate quick start - write

* docs: fix jump link in write

* docs: translate document in quick start

* docs: translate international in quick start

* docs: translate deployment in quick start

* docs: translate optimize-build in quick start

---------

Co-authored-by: pengzhanbo <volodymyr@foxmail.com>
This commit is contained in:
zhenghaoyang24 2025-03-09 11:14:47 +08:00 committed by GitHub
parent 4cc290de28
commit a4ac3a30e0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
28 changed files with 3582 additions and 478 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
CONTRIBUTING_EN.md Normal file
View File

@ -0,0 +1,69 @@
# Contribution Guide
## Overview
The project repository uses [pnpm workspaces](https://pnpm.io/zh/workspaces) to implement a [Monorepo](https://en.wikipedia.org/wiki/Monorepo), which stores multiple interrelated independent Packages.
- The theme is developed and maintained in the `theme` directory.
- Plugins are developed and maintained in the `plugins` directory.
- Documentation is developed and maintained in the `docs` directory.
In the `plugins` directory:
- `plugin-content-update`: Rewrites the `Content` component and provides the `onContentUpdated` hook.
- `plugin-search`: Provides full-text fuzzy search functionality for the theme.
- `plugin-shikiji`: A code highlighting plugin that supports highlight, diff, focus, and error level.
- `plugin-md-power`: Provides enhanced markdown features.
## Development Configuration
Development requirements:
- [Node.js](http://nodejs.org/) version 18.16.0+
- [pnpm](https://pnpm.io/zh/) version 9+
Clone the repository and install dependencies:
```sh
pnpm install
```
Before starting the development service for the first time, build the source code:
```sh
pnpm build
```
### Main Tools
- [TypeScript](https://www.typescriptlang.org/) as the development language.
- [ESLint](https://eslint.org/) for code checking and formatting.
- [StyleLint](https://stylelint.io/) for code checking and formatting.
### Scripts
#### `pnpm build`
The `build` command uses `tsc` to compile the source code into `.js` files in the `lib` directory. It also copies resources that do not need to be compiled to the corresponding `lib` directory.
After cloning the repository, you need to run this command first to ensure that the project code can run smoothly, as the compiled output directory is excluded from the repository by `.gitignore`.
#### `pnpm dev`
The `dev` command starts two services locally. One runs the `tsup:watch & copy:watch` for the `theme` directory, and the other runs the `vuepress` development service for the example `docs` directory.
By default, all plugins under the `plugins` directory do not have a `dev` command. Therefore, changes to the `plugins` directory may require running the `pnpm build` command to rebuild. Some changes to the `plugins/**/node` directory require re-running `pnpm dev` to take effect.
#### `pnpm lint`
The `lint` command uses ESLint to check all source files.
When `lint` reports errors, you can manually modify the source code to fix the ESLint errors, or run `pnpm lint:fix` to automatically fix them.
#### `pnpm test`
The `test` command uses Vitest to run all tests.
### IDE Support
It is recommended to use `vs code` for development. This repository is configured with the recommended `vs code` extensions for developing this theme. When you import this repository, `vs code` may recommend that you install some extensions.

8
docs/.vuepress/notes/en/index.ts
View File

@ -1,8 +1,12 @@
import { defineNotesConfig } from 'vuepress-theme-plume'
import { themeGuide } from './theme-guide.js'
import { themeConfig } from './theme-config'
import { themeGuide } from './theme-guide'
export const enNotes = defineNotesConfig({
dir: 'en/notes',
link: '/',
notes: [themeGuide],
notes: [
themeGuide,
themeConfig,
],
})

27
docs/.vuepress/notes/en/theme-config.ts Normal file
View File

@ -0,0 +1,27 @@
import { defineNoteConfig } from 'vuepress-theme-plume'
export const themeConfig = defineNoteConfig({
dir: 'theme/config',
link: '/config/',
sidebar: [
{
text: 'Config',
collapsed: false,
items: [
'intro',
'basic',
'locales',
'notes',
],
},
{
text: 'frontmatter',
prefix: 'frontmatter',
collapsed: false,
items: [
'basic',
'article',
],
},
],
})

33
docs/.vuepress/notes/en/theme-guide.ts
View File

@ -10,6 +10,39 @@ export const themeGuide = defineNoteConfig({
icon: 'carbon:idea',
items: [
'intro',
'quick-start',
'project-structure',
'write',
'blog',
'document',
'international',
'deployment',
'optimize-build',
],
},
{
text: 'Write',
icon: 'fluent-mdl2:edit-create',
collapsed: false,
items: [
{
text: 'markdown',
icon: 'material-symbols:markdown-outline',
prefix: 'markdown',
collapsed: true,
items: [
'basic',
'extensions',
],
},
],
},
{
text: 'Customization',
icon: 'material-symbols:dashboard-customize-outline-rounded',
collapsed: false,
items: [
'custom-home',
],
},
],

3
docs/README.md
View File

@ -183,7 +183,8 @@ export default defineUserConfig({
'hrradev',
{ github: 'TheCoderAlex', name: 'Tang Zifeng' },
{ github: 'HydroGest', name: 'MarkChai' },
{ github: 'sunnyboy-mu', name: '小沐沐吖' }
{ github: 'sunnyboy-mu', name: '小沐沐吖' },
{ github: 'zhenghaoyang24', name: 'zhenghaoyang24' },
]"
/>

7
docs/en/4.Tutorials/frontmatter.md Normal file
View File

@ -0,0 +1,7 @@
---
title: How to user frontmatter
createTime: 2025/03/03 14:12:59
permalink: /en/article/gh9w1jj1/
---
todo ...

185
docs/en/README.md
View File

@ -1,6 +1,5 @@
---
home: true
externalLink: false
pageLayout: home
config:
-
type: hero
@ -8,19 +7,191 @@ config:
background: tint-plate
hero:
name: Theme Plume
tagline: Vuepress Next Theme
text: A simple, feature-rich vuepress document & blog theme
tagline: VuePress Next Theme
text: A simple, easy-to-use, feature-rich VuePress documentation & blog theme
actions:
-
theme: brand
text: Quick Start →
link: /
text: Get Started →
link: /en/guide/intro/
-
theme: alt
text: Github
link: https://github.com/pengzhanbo/vuepress-theme-plume
-
type: features
features:
-
title: Responsive Layout
icon: twemoji:laptop-computer
details: Adapts to mobile devices, PCs, and tablets
-
title: Blog & Documentation
icon: twemoji:open-book
details: Whether you want to write a blog, product documentation, or both
-
title: Out-of-the-Box
icon: twemoji:rocket
details: Supports zero-configuration out-of-the-box, as well as rich customization options
-
title: Multi-language
icon: twemoji:balance-scale
details: Built-in support for Chinese/English, and you can customize and add more language support
-
title: Dual Color Theme
icon: twemoji:cityscape
details: Supports light/dark themes, including code highlighting
-
title: Plugins
icon: twemoji:card-file-box
details: Built-in rich plugins to meet general website needs
-
title: Search & Comments
icon: twemoji:magnifying-glass-tilted-right
details: Supports multiple comment systems, local search, and Algolia search
-
title: Encryption
icon: twemoji:locked-with-key
details: Supports full-site encryption and partial encryption (encrypted directories, encrypted articles)
-
title: Markdown Enhancement
icon: twemoji:writing-hand-light-skin-tone
details: Supports Markdown syntax, code block grouping, hint containers, task lists, mathematical formulas, code demonstrations, etc.
-
type: image-text
title: Features
description: Built-in rich features to meet general website needs.
image: /images/plume-1.svg
list:
-
title: Article Information
description: Add tags, categories, word count, reading time, writing date, and other information to articles.
-
title: Comments
description: Supports 4 comment systems： Giscus, Waline, Twikoo, Artalk<br>You can freely choose the comment system that suits your needs.
-
title: Search
description: Supports local search based on minisearch, and also supports Algolia search.
-
title: Encryption
description: Supports full-site encryption and partial encryption (encrypted directories, encrypted articles).
-
title: Code
description: Code copying, CodePen demonstration, JSFiddle demonstration, CodeSandbox demonstration, code groups, line highlighting, line focusing, line warnings, difference comparison, code block folding, etc.
-
title: Resource Embedding
description: Charts：chart.js/ECharts/Mermaid/flowchart<br>Videos：Bilibili/Youtube/ArtPlayer<br>PDF, 200K+ Iconify icons
-
type: text-image
title: Blog
description: The theme supports blogs by default, allowing you to create your personal blog.
image: /images/plume-2.svg
list:
-
title: Article List
description: Automatically sorts and generates a blog article list page based on the article writing date.
-
title: Blogger Information
description: Customize name, motto, avatar, and social media links.
-
title: Categories, Tags, Archives
description: Automatically generates category pages, tag pages, and archives articles by year.
-
type: image-text
title: Documentation
image: /images/plume-3.svg
description: The theme supports documentation by default, allowing you to create product documentation or organize your knowledge system.
list:
-
title: Sidebar
description: Automatically generates a sidebar based on the documentation directory, or you can manually configure it. The theme provides a simpler configuration method.
-
title: Documentation Classification
description: You can categorize different documents into different directories for better management of the documentation structure.
-
type: custom
---
Todo...
<div style="max-width: 960px;margin:0 auto;" class="home-custom-content">
::: center
![GitHub Repo stars](https://img.shields.io/github/stars/pengzhanbo/vuepress-theme-plume)
![npm version](https://img.shields.io/npm/v/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&label=npm)
![npm downloads](https://img.shields.io/npm/dm/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&label=downloads)
![npm downloads](https://img.shields.io/npm/dt/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&label=downloads)
![github license](https://img.shields.io/github/license/pengzhanbo/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A)
![peer dependency](https://img.shields.io/npm/dependency-version/vuepress-theme-plume/peer/vuepress?color=32A9C3&labelColor=1B3C4A)
![codecov](https://codecov.io/gh/pengzhanbo/vuepress-theme-plume/graph/badge.svg?token=W6KYBX7WO5)
:::
### Installation
:::code-tabs
@tab pnpm
```sh
pnpm add vuepress@next vuepress-theme-plume vue
```
@tab npm
```sh
npm install vuepress@next vuepress-theme-plume
```
@tab yarn
```sh
yarn add vuepress@next vuepress-theme-plume
```
:::
### Configuration
::: code-tabs
@tab .vuepress/config.ts
```ts :no-line-numbers
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
// vuepress config...
theme: plumeTheme({
// theme config...
})
})
```
:::
### Update Log
[Changelog](../changelog)
### Contributors
<Contributors
:contributors="[
'pengzhanbo',
{ github: 'huankong233', name: 'huan_kong' },
{ github: 'northword', name: 'Northword' },
'KrLite',
'shylock-wu',
'hrradev',
{ github: 'TheCoderAlex', name: 'Tang Zifeng' },
{ github: 'HydroGest', name: 'MarkChai' },
{ github: 'sunnyboy-mu', name: '小沐沐吖' },
{ github: 'zhenghaoyang24', name: 'zhenghaoyang24' },
]"
/>
</div>
<style>
.home-custom-content img {
cursor: default !important;
}
</style>

17
docs/en/notes/theme/config/basic.md Normal file
View File

@ -0,0 +1,17 @@
---
title: Theme Configuration
createTime: 2025/03/03 14:27:13
permalink: /en/config/basic/
---
todo ...
## Basic Configuration
### autoFrontmatter
### article
### blog
## Locales Configuration

12
docs/en/notes/theme/config/frontmatter/article.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Blog Article
author: pengzhanbo
createTime: 2025/03/03 19:11:37
permalink: /en/config/frontmatter/article/
---
## Configuration
### sticky
todo ...

9
docs/en/notes/theme/config/frontmatter/basic.md Normal file
View File

@ -0,0 +1,9 @@
---
title: General configuration
author: pengzhanbo
createTime: 2025/03/04 12:30:38
permalink: /en/config/frontmatter/basic/
badge: badge
---
todo ...

7
docs/en/notes/theme/config/locales.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Multilingual Configuration
createTime: 2025/03/04 13:23:51
permalink: /en/config/locales/
---
todo ...

12
docs/en/notes/theme/config/notes.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Notes Configuration
author: pengzhanbo
createTime: 2025/03/03 14:44:18
permalink: /en/config/notes/
---
## Configuration
### Auto Generated Sidebar
todo ...

489
docs/en/notes/theme/guide/blog.md Normal file
View File

@ -0,0 +1,489 @@
---
title: Blog
icon: material-symbols:article-outline
createTime: 2025/03/04 12:15:40
permalink: /en/guide/blog/
tags:
- Guide
- Quick Start
---
<script setup lang="ts">
import VPBlogProfile from 'vuepress-theme-plume/components/Blog/VPBlogProfile.vue'
import VPPostItem from 'vuepress-theme-plume/components/Blog/VPPostItem.vue'
</script>
## Overview
By default, the theme will treat all md files in the [documentation source directory](./project-structure.md#documentation-source-directory) as blog posts, except for specific directories (e.g., the `notes` directory, which is used for notes).
The theme will also categorize blog posts based on the directory structure of the md files, using the **directory name** as the **category** of the blog post.
The theme will automatically generate a blog post list page with the link address `/blog/`, displaying all blog posts and relevant information about the blogger.
## Configuration
The blog feature is enabled by default in the theme, and you usually do not need to perform additional configurations.
::: code-tabs
@tab .vuepress/config.ts
```ts
export default defineUserConfig({
theme: plumeTheme({
// Disable the blog feature
// blog: false,
blog: {
/**
* Configure included files via glob string,
* by default, it reads all `.md` files in the source directory, but excludes directories used for notes in the `notes` configuration.
*/
include: ['**/*.md'],
// If you want to only read articles from a specific directory in the source directory, such as the `blog` directory, you can configure it as:
// include: ['blog/**/*.md'],
/**
* Configure excluded files via glob string, relative to the source directory
*/
exclude: ['.vuepress/', '**/README.md'],
// Disable pagination
// pagination: false,
// Number of articles displayed per page
pagination: 15,
}
})
})
```
:::
## Blogger Information
The theme supports displaying basic information about the blogger.
<div
style="width: 310px;margin: 0 auto;padding: 20px 20px 1px;text-align:center;border-radius: 4px;
background-color: var(--vp-c-bg-soft);transition: background-color var(--vp-t-color);"
>
<VPBlogProfile />
</div>
### Configuration
You can set the blogger's avatar and other related information through the `profile` attribute.
::: code-tabs
@tab .vuepress/config.ts
```ts
export default defineUserConfig({
theme: plumeTheme({
profile: {
name: 'Your Name',
description: 'Description text, motto/signature',
avatar: '/blogger.png',
location: 'Your Location',
organization: 'Your Organization',
circle: true, // Whether the avatar is circular
layout: 'right', // Whether the personal information is on the left or right, 'left' | 'right'
},
// Social links
social: [
{ icon: 'github', link: 'https://github.com/vuepress-theme-plume ' },
// ... more
]
})
})
```
:::
## Article Metadata
You can configure the display of blog post metadata, such as title, author, date, tags, etc. This data is configured through `frontmatter`.
```md
---
title: Article Title
createTime: 2024/01/01 00:00:00
tags:
- tag1
- tag2
---
```
Among them, `title` / `createTime` will be automatically filled in by the theme when creating a new md file, and you can modify them at will.
The following are the available `frontmatter` properties in blog posts.
| Property | Type | Default Value | Description |
| ----------- | --------------------------- | ------------------------- | --------------------------------------------------- |
| title | `string` | Automatically filled in with the filename | Article title |
| createTime | `string` | Current time | Article creation time |
| tags | `string[]` | `[]` | Article tags |
| sticky | `boolean \| number` | false | Whether to pin the article, if it's a number, the larger the number, the higher the pinning priority |
| draft | `boolean` | false | Whether it's a draft, draft articles will not be displayed |
| cover | `string` | `''` | Article cover image |
| coverStyle | `BlogPostCoverStyle` | `null` | Article cover image style |
| excerpt | `boolean \| string` | '' | Article excerpt, by default generated via `<!-- more -->` comment, passing a string indicates custom content, and it will no longer be extracted from the main text |
In addition to the above fields, you can also use the fields in the [general frontmatter configuration](../config/frontmatter/basic.md) to flexibly control the behavior of the current page.
## Article Excerpt
If you want to add an excerpt to an article, you can use the `<!-- more -->` comment to mark it. Any content before this comment will be considered as the excerpt.
**Example:**
```md
---
title: Title
---
This content will be used as the excerpt
<!-- more -->
This content will not be used as the excerpt
```
You can also use `frontmatter.excerpt` to control whether the article displays an excerpt and to customize the excerpt content.
- `frontmatter.excerpt` defaults to `false`, indicating that the excerpt is not displayed, and the `<!-- more -->` comment will be ignored.
- When `frontmatter.excerpt` is of type `string`, it indicates custom excerpt content, and the `<!-- more -->` comment will be ignored.
**Example:**
```md
---
title: Title
excerpt: Custom excerpt content
---
```
You can use different methods to control the excerpt of the article as needed.
::: tip The theme more strongly recommends using the `<!-- more -->` comment to add excerpts
:::
## Article Cover Image
On the blog post list page, the theme supports adding cover images to articles and supports different layouts and flexible size configurations.
To add a cover image to a blog post, you can configure `cover` in `frontmatter`:
```md
---
title: Title
cover: /images/cover.jpg # [!code ++]
---
```
**Cover images** only support absolute paths or remote paths. When using an absolute path, the image is loaded from the `.vuepress/public` directory.
::: file-tree
- docs
- .vuepress
- public
- images
- cover.jpg
- config.ts
- article.md
- …
:::
The default effect is as follows:
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--vp-t-color)">
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ' }"
:index="1"
/>
</div>
You can also adjust the layout position and aspect ratio of the cover image:
```md
---
title: Article Title
cover: /images/cover.jpg # [!code ++:5]
coverStyle:
layout: left
ratio: 16:9
width: 300
---
```
The effect is as follows:
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--vp-t-color)">
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ', coverStyle: { layout: 'left', ratio: '16:9', width: 300 } }"
:index="1"
/>
</div>
When an article has no excerpt, it may look a bit empty. To address this, you can use `compact: true` to make the cover image fit the container edges, making the overall layout more compact:
```md
---
title: Article Title
cover: /images/cover.jpg # [!code ++:6]
coverStyle:
layout: left
ratio: 16:9
width: 300
compact: true
---
```
The effect is as follows:
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--vp-t-color)">
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ',
coverStyle: { layout: 'left', ratio: '16:9', width: 300, compact: true } }"
:index="1"
/>
</div>
::: warning compact: true only takes effect when the article has no excerpt
:::
You can also set the cover image above the title, which becomes a large image style:
```md
---
title: Article Title
cover: /images/cover.jpg # [!code ++:5]
coverStyle:
layout: top
ratio: 16:9
width: 300
---
```
The effect is as follows:
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--vp-t-color)">
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ',
coverStyle: { layout: 'top', ratio: '16:9', width: 300 } }"
:index="1"
/>
</div>
### Preset Configuration
Although the theme supports using different configurations for each article's cover image, for the sake of overall layout style and to simplify configuration, the theme also supports preset configurations for cover images:
::: code-tabs
@tab .vuepress/config.ts
```ts
export default defineUserConfig({
theme: plumeTheme({
blog: {
// Configure the layout position of the cover image
// postCover: 'left', // 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
postCover: {
layout: 'left',
ratio: '16:9',
width: 300,
compact: true
}
}
})
})
```
:::
```ts
type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
interface BlogPostCoverStyle {
/**
* The position of the blog post cover image
*/
layout?: BlogPostCoverLayout
/**
* The aspect ratio of the blog post cover image
*
* @default '4:3'
*/
ratio?: number | `${number}:${number}`
/**
* The width of the cover image, only effective when layout is 'left' or 'right'
*
* @default 240
*/
width?: number
/**
* Whether to use compact mode, in compact mode, the cover image fits the container edges
* @default false
*/
compact?: boolean
}
```
You may have noticed that in the preset configuration's `layout`, there are also two configurations supported: `odd-left` and `odd-right`.
- `odd-left`: Indicates that odd items are on the left and even items are on the right
- `odd-right`: Indicates that odd items are on the right and even items are on the left
For example, the effect of `odd-left` is as follows:
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;display: flex;flex-direction: column;gap: 24px;transition: var(--vp-t-color)">
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ',
coverStyle: { layout: 'odd-left', ratio: '16:9', width: 300, compact: true } }"
:index="0"
/>
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ',
coverStyle: { layout: 'odd-left', ratio: '16:9', width: 300,compact: true } }"
:index="1"
/>
<VPPostItem
:post="{ path: '/article/ecxnxxd0/', title: 'Article Title',
categoryList: [{id:'65f30c',sort:4,name:'Tutorial'}], createTime: '2024/09/18 09:19:36',
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing ',
coverStyle: { layout: 'odd-left', ratio: '16:9', width: 300, compact: true } }"
:index="2"
/>
</div>
::: warning Note
When on narrow screens of mobile devices, for visual effect considerations, the `layout` configuration is forcibly reset to `top`.
:::
## Tag Page, Category Page, and Archive Page
In addition to automatically generating the **blog post list page**, the theme will also automatically generate **tag pages**, **category pages**, and **archive pages**.
The tag page can filter and display blog posts based on tags, with the default address being `/blog/tags/`
The category page can display blog posts based on the original directory structure, with the default address being `/blog/categories/`
The archive page archives articles based on their creation time, with the default address being `/blog/archives/`
## Internationalization Support
If internationalization is enabled, the blog list page will display the blog list of the corresponding language directory based on different languages. That is, the article list of each language is kept independent.
Specifically, if one of your blog posts has different language versions, ensure that the same directory file structure and filename exist under different language directories. When switching languages, the theme can correctly switch to the corresponding language article.
::: file-tree
- docs
- en
- my-article.md
- fr
- my-article.md
- my-article.md
:::
## Setting the Blog as the Homepage
By default, the theme separates the **homepage** and the **blog page**.
However, for users who want to build only a blog site, it might be a better choice to directly set the blog page as the **homepage**.
The theme provides two ways to set the blog as the homepage to meet different scenario needs:
- **Method One: Configure the `pageLayout` attribute of the homepage to `blog`**
::: code-tabs
@tab docs/README.md
```md
---
pageLayout: blog
---
```
:::
This configuration will directly apply the blog layout to the page, displaying the blog post list.
This is the simplest way to modify the homepage to a blog page, but the downside is the lack of flexibility.
- **Method Two: Configure the `pageLayout` attribute of the homepage to `home`, and add a homepage area type of `type: blog`**
::: code-tabs
@tab docs/README.md
```md
---
pageLayout: home
config:
- type: blog
---
```
:::
With this method, you can not only add a blog post list to the homepage but also flexibly add different content to other areas of the page.
For example, configure the first screen as `banner`, followed by the blog post list:
::: code-tabs
@tab docs/README.md
```md
---
pageLayout: home
config:
- type: banner
- type: blog
---
```
:::
For more customization configurations, please refer to [Customize the Homepage](./custom-home.md).
After using the above two methods to configure the homepage as the blog page, since the theme still generates the blog post list page with the address `/blog/` by default, this results in duplicate functional pages. Therefore, you need to [Theme Configuration > Blog Configuration](../config/basic.md#blog) to **disable the automatic generation of the blog post list page**:
(You can also modify the link addresses of the category page/tag page/archive page)
::: code-tabs
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
blog: {
postList: false, // Prevent the generation of the blog post list page
// tagsLink: '/blog/tags/',
// categoriesLink: '/blog/categories/',
// archiveLink: '/blog/archives/',
}
})
})
```
:::

8
docs/en/notes/theme/guide/custom-home.md Normal file
View File

@ -0,0 +1,8 @@
---
title: Customize Homepage
icon: material-symbols:home-outline
createTime: 2025/03/04 12:40:11
permalink: /en/guide/custom-home/
---
todo ...

271
docs/en/notes/theme/guide/deployment.md Normal file
View File

@ -0,0 +1,271 @@
---
title: Deployment
icon: material-symbols:deployed-code-outline
createTime: 2025/03/04 13:31:42
permalink: /en/guide/deployment/
tags:
- Guide
- Deployment
---
::: tip
This document is forked from the [vuepress official doc](https://v2.vuepress.vuejs.org/zh/guide/deployment.html).
:::
The following guide is based on the following conditions:
- The Markdown source files are placed in the `docs` directory of your project;
- The default build output directory (`.vuepress/dist`) is used;
- [pnpm](https://pnpm.io/zh/) is used as the package manager, although npm or yarn is also supported;
- VuePress is installed as a project dependency, and the following script is configured in `package.json`:
```json
{
"scripts": {
"docs:build": "vuepress build docs"
}
}
```
## GitHub Pages
1. Set the correct [base](https://v2.vuepress.vuejs.org/zh/reference/config.html#base) option.
If you are going to publish to `https://<USERNAME>.github.io/`, you can skip this step because the default `base` is `"/"`.
If you are going to publish to `https://<USERNAME>.github.io/<REPO>/`, which means your repository address is `https://github.com/<USERNAME>/<REPO>`, set `base` to `"/<REPO>/"`.
2. Choose the CI tool you want to use. Here we take [GitHub Actions](https://github.com/features/actions) as an example.
Create the `.github/workflows/docs.yml` file to configure the workflow.
::: details Click to expand the configuration example
```yaml
name: docs
on:
# Trigger deployment whenever a push is made to the main branch
push:
branches: [main]
# Manually trigger deployment
workflow_dispatch:
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
# To fetch all commit history for "Last updated time" and other git log information
fetch-depth: 0
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
# Choose the pnpm version to use
version: 8
# Install dependencies using pnpm
run_install: true
- name: Setup Node.js
uses: actions/setup-node@v4
with:
# Choose the node version to use
node-version: 20
# Cache pnpm dependencies
cache: pnpm
# Run the build script
- name: Build VuePress site
run: pnpm docs:build
# See the workflow documentation for more information
# @see https://github.com/crazy-max/ghaction-github-pages
- name: Deploy to GitHub Pages
uses: crazy-max/ghaction-github-pages@v4
with:
# Deploy to the gh-pages branch
target_branch: gh-pages
# The deployment directory is the default output directory of VuePress
build_dir: docs/.vuepress/dist
env:
# @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
:::
::: tip
Please refer to the [GitHub Pages official guide](https://pages.github.com/) for more information.
:::
## GitLab Pages
1. Set the correct [base](https://v2.vuepress.vuejs.org/zh/reference/config.html#base) option.
If you are going to publish to `https://<USERNAME>.gitlab.io/`, you can skip this step, so the default `base` is `"/"`.
If you are going to publish to `https://<USERNAME>.gitlab.io/<REPO>/`, which means your repository address is `https://gitlab.com/<USERNAME>/<REPO>`, set `base` to `"/<REPO>/"`.
2. Create the `.gitlab-ci.yml` file to configure the [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) workflow.
::: details Click to expand the configuration example
```yaml
# Choose the docker image you want to use
image: node:18-buster
pages:
# Trigger deployment whenever a push is made to the main branch
only:
- main
# Cache node_modules
cache:
key:
files:
- pnpm-lock.yaml
paths:
- .pnpm-store
# Install pnpm
before_script:
- curl -fsSL https://get.pnpm.io/install.sh | sh -
- pnpm config set store-dir .pnpm-store
# Install dependencies and run the build script
script:
- pnpm install --frozen-lockfile
- pnpm docs:build --dest public
artifacts:
paths:
- public
```
:::
::: tip
Please refer to the [GitLab Pages official guide](https://docs.gitlab.com/ce/user/project/pages/#getting-started) for more information.
:::
## Google Firebase
1. Ensure you have installed [firebase-tools](https://www.npmjs.com/package/firebase-tools).
2. Create `firebase.json` and `.firebaserc` in the root directory of your project with the following content:
`firebase.json`:
```json
{
"hosting": {
"public": "./docs/.vuepress/dist",
"ignore": []
}
}
```
`.firebaserc`:
```json
{
"projects": {
"default": "<YOUR_FIREBASE_ID>"
}
}
```
3. After running `pnpm docs:build`, use the `firebase deploy` command to deploy.
::: tip
Please refer to the [Firebase CLI official guide](https://firebase.google.com/docs/cli) for more information.
:::
## Heroku
1. First, install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli);
2. [Sign up](https://signup.heroku.com) for a Heroku account here;
3. Run `heroku login` and enter your Heroku credentials:
```bash
heroku login
```
4. In the root directory of your project, create a file named `static.json` with the following content:
`static.json`:
```json
{
"root": "./docs/.vuepress/dist"
}
```
This is the configuration for your project. For more information, please refer to [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
## Kinsta
Please see [Set Up VuePress on Kinsta](https://kinsta.com/docs/vuepress-application/).
## Edgio
Please see [Edgio Documentation > Framework Guides > VuePress](https://docs.edg.io/guides/vuepress).
## Netlify
1. Go to [Netlify](https://netlify.com), create a new project from GitHub, and configure as follows:
- **Build Command:** `pnpm docs:build`
- **Publish directory:** `docs/.vuepress/dist`
2. Set [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) to select the Node version:
- `NODE_VERSION`: 18
3. Click the deploy button.
## Vercel
1. Go to [Vercel](https://vercel.com), create a new project from GitHub, and configure as follows:
- **FRAMEWORK PRESET:** `Other`
- **BUILD COMMAND:** `pnpm docs:build`
- **OUTPUT DIRECTORY:** `docs/.vuepress/dist`
2. Click the deploy button.
## CloudBase
[CloudBase](https://cloudbase.net/?site=vuepress) is a cloud-native integrated Serverless cloud platform that supports multiple hosting capabilities such as static websites and containers, and provides a simple deployment tool [CloudBase Framework](https://cloudbase.net/framework.html?site=vuepress) to deploy applications with one click.
1. Install CloudBase CLI globally:
```bash
pnpm install -g @cloudbase/cli
```
2. Run the following commands in the root directory of your project to deploy the VuePress application with one click. Before deployment, you can first [activate the environment](https://console.cloud.tencent.com/tcb/env/index?tdl_anchor=ad&tdl_site=vuejs):
```bash
cloudbase init --without-template
cloudbase framework:deploy
```
The CloudBase CLI will first redirect to the console for login authorization, and then interactively confirm.
After confirming the information, deployment will start immediately. After deployment, you will obtain a website application with automatic SSL and CDN acceleration. You can also use GitHub Action to continuously deploy VuePress applications on GitHub.
You can also use `cloudbase init --template vuepress` to quickly create and deploy a new VuePress application.
::: tip
For more detailed information, please see the [deployment project example](https://github.com/TencentCloudBase/cloudbase-framework?site=vuepress#%E9%A1%B9%E7%9B%AE%E7%A4%BA%E4%BE%8B) of CloudBase Framework.
:::
## 21 Cloud Box
Please see [21 Cloud Box - Deploy a VuePress Static Web Page](https://www.21yunbox.com/docs/#/deploy-vuepress).

628
docs/en/notes/theme/guide/document.md Normal file
View File

@ -0,0 +1,628 @@
---
title: Documents/Notes
icon: teenyicons:doc-outline
createTime: 2025/03/04 12:52:47
permalink: /en/guide/document/
tags:
- Guide
- Quick Start
---
## Overview
The theme provides a `notes` feature, which is used to aggregate articles from the same series or serve as the site's **sub-documentation**.
"Notes" are organized based on the file structure. By default, the `notes/` directory is used as the root directory. Documents stored under the `notes` directory will not be treated as blog posts and will not appear on the blog post list page.
## File Structure and Configuration
In one of our projects, we have the following file structure:
::: file-tree
- docs
- notes
- typescript \# Typescript notes
- basic.md
- types.md
- rust \# Rust notes
- tuple.md
- struct.md
- blog-post.md \# Blog post
- README.md \# Site home page
:::
Under the `docs/notes` directory, there are two subdirectories for storing the series content of `typescript` and `rust`, respectively.
Next, configure `notes` in the configuration file:
::: code-tabs
@tab .vuepress/config.ts
```js
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
notes: {
// Declare the directory for all notes, (default configuration, usually you don't need to declare it)
dir: '/notes/',
link: '/', // Declare the default link prefix for all notes, default is '/' (default configuration, usually you don't need to declare it)
notes: [
// Each note is an object in the `notes` array
{
// Declare the note's directory, relative to `notes.dir`, here it represents the `notes/typescript` directory
dir: 'typescript',
// Declare the note's link prefix, concatenated with `notes.link`, here it represents `/typescript/`
// All articles within the note will use `/typescript/` as the access link prefix.
link: '/typescript/',
// Configure the note's sidebar navigation, used to navigate all documents within the note
// Declared as `auto`, the sidebar navigation will be automatically generated based on the directory structure
sidebar: 'auto'
},
{
dir: 'rust',
link: '/rust/',
sidebar: [
{ text: 'Introduction', items: ['foo'] }
]
}
]
}
})
})
```
:::
::: tip
It is recommended to configure the note's directory and link prefix before creating files.
The theme has enabled [auto-frontmatter](../config/basic.md#autofrontmatter) by default,
which needs to generate permanent links and sidebars for md files in the directory based on the configuration.
:::
## Writing Notes Configuration
Since writing all `notes` configurations inside `plumeTheme({ })` may cause the code nesting to be too deep, it is more recommended to use the `defineNotesConfig()` and `defineNoteConfig()` provided by the theme to extract the notes configuration to the outside. They can also help you get better type hints, making it more readable and easier to maintain.
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig, defineNotesConfig } from 'vuepress-theme-plume'
/**
* Configure a single note
*/
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
'/guide/intro.md',
'/guide/getting-start.md',
'/config/config-file.md',
]
})
/**
* Configure notes
*/
export default defineNotesConfig({
// Declare the directory for all notes, (default configuration, usually you don't need to declare it)
dir: '/notes/',
link: '/',
// Add note configurations here
notes: [typescript] // [!code ++]
})
```
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import notes from './notes' // [!code ++]
export default defineUserConfig({
theme: plumeTheme({
notes // [!code ++]
}),
})
```
:::
:::: details How to configure when there are many notes?
If you have a large number of notes and putting them all in one `notes.ts` file may make the file too large and difficult to maintain,
you can split the files, using the `.vuepress/notes/` directory as the directory for note configurations.
::: file-tree
- docs
- .vuepress
- notes
- typescript.ts
- rust.ts
- index.ts
- …
- notes
- typescript/
- rust/
:::
The code is as follows:
::: code-tabs
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import notes from './notes/index.ts' // [!code ++]
export default defineUserConfig({
theme: plumeTheme({
notes // [!code ++]
}),
})
```
@tab .vuepress/notes/index.ts
```ts
import { defineNotesConfig } from 'vuepress-theme-plume'
import rust from './rust' // [!code ++]
import typescript from './typescript' // [!code ++]
export default defineNotesConfig({
// Declare the directory for all notes, (default configuration, usually you don't need to declare it)
dir: '/notes/',
link: '/',
// Add note configurations here
notes: [ // [!code ++:4]
typescript,
rust,
]
})
```
@tab .vuepress/notes/typescript.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
export default defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
'/guide/intro.md',
'/guide/getting-start.md',
'/config/config-file.md',
]
})
```
@tab .vuepress/notes/rust.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
export default defineNoteConfig({
dir: 'rust',
link: '/rust/',
sidebar: [
'/guide/intro.md',
'/guide/getting-start.md',
'/config/config-file.md',
]
})
```
:::
::::
### Sidebar Configuration
Taking the `typescript` directory as an example, it has the following file structure:
::: file-tree
- typescript
- guide
- intro.md
- getting-start.md
- config
- config-file.md
- configuration.md
- reference
- basic.md
- syntax.md
- modules.md
- built-in
- types
- Required.md
- Omit.md
- README.md
:::
#### Automatically Generating Sidebar
The simplest configuration method is `sidebar: 'auto'`, the theme will automatically generate the sidebar based on the file structure and sort it according to the encoding of the first character.
If you want to modify the order of the automatically generated sidebar, you can add prefixes such as `1.` or `2.` before the directory name or file name.
::: file-tree
- typescript
- 1.guide
- 1.intro.md
- 2.getting-start.md
- 2.config
- 1.config-file.md
- 2.configuration.md
- …
:::
The theme will sort based on the numbers in these prefixes, and the prefix part will not be displayed in the sidebar.
#### Customizing the Sidebar
Sometimes, automatically generating the sidebar may not fully meet the requirements, and you can customize the sidebar.
Here is the type definition for the sidebar:
```ts
type Sidebar = (string | SidebarItem)[]
interface SidebarItem {
/**
* Sidebar text
*/
text?: string
/**
* Sidebar link
*/
link?: string
/**
* Sidebar icon
*/
icon?: ThemeIcon
/**
* The link prefix for the current group, the link prefix will be concatenated before the `link` in `items`
* It will only be concatenated when the `link` in `items` is a relative path
*/
prefix?: string
/**
* Subordinate sidebar groups
*/
items?: 'auto' | (string | SidebarItem)[]
/**
* If not specified, the group is not collapsible.
* If `true`, the group is collapsible and defaults to collapsed.
* If `false`, the group is collapsible but defaults to expanded.
*/
collapsed?: boolean
}
```
When the type passed in is `string`, it represents the path to a markdown file:
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
'/guide/intro.md',
'/guide/getting-start.md',
'/config/config-file.md',
// …
]
})
// … other code
```
:::
You can also omit the `.md` file suffix and abbreviate it to `/guide/intro`. The theme will parse the corresponding file, obtain the **title** and **page link address**, and convert it into the data format of `{ text: string, link: string }`.
When the type passed in is `SidebarItem`:
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{ text: 'Introduction', link: '/guide/intro' },
{ text: 'Quick Start', link: '/guide/getting-start' },
// …
]
})
// … other code
```
:::
You can also nest multiple levels:
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
text: 'Guide',
prefix: '/guide', // Use prefix to concatenate, you can abbreviate the link in the items below to a relative path
items: [
// You can mix string and SidebarItem
{ text: 'Introduction', link: 'intro' },
'getting-start',
],
},
{
text: 'Configuration',
prefix: '/config',
items: 'auto', // items is 'auto', the sidebar will be automatically generated based on the file structure of prefix
},
]
})
// … other code
```
:::
### About `prefix`
The purpose of `prefix` is to abbreviate the links in the same level `items` by extracting the common prefix to `prefix`, allowing the theme to complete the full link concatenation for you.
It should be noted that only relative path links in `items` will be concatenated with `prefix`, while absolute paths will not be processed.
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
prefix: '/guide',
items: [
'intro', // Relative path, finally concatenated to /guide/intro
'/config/config-file', // Absolute path, not concatenated
{
text: 'Blog',
link: 'blog', // Relative path, finally concatenated to /guide/blog
},
{
text: 'Configuration',
link: '/config', // Absolute path, not concatenated
}
]
}
]
})
```
:::
At the same time, deep nesting is also supported within `items`, and `prefix` is still supported inside, following the same rules. If `prefix` is a relative path, it will be concatenated with the `prefix` of the upper level, and then with the `link` in the current level `items`. If `prefix` is an absolute path, it will not be concatenated with the `prefix` of the upper level.
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
prefix: '/guide',
items: [
'intro', // Relative path, finally concatenated to /guide/intro
{
prefix: '/config',
items: [
'config-file', // Relative path, finally concatenated to /config/config-file
'configuration', // Relative path, finally concatenated to /config/configuration
]
},
{
prefix: 'blog',
items: [
'intro', // Relative path, finally concatenated to /guide/blog/intro
'getting-start', // Relative path, finally concatenated to /guide/blog/getting-start
]
}
]
}
]
})
```
:::
**The criterion for whether it is an absolute path is that if it starts with `/`, it is an absolute path; otherwise, it is a relative path.**
:::warning
It is not recommended to have too many levels in the sidebar. Sidebars with more than 3 levels may lead to poor UI effects.
:::
### Sidebar Icons
Adding icons to the sidebar helps to better present the sidebar. Thanks to the powerful open-source icon library [iconify](https://iconify.design/), you can use over `200k` icons by simply adding the `icon` configuration.
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
text: 'Guide',
prefix: '/guide',
icon: 'ep:guide', // iconify icon name // [!code hl]
items: [
{ text: 'Introduction', link: 'intro', icon: 'ph:info-light' }, // [!code hl]
],
},
]
})
```
:::
You can also use local icons or local images:
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
text: 'Guide',
prefix: '/guide',
icon: '/images/guide.png', // iconify icon name // [!code hl]
items: [
{ text: 'Introduction', link: 'intro', icon: '/images/info.png' }, // [!code hl]
// It can also be a remote image
{ text: 'Quick Start', link: 'getting-start', icon: 'https://cn.vuejs.org/images/logo.png ' },
],
},
]
})
```
:::
**Please note that using local images must start with `/`, indicating a static resource path, which will be loaded from the `.vuepress/public/` directory.**
::: file-tree
- docs
- .vuepress
- public \# Save static resources in this location
- images
- guide.png
- info.png
- …
:::
You may have noticed how to configure sidebar icons when `sidebar: auto`. In fact, it's very simple. Just add an `icon` field in the `frontmatter` section of the file.
::: code-tabs
@tab typescript/guide/intro.md
```md
---
title: Introduction
icon: ep:guide
---
```
:::
### Sidebar Group Internal Separation
Separating items within a group is a relatively niche requirement. It may be more applicable when there are many items in a group, but it is not suitable to split them into multiple groups, or when it is not suitable to split the group into multiple subgroups. It provides a way to use auxiliary text color to display a separator item name at the same level, for simple separation of items.
::: code-tabs
@tab .vuepress/notes.ts
```ts
import { defineNoteConfig } from 'vuepress-theme-plume'
const typescript = defineNoteConfig({
dir: 'typescript',
link: '/typescript/',
sidebar: [
{
text: 'Guide',
items: [
'Project 1',
'Project 2',
'Project 3',
{ text: 'Separator', link: '---' }, // [!code ++]
'Project 4',
'Project 5',
// …
],
},
]
})
```
:::
It is very simple to complete the separation within a group. You just need to insert a `{ text: 'xxxx', link: '---' }` at the appropriate position. The key is to set the `link` to consecutive `---`, at least three `-`. You can define the text arbitrarily and also add icons.
## Note Home Page
You may have noticed that there is a `README.md` file in the `typescript` directory, which will be displayed as the note home page.
::: file-tree
- typescript
- README.md
- …
- …
:::
By default, it is no different from ordinary documentation pages because the theme sets `pageLayout: docs` for all pages by default.
But you can directly configure `pageLayout: 'home'`, just like configuring the [site home page](./custom-home.md), to customize a home page for the note!
::: code-tabs
@tab typescript/README.md
```md
---
pageLayout: home
config:
- type: hero
- type: features
---
```

162
docs/en/notes/theme/guide/international.md Normal file
View File

@ -0,0 +1,162 @@
---
title: Internationalization
icon: material-symbols-light:language
createTime: 2025/03/04 13:12:03
permalink: /en/guide/international/
tags:
- Guide
- i18n
---
Implementing ==internationalization== in the theme only requires some simple configurations.
Let's take an example of creating a project with **Chinese** as the default language and including **English** and **French**.
## Directory Structure
First, you need to create a directory structure similar to the following:
::: file-tree
- docs
- **en** \# English directory
- foo.md
- README.md \# English home page
- **fr** \# French directory
- foo.md
- README.md \# French home page
- foo.md
- README.md \# Chinese home page
:::
Here, `docs/en/` is used to store **English** documents, `docs/fr/` stores **French** documents, and **Chinese** documents are stored directly under `docs/`.
::: important Consistent directory and file names across languages
Try to keep the file names and directory names consistent across different language directories. This helps the theme correctly navigate to different language versions of the article when switching languages.
:::
## VuePress Configuration
### Default Language
In `.vuepress/config.ts`, declare the default language:
::: code-tabs
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
// Declare the default language
lang: 'zh-CN', // [!code ++]
// Locales supported under multilingual
locales: {
'/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
}
})
```
:::
### Adding Other Languages
You need to set the `lang` option for each language. Even if you are only using a single language, you must set `lang` in `.vuepress/config.{js,ts}`.
::: tip Why do this?
To provide the correct locale text, the theme needs to know which language is being used in the root folder and each multilingual folder.
:::
Configure in `.vuepress/config.ts`:
::: code-tabs
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
// Declare the default language
lang: 'zh-CN',
// Locales supported under multilingual
locales: {
// Configure languages under different paths
'/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
'/en/': { lang: 'en-US', title: 'Blog' }, // English // [!code ++]
'/fr/': { lang: 'fr-FR', title: 'Le blog' }, // French // [!code ++]
}
})
```
:::
The `key` in the `locales` configuration acts as the `localePath`, corresponding to the language path under the `docs` directory, and should have the same naming.
At the same time, the `key` (`localePath`) will also serve as the prefix for the page access links of different languages.
::: important Language codes
The `key` in the `locales` configuration, i.e., `localePath`, must comply with the [ISO 639](https://zh.wikipedia.org/wiki/ISO_639-1) standard. For non-default languages, such as **English**, it should be `/en/`.
In `locales[localePath]`, `lang` is the **language code** for the current language. Please use the standard [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code. For example, **English** should be `en-US` (indicating English (United States)).
:::
## Theme Configuration
In the theme configuration, the `locales` configuration item is also used for multilingual configuration.
`locales` supports all theme configuration items.
::: code-tabs
@tab .vuepress/config.ts
```js
import { plumeTheme } from '@vuepress-plume/vuepress-theme-plume'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
lang: 'zh-CN',
locales: {
'/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
'/en/': { lang: 'en-US', title: 'Blog' }, // English
'/fr/': { lang: 'fr-FR', title: 'Le blog' }, // French
},
theme: plumeTheme({
// Multilingual configuration within the theme
locales: {
'/': { // [!code hl]
// The text displayed in the navigation bar language dropdown menu for the current language
selectLanguageName: '简体中文',
navbar: [
{ text: '首页', link: '/' },
{ text: '博客', link: '/blog/' },
]
},
'/en/': { // [!code hl]
selectLanguageName: 'English',
navbar: [
{ text: 'Home', link: '/en/' },
{ text: 'Blog', link: '/en/blog/' },
]
},
'/fr/': { // [!code hl]
selectLanguageName: 'Français',
navbar: [
{ text: 'Accueil', link: '/fr/' },
{ text: 'Le Blog', link: '/fr/blog/' },
]
}
}
})
})
```
:::
The `key` in the theme `theme.locales` configuration should be consistent with the `key` in the `locales` configuration of `vuepress`.
You should configure `selectLanguageName` for `theme.locales[localePath]` to display the name of the current language in the navigation bar language dropdown menu.
For more `locales` configuration, please refer to
- [Theme Configuration > Locales Configuration](../config/basic.md#locales-configuration) - Configure the behavior of the theme under different languages.
- [Theme Configuration > Multilingual Configuration](../config/locales.md) - Configure text related to languages.

65
docs/en/notes/theme/guide/intro.md
View File

@ -1,8 +1,71 @@
---
title: Theme Introduction
author: pengzhanbo
icon: mdi:tooltip-text-outline
createTime: 2024/03/04 11:06:24
permalink: /en/guide/intro/
tags:
- Guide
- Quick Start
---
Todo...
==vuepress-theme-plume== is a theme based on VuePress. Whether you want to write **lifestyle blogs**, **technical blogs**, or **product documentation**, **knowledge bases**, **series documentation**, etc., the theme can meet your needs.
The theme has made extensive optimizations for the presentation of text and image content, especially for the syntax of Markdown content. You can easily use these features to write **attractive, readable, and expressive** content.
::: details Not familiar with VuePress?
VuePress is a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG). It is designed to build fast, content-centric sites. In short, VuePress takes content written in Markdown, applies a theme to it, and generates static HTML pages that can be easily deployed anywhere.
:::
## Advantages
Compared to the default VuePress theme:
### Better User Experience
The interface and interaction have been greatly optimized, making it more beautiful, concise, and easy to use.
### More Features
- A flexible, fully customizable ==homepage==;
- Optional ==blog==, ==documentation==, ==knowledge notes==;
- Built-in support for ==full-text search==, ==article comments==, ==content encryption==, ==article watermarking==, etc.;
- ==Code blocks== can be grouped, folded, focused, highlighted by line, compared for differences, and you can embed CodePen, JSFiddle, CodeSandbox, etc., as ==code demonstrations==;
- Built-in support for [iconify](https://icon-sets.iconify.design/) **200k+** ==icons==;
- Support for embedding ==PDFs==, ==Bilibili/Youtube videos==;
- Support for chart.js, Echarts, Mermaid, flowchart, and other optional ==charts==;
- Flexible markdown container syntax, supports ==hint container==, ==file tree==, ==example container==, ==card container==, ==cascade container==, etc.;
- Support for ==layout slots==, ==component overrides==, ==custom styles==, etc., allowing you to flexibly extend components and achieve personalized layouts.
There are more features waiting for you to discover!
### Better Development Experience
Added compilation caching to cache the compilation of markdown files and the parsing results of complex code block content.
### Better Configuration
Supports using a separate theme configuration file to avoid frequent restarts of the VuePress service due to configuration changes.
The configuration has been greatly simplified, making it easier to use while still retaining rich and flexible configuration options to meet personalized needs.
### More
The ==plume theme== includes as many features as possible that you might need, as well as general configurations for building a site. You don't need to worry about these details. The goal is to allow you to focus more on content creation, better express your ideas, and enjoy the convenience of the enhanced Markdown syntax.
::: tip
This theme is based on [vuepress-next](https://github.com/vuepress/vuepress-next), and is currently in the RC stage.
The theme's features and API are stabilizing, but there is still a small probability of breaking changes in future updates.
If you encounter any issues or have new ideas while using the theme, please raise them in the [Issues](https://github.com/pengzhanbo/vuepress-theme-plume/issues). You are also welcome to help improve the theme through [PR](https://github.com/pengzhanbo/vuepress-theme-plume/pulls).

12
docs/en/notes/theme/guide/markdown/basic.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Basic
author: pengzhanbo
icon: fluent:markdown-20-filled
createTime: 2025/03/03 13:55:19
permalink: /en/guide/markdown/basic/
tags:
- Guide
- markdown
---
todo ...

12
docs/en/notes/theme/guide/markdown/extensions.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Extensions
author: pengzhanbo
icon: fluent-mdl2:auto-enhance-on
createTime: 2025/03/03 14:04:34
permalink: /en/guide/markdown/extensions/
tags:
- Guide
- markdown
---
todo ...

67
docs/en/notes/theme/guide/optimize-build.md Normal file
View File

@ -0,0 +1,67 @@
---
title: Build Optimization
icon: clarity:bundle-solid
outline: 2
createTime: 2025/03/05 16:06:03
permalink: /en/guide/optimize-build/
---
## Image Optimization <Badge type="warning" text="Experimental" />
When we embed images in markdown using `[alt](url)` or `<img src="url">`, the page displays the images as expected.
However, due to different image sizes, when images are small or network conditions are good, we may not notice significant layout shifts. When images are large or network conditions are poor, the layout can change noticeably as images load, causing other content to shift.
This experience is not user-friendly, especially with many images on a page. Frequent layout changes can cause noticeable jitter.
To stabilize the layout, images must be optimized. According to [MDN > img](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/img#height):
::: info
`<img>` with both `height` and `width` allows the browser to calculate the image's aspect ratio before loading. This reserves space for the image, reducing or preventing layout shifts during download and rendering. Reducing layout shifts is crucial for good user experience and web performance.
:::
Our theme provides a solution: automatically adding `width` and `height` attributes to `[alt](url)` or `<img src="url">` in markdown files.
Enable it by configuring `markdownPower`:
```ts
export default defineUserConfig({
theme: plumeTheme({
plugins: {
markdownPower: {
imageSize: true, // 'local' | 'all'
},
}
})
})
```
When enabled, the theme retrieves the original dimensions of images from their source URLs and adds `width` and `height` attributes.
- `'local'`: Only adds attributes to local images.
- `'all'`: Adds attributes to both local and remote images.
- `true`: Equivalent to `'local'`.
::: important
For performance reasons, this feature only takes effect during production build.
:::
::: important
Use `'all'` cautiously. It requests all remote images during production build, which can increase build time for sites with many images. The theme optimizes this by only requesting a few KB of data to analyze dimensions and processing images concurrently.
:::
## Icon Optimization
Thanks to the open-source project [iconify](https://icon-sets.iconify.design/), you can use approximately 200,000 icons in our theme.
However, this doesn't mean the theme needs to load all icons. You may have noticed the theme recommends installing the `@iconify/json` package locally, which requires downloading a 70Mb resource pack. Loading all icons into the documentation site would be excessively large.
But rest assured, the theme only loads the icon resources you actually use. This includes Iconify icons in navigation, sidebar, homepage Features, and icons used via the `:[collect:name]:` syntax or `<Icon name="icon_name" />` component.
When loading icons from local `@iconify/json`, iconify names icons by `[collect]:[name]`, with each collection containing 100 to 1000+ icons in a `json` file. Using many different `collect` icons can slow down initial loading and parsing. For example, our theme uses 54 `collect` collections with over 160 icons, taking about `500ms` to load and parse initially.
To optimize, the theme caches used icons on first launch. On subsequent launches, it优先从缓存加载图标， which is much faster than parsing different `collect` collections. This reduces loading time from `500ms` to `20ms` or less, also improving development server startup time!
::: info
Using 54 `collect` collections is extreme. While `500ms` for 54 I/O reads and JSON parses seems normal, it's unexpected for only 160+ icons. Caching these icons is a good solution.
:::

222
docs/en/notes/theme/guide/project-structure.md Normal file
View File

@ -0,0 +1,222 @@
---
title: Project Structure
icon: ph:tree-structure-bold
createTime: 2025/03/02 13:41:25
permalink: /en/guide/project-structure/
---
This guide will illustrate the file structure of a project created with VuePress and Plume, as well as how to utilize them within your project.
When you [create a project using the command-line tool](./quick-start.md#command-line-installation), its file structure looks like this:
::: file-tree
- .git/
- **docs** \# Documentation source directory
- .vuepress \# VuePress configuration folder
- public/ \# Static resources directory
- client.ts \# Client-side configuration (optional)
- config.ts \# VuePress configuration
- navbar.ts \# Navigation bar configuration (optional)
- notes.ts \# Notes configuration (optional)
- plume.config.ts \# Theme configuration file (optional)
- notes \# Series documentation, knowledge notes
- demo
- foo.md
- bar.md
- preview \# One of the blog categories
- markdown.md \# Blog post under the category
- article.md \# Blog post
- README.md \# Home page
- …
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
:::
::: tip If you created the project manually, you can also manage your project by referring to this file structure.
:::
## Documentation Source Directory
The **documentation source directory** refers to the directory where all your site's markdown files are located. This directory is generally specified when you start VuePress using the command-line tool:
```sh
# [!code word:docs]
vuepress dev docs
# Here, the documentation source directory is declared as docs
```
```json title="package.json"
{
"scripts": {
"docs:dev": "vuepress dev docs",
// ^^^^
"docs:build": "vuepress build docs"
// ^^^^
}
}
```
Generally, VuePress only takes over this directory, and other files outside the source directory will be ignored.
## `.vuepress` Directory
The `.vuepress/` directory is the VuePress configuration folder, where you can also create your own components, customize theme styles, etc.
**In this directory:**
### `client.ts`
Client-side configuration file, where you can extend VuePress's functionality, such as declaring new global components, etc.
::: code-tabs
@tab .vuepress/client.ts
```ts
import { defineClientConfig } from 'vuepress/client'
export default defineClientConfig({
enhance({ app, router, siteData }) {
// app: vue app instance
// router: vue router instance
// siteData: vuepress site configuration
// Register global components
app.component('MyComponent', MyComponent)
},
setup() {
// Equivalent to the setup method on the root component of vue
}
})
```
:::
### `config.ts`
The VuePress configuration file, where you need to make some necessary configurations, such as theme, plugins, build tools, etc.
::: code-tabs
@tab .vuepress/config.ts
```ts
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
lang: 'en-US',
theme: plumeTheme({
// more...
}),
bundler: viteBundler(),
})
```
:::
### `plume.config.ts`
Theme configuration file. Since modifying `.vuepress/config.ts` requires restarting the VuePress service each time, which is not necessary in most cases.
The theme moves the configurations that do not require restarting the service to here. When you modify the configuration here, the theme will be updated via hot reload.
::: code-tabs
@tab .vuepress/plume.config.ts
```ts
import { defineThemeConfig } from 'vuepress-theme-plume'
import navbar from './navbar'
import notes from './notes'
export default defineThemeConfig({
logo: '/logo.svg',
profile: {
name: 'Theme Plume',
},
navbar,
notes,
// ... more
})
```
@tab .vuepress/navbar.ts
```ts
import { defineNavbarConfig } from 'vuepress-theme-plume'
export default defineNavbarConfig([
// ...
])
```
@tab .vuepress/notes.ts
```ts
import { defineNotesConfig } from 'vuepress-theme-plume'
export default defineNotesConfig({
// ...
})
```
:::
## notes Directory
The **notes** directory is used to store your knowledge notes, series documentation, etc.
### How to Understand Knowledge Notes/Series Documentation?
A common scenario is that you are learning a skill and plan to record your learning experiences, key points, difficulties, etc., in your notes. In this case, you might write multiple documents for recording.
Alternatively, you are preparing for an interview and want to prepare interview questions and answers in advance. You might then have each question and answer as a separate document.
You would easily want to manage them all in a separate directory and, at the same time, be able to quickly navigate between different documents in the skill notes or between different interview questions in the generated documentation site.
This is a requirement that blog-type documentation cannot meet, and it is a pain point that `notes` aims to solve.
The above content can easily result in the following directory structure:
::: file-tree
- notes
- interview \# Interview questions
- Self-Introduction.md
- My-Skills.md
- Projects-Worked.md
- …
- typescript \# Learning notes
- Basics
- Basic-Types.md
- Generics.md
- …
- Advanced
- Functions.md
- …
:::
This allows for easy management of multiple series of documents, each with its own directory structure.
## Other Directories/Files
In the ==documentation source directory==, other directories and files, except for `README.md` which is recognized as the `home page`, will be identified as blog posts. The directory structure will be recognized as blog categories.
::: file-tree
- docs
- Life
- Travel-Diary.md
- …
- Study
- Exam-Notes.md
- …
- Work
- Tomato-Time.md
- …
- Miscellaneous.md \# Articles without categories
- README.md \# Home page
- …
:::

231
docs/en/notes/theme/guide/quick-start.md Normal file
View File

@ -0,0 +1,231 @@
---
title: Installation/Usage
icon: grommet-icons:install
createTime: 2025/03/02 13:28:45
permalink: /en/guide/quick-start/
tags:
- Guide
- Quick Start
---
<script setup>
const vuepressVersion = __VUEPRESS_VERSION__
</script>
## Dependency Environment
- [Node.js v20.6.0+](https://nodejs.org/)
- [npm 8+](https://www.npmjs.com/) or [pnpm 8+](https://pnpm.io/zh/) or [Yarn 2+](https://yarnpkg.com/)
:::: details How to install the dependency environment?
::: steps
1. **Please go to the [Node.js Official Website](https://nodejs.org/zh-cn) to download the latest stable version**
Follow the instructions to complete the installation. Generally, you only need to keep the default settings and choose Next during the installation process.
2. **Install PNPM**
After you have installed node.js, please open the terminal and run the following command:
```sh
corepack enable
```
The theme recommends using pnpm as the project manager.
3. **Done**
:::
::::
## Command Line Installation
The theme provides a command line tool to help you build a basic project. You can run the following command to start the installation wizard.
::: npm-to
```sh
npm create vuepress-theme-plume@latest
```
:::
After starting the wizard, you only need to answer a few simple questions:
<!-- @include: ../snippet/create.snippet.md ---->
::: details How to use the command line tool?
Taking the Windows system as an example, you can use the following methods to start the CMD command line tool:
1. Press the `Win + R` keys to open the "Run" dialog.
2. Enter `cmd` and press the Enter key. (You can also enter `powershell` to open PowerShell)
Note that `cmd` may not be in the directory you expect. You can use the following command to switch to the correct directory:
```sh
D: # This command switches to the D: drive, enter other drives according to the actual situation
cd open-source # Enter the open-source directory under D:
```
Now, you can create a basic project by entering `pnpm create vuepress-theme-plume@latest` here.
The created project will be located in the `D:\open-source\my-project` directory.
:::
## Manual Installation
::: info Note
- When using [pnpm](https://pnpm.io/zh/), you need to install `vue` as a peer-dependency.
- When using [Yarn 2+](https://yarnpkg.com/), you need to set `nodeLinker: 'node-modules'` in the `.yarnrc.yml` file.
:::
To use this theme, you need to first create a new project and install `vuepress@next` and this theme.
:::: steps
- ### Create a new folder and enter the directory
``` sh :no-line-numbers
mkdir my-blog
cd my-blog
```
- ### Initialize the project
::: npm-to
``` sh
git init
npm init
```
:::
- ### Install related dependencies
Install `vuepress@next` and `vuepress-theme-plume` as local dependencies.
::: npm-to
```sh
# Install vuepress
npm i -D vuepress@next vue
# Install theme and bundler
npm i -D vuepress-theme-plume @vuepress/bundler-vite@next
```
:::
:::warning
The current version of the theme has been adapted to <code>vuepress@{{ vuepressVersion }}</code>. You should install this version of VuePress. Versions higher or lower than this may have potential compatibility issues.
:::
- ### Add `script` in `package.json`
::: code-tabs
@tab package.json
``` json :no-line-numbers
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
```
:::
`vuepress` defaults to placing the documentation source code in the `docs` directory.
- ### Add the default temporary and cache directories to the `.gitignore` file
::: code-tabs
@tab .gitignore
``` txt :no-line-numbers
node_modules
.temp
.cache
```
@tab sh
``` sh :no-line-numbers
echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore
```
:::
- ### Configure the theme in `docs/.vuepress/config.{js,ts}`
::: code-tabs
@tab docs/.vuepress/config.ts
``` ts :no-line-numbers
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
// Don't forget to set the default language
lang: 'zh-CN',
theme: plumeTheme({
// more...
}),
bundler: viteBundler(),
})
```
:::
:::warning
Whether or not you need to use **multiple languages**, you should configure the correct value for the `lang` option in VuePress. The theme needs to determine the language environment text based on the `lang` option.
:::
- ### Create a new `README.md` file in the `docs` directory
Declare the home page configuration.
::: code-tabs
@tab README.md
``` md :no-line-numbers
---
home: true
---
```
:::
- ### Start your documentation site on the local server
::: npm-to
``` sh
npm run docs:dev
```
:::
Vuepress will start a hot-reload development server at [http://localhost:8080](http://localhost:8080). When you modify your Markdown files, the content in the browser will also update automatically.
- ### Done
::::
## Update the Theme
You can run the following command directly in your project to check for available updates:
::: npm-to
``` sh
npx vp-update
```
:::

183
docs/en/notes/theme/guide/write.md Normal file
View File

@ -0,0 +1,183 @@
---
title: Writing Articles
icon: mingcute:edit-4-line
createTime: 2025/03/03 13:43:55
permalink: /en/guide/write/
tags:
- Guide
- Quick Start
---
VuePress supports the complete [Markdown syntax](./markdown/basic.md),
and uses [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)
to define frontmatter page metadata, such as title and creation time.
The theme also provides [extensions](./markdown/extensions.md) for Markdown syntax. You can also write HTML directly in
Markdown, or use Vue components.
## Frontmatter
You can customize each page in VuePress by setting values in the frontmatter.
Frontmatter is the part at the top of your file between `---`.
::: code-tabs
@tab post.md
```md
---
title: Article Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---
The page content is after the second `---`.
```
:::
::: details What is frontmatter?
Frontmatter is a [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) formatted configuration content, placed at the top of the markdown file, separated by `---`.
You can read [this article](../../../4.Tutorials/frontmatter.md) to learn how to write frontmatter correctly.
:::
## Auto-Generated Frontmatter
By default, the theme will help generate some `frontmatter` configurations for markdown files in the source directory after starting the development service.
These configurations include: **title**, **creation time**, and **permalink**.
On one hand, this can reduce the repetitive work of content creators; on the other hand, these configurations also provide prerequisite support for other features of the theme.
```md
---
title: Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---
```
### Title
The theme defaults to using the file name as the article title. When parsing the file name, the file name named according to the [file naming convention](#file-naming-convention) such as `1.My Article.md`, the parts `1.` and `.md` will be trimmed, and the final article title will be `My Article`.
### Creation Time
The theme defaults to using the file creation time as the article creation time, and formats it as `yyyy/MM/dd HH:mm:ss`.
### Permalink
**Permalink** refers to the access address after the article is published. Once this address is generated, it will not change unless you manually modify it, even if the file path or file name changes.
Preparing **permalink** in advance is quite valuable. On one hand, it can help improve the SEO of the site and avoid frequent changes to the included addresses; on the other hand, the theme uses a set of specifications to generate **permalink**, which makes the link style of the entire site consistent.
- **Blog Articles**
For blog articles, the default prefix for permalink is `/article/`, and then a random string of length `8` is generated using [`nanoid`](https://github.com/ai/nanoid) for concatenation as the article's permalink, such as `/article/9eh4d6ao/`.
The link prefix can also be replaced by modifying [Theme Configuration > article](../config/basic.md#article).
- **Notes**
For notes, the theme uses a more flexible custom solution. You can declare different link prefixes for notes in [notes > note.link](../config/notes.md#configuration), and then use [`nanoid`](https://github.com/ai/nanoid) to generate a random string of length `8` for concatenation as the permalink for note articles.
### Disabling Auto-Generation
You may not want the theme to do extra auto-generation and prefer to have full control. This is completely fine, and the theme supports controlling the behavior of auto-generating frontmatter through configuration.
You can easily achieve this through [Theme Configuration > autoFrontmatter](../config/basic.md#autofrontmatter).
::: code-tabs
@tab .vuepress/config.ts
```ts
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Completely disable all auto-generation
// autoFrontmatter: false,
// Control partial auto-generation
autoFrontmatter: {
permalink: true, // Whether to generate permalink
createTime: true, // Whether to generate creation time
title: true, // Whether to generate title
}
})
})
```
:::
## Conventions
::: info Note
The following content is based on the file structure in [Project Structure](./project-structure.md).
:::
Writing articles with this theme is very easy. You can create `Markdown` files with any name you like in the `docs` directory according to your personal naming preferences.
### Folder Naming Convention
For folder naming in `docs`, the theme has a simple set of conventions.
- The folder name will serve as the `category`, i.e., **category**.
- Multi-level directories are allowed, and subdirectories will be sub-items of the parent directory's category.
- If the directory name is declared in [Theme Configuration notes](../config/notes.md) for notes article management, it will not be used as a category directory by default.
Since folder names will serve as category names and are not sorted in theme configuration, for scenarios where sorting is needed, use the following rule for naming:
``` ts :no-line-numbers
const dir = /\d+\.[\s\S]+/
// That is, number + . + category name
// For example: 1.Frontend
```
The number will serve as the basis for **sorting**. If there is no number, the default sorting rule will be applied.
**Example:**
::: file-tree
- docs
- 1.Frontend
- 1.HTML/
- 2.CSS/
- 3.JavaScript/
- 2.Backend/
- Operations-And-Maintenance/
:::
The theme will generate a category page based on the directory structure.
### File Naming Convention
- **Blog Articles**
For the names of **blog articles**, the theme has no specific conventions, and you can name them arbitrarily. The default sorting rule for blog articles is based solely on file creation time.
You can also use [frontmatter > sticky](../config/frontmatter/article.md#sticky) to configure whether the article is stickied.
- **Notes**
For the names of markdown files in **notes**, the same rules as [Folder Naming Convention](#folder-naming-convention) still apply.
This can provide a basis for sorting the [auto-generated sidebar](../config/notes.md#auto-generated-sidebar) for notes.
## Article Writing
You can start writing your own articles by creating Markdown files in `docs` using `markdown` syntax.
For the supported features of markdown extensions, please refer to [this document](./markdown/extensions.md).
Since the theme defaults to auto-generating a `title` for the article's `frontmatter`, the main part of the article content should start with `h2`, i.e., `## Secondary Heading`. If you have disabled `autoFrontmatter.title`, you should start with `h1`, i.e., `# Primary Heading`.
### Tags
You can add tags to an article through `frontmatter.tags`.
```md
---
title: My Article
tags:
- Tag 1
- Tag 2
---
```

42
docs/en/notes/theme/snippet/create.snippet.md Normal file
View File

@ -0,0 +1,42 @@
```ansi :no-line-numbers :collapsed-lines
┌ Welcome to VuePress and vuepress-theme-plume !
│
◇ Select a language to display / 选择显示语言
│ Simplified Chinese
│
◇ Where do you want to initialize VuePress? 
│ ./my-project
│
◇ Site name: 
│ My Vuepress Site
│
◇ Site description: 
│ My Vuepress Site Description
│
◇ Use multiple languages? 
│ No
│
◇ Select the default language for the site 
│ Simplified Chinese
│
◇ Use TypeScript? 
│ Yes
│
◇ Select the bundler tool 
│ Vite
│
◇ Deployment method: 
│ Custom
│
◇ Initialize git repository? 
│ Yes
│
◇ Install dependencies? 
│ Yes
│
◇ 🎉 Creation successful! 
│
└ 🔨 Start with the following commands:
cd ./my-project
pnpm run docs:dev
```

1196
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

6
readme.md
View File

@ -1,6 +1,7 @@
<h1 align="center">vuepress-theme-plume</h1>
<p align="center">
<img src="https://theme-plume.vuejs.press/plume.svg" width="200px" alt="plume">
<img src="https://theme-plume.vuejs.press/plume.svg" width="200px" alt="plume">
</p>
<p align="center">
@ -16,7 +17,10 @@
<a href="https://codecov.io/gh/pengzhanbo/vuepress-theme-plume" >
<img src="https://codecov.io/gh/pengzhanbo/vuepress-theme-plume/graph/badge.svg?token=W6KYBX7WO5" alt="codecov"/>
</a>
</p>
<p align="center">
中文 | <a href="/readme_en.md">English</a>
</p>
一个简约的，干净的，容易上手的 vuepress 主题，适用于博客和文档。

77
readme_en.md Normal file
View File

@ -0,0 +1,77 @@
<h1 align="center">vuepress-theme-plume</h1>
<p align="center">
<img src="https://theme-plume.vuejs.press/plume.svg" width="200px" alt="plume">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/vuepress-theme-plume" target="_blank">
<img src="https://img.shields.io/npm/v/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&label=npm" alt="npm version">
</a>
<a href="https://www.npmjs.com/package/vuepress-theme-plume" target="_blank">
<img src="https://img.shields.io/npm/dy/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&label=downloads" alt="npm download">
</a>
<img src="https://img.shields.io/npm/dependency-version/vuepress-theme-plume/peer/vuepress?color=32A9C3&labelColor=1B3C4A" alt="peer dependency">
<img src="https://img.shields.io/github/license/pengzhanbo/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A" alt="github license">
<br>
<a href="https://codecov.io/gh/pengzhanbo/vuepress-theme-plume">
<img src="https://codecov.io/gh/pengzhanbo/vuepress-theme-plume/graph/badge.svg?token=W6KYBX7WO5" alt="codecov">
</a>
</p>
<p align="center">
<a href="/readme.md">中文</a> | English
</p>
A simple, clean, and easy-to-use VuePress theme for blogs and documentation.
Ready to use out-of-the-box with minimal configuration, allowing you to focus more on content creation and better express your ideas to form your knowledge notes.
It includes a rich set of powerful features designed to make content more expressive.
## Features
- 💻 Responsive layout, adapts to different screen sizes
- 📖 Blog & Documentation
- 🔗 Automatically generates article permanent links
- ⚖ Supports multiple languages
- 🔑 Supports full-site encryption and partial encryption
- 👀 Supports search and article comments
- 👨‍💻 Supports light/dark themes (including code highlighting)
- 📠 Markdown enhancement, supports code block grouping, hint containers, task lists, mathematical formulas, code demonstrations, file trees, etc.
- 📚 Embedded code demonstrations, supports CodePen, JSFiddle, CodeSandbox, etc.
- 📊 Embedded charts, supports chart.js, Echarts, Mermaid, flowchart
- 🎛 Resource embedding, supports PDF, Bilibili videos, YouTube videos, local videos, audio, etc.
- 🪞 Supports full-site watermark and partial content watermark
## [Documentation](https://theme-plume.vuejs.press)
QQ communication group：[792882761](https://qm.qq.com/q/O3HNy4rxYc)
## Examples
- [My Personal Blog](https://pengzhanbo.cn/)
View [more examples](https://theme-plume.vuejs.press/demos/)
### Note
This theme is based on `vuepress 2` and is in the RC stage.
This means that the functionality is relatively stable, but there is still a small probability of breaking changes in the future.
## Contribution Guide
View the [[Contribution Guide]](/CONTRIBUTING_EN.md) for more information
## Contributors
Thank you to all contributors!
![GitHub contributors](https://img.shields.io/github/contributors/pengzhanbo/vuepress-theme-plume?color=32A9C3&labelColor=1B3C4A&logo=contributorcovenant)
[![contributors](https://contrib.rocks/image?repo=pengzhanbo/vuepress-theme-plume)](https://github.com/pengzhanbo/vuepress-theme-plume/graphs/contributors)
## License
[MIT](/LICENSE)