Writing Articles
VuePress fully supports Standard Markdown Syntax, while also allowing page metadata (such as title, creation time, etc.) to be defined via Frontmatter in YAML format.
Additionally, the theme provides extensive Markdown Extended Syntax. You can not only write HTML directly in Markdown but also use Vue components to enhance content expressiveness.
Frontmatter Page Configuration
Frontmatter allows you to customize the properties and behavior of each page. Frontmatter is located at the top of the file, enclosed by --- delimiters.
---
title: Article Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---
Page content starts after the second `---`.What is Frontmatter?
Frontmatter is a configuration block using YAML format, located at the top of a Markdown file and delimited by ---.
It is recommended to read the Frontmatter Detailed Guide for the complete syntax specification.
Automatic Frontmatter Generation
After the development server starts, the theme automatically generates necessary Frontmatter fields for Markdown files in the documentation source directory, including: title, creation time, and permalink.
This feature reduces the repetitive workload for content creators and provides essential data support for the theme's subsequent functionalities.
---
title: Title
createTime: 2024/09/08 22:53:34
permalink: /article/9eh4d6ao/
---Title Generation Rules
The theme uses the filename as the article title by default. During parsing, the sequence number and extension from the File Naming Convention are automatically removed. For example, 1.my-article.md will generate the title my-article.
Creation Time
The theme uses the file's creation time as the baseline, formatted as yyyy/MM/dd HH:mm:ss, to serve as the article creation time.
Permalink
The permalink is the fixed access URL for the article after publication. Once generated, this link remains constant even if the file path or name changes.
Setting the permalink in advance helps:
- Improve SEO effectiveness by avoiding frequent changes to indexed URLs
- Maintain consistency in the site's overall link style
Disabling Automatic Generation
If full manual control over Frontmatter is required, automatic generation can be disabled via Theme Configuration > autoFrontmatter.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Completely disable all automatic generation
// autoFrontmatter: false,
// Enable specific features as needed
autoFrontmatter: {
permalink: true, // Generate permalink
createTime: true, // Generate creation time
title: true, // Generate title
},
collections: [{
type: 'post',
dir: 'blog',
title: 'Blog',
// Configure for specific collection
autoFrontmatter: {
permalink: true,
createTime: true,
title: true
}
}]
})
})File Organization Conventions
Note
The following examples are based on the baseline file structure from the Project Structure.
The theme provides a flexible file organization approach. You can create Markdown files with any preferred names within the docs directory.
Directory Naming Convention
The theme applies the following rules to directory names within the docs directory:
For post type collections:
- Directory names serve as article categories
- Multi-level directories are supported, with subdirectories acting as children of parent categories
When sorting is required, use the following naming pattern (applicable to all collection types):
const dir = /\d+\.[\s\S]+/
// Format: Number + . + Category Name
// Example: 1.FrontendThe numeric part serves as the sorting basis. Directories without numbers are sorted according to default rules.
Example Structure:
1.html
2.css
3.javascript
2.Backend
DevOps
1.Variables.md
2.Types.md
2.Advanced.md
The theme automatically generates category pages or sidebars based on the directory structure.
File Naming Convention
File naming follows the same rules as the Directory Naming Convention, providing the sorting basis for the auto sidebar generation in collections.
Start Writing
You can now create Markdown files under the docs directory to start writing. For a complete description of Markdown extension features, please refer to the Extended Syntax Documentation.
Since the theme automatically generates article titles by default, the main content should start with level 2 headings ## Level 2 Heading. If autoFrontmatter.title is disabled, start with level 1 headings # Level 1 Heading.
Article Tags
Add tags to articles via frontmatter.tags:
---
title: My Article
tags:
- Tag1
- Tag2
---
