Writing Articles
VuePress supports the complete Markdown syntax, and uses YAML to define frontmatter page metadata, such as title and creation time.
The theme also provides extensions for Markdown syntax. You can also write HTML directly in Markdown, or use Vue components.
Frontmatter
You can customize each page in VuePress by setting values in the frontmatter. Frontmatter is the part at the top of your file between ---.
---
title: Article Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---
The page content is after the second `---`.What is frontmatter?
Frontmatter is a YAML formatted configuration content, placed at the top of the markdown file, separated by ---.
You can read this article to learn how to write frontmatter correctly.
Auto-Generated Frontmatter
By default, the theme will help generate some frontmatter configurations for markdown files in the source directory after starting the development service. These configurations include: title, creation time, and permalink.
On one hand, this can reduce the repetitive work of content creators; on the other hand, these configurations also provide prerequisite support for other features of the theme.
---
title: Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---Title
The theme defaults to using the file name as the article title. When parsing the file name, the file name named according to the file naming convention such as 1.My Article.md, the parts 1. and .md will be trimmed, and the final article title will be My Article.
Creation Time
The theme defaults to using the file creation time as the article creation time, and formats it as yyyy/MM/dd HH:mm:ss.
Permalink
Permalink refers to the access address after the article is published. Once this address is generated, it will not change unless you manually modify it, even if the file path or file name changes.
Preparing permalink in advance is quite valuable. On one hand, it can help improve the SEO of the site and avoid frequent changes to the included addresses; on the other hand, the theme uses a set of specifications to generate permalink, which makes the link style of the entire site consistent.
Blog Articles
For blog articles, the default prefix for permalink is
/article/, and then a random string of length8is generated usingnanoidfor concatenation as the article's permalink, such as/article/9eh4d6ao/.The link prefix can also be replaced by modifying Theme Configuration > article.
Notes
For notes, the theme uses a more flexible custom solution. You can declare different link prefixes for notes in notes > note.link, and then use
nanoidto generate a random string of length8for 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.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Completely disable all auto-generation
// autoFrontmatter: false,
// Control partial auto-generation
autoFrontmatter: {
permalink: true, // Whether to generate permalink
createTime: true, // Whether to generate creation time
title: true, // Whether to generate title
}
})
})Conventions
Note
The following content is based on the file structure in Project Structure.
Writing articles with this theme is very easy. You can create Markdown files with any name you like in the docs directory according to your personal naming preferences.
Folder Naming Convention
For folder naming in docs, the theme has a simple set of conventions.
- The folder name will serve as the
category, i.e., category. - Multi-level directories are allowed, and subdirectories will be sub-items of the parent directory's category.
- If the directory name is declared in Theme Configuration notes 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:
const dir = /\d+\.[\s\S]+/
// That is, number + . + category name
// For example: 1.FrontendThe number will serve as the basis for sorting. If there is no number, the default sorting rule will be applied.
Example:
The theme will generate a category page based on the directory structure.
File Naming Convention
Blog Articles
For the names of blog articles, the theme has no specific conventions, and you can name them arbitrarily. The default sorting rule for blog articles is based solely on file creation time. You can also use frontmatter > sticky to configure whether the article is stickied.
Notes
For the names of markdown files in notes, the same rules as Folder Naming Convention still apply. This can provide a basis for sorting the 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.
Since the theme defaults to auto-generating a title for the article's frontmatter, the main part of the article content should start with h2, i.e., ## Secondary Heading. If you have disabled autoFrontmatter.title, you should start with h1, i.e., # Primary Heading.
Tags
You can add tags to an article through frontmatter.tags.
---
title: My Article
tags:
- Tag 1
- Tag 2
---
