yuany3721/vuepress-theme-plume
1
0
Fork 0
forked from gitea-yuany3721/vuepress-theme-plume
Code Pull Requests Activity

docs: add en markdown doc (#538)

Browse Source 
* docs: add markdown-basic en

* docs: add markdown-extensions en

* docs: add markdown-icons en

* docs: add markdown-mark en , change file structure

* docs: update usage

* docs: add to markdown-caniuse en

* docs: add en docs markdown - import files

* docs: add en docs markdown - collapse

* chore: fix package lock file

---------

Co-authored-by: pengzhanbo <volodymyr@foxmail.com>
This commit is contained in:
zhenghaoyang24 2025-03-27 21:06:53 +08:00 committed by GitHub
parent 2f9ad84553
commit 9f99ae3ca7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
32 changed files with 3947 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,9 +8,10 @@ export const themeGuide = defineNoteConfig({
text: 'Quick Start',
collapsed: false,
icon: 'carbon:idea',
prefix: 'quick-start',
items: [
'intro',
'quick-start',
'usage',
'project-structure',
'write',
'blog',
@ -33,6 +34,21 @@ export const themeGuide = defineNoteConfig({
items: [
'basic',
'extensions',
'icons',
'mark',
'plot',
'abbr',
'annotation',
'card',
'steps',
'file-tree',
'tabs',
'timeline',
'demo-wrapper',
'collapse',
'npm-to',
'caniuse',
'include',
],
},
],
@ -41,8 +57,10 @@ export const themeGuide = defineNoteConfig({
text: 'Customization',
icon: 'material-symbols:dashboard-customize-outline-rounded',
collapsed: false,
prefix: 'custom',
items: [
'custom-home',
'home',
'style',
],
},
],

0
docs/en/notes/theme/guide/custom-home.md → docs/en/notes/theme/guide/custom/home.md
View File

10
docs/en/notes/theme/guide/custom/style.md Normal file
View File

@ -0,0 +1,10 @@
---
title: Customize Style
icon: icon-park-outline:theme
createTime: 2025/03/23 14:53:21
permalink: /en/guide/custom-style/
---
## Style File
The titles are used for external jumps.
todo ...

9
docs/en/notes/theme/guide/features/component.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Component
icon: radix-icons:component-2
createTime: 2025/03/24 19:52:21
outline: 2
permalink: /en/guide/features/component/
---
The original content of this document has been migrated to Component .

54
docs/en/notes/theme/guide/markdown/abbr.md Normal file
View File

@ -0,0 +1,54 @@
---
title: Abbreviation
icon: mdi:tooltip-question-outline
createTime: 2025/03/24 17:07:33
permalink: /en/guide/markdown/abbreviation/
---
## Overview
**Abbreviations** refer to short forms used in Markdown, such as technical terms like W3C and ECMA.
When hovering over an abbreviation, the full term will be displayed along with its definition or explanation.
## Configuration
This feature is disabled by default. Enable it in `theme` configuration:
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
abbr: true, // [!code ++]
}
})
})
```
## Syntax
In Markdown, define abbreviations using `*[ABBR]: Description` on separate lines. The description may include the abbreviation's definition, explanation, etc.
Place the abbreviation within `[]` and its description after `:`. The description supports Markdown inline syntax.
If the Markdown plain text contains defined abbreviations, the explanation of the abbreviation will be automatically displayed when the mouse moves over it.
**Input:**
```md
The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
```
**Output:**
The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
*[ECMA]: European Computer Manufacturers Association
::: warning Abbreviations should be standalone words or phrases. For Chinese abbreviations, add spaces around the term to ensure proper detection.
:::

146
docs/en/notes/theme/guide/markdown/annotation.md Normal file
View File

@ -0,0 +1,146 @@
---
title: Annotation
icon: iconamoon:comment-add-light
createTime: 2025/03/24 17:19:13
permalink: /en/guide/markdown/annotation/
---
## Description
==Annotation== is a special Markdown syntax for adding extra information, explanations, or hints in documents.
Annotations are not displayed directly in the document and require user interaction to be shown.
## Configuration
This feature is not enabled by default. You need to enable it in the `theme` configuration.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
annotation: true, // [!code ++]
}
})
})
```
## Syntax
==Annotation== syntax consists of two parts:
### Inline Annotation
Insert an annotation tag inline using the `[+label]` syntax.
The annotation tag is composed of `[+` + `label` + `]`. To distinguish it from the content, there should be a space before `[+label]`.
`label` is the annotation tag and can be any string.
::: important The symbol `+` is required
:::
### Define Annotation
Define the annotation in a separate area of the document using the `[+label]:` syntax.
The annotation definition area is composed of `[+` + `label` + `]:` + `content`.
`label` should match the `[+label]` used earlier to mark the annotation.
**Content** can be written after the `:`:
```md
[+label]: Here is the content, which can use **Markdown** syntax.
```
**Content** can also start on the next line with indentation, and should maintain consistent indentation for multiple lines.
```md
[+label]:
Here is the content.
Indent consistently, this line is also part of the content.
Even if the previous line is blank, but this line's indentation is consistent, it is still part of the content.
You can use **Markdown** syntax.
This line is no longer indented, so the annotation definition for this tag ends on the previous line.
```
The content of the annotation definition is not rendered directly in the document, but is displayed when the `[+label]` inline annotation is clicked.
## Example
### Example 1
**Input:**
```md
The site is powered by VuePress [+vuepress].
[+vuepress]:
VuePress is a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator ) (SSG).
Designed specifically for building fast, content-focused websites.
```
**Output:**
The site is powered by VuePress [+vuepress].
[+vuepress]:
VuePress is a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator ) (SSG).
Designed specifically for building fast, content-focused websites.
### Example 2
**Multiple annotations for the same `label`, rendered as a list.**
**Input:**
```md
The Four Great Classical Novels of ancient China [+classics] are widely known.
[+classics]:
**Romance of the Three Kingdoms:**
Set against the history of the Three Kingdoms period, it depicts the political and military struggles among the Wei, Shu, and Wu kingdoms, creating numerous historical figures like Zhuge Liang, Cao Cao, Guan Yu, and Liu Bei.
[+classics]:
**Journey to the West:**
Tells the story of Tang僧 and his four disciples (Sun Wukong, Zhu Bajie, Sha僧, and White Dragon Horse) on their pilgrimage to the West for Buddhist scriptures, filled with mythological elements and fantastic adventures.
[+classics]:
**Dream of the Red Chamber:**
Set against the rise and fall of the four major families (Jia, Shi, Wang, and Xue), it depicts the love tragedy of Jia Baoyu, Lin Daiyu, and Xue Baochai, showcasing the decadence and decline of feudal society.
[+classics]:
**Water Margin:**
Depicts the story of 108 heroes led by Song Jiang gathering at Liangshan泊 to resist the court during the late Northern Song Dynasty, revealing the social reality of oppression leading to rebellion.
```
**Output:**
The Four Great Classical Novels of ancient China [+classics] are widely known.
[+classics]:
**Romance of the Three Kingdoms:**
Set against the history of the Three Kingdoms period, it depicts the political and military struggles among the Wei, Shu, and Wu kingdoms, creating numerous historical figures like Zhuge Liang, Cao Cao, Guan Yu, and Liu Bei.
[+classics]:
**Journey to the West:**
Tells the story of Tang僧 and his four disciples (Sun Wukong, Zhu Bajie, Sha僧, and White Dragon Horse) on their pilgrimage to the West for Buddhist scriptures, filled with mythological elements and fantastic adventures.
[+classics]:
**Dream of the Red Chamber:**
Set against the rise and fall of the four major families (Jia, Shi, Wang, and Xue), it depicts the love tragedy of Jia Baoyu, Lin Daiyu, and Xue Baochai, showcasing the decadence and decline of feudal society.
[+classics]:
**Water Margin:**
Depicts the story of 108 heroes led by Song Jiang gathering at Liangshan泊 to resist the court during the late Northern Song Dynasty, revealing the social reality of oppression leading to rebellion.

829
docs/en/notes/theme/guide/markdown/basic.md
View File

@ -8,4 +8,831 @@ tags:
- markdown
---
todo ...
::: note This document is forked from [vuepress-theme-hope](https://theme-hope.vuejs.press/zh/cookbook/markdown/ ), following the [MIT](https://github.com/vuepress-theme-hope/vuepress-theme-hope/blob/main/LICENSE ) license.
:::
Markdown is a markup language that can be written using a plain text editor. Through simple syntax, it allows regular text content to have formatting capabilities.
The goal of Markdown is to achieve「readability and writability」.
<!-- more -->
## Overview
The most emphasized aspect is its readability. A document written in Markdown should be directly publishable as plain text,
and should not appear to be composed of tags or formatting instructions. Markdown syntax is influenced by several existing text-to-HTML formats,
including [Setext][1], [atx][2], [Textile][3], [reStructuredText][4], [Grutatxt][5], and [EtText][6],
with the primary inspiration coming from plain text email formatting.
Thus, Markdown syntax consists entirely of punctuation marks, carefully selected to visually represent their meaning.
For example, adding asterisks around text looks like \*emphasis\*. Markdown lists look like lists.
If you've used email, blockquotes resemble quoted text.
Markdown has various derivatives to extend its functionality (e.g., tables, footnotes, embedded HTML),
features not originally available in basic Markdown. These enable conversion to formats like LaTeX, Docbook.
Notable enhanced versions include Markdown Extra, MultiMarkdown, and Maruku. These derivatives are either tool-based (e.g., Pandoc)
or website-based (e.g., GitHub, Wikipedia), maintaining basic syntax compatibility but modifying rendering effects.
## Usage
Markdown's syntax has a primary purpose: to serve as a writing language for web content. Markdown focuses on making documents easier to read and write,
thus its syntax only covers what plain text can represent.
Markdown's syntax is simple, easy to learn, and more powerful than plain text, making it popular for blogging. WordPress, the world's most popular blogging platform, supports Markdown well.
It's used for documentation, typically saved as `README.md` in software directories.
Additionally, Markdown can quickly convert to presentation slides, Word documents, LaTeX papers, or even minimal viable prototypes with minimal code. In data science, Markdown has become essential for dynamic reproducible research.
### Inline HTML
Any HTML tags not covered by Markdown can be directly written in the document. No special annotation is needed; simply include the tags.
Block-level elements like `<div>`, `<table>`, `<pre>`, and `<p>` must be separated by blank lines.
These tags cannot be indented with tabs or spaces. Markdown's parser intelligently avoids adding unnecessary `<p>` tags around block elements.
For example, adding an HTML table in a Markdown file:
```md
This is a regular paragraph.
<table>
<tr>
<td>Foo</td>
</tr>
</table>
This is another regular paragraph.
```
Note that Markdown syntax is not processed within HTML blocks. For instance, you cannot use `*emphasis*` inside HTML blocks.
### Special Character Auto-Conversion
In HTML files, two characters require special handling: `<` and `&`. The `<` character starts a tag, and `&` marks an HTML entity. If you want to use these characters literally, you must use their entity forms, like `&lt;` and `&amp;`.
The `&` character can be problematic for those writing web documents. If you want to write "AT&T," you must write "AT&amp;T." You also need to escape the `&` in URLs. For example, if you want to link to `http://images.google.com/images?num=30&q=larry+bird`
you must convert the URL to:
```html
http://images.google.com/images?num=30&amp;q=larry+bird
```
to place it in the `href` attribute of a link tag. It's easy to forget this, and it might be the most common error detected by HTML validators.
Markdown allows you to use these characters directly, but you need to be careful with escape characters. If you use `&` in an HTML entity, it won't be converted. In other cases, it will be converted to `&amp;`. So, if you want to insert a copyright symbol in your text, you can write:
```md
&copy;
```
Markdown will not modify this text. However, if you write:
```md
AT&T
```
Markdown will convert it to:
```html
AT&amp;T
```
Similar behavior occurs with the `<` character. Since Markdown supports [inline HTML](#inline-html), if you use `<` as an HTML tag, Markdown won't convert it. But if you write:
```md
4 < 5
```
Markdown will convert it to:
```html
4 &lt; 5
```
Note that within code spans, whether inline or block, both `<` and `&` are always converted to HTML entities. This feature allows you to easily write HTML code in Markdown, as you don't have to convert all `<` and `&` in HTML syntax to HTML entities to write HTML code.
---
## Block Elements
### Paragraphs and Line Breaks
A paragraph is composed of one or more connected lines, and one or more blank lines separate different paragraphs. (A blank line is defined as a line that appears empty; for example, a line with only spaces and tabs is also considered a blank line.) Generally, paragraphs do not require indentation with spaces or tabs.
The phrase "composed of one or more connected lines" implies that Markdown allows forced line breaks within paragraphs. This differs from other text-to-HTML formats (including MovableType's "Convert Line Breaks" option), which convert every line break into a `<br />` tag.
<!-- markdownlint-disable MD038 -->
If you really want to insert a `<br />` tag, add two or more spaces (` `) or a slash (`/`) at the end of the line, then press Enter.
<!-- markdownlint-enable MD038 -->
Yes, this requires more effort to insert a `<br />`, but the method of converting every line break to `<br />` is not suitable for Markdown.
In Markdown, email-style [block quotes][bq] and multi-paragraph [lists][l] are more usable and readable when using line breaks for formatting.
### Headings
Headings indicate the structure of an article.
Markdown supports two heading syntax styles: [Setext][1] and [atx][2].
The Setext style uses underlines with `=` (for first-level headings) and `-` (for second-level headings), like:
```md
# This is an H1
## This is an H2
```
Any number of `=` or `-` characters can be used.
The Atx style (recommended) involves placing 1 to 6 `#` characters at the beginning of a line, corresponding to heading levels 1 to 6, like:
- H1: `# Header 1`
- H2: `## Header 2`
- H3: `### Header 3`
- H4: `#### Header 4`
- H5: `##### Header 5`
- H6: `###### Header 6`
### Blockquotes
Markdown uses email-style block quotes. If you're familiar with quoting in emails, you'll know how to create a block quote in a Markdown file. It looks like a forced line break with `>` at the beginning of each line:
```md
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.
```
Markdown also allows you to place `>` only at the beginning of the first line of a paragraph:
```md
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.
```
Block quotes can have levels (e.g., quotes within quotes) by adding more `>` characters according to the level:
```md
> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.
```
Other Markdown syntax, including headings, lists, and code blocks, can be used within block quotes:
```md
> ## This is a header.
>
> 1. This is the first list item.
> 1. This is the second list item.
>
> Here's some example code:
>
> return shell_exec("echo $input | $markdown_script");
```
Any standard text editor can easily create email-style quotes. For example, in BBEdit, you can select text and choose "Increase Quote Level" from the menu.
### Lists
Markdown supports ordered and unordered lists.
Unordered lists use hyphens as list markers (you can also use asterisks or plus signs):
```md
- Red
- Green
- Blue
```
You can also (though not recommended):
```md
- Red
- Green
- Blue
* Red
* Green
* Blue
```
Ordered lists use numbers followed by a period:
```md
1. Bird
2. McHale
3. Parish
```
Importantly, the numbers you use for list markers do not affect the HTML output. The HTML for the above list would be:
```html
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>
```
If you write the list markers as:
```md
1. Bird
1. McHale
1. Parish
```
You'll still get the same HTML output. The key point is that you can make the list numbers in the Markdown file match the output, or just use `1` and not worry about the numbering.
List markers are typically placed at the left margin but can be indented by up to three spaces, with at least one space or tab after the marker.
To make lists look neater, you can align the content with consistent indentation:
```md
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
```
However, if you're lazy, you don't have to:
```md
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
```
If list items are separated by blank lines, Markdown will wrap the item content in `<p>` tags. For example:
```md
- Bird
- Magic
```
Would be converted to:
```html
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
```
But this:
```md
- Bird
- Magic
```
Would be converted to:
```html
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
```
List items can contain multiple paragraphs, with each paragraph indented by 4 spaces or one tab:
```md
1. This is a list item with two paragraphs. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
```
If every line is indented, it looks better, but again, if you're lazy, Markdown allows:
```md
- This is a list item with two paragraphs.
This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.
- Another item in the same list.
```
To include a quote within a list item, the `>` needs to be indented:
```md
- A list item with a blockquote:
> This is a blockquote
> inside a list item.
```
Accidental lists can occur with syntax like:
```md
1986. What a great season.
```
To avoid this, place a backslash before the period:
```md
1986\. What a great season.
```
### Code Blocks
For code writing or raw code of markup languages, you often need preformatted code blocks that shouldn't be formatted like regular paragraphs but displayed as-is. Markdown wraps these code blocks with `<pre>` and `<code>` tags.
Creating a code block in Markdown is simple: indent every line with 4 spaces or one tab. For example:
```md
This is a normal paragraph:
This is a code block.
```
Markdown converts this to:
```html
<p>This is a normal paragraph:</p>
<pre>
<code>This is a code block.</code>
</pre>
```
The indentation (4 spaces or one tab) is removed, so:
```md
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
```
Becomes:
```html
<p>Here is an example of AppleScript:</p>
<pre><code>tell application "Foo"
beep
end tell
</code></pre>
```
A code block continues until a line with no indentation (or the end of the file).
Within code blocks, `<`, `&`, and `>` are automatically converted to HTML entities, making it easy to insert HTML code examples. Just copy, paste, and indent, and Markdown handles the rest. For example:
````md
```html
<div class="footer">
&copy; 2004 Foo Corporation
</div>
```
````
Is converted to:
```html
<pre>
<code>&lt;div class="footer"&gt;
&amp;copy; 2004 Foo Corporation
&lt;/div&gt;</code>
</pre>
```
In code blocks, regular Markdown syntax isn't processed, so asterisks remain asterisks. This allows you to easily write about Markdown syntax.
If you want to include Markdown-formatted code libraries within a code block, you can nest them.
`````md
````md
```js
const a = 1
```
````
`````
Renders as
````md
```js
const a = 1
```
````
### Horizontal Rules
You can create a horizontal rule by placing three or more asterisks, hyphens, or underscores on a line. No other content should be on the line. You can also add spaces between the characters. Any of the following will create a horizontal rule:
```html
---(recommended) * * * *** ***** - - - ---------------------------------------
```
## Inline Elements
### Links
Markdown supports two types of link syntax: *inline* and *reference*.
In both cases, link text is marked with `[square brackets]`.
For an inline link, immediately after the square brackets, add parentheses with the URL. You can also include a title in quotes, like:
```html
This is [an example](http://example.com/ "Title") inline link. [This
link](http://example.net/ ) has no title attribute.
```
This produces:
```html
<p>
This is <a href="http://example.com/ " title="Title"> an example</a> inline
link.
</p>
<p><a href="http://example.net/ ">This link</a> has no title attribute.</p>
```
For linking to resources on the same host, you can use relative paths:
```md
See my [About](/about/) page for details.
```
Reference-style links use another set of square brackets after the link text, with an identifier for the link:
```md
This is [an example][id] reference-style link.
```
Then, define the link identifier anywhere in the document:
```md
[id]: http://example.com/ "Optional Title Here"
```
The link definition consists of:
- Square brackets with the link ID
- A colon
- One or more spaces or a tab
- The URL
- An optional title in single quotes, double quotes, or parentheses
These three link definitions are equivalent:
```md
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ "Optional Title Here"
```
**Note:** A known issue is that Markdown.pl 1.0.1 ignores single-quoted link titles.
URLs in link definitions can be enclosed in square brackets:
```md
[id]: http://example.com/ "Optional Title Here"
```
You can also place the title on a new line with indentation for better readability with long URLs:
```md
[id]: http://example.com/longish/path/to/resource/here "Optional Title Here"
```
Link identifiers are case-insensitive and can include letters, numbers, spaces, and punctuation. These two links are the same:
```md
[link text][a]
[link text][a]
```
The *default link ID* feature allows you to omit the link ID, making it the same as the link text. To use this, add empty square brackets after the link text. For example:
```md
[Google][]
```
Then define the link:
```md
[google]: http://google.com/
```
Since link text can contain spaces, the simplified ID can also include multiple words:
```md
Visit [Daring Fireball][] for more information.
```
Then define the link:
```md
[daring fireball]: http://daringfireball.net/
```
Link definitions can be placed anywhere in the document, either after the paragraph where the link appears or at the end like annotations.
Here's an example of reference-style links:
```md
I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
```
Using link names instead:
```md
I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
```
Both methods produce the same HTML:
```html
<p>
I get 10 times more traffic from
<a href="http://google.com/ " title="Google">Google</a> than from
<a href="http://search.yahoo.com/ " title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/ " title="MSN Search">MSN</a>.
</p>
```
For comparison, here's the inline-style version of the same content:
```md
I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").
```
Reference-style links are more readable. The reference-style version has 81 characters, while the inline-style version has 176, and pure HTML would have 234. In HTML, tags outnumber text.
Using Markdown's reference-style links makes the document resemble the final browser output, allowing you to keep markup details separate from the main text for uninterrupted reading.
### Emphasis
Markdown uses asterisks (`*`) and underscores (`_`) to mark emphasis. Text surrounded by `*` or `_` is wrapped in `<em>`, while text surrounded by double `*` or `_` is wrapped in `<strong>`, like:
```md
**double asterisks** (recommended)
**double underscores** (recommended)
_single asterisks_
_single underscores_
```
This converts to:
```html
<em>single asterisks</em>
<em>single underscores</em>
<strong>double asterisks</strong>
<strong>double underscores</strong>
```
You can choose your preferred style, as long as you use the same character to open and close.
Emphasis can be added in the middle of words:
```md
un*frigging*believable
```
However, if `*` or `_` has spaces on both sides, it will be treated as regular text.
To insert literal asterisks or underscores, use a backslash:
```md
\*this text is surrounded by literal asterisks\*
```
### Code
To mark inline code, wrap it in backticks (`` ` ``), like:
```md
Use the `printf()` function.
```
This produces:
```md
<p>Use the <code>printf()</code> function.</p>
```
To include a backtick within the code, use multiple backticks to open and close the inline code:
```md
``There is a literal backtick (`) here.``
```
This renders as:
```html
<p><code>There is a literal backtick (`) here.</code></p>
```
You can add a space at the start or end of the code span to include a backtick at the beginning:
```md
A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
```
This results in:
```html
<p>A single backtick in a code span: <code>`</code></p>
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
```
Within code spans, `&` and brackets are converted to HTML entities, making it easier to insert HTML code. Markdown converts:
```md
Please don't use any `<blink>` tags.
```
To:
```html
<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
```
You can also write:
```md
`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
```
Which produces:
```html
<p>
<code>&amp;#8212;</code> is the decimal-encoded equivalent of
<code>&amp;mdash;</code>.
</p>
```
### Images
Creating a natural syntax for inserting images in plain text is challenging.
Markdown uses a syntax similar to links for images, supporting both *inline* and *reference* styles.
The inline image syntax looks like:
```md
![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")
```
This consists of:
- An exclamation mark `!`
- Square brackets containing the image's alt text
- Parentheses containing the image URL, optionally followed by a quoted title.
Reference-style image syntax looks like:
```md
![Alt text][id]
```
Where `id` is the image reference name, defined like:
```md
[id]: url/to/image "Optional title attribute"
```
Currently, Markdown doesn't support specifying image width and height. For that, use the regular `<img>` tag.
### Other Text Styles
- Delete: `~~delete~~`
- Paragraphs: Leave a blank line between paragraphs
- Line breaks: Add two spaces at the end of a line
---
## Other
### Automatic Links
Markdown supports concise automatic link syntax for URLs and email addresses. Enclosing text in brackets automatically converts it to a link. For example:
```md
<http://example.com/>
```
Markdown converts this to:
```html
<a href="http://example.com/">http://example.com/</a>
```
Automatic email links are similar, but Markdown encodes characters as hexadecimal HTML entities to confuse address-harvesting bots. For example:
```md
<address@example.com>
```
Markdown converts this to:
```html
<a
href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;"
>&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a
>
```
This creates a clickable <address@example.com> link in the browser.
### Escape Characters
Markdown uses backslashes to insert characters that have special meaning in its syntax. For example, to use asterisks for emphasis without `<em>` tags, precede them with a backslash:
```md
\*literal asterisks\*
```
Markdown supports escaping the following characters:
- `\` backslash
- `` ` `` backtick
- `*` asterisk
- `_` underscore
- `{}` curly braces
- `[]` square brackets
- `()` parentheses
- `#` hash
- `+` plus
- `-` minus
- `.` period
- `!` exclamation mark
## Keyboard Shortcuts
| Rendered Effect | Markdown Syntax | Shortcut Key |
| --------------- | --------------- | ------------ |
| **Bold** | `**text**` | Ctrl/⌘ + B |
| _Emphasize_ | `*text*` | Ctrl/⌘ + I |
| `Inline Code` | \`code\` | Select then `` ` `` |
## Tables
| Center | Right Aligned | Left Aligned |
| :-------------: | ---------------------: | :------------------- |
| Use `:-:` | Use `-:` | Use `:-` |
| b | aaaaaaaaa | aaaa |
| c | aaaa | a |
[1]: http://docutils.sourceforge.net/mirror/setext.html
[2]: http://www.aaronsw.com/2002/atx/
[3]: http://textism.com/tools/textile/
[4]: http://docutils.sourceforge.net/rst.html
[5]: http://www.triptico.com/software/grutatxt.html
[6]: http://ettext.taint.org/doc/
[bq]: #blockquotes
[l]: #lists

103
docs/en/notes/theme/guide/markdown/caniuse.md Normal file
View File

@ -0,0 +1,103 @@
---
title: Can I Use
createTime: 2025/03/24 22:10:32
icon: streamline:desktop-help
permalink: /en/guide/markdown/caniuse/
---
## Overview
When writing articles, you can embed the support status of [can-i-use](https://caniuse.com/) WEB features across platforms.
This makes it easier to describe the support level of a particular WEB feature.
## Configuration
This feature is not enabled by default. You can enable it in the configuration file.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdownP: {
caniuse: true, // [!code ++]
},
})
})
```
In your Markdown file, use the following format:
```md
@[caniuse](feature)
```
For convenience, the theme provides a tool: [caniuse feature search](../../../../../notes/tools/caniuse.md), which can help generate the Markdown code.
## Syntax
```md
@[caniuse](feature)
@[caniuse{browser_versions}](feature)
@[caniuse embed_type](feature)
@[caniuse embed_type{browser_versions}](feature)
```
- `feature`
Required. For correct values, refer to [caniuse-embed.vercel.app](https://caniuse-embed.vercel.app/zh-CN)
- `{browser_versions}`
Optional. The support status of the feature across multiple browser versions.
Default value: `{-2,1}`
Format: `{past,future}` with values ranging from `-5 ~ 3`
- Less than `0` indicates support below the current browser version
- `0` indicates support at the current browser version
- Greater than `0` indicates support above the current browser version
- `embed_type`
Optional. The type of resource embedding.
Type: `'embed' | 'image'`
Default value: `'embed'`
:::caution
The use of image type is no longer recommended. Instead, use the embed type, as the theme has changed the embed implementation, offering faster loading, smaller size, and better interaction.
:::
## Examples
**Get the browser support status for the CSS pseudo-class selector `:dir()`:**
```md
@[caniuse](css-matches-pseudo)
```
Effect:
@[caniuse](css-matches-pseudo)
**Get the browser support status for the CSS pseudo-class selector `:dir()` as an image:**
```md
@[caniuse image](css-matches-pseudo)
```
Effect:
@[caniuse image](css-matches-pseudo)
**Get the browser support status for the CSS pseudo-class selector `:dir()` for specific browser versions:**
```md
@[caniuse{-2,3}](css-matches-pseudo)
```
Effect:
@[caniuse{-2,3}](css-matches-pseudo)

91
docs/en/notes/theme/guide/markdown/card.md Normal file
View File

@ -0,0 +1,91 @@
---
title: Card
createTime: 2025/03/24 19:46:13
icon: solar:card-broken
permalink: /en/guide/markdown/card/
---
## Overview
To highlight content, place it in a card container `::: card`.
To display multiple cards side by side when space allows, use the `card-grid` container around multiple cards.
## Syntax
```md
<!-- Single card -->
::: card title="Title" icon="twemoji:astonished-face"
This is the card content.
:::
<!-- Multiple cards -->
:::: card-grid
::: card title="Card Title 1" icon="twemoji:astonished-face"
This is the card content.
:::
::: card title="Card Title 2" icon="twemoji:astonished-face"
This is the card content.
:::
::::
```
Cards support optional `title` and `icon`. The icon can be an image URL or an Iconify icon name.
## Example
**Input:**
```md
::: card title="Card Title" icon="twemoji:astonished-face"
This is the card content.
:::
```
**Output:**
::: card title="Card Title" icon="twemoji:astonished-face"
This is the card content.
:::
**Input:**
```md
:::: card-grid
::: card title="Card Title 1" icon="twemoji:astonished-face"
This is the card content.
:::
::: card title="Card Title 2" icon="twemoji:astonished-face"
This is the card content.
:::
::::
```
**Output:**
:::: card-grid
::: card title="Card Title 1" icon="twemoji:astonished-face"
This is the card content.
:::
::: card title="Card Title 2" icon="twemoji:astonished-face"
This is the card content.
:::
::::
::: info
If you prefer to use cards via components, you can check out the [Card Component](/en/guide/features/component/#card).
:::

268
docs/en/notes/theme/guide/markdown/collapse.md Normal file
View File

@ -0,0 +1,268 @@
---
title: Collapsible panel
icon: carbon:collapse-categories
createTime: 2025/03/25 10:13:04
permalink: /en/guide/markdown/collapse/
badge:
type: tip
text: 1.0.0-rc.137 +
---
## Overview
In Markdown, the `::: collapse` container, combined with Markdown unordered list syntax, can be used to create ==collapsible panels==.
- It supports setting the mode to **accordion** using the `accordion` option.
## Enable
This feature is not enabled by default. You need to enable it in the `theme` configuration.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
collapse: true, // [!code ++]
}
})
})
```
## Usage
In Markdown, use the `::: collapse` container with Markdown unordered list syntax, where each item represents a separate collapsible area.
```md title="collapse.md"
::: collapse
- Title 1 <!-- Title, click to control expand/collapse -->
<!-- There must be an empty line between the title and the content -->
Content <!-- Content, the collapsible area -->
- Title 2
Content
:::
```
For each item in the list:
- From the **first line** to the **first empty line** is the **title**.
- **After the first empty line**: The main content.
:::important Please note the correct indentation
:::
**A simple example:**
**Input:**
```md
::: collapse
- Title 1
Main content
- Title 2
Main content
:::
```
**Output:**
::: collapse
- Title 1
Main content
- Title 2
Main content
:::
## Configuration
After the `::: collapse` container syntax, you can add configuration options:
- `accordion`: Sets the collapsible panels to ==accordion== mode. In accordion mode, only one panel can be expanded at a time. Clicking another panel will close the previously opened one.
- `expand`: Expands all panels by default. This option is invalid in accordion mode.
Before the title of each list item, you can use special markers `:+` or `:-` to set the initial state of the item to **expanded** or **collapsed**.
## Examples
### Basic Usage
**Input:**
```md
::: collapse
- Title 1
Main content
- Title 2
Main content
:::
```
**Output:**
::: collapse
- Title 1
Main content
- Title 2
Main content
:::
### Expand All by Default
Add the `expand` option to expand all panels by default.
**Input:**
```md /expand/
::: collapse expand
- Title 1
Main content
- Title 2
Main content
:::
```
**Output:**
::: collapse expand
- Title 1
Main content
- Title 2
Main content
:::
### Accordion Mode
Add the `accordion` option to set the mode to accordion, allowing only one panel to be expanded at a time. Clicking another panel will close the previously opened one.
```md /accordion/
::: collapse accordion
- Title 1
Main content
- Title 2
Main content
- Title 3
Main content
:::
```
**Output:**
::: collapse accordion
- Title 1
Main content
- Title 2
Main content
- Title 3
Main content
:::
### Expand Items with `:+`
By default, all collapsible panels are closed. You can use the `:+` marker to set the initial state of an item to expanded.
**Input:**
```md /:+/
::: collapse
- Title 1
Main content
- :+ Title 2
Main content
- :+ Title 3
Main content
:::
```
**Output:**
::: collapse
- Title 1
Main content
- :+ Title 2
Main content
- :+ Title 3
Main content
:::
### Collapse Items with `:-`
When the `expand` option is configured, all panels are expanded by default. You can use the `:-` marker to set the initial state of an item to collapsed.
**Input:**
```md /:-/
::: collapse expand
- Title 1
Main content
- :- Title 2
Main content
- Title 3
Main content
:::
```
**Output:**
::: collapse expand
- Title 1
Main content
- :- Title 2
Main content
- Title 3
Main content
:::

95
docs/en/notes/theme/guide/markdown/demo-wrapper.md Normal file
View File

@ -0,0 +1,95 @@
---
title: Demo Wrapper
createTime: 2025/03/24 21:49:01
icon: icon-park-outline:eyes
permalink: /en/guide/markdown/demo-wrapper/
outline: 2
---
## Overview
Sometimes, you may need to add examples in your content but want them to be presented separately from other content.
The theme supports adding demo wrapper in Markdown files.
## Syntax
````md
::: demo-wrapper
Add your example here
:::
````
## Options
- `title="xxx"`: Title
- `no-padding`: No padding
- `img`: Use when only containing an image
- `height="xxx"`: Height
## Example
Image only:
```md
::: demo-wrapper img no-padding
![hero](/images/custom-hero.jpg)
:::
```
**Output:**
::: demo-wrapper img no-padding
![hero](/images/custom-hero.jpg)
:::
Markdown content:
```md
::: demo-wrapper title="Title"
### Third-level heading
This is the content within the demo wrapper.
:::
```
**Output:**
::: demo-wrapper title="Title"
### Third-level heading
This is the content within the demo wrapper.
:::
HTML/Vue code:
```md
::: demo-wrapper
<h1 class="your-demo-title">This is a heading</h1>
<p class="your-demo-paragraph">This is a paragraph</p>
<style>
.your-demo-title {
color: red;
}
.your-demo-paragraph {
color: blue;
}
</style>
:::
```
**Output:**
::: demo-wrapper
<h1 class="your-demo-title">This is a title</h1>
<p class="your-demo-paragraph">This is a paragraph</p>
<style>
.your-demo-title {
color: red !important;
}
.your-demo-paragraph {
color: blue !important;
}
</style>
:::

360
docs/en/notes/theme/guide/markdown/extensions.md
View File

@ -8,4 +8,362 @@ tags:
- markdown
---
todo ...
## Header Anchors
Headers automatically have anchors applied.
### Custom Anchors
To specify a custom anchor for a header instead of using the auto-generated one, add a suffix to the header:
```md
# Using a Custom Anchor {#my-anchor}
```
This allows linking to the header as `#my-anchor` instead of the default `#using-a-custom-anchor`.
## Links
Internal and external links are specially processed.
The theme automatically generates a new link for each md file and stores it in the `permalink` of the corresponding md file's frontmatter. You can modify these links at any time. You can also disable this feature via the `theme.autoFrontmatter` option, reverting to VuePress's default behavior.
### Internal Links
There are three ways to use internal links:
- Use the generated `permalink` as the target for the internal link.
- Use the relative path of the md file as the target for the internal link.
- Use the absolute path of the md file as the target for the internal link. The absolute path `/` indicates starting from the `${sourceDir}` directory.
```md
[Markdown](/guide/markdown/)
[Markdown](./basic.md)
```
Renders as:
[Markdown](/guide/markdown/)
[Markdown](./basic.md)
### External Links
External links have `target="_blank" rel="noreferrer"`:
[VuePress](https://v2.vuepress.vuejs.org/ )
## GitHub-Style Tables
**Input:**
```md
| Tables | Are | Cool |
| ------------- | :-----------: | ----: |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
```
**Output:**
| Tables | Are | Cool |
| ------------- | :-----------: | ----: |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
## Emoji :tada:
**Input:**
```md
:tada: :100:
```
**Output:**
:tada: :100:
You can find the [list of all supported emojis](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs ) here.
## Table of Contents
**Input:**
```md
[[TOC]]
```
**Output:**
[[TOC]]
## Custom Containers
Custom containers can be defined by their type, title, and content.
### Default Title
**Input:**
```md
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
```
**Output:**
::: note
This is a note box
:::
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: caution
This is a dangerous warning.
:::
::: details
This is a details block.
:::
### Custom Title
You can set a custom title by appending text after the container's "type".
**Input:**
````md
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VitePress!')
```
:::
````
**Output:**
::: caution STOP
Danger zone, do not proceed
:::
::: details Click to view code
```js
console.log('Hello, VitePress!')
```
:::
## GitHub-Style Alerts
The theme also supports rendering [GitHub-style 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 ). They are rendered in the same way as [custom containers](#custom-containers).
**Input:**
```md
> [!NOTE]
> Emphasizes important information that users should know even when skimming the document.
> [!TIP]
> Advisory information that helps users achieve their goals more smoothly.
> [!IMPORTANT]
> Information crucial for users to achieve their goals.
> [!WARNING]
> Key content that requires immediate user attention due to potential risks.
> [!CAUTION]
> Negative impacts of certain actions.
```
**Output:**
> [!NOTE]
> Emphasizes important information that users should know even when skimming the document.
> [!TIP]
> Advisory information that helps users achieve their goals more smoothly.
> [!IMPORTANT]
> Information crucial for users to achieve their goals.
> [!WARNING]
> Key content that requires immediate user attention due to potential risks.
> [!CAUTION]
> Negative impacts of certain actions.
## Mathematical Equations
**Input:**
````When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
**Maxwell's equations:**
| equation | description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
````
**Output:**
When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
**Maxwell's equations:**
| equation | description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
## Superscripts and Subscripts
- Use `^ ^` for superscript notation.
- Use `~ ~` for subscript notation.
**Input:**
```md
- 19^th^
- H~2~O
```
**Output:**
- 19^th^
- H~2~O
## Custom Alignment
**Input:**
````md
::: left
Left-aligned content
:::
::: center
Centered content
:::
::: right
Right-aligned content
:::
````
**Output:**
::: left
Left-aligned content
:::
::: center
Centered content
:::
::: right
Right-aligned content
:::
## Attribute Support
You can use special syntax to add attributes to Markdown elements.
**Adding attributes to an image:**
This adds a class attribute named `full-width` and a `width` attribute with the value `100%` to the image.
```md
![](/plume.png){.full-width width="100%"}
```
Other attributes are also supported:
```md
A paragraph with text. {#p .a .b align=center customize-attr="content with spaces"}
```
This will be rendered as:
```html
<p id="p" class="a b" align="center" customize-attr="content with spaces">
A paragraph with text.
</p>
```
## Task Lists
**Input:**
````md
- [ ] Task 1
- [x] Task 2
- [ ] Task 3
````
**Output:**
- [ ] Task 1
- [x] Task 2
- [ ] Task 3
## Footnotes
**Input:**
````md
The farthest distance in the world Is not the distance between life and death But you don't know I love you when I stand in front of you.[^footnote1]。
[^footnote1]: From India.Rabindranath Tagore **The Farthest Distance in the World**
````
**Output:**
The farthest distance in the world Is not the distance between life and death But you don't know I love you when I stand in front of you.[^footnote1]。
[^footnote1]: From India.Rabindranath Tagore **The Farthest Distance in the World**

131
docs/en/notes/theme/guide/markdown/file-tree.md Normal file
View File

@ -0,0 +1,131 @@
---
title: File Tree
createTime: 2025/03/24 20:15:12
icon: mdi:file-tree
permalink: /en/guide/markdown/file-tree/
---
## Overview
In Markdown, you can use the `file-tree` container to display a directory structure with file icons and collapsible subdirectories.
## Syntax
In the `::: file-tree` container, use the built-in **Markdown unordered list syntax** to specify the organization of files and directories.
Use nested list items to create subdirectories; if you want a directory to not display specific content, simply add a slash `/` at the end of the list item.
The following syntax can be used to customize the appearance of the file tree:
- Highlight files or directories by bolding their names, e.g., `**README.md**`
- Add annotations to files or directories by appending additional text after the name
- Use `...` or `…` as names to add placeholder files and directories.
- Adding `icon="simple"` or `icon="colored"` after `:::file-tree` can switch to simple icons or colored icons, with colored icons being the default.
**Input:**
```md
::: file-tree
- docs
- .vuepress
- config.ts
- page1.md
- README.md
- theme A **theme** directory
- client
- components
- **Navbar.vue**
- composables
- useNavbar.ts
- styles
- navbar.css
- config.ts
- node/
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
- …
:::
```
**Output:**
::: file-tree
- docs
- .vuepress
- config.ts
- page1.md
- README.md
- theme A **theme** directory
- client
- components
- **Navbar.vue**
- composables
- useNavbar.ts
- styles
- navbar.css
- config.ts
- node/
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
- …
:::
## Using Simple Icons
**Input:**
```md
::: file-tree icon="simple"
- docs
- .vuepress
- config.ts
- page1.md
- README.md
- package.json
:::
```
**Output:**
::: file-tree icon="simple"
- docs
- .vuepress
- config.ts
- page1.md
- README.md
- package.json
:::
## Configuration
You can configure the default icon type for the file tree in the `plugins.mdPower.fileTree` option:
::: code-tabs
@tab .vuepress/config.ts
```ts
export default defineUserConfig({
theme: plumeTheme({
markdown: {
fileTree: {
icon: 'simple', // 'simple' | 'colored'
}
},
})
})
```
:::
::: tip Worried that colored icons will affect the build package size?
You don't need to worry. The colored icons for the file tree are also parsed from `iconify`. We recommend that you install the `@iconify/json` project locally.
The theme will automatically parse the icon data from `@iconify/json` into local icon resources. Even if you use them multiple times on different pages, including the navbar, sidebar, icon components, etc., the same icon will only exist as one resource!
Each colored icon is approximately between `1kb ~ 2kb` in size. Even if your file tree uses 100+ different icons, the impact on the final build package size will not be significant.
:::

74
docs/en/notes/theme/guide/markdown/icons.md Normal file
View File

@ -0,0 +1,74 @@
---
title: Icons
createTime: 2025/03/23 14:24:45
icon: grommet-icons:emoji
permalink: /en/guide/markdown/iconify/
---
## Overview
Use [iconify](https://iconify.design/) icons in Markdown files.
The theme provides an [`<Icon />`](../components/icon.md) component for using icons in Markdown and a simplified Markdown syntax for easier icon usage.
To enhance this feature, the theme recommends installing the `@iconify/json` dependency. It automatically parses icon data from `@iconify/json`, packs used icons as local resources for better access.
::: npm-to
```sh
npm install @iconify/json
```
:::
## Syntax
```md
:[collect:name]:
```
To set icon size and color:
```md
:[collect:name size]:
:[collect:name /color]:
:[collect:name size/color]:
```
Iconify has numerous icons grouped into different `collect` categories. Each `collect` has its own set of icons.
You can find `collect` and `name` at <https://icon-sets.iconify.design/>.
## Examples
Input:
```md
:[ion:logo-markdown]:
```
Output:
:[ion:logo-markdown]:
This is an inline syntax, allowing use with other Markdown elements in the same line.
Input:
```md
github: :[tdesign:logo-github-filled]:
Change color: :[tdesign:logo-github-filled /#f00]:
Change size: :[tdesign:logo-github-filled 36px]:
Change size and color: :[tdesign:logo-github-filled 36px/#f00]:
Colored icon: :[skill-icons:vscode-dark 36px]:
```
Output:
github: :[tdesign:logo-github-filled]:
Change color: :[tdesign:logo-github-filled /#f00]:
Change size: :[tdesign:logo-github-filled 36px]:
Change size and color: :[tdesign:logo-github-filled 36px/#f00]:
Colored icon: :[skill-icons:vscode-dark 36px]:

159
docs/en/notes/theme/guide/markdown/include.md Normal file
View File

@ -0,0 +1,159 @@
---
title: Import files
createTime: 2025/03/25 09:15:18
icon: fluent:table-simple-include-16-regular
permalink: /en/guide/markdown/include/
outline: 2
---
## Overview
The theme supports importing file slices in Markdown files.
Importing files is enabled by default, and you can also customize the behavior through configuration.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
include: { // [!code ++:3]
// ... options
},
}
})
})
```
## Syntax
Use `<!-- @include: filename -->` to import a file.
If you want to import a portion of the file, you can specify the line numbers:
- `<!-- @include: filename{start-end} -->`
- `<!-- @include: filename{start-} -->`
- `<!-- @include: filename{-end} -->`
You can also import file regions:
- `<!-- @include: filename#region -->`
::::tip File Regions
File regions are a concept in VSCode, where the content is enclosed by `#region` and `#endregion` comments.
<!-- @include: ../../snippet/include-1.snippet.md -->
::::
## Configuration
You can also set an object to customize the file path and inclusion behavior.
```ts
interface IncludeOptions {
/**
* Process the include file path
*
* @default (path) => path
*/
resolvePath?: (path: string, cwd: string | null) => string
/**
* Whether to deeply import included Markdown files
*
* @default false
*/
deep?: boolean
/**
* Whether to use `<!-- @include: xxx -->` instead of `@include: xxx` to import files
*
* @default true
*/
useComment?: boolean
/**
* Whether to resolve relative image paths in included Markdown files
*
* @default true
*/
resolveImagePath?: boolean
/**
* Whether to resolve relative file paths in included Markdown files
*
* @default true
*/
resolveLinkPath?: boolean
}
```
For example: You can use `@src` as an alias for the source folder.
```ts{5-11} title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
include: {
resolvePath: (file) => {
if (file.startsWith('@src'))
return file.replace('@src', path.resolve(__dirname, '..'))
return file
},
},
}
})
})
```
Additionally, if you want to place Markdown files next to the actual files but do not want them to be rendered as pages, you can set the `pagePatterns` option in the VuePress configuration. For more details, see [pagePatterns](https://vuejs.press/zh/reference/config.html#pagepatterns ).
```ts title=".vuepress/config.ts"
export default defineUserConfig({
// Now any file with the `.snippet.md` extension will not be rendered as a page
pagePatterns: ['**/*.md', '!**/*.snippet.md', '!.vuepress', '!node_modules'], // [!code ++]
theme: plumeTheme({
markdown: {
include: true
}
})
})
```
## Examples
There is a `foo.snippet.md` file in the project:
:::: code-tabs
@tab foo.snippet.md
```md
### Level 3 Heading
This is the content of the `foo.snippet.md` file.
::: info
Content of the info container
:::
<!-- region snippet -->
This is the content wrapped by `<!-- region snippet -->`.
It can be imported via `<!-- @include: ./foo.snippet.md#snippet -->`.
<!-- endregion snippet -->
```
::::
Import the file using `<!-- @include: ./foo.snippet.md -->`：
:::: demo-wrapper title="Include by file"
<!-- @include: ../../snippet/include-2.snippet.md -->
::::
Import lines 5 to 7 of the file using `<!-- @include: ./foo.snippet.md{5-7} -->`:
:::: demo-wrapper title="Include by lines"
<!-- @include: ../../snippet/include-2.snippet.md{5-7} -->
::::
Import the `snippet` region using `<!-- @include: ./foo.snippet.md#snippet -->`:
:::: demo-wrapper title="Include by file region"
<!-- @include: ../../snippet/include-2.snippet.md#snippet -->
::::

147
docs/en/notes/theme/guide/markdown/mark.md Normal file
View File

@ -0,0 +1,147 @@
---
title: Mark
icon: mingcute:mark-pen-line
createTime: 2025/03/23 14:33:48
permalink: /en/guide/markdown/mark/
---
## Overview
The ==marker pen== feature extends Markdown's `==Mark==` syntax, allowing text to be marked with various colors and customizable options.
## Syntax
### Basic Usage
Use `== ==` to mark text. Note the spaces around the equals signs.
**Input:**
```md
vuepress-theme-plume is a ==simple and beautiful== theme
```
**Output:**
vuepress-theme-plume is a ==simple and beautiful== theme
### Color Customization
Different marker pen colors are set using [Markdown attribute syntax](./extensions.md#attribute-support).
Add `{.classname}` immediately after the `==Mark==` syntax to customize colors.
**Input:**
```md
==a tip=={.tip} ==a warning=={.warning} ==an error=={.danger} ==important content=={.important}
```
**Output:**
==a tip=={.tip} ==a warning=={.warning} ==an error=={.danger} ==important content=={.important}
## Built-in Color Schemes
The theme includes these predefined schemes:
- **default**: `==Default==` - ==Default==
- **info**: `==Info=={.info}` - ==Info=={.info}
- **note**: `==Note=={.note}` - ==Note=={.note}
- **tip**: `==Tip=={.tip}` - ==Tip=={.tip}
- **warning**: `==Warning=={.warning}` - ==Warning=={.warning}
- **danger**: `==Danger=={.danger}` - ==Danger=={.danger}
- **caution**: `==Caution=={.caution}` - ==Caution=={.caution}
- **important**: `==Important=={.important}` - ==Important=={.important}
## Custom Color Schemes
Marker pen can be customized via [custom styles](../custom/style.md).
You can fully customize highlighter colors, including modifying built-in schemes.
Within the theme, markers are set using the combination of `class name` and `CSS variables`.
The following are `CSS variables` related to markers:
- `--vp-mark-text` - Text color of marker pen
- `--vp-mark-bg` - Background color of marker pen
- `--vp-mark-linear-color` - gradient color, only used in the built-in `--vp-mark-bg-image`
- `--vp-mark-bg-shift` - Built in gradient background offset of marker pen
- `--vp-mark-bg-image` - Background image of marker pen
### Modifying Built-in Schemes
Copy these built-in configurations to your [style file](../custom/style.md#style-file) for modification:
```css :collapsed-lines
mark {
--vp-mark-text: currentcolor;
--vp-mark-bg: transparent;
--vp-mark-bg-shift: 0.55lh;
--vp-mark-linear-color: var(--vp-c-brand-3);
--vp-mark-bg-image: linear-gradient(to right, var(--vp-mark-linear-color) 50%, transparent 50%);
}
mark.note {
--vp-mark-linear-color: #ff0;
}
mark.info {
--vp-mark-linear-color: var(--vp-c-default-1);
}
mark.tip {
--vp-mark-linear-color: #39ff14;
}
mark.warning {
--vp-mark-linear-color: #fc0;
}
mark.caution, mark.danger {
--vp-mark-linear-color: #f99;
}
mark.important {
--vp-mark-linear-color: #ccf;
}
[data-theme="dark"] mark.note {
--vp-mark-linear-color: #660;
}
[data-theme="dark"] mark.tip {
--vp-mark-linear-color: #063;
}
[data-theme="dark"] mark.warning {
--vp-mark-linear-color: #c60;
}
[data-theme="dark"] mark.caution,
[data-theme="dark"] mark.danger {
--vp-mark-linear-color: #c66;
}
[data-theme="dark"] mark.important {
--vp-mark-linear-color: #66c;
}
```
### Adding New Schemes
Add new color schemes in your [style file](../custom/style.md#style-file) using this format:
```css
mark.classname {
--vp-mark-text: marktext; /* Text color */
--vp-mark-bg-image: none; /* Background image */
--vp-mark-bg: mark; /* Background color */
--vp-mark-linear-color: mark; /* Gradient color */
}
```
Use `==Mark=={.classname}` in Markdown.
You can name `classname` freely and add other CSS properties besides modifying CSS variables.

203
docs/en/notes/theme/guide/markdown/npm-to.md Normal file
View File

@ -0,0 +1,203 @@
---
title: npmTo Container
icon: gg:npm
createTime: 2025/03/24 21:56:32
permalink: /en/guide/markdown/npm-to/
---
## Overview
The npmTo container converts npm command-line code blocks into `pnpm / yarn / deno / bun` command-line code blocks, presenting them as a group of code blocks on the page.
Within the `::: npm-to` container, you only need to write the npm command code block once.
::: details Why do we need the npmTo container?
When I write documentation, I often need to provide commands for different environments like `pnpm / yarn / npm`.
This requires multiple code blocks wrapped in the `::: code-tabs` container, which is time-consuming and takes up a lot of space in the Markdown content, leading to a poor experience. That's why I created the `::: npm-to` container to solve this problem.
:::
## Usage
````md{1,5}
::: npm-to
``` sh
npm install -D vuepress vuepress-theme-plume
```
:::
````
Just wrap the code block containing the `npm` command-line in the `::: npm-to` container.
::: warning The npm-to container only supports a single code block and cannot contain other content
:::
The code above will be converted internally to:
````md
::: code-tabs
@tab pnpm
``` sh
pnpm add -D vuepress vuepress-theme-plume
```
@tab yarn
``` sh
yarn add -D vuepress vuepress-theme-plume
```
@tab npm
``` sh
npm install -D vuepress vuepress-theme-plume
```
:::
````
The final output on the page will be:
::: npm-to
``` sh
npm install -D vuepress vuepress-theme-plume
```
:::
You can also control the display order of the code blocks in the group, as shown below:
**Input:**
````md {1,5}
::: npm-to tabs="npm,yarn,pnpm,bun,deno"
``` sh
npm install -D vuepress vuepress-theme-plume
```
:::
````
**Output:**
::: npm-to tabs="npm,yarn,pnpm,bun,deno"
``` sh
npm install -D vuepress vuepress-theme-plume
```
:::
## Configuration
This feature is not enabled by default. You need to enable it in the `theme` configuration.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
// npmTo: true, // Enable with default configuration
npmTo: {
tabs: ['npm', 'yarn', 'pnpm'], // Default display order of code blocks
}
},
})
})
```
`npm-to` supports converting `npm` command lines to `pnpm / yarn / deno / bun` command lines. You can configure the `tabs` according to your needs.
## Supported Command Lines
`npmTo` does not support all `npm` command lines. Here is the list of supported commands:
- `npm install` / `npm i`
- `npm run` / `npm run-script`
- `npm init`
- `npm create`
- `npm uninstall` / `npm rm` / `npm remove` / `npm un` / `npm unlink`
- `npm ci`
- `npx`
::: info
For unsupported command lines, `npmTo` will not process them and will only copy them to the other code blocks.
:::
## Examples
**Input:**
````md
::: npm-to
```sh
npm install && npm run docs:dev
```
:::
````
**Output:**
::: npm-to
```sh
npm install && npm run docs:dev
```
:::
**Input:**
````md
::: npm-to
```sh
npm i -D vue
npm i --save-peer vuepress
npm i typescript
```
:::
````
**Output:**
::: npm-to
```sh
npm i -D vue
npm i --save-peer vuepress
npm i typescript
```
:::
**Input:**
````md
::: npm-to
```sh
npm run docs:dev -- --clean-cache
```
:::
````
**Output:**
::: npm-to
```sh
npm run docs:dev -- --clean-cache
```
:::
**Input:**
````md
::: npm-to tabs="pnpm,yarn,npm,bun,deno"
```sh
npm ci
```
:::
````
**Output:**
::: npm-to tabs="pnpm,yarn,npm,bun,deno"
```sh
npm ci
```
:::

84
docs/en/notes/theme/guide/markdown/plot.md Normal file
View File

@ -0,0 +1,84 @@
---
title: Secret Text
createTime: 2025/03/24 16:56:15
icon: weui:eyes-off-outlined
permalink: /en/guide/markdown/plot/
---
## Overview
Sometimes you may want to partially conceal text content rather than displaying it outright - whether to spark readers' curiosity or simply add an element of playful interactivity.
To fulfill this whimsical need, the theme provides an interesting **'secret text'** feature. Here's how it looks:
:::demo-wrapper
Did you know that !!Lu Xun!! once said: "!!I never said this quote!!!" This revelation struck me with sudden clarity, inspiring me with unparalleled energy! Consequently, !!I rolled over in bed!!!
:::
Readers can't directly view the complete content - concealed portions require mouse hover to reveal.
## Configuration
This feature is disabled by default. Enable it in `theme` configuration:
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
plot: true, // [!code ++]
}
})
})
```
`markdownPower.plot` accepts `boolean | PlotOptions` type:
```ts
interface PlotOptions {
/**
* Enable `!! !!` markdown syntax (non-standard markup, requires plugin)
* If false, only <Plot /> component can be used
* @default true
*/
tag?: boolean
/**
* Mask layer color
*/
mask?: string | { light: string, dark: string }
/**
* Text color
*/
color?: string | { light: string, dark: string }
/**
* Trigger method
*
* @default 'hover'
*/
trigger?: 'hover' | 'click'
}
```
## Syntax
```md
!!Content to conceal!!
```
If you prefer not to use non-standard `!! !!` syntax, set `plot.tag` to `false` and use the [`<Plot />`](../components/plot.md) component instead.
## Examples
Input:
```md
Did you know that !!Lu Xun!! once said: "!!I never said this quote!!!" This revelation struck me with sudden clarity, inspiring me with unparalleled energy! Consequently, !!I rolled over in bed!!!
```
Output:
:::demo-wrapper
Did you know that !!Lu Xun!! once said: "!!I never said this quote!!!" This revelation struck me with sudden clarity, inspiring me with unparalleled energy! Consequently, !!I rolled over in bed!!!
:::

77
docs/en/notes/theme/guide/markdown/steps.md Normal file
View File

@ -0,0 +1,77 @@
---
title: Steps
createTime: 2025/03/24 20:10:59
icon: streamline:steps-number
permalink: /en/guide/markdown/steps/
---
## Overview
Sometimes, you need to display content in progressive steps. You can achieve this using the `steps` container.
## Syntax
Within the `steps` container, use ordered (or unordered) lists to represent steps. You can use any Markdown syntax inside the container.
````md
::: steps
1. Step 1
Related content
2. Step 2
Related content
:::
````
## Example
Input:
````md
:::: steps
1. Step 1
```ts
console.log('Hello World!')
```
2. Step 2
Here is the content related to step 2
3. Step 3
::: tip
Hint container
:::
4. End
::::
````
Output:
:::: steps
1. Step 1
```ts
console.log('Hello World!')
```
2. Step 2
Here is the content related to step 2
3. Step 3
::: tip
Hint container
:::
4. End
::::

110
docs/en/notes/theme/guide/markdown/tabs.md Normal file
View File

@ -0,0 +1,110 @@
---
title: Tabs
createTime: 2025/03/24 21:13:58
icon: vaadin:tabs
permalink: /en/guide/markdown/tabs/
---
## Overview
Markdown supports tabs functionality.
## Syntax
You need to wrap the tabs in a `tabs` container.
You can add an id suffix to the `tabs` container, which will be used as the tab id.
All tabs with the same id will share the same toggle event.
```md
::: tabs#fruit
<!-- Here, fruit will be used as the id, it is optional -->
<!-- Tab content -->
:::
```
Within this container, you should use the `@tab` tag to mark and separate the tab content.
After the `@tab` tag, you can add the text `:active` to default activate the tab, and the subsequent text will be parsed as the tab title.
```md
::: tabs
@tab Title 1
<!-- Tab 1 content -->
@tab Title 2
<!-- Tab 2 content -->
@tab:active Title 3
<!-- Tab 3 will be default activated -->
<!-- Tab 3 content -->
:::
```
By default, the title will be used as the tab's value, but you can override it with an id suffix.
```md
::: tabs
@tab Title 1
<!-- Here, the tab 1's title "Title 1" will be used as the value. -->
<!-- Tab 1 content -->
@tab Title 2#Value 2
<!-- Here, the tab 2's title will be "Title 2", but it will use "Value 2" as the tab's value -->
<!-- Tab 2 content -->
:::
```
You can use Vue syntax and components within each tab, and you can access value and isActive,
which represent the tab's bound value and whether the tab is active.
## Example
**Input:**
````
::: tabs
@tab npm
npm should be installed together with Node.js.
@tab pnpm
```sh
corepack enable
corepack use pnpm@8
```
:::
````
**Output:**
::: tabs
@tab npm
npm should be installed together with Node.js.
@tab pnpm
```sh
corepack enable
corepack use pnpm@8
```
:::

692
docs/en/notes/theme/guide/markdown/timeline.md Normal file
View File

@ -0,0 +1,692 @@
---
title: Timeline
icon: mdi:timeline-text-outline
createTime: 2025/03/24 21:19:12
permalink: /en/guide/markdown/timeline/
badge:
text: 1.0.0-rc.137 +
type: tip
---
## Overview
In markdown, using the `::: timeline` container with markdown unordered list syntax achieves a ==timeline== rendering effect.
- Supports ==horizontal== and ==vertical== directions
- Vertical direction supports **left alignment**, **right alignment**, and **both ends alignment**
- Supports **icons** and **line styles**
- Supports preset **types** to set **colors** and custom colors
## Enablement
This feature is not enabled by default. You need to enable it in the `theme` configuration.
```ts title=".vuepress/config.ts"
export default defineUserConfig({
theme: plumeTheme({
markdown: {
timeline: true, // [!code ++]
}
})
})
```
## Usage
In the `::: timeline` container, use markdown unordered list syntax, with each list item being a point on the timeline.
```md{1,9} title="timeline.md"
::: timeline Configuration
- Title
Configuration
Body content
- Title
Configuration
Body content
:::
```
For each list item:
- From **the first line** to **the first blank line**, it is the **title**, with the line following the title used to **configure** the item's behavior
- **After the first blank line**: body content
:::important Please note to add the correct indentation
:::
_A simple example:_
_Input:_
```md
::: timeline
- Node one
time=2025-03-20 type=success
Body content
- Node two
time=2025-02-21 type=warning
Body content
- Node three
time=2025-01-22 type=danger
Body content
:::
```
_Output:_
::: timeline
- Node one
time=2025-03-20 type=success
Body content
- Node two
time=2025-02-21 type=warning
Body content
- Node three
time=2025-01-22 type=danger
Body content
:::
::: important The timeline defaults to vertical direction
:::
## Configuration
The **timeline** supports flexible configuration options, divided into two main parts:
- **Container configuration**: Configurations on the `::: timeline` container, following `::: timeline` like `::: timeline horizontal` for horizontal timeline rendering.
- **List item configuration**: Configurations for each list item, following the title line like:
```md
::: timeline
- Title <!--Title line-->
Also title <!--Title line-->
time=2025-03-20 type=success <!--Configuration line, optional-->
<!--Blank line, required if there's body content-->
Body content
:::
```
### Container Configuration
#### horizontal
- **Type**: `boolean`
- **Default**: `false`
Renders the timeline horizontally.
#### card
- **Type**: `boolean`
- **Default**: `false`
Renders each timeline node as a card style (can be overridden in list item configuration).
#### placement
- **Type**: `'left' | 'right' | 'between'`
- **Default**: `'left'`
Alignment of timeline nodes ==only effective in vertical direction=={.warning}.
- `left`: Aligns timeline to the left
- `right`: Aligns timeline to the right
- `between`: Aligns timeline to both ends (define position via `placement` in list item configuration, default is `left`)
#### line
- **Type**: `'solid' | 'dashed' | 'dotted'`
- **Default**: `'solid'`
Line style (can be overridden in list item configuration).
### List Item Configuration
#### time
- **Type**: `string`
- **Default**: `''`
Time point, can be any string like `2025-03-20` or `Q1`.
#### type
- **Type**: `'info' | 'tip' | 'success' | 'warning' | 'danger' | 'caution' | 'important'`
- **Default**: `'info'`
Type of timeline node.
#### card
- **Type**: `boolean`
- **Default**: `false` (inherits from container configuration)
Renders the current node as a card style.
#### line
- **Type**: `'solid' | 'dashed' | 'dotted'`
- **Default**: `'solid'` (inherits from container configuration)
Line style.
#### icon
- **Type**: `string`
- **Default**: `''`
Icon for the timeline node, supports all [iconify](https://icon-sets.iconify.design/) icons.
#### placement
- **Type**: `'left' | 'right'`
- **Default**: `'left'`
Position of the node when container is set to `between`.
- `left`: On the left side of the timeline
- `right`: On the right side of the timeline
#### color
- **Type**: `string`
- **Default**: `''`
Color for the timeline node line, can be any valid color value.
## Examples
### Horizontal Direction
Add `horizontal` after `:::timeline` to render the timeline horizontally.
Input:
```md /horizontal/
::: timeline horizontal
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
```
Output:
::: timeline horizontal
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
### Right Alignment
Add `placement="right"` after `:::timeline` to render the timeline right-aligned.
Input:
```md /placement="right"/
::: timeline placement="right"
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
```
Output:
::: timeline placement="right"
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
### Both Ends Alignment
Add `placement="between"` after `:::timeline` to render the timeline aligned to both ends.
List items default to the left side of the timeline, use `placement="right"` in list item configuration to set the position to the right.
Input:
```md /placement="between"/ /placement=right/
::: timeline placement="between"
- Node one
time=2025-03-20 placement=right
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger placement=right
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
```
Output:
::: timeline placement="between"
- Node one
time=2025-03-20 placement=right
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger placement=right
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
### Node Types
Add `type=node type` in list item configuration to set the node type.
Input:
```md /type=success/ /type=warning/ /type=danger/ /type=important/
::: timeline
- Node one
time=2025-03-20 type=success
Body content
- Node two
time=2025-04-20 type=warning
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
```
Output:
::: timeline
- Node one
time=2025-03-20 type=success
Body content
- Node two
time=2025-04-20 type=warning
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
### Line Styles
- Add `line=line style` in container configuration to set the default line style for all nodes.
- Add `line=line style` in list item configuration to set the line style for individual nodes.
Input:
```md /line="dotted"/ /line=solid/ /line=dashed/
::: timeline line="dotted"
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger line=dashed
Body content
- Node four
time=2025-01-22 type=important line=solid
Body content
:::
```
Output:
::: timeline line="dotted"
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success
Body content
- Node three
time=2025-01-22 type=danger line=dashed
Body content
- Node four
time=2025-01-22 type=important line=solid
Body content
:::
### Nodes with Icons
Add `icon=icon name` in list item configuration to add icons to nodes.
Icon names support [iconify](https://icon-sets.iconify.design/) icon names.
Input:
```md /icon=mdi:balloon/ /icon=mdi:bookmark/
::: timeline placement="between"
- Node one
time=2025-03-20 placement=right icon=mdi:balloon
Body content
- Node two
time=2025-04-20 type=success icon=mdi:bookmark
Body content
- Node three
time=2025-01-22 type=danger placement=right icon=mdi:bullhorn-variant-outline
Body content
- Node four
time=2025-01-22 type=important card=true icon="mdi:cake-variant-outline"
Body content
:::
```
Output:
::: timeline placement="between"
- Node one
time=2025-03-20 placement=right icon=mdi:balloon
Body content
- Node two
time=2025-04-20 type=success icon=mdi:bookmark
Body content
- Node three
time=2025-01-22 type=danger placement=right icon=mdi:bullhorn-variant-outline
Body content
- Node four
time=2025-01-22 type=important card=true icon="mdi:cake-variant-outline"
Body content
:::
### Card Nodes
Card nodes can be flexibly controlled:
- Add `card` in container configuration to make each list item a card node.
- Add `card=true` in list item configuration to set the node as a card node.
- Add `card=false` in list item configuration to set the node as a non-card node.
The style of card nodes is affected by the `type` configuration.
::: tip Adding `card=true` / `card=false` in list item configuration overrides the container's `card` configuration
:::
Input:
```md{1} /card=false/
::: timeline card
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success card=false
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
```
Output:
::: timeline card
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=success card=false
Body content
- Node three
time=2025-01-22 type=danger
Body content
- Node four
time=2025-01-22 type=important
Body content
:::
## Custom Node Types
Timeline node types are controlled via CSS Variables. The theme provides the following CSS variables:
```css
:root {
--vp-timeline-c-line: var(--vp-c-border); /* Line color */
--vp-timeline-c-point: var(--vp-c-border); /* Point color */
--vp-timeline-c-title: var(--vp-c-text-1); /* Title text color */
--vp-timeline-c-text: var(--vp-c-text-1); /* Body text color */
--vp-timeline-c-time: var(--vp-c-text-3); /* Time text color */
--vp-timeline-c-icon: var(--vp-c-bg); /* Icon color */
--vp-timeline-bg-card: var(--vp-c-bg-soft); /* Card node background color */
}
```
For example, the theme's built-in node type `tip`:
```css /.tip/
.vp-timeline-item.tip {
--vp-timeline-c-line: var(--vp-c-tip-1);
--vp-timeline-c-point: var(--vp-c-tip-1);
--vp-timeline-bg-card: var(--vp-c-tip-soft);
}
```
You can override built-in types or add new ones in [custom styles](../custom/style.md).
Example:
```css title=".vuepress/styles/index.css"
.vp-timeline-item.your-type {
--vp-timeline-c-line: #3cf;
--vp-timeline-c-point: #3cf;
--vp-timeline-bg-card: rgba(60, 252, 255, 0.314);
}
```
```md /type=your-type/
::: timeline
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=your-type card=true
Body content
- Node three
time=2025-01-22 type=danger
Body content
:::
```
::: timeline
- Node one
time=2025-03-20
Body content
- Node two
time=2025-04-20 type=your-type card=true
Body content
- Node three
time=2025-01-22 type=danger
Body content
:::
<style>
.vp-timeline-item.your-type {
--vp-timeline-c-line: #3cf;
--vp-timeline-c-point: #3cf;
--vp-timeline-bg-card: rgba(60, 252, 255, 0.314);
}
</style>

8
docs/en/notes/theme/guide/blog.md → docs/en/notes/theme/guide/quick-start/blog.md
View File

@ -15,7 +15,7 @@ import VPPostItem from 'vuepress-theme-plume/components/Blog/VPPostItem.vue'
## 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).
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.
@ -129,7 +129,7 @@ The following are the available `frontmatter` properties in blog posts.
| 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.
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
@ -461,9 +461,9 @@ config:
:::
For more customization configurations, please refer to [Customize the Homepage](./custom-home.md).
For more customization configurations, please refer to [Customize the Homepage](../custom/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**:
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)

0
docs/en/notes/theme/guide/deployment.md → docs/en/notes/theme/guide/quick-start/deployment.md
View File

4
docs/en/notes/theme/guide/document.md → docs/en/notes/theme/guide/quick-start/document.md
View File

@ -80,7 +80,7 @@ export default defineUserConfig({
::: 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,
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.
:::
@ -613,7 +613,7 @@ You may have noticed that there is a `README.md` file in the `typescript` direct
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!
But you can directly configure `pageLayout: 'home'`, just like configuring the [site home page](../custom/custom-home.md), to customize a home page for the note!
::: code-tabs
@tab typescript/README.md

4
docs/en/notes/theme/guide/international.md → docs/en/notes/theme/guide/quick-start/international.md
View File

@ -158,5 +158,5 @@ You should configure `selectLanguageName` for `theme.locales[localePath]` to dis
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.
- [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.

0
docs/en/notes/theme/guide/intro.md → docs/en/notes/theme/guide/quick-start/intro.md
View File

0
docs/en/notes/theme/guide/optimize-build.md → docs/en/notes/theme/guide/quick-start/optimize-build.md
View File

2
docs/en/notes/theme/guide/project-structure.md → docs/en/notes/theme/guide/quick-start/project-structure.md
View File

@ -7,7 +7,7 @@ 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:
When you [create a project using the command-line tool](usage.md#command-line-installation), its file structure looks like this:
::: file-tree

2
docs/en/notes/theme/guide/quick-start.md → docs/en/notes/theme/guide/quick-start/usage.md
View File

@ -2,7 +2,7 @@
title: Installation/Usage
icon: grommet-icons:install
createTime: 2025/03/02 13:28:45
permalink: /en/guide/quick-start/
permalink: /en/guide/usage/
tags:
- Guide
- Quick Start

22
docs/en/notes/theme/guide/write.md → docs/en/notes/theme/guide/quick-start/write.md
View File

@ -8,11 +8,11 @@ tags:
- Quick Start
---
VuePress supports the complete [Markdown syntax](./markdown/basic.md),
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
The theme also provides [extensions](../markdown/extensions.md) for Markdown syntax. You can also write HTML directly in
Markdown, or use Vue components.
## Frontmatter
@ -38,7 +38,7 @@ 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.
You can read [this article](../../../../4.Tutorials/frontmatter.md) to learn how to write frontmatter correctly.
:::
## Auto-Generated Frontmatter
@ -74,16 +74,16 @@ Preparing **permalink** in advance is quite valuable. On one hand, it can help i
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).
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.
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).
You can easily achieve this through [Theme Configuration > autoFrontmatter](../../config/basic.md#autofrontmatter).
::: code-tabs
@tab .vuepress/config.ts
@ -112,7 +112,7 @@ export default defineUserConfig({
## Conventions
::: info Note
The following content is based on the file structure in [Project Structure](./project-structure.md).
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.
@ -123,7 +123,7 @@ 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.
- 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:
@ -155,17 +155,17 @@ The theme will generate a category page based on the directory structure.
- **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.
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.
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).
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`.

252
docs/en/notes/theme/snippet/include-1.snippet.md Normal file
View File

@ -0,0 +1,252 @@
::: code-tabs
@tab HTML
```html
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
</head>
<body>
<!-- region snippet -->
<p>
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Eligendi,
repellendus. Voluptatibus alias cupiditate at, fuga tenetur error officiis
provident quisquam autem, porro facere! Neque quibusdam animi quaerat
eligendi recusandae eaque.
</p>
<!-- endregion snippet -->
<p>
Veniam harum illum natus omnis necessitatibus numquam architecto eum
dignissimos, quos a adipisci et non quam maxime repellendus alias ipsum,
vero praesentium laborum commodi perferendis velit repellat? Vero,
cupiditate sequi.
</p>
</body>
</html>
```
@tab Markdown
```md
## Hello world
<!-- #region snippet -->
Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptates
inventore iure quo aut doloremque, ipsum ab voluptatem ipsa, velit laborum
illo quae omnis reiciendis hic, ut dolorem non debitis in!
<!-- #endregion snippet -->
Veniam harum illum natus omnis necessitatibus numquam architecto eum
dignissimos, quos a adipisci et non quam maxime repellendus alias ipsum,
vero praesentium laborum commodi perferendis velit repellat? Vero,
cupiditate sequi.
```
@tab TS
```ts
import { include } from '@mdit/plugin-include'
import MarkdownIt from 'markdown-it'
// #region snippet
const mdIt = MarkdownIt().use(include, {
// your options, currentPath is required
currentPath: env => env.filePath,
})
// #endregion snippet
mdIt.render('<!-- @include: ./path/to/include/file.md -->', {
filePath: 'path/to/current/file.md',
})
```
@tab JS
```js
const { include } = require('@mdit/plugin-include')
const MarkdownIt = require('markdown-it')
// #region snippet
const mdIt = MarkdownIt().use(include, {
// your options, currentPath is required
currentPath: env => env.filePath,
})
// #endregion snippet
mdIt.render('<!-- @include: ./path/to/include/file.md -->', {
filePath: 'path/to/current/file.md',
})
```
@tab css
```css
html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}
```
@tab Less
```less
html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}
```
@tab Sass
```scss
html,
body {
margin: 0;
padding: 0;
}
/* #region snippet */
h1 {
font-size: 1.5rem;
}
/* #endregion snippet */
h2 {
font-size: 1.2rem;
}
```
@tab Java
```java
public class HelloWorld {
// #region snippet
public static void main(String args[]){
System.out.println("Hello World");
}
// #endregion snippet
}
```
@tab Python
```py
class MyClass:
msg = "world"
#region snippet
def sayHello(self):
print("Hello " + self.msg + "!")
#region snippet
def sayBye(self):
print("Bye " + self.msg + "!")
```
@tab Visual Basic
```vb
Imports System
Module Module1
# Region snippet
Sub Main()
Console.WriteLine("Hello World!")
Console.WriteLine("Press Enter Key to Exit.")
Console.ReadLine()
End Sub
# EndRegion
End Module
```
@tab Bat
```bat
>nul 2>&1 "%SYSTEMROOT%\system32\cacls.exe" "%SYSTEMROOT%\system32\config\system"
if '%errorlevel%' NEQ '0' (
echo Requesting administrative privileges...
goto UACPrompt
) else ( goto gotAdmin )
::#region snippet
:UACPrompt
echo Set UAC = CreateObject^("Shell.Application"^) > "%temp%\getadmin.vbs"
echo UAC.ShellExecute "%~s0", "", "", "runas", 1 >> "%temp%\getadmin.vbs"
"%temp%\getadmin.vbs"
exit /B
::#endregion snippet
:gotAdmin
if exist "%temp%\getadmin.vbs" ( del "%temp%\getadmin.vbs" )
pushd "%CD%"
CD /D "%~dp0"
```
@tab C\#
```cs
using System;
namespace HelloWorldApp {
class Geeks {
// #region snippet
static void Main(string[] args) {
// statement
// printing Hello World!
Console.WriteLine("Hello World!");
// To prevents the screen from
// running and closing quickly
Console.ReadKey();
}
// #endregion snippet
}
}
```
@tab C/C++
```cpp
#include <iostream>
#include <vector>
std::vector<int> v;
#pragma region snippet
int f() {
for (int item : v) std::cout << item << std::endl;
return v.size();
}
#pragma endregion snippet
int main() {
int n, u;
std::cin >> n;
for (int i = 1; i <= n; ++i) {
std::cin >> u;
v.push_back(u);
}
std::cout << f();
return 0;
}
```
:::

14
docs/en/notes/theme/snippet/include-2.snippet.md Normal file
View File

@ -0,0 +1,14 @@
### Level 3 Heading
This is the content of the `foo.snippet.md` file.
:::info
Content of the info container
:::
<!-- region snippet -->
This is the content wrapped by `<!-- region snippet -->`.
It can be imported via `<!-- @include: ./foo.snippet.md#snippet -->`.
<!-- endregion snippet -->