Permalinks

Background

Prior to VuePress version 1.0.0, VuePress retrieved all Markdown files in the documents source directory and defined the page links based on the file hierarchy. For example, if you had the following file and directory structure:

├── package.json
└── source
    ├── _post
    │   └── intro-vuepress.md
    ├── index.md
    └── tags.md

You would then get the following pages:

/source/
/source/tags.html
/source/_post/intro-vuepress.html

But for blogs, a customized link of a post would be highly preferrable. VuePress version 1.0.0 introduced support for this feature, known as a permalink. With version 1.0.0 or newer, you instead get the following pages:

/source/
/source/tags/
/source/2018/4/1/intro-vuepress.html

This describes the beginning of how VuePress can be used for a blog!

A permalink is a URL that is intended to remain unchanged for a long time, yielding a hyperlink that is less susceptible to what is known as link rot. VuePress supports a flexible way to build permalinks, allowing you to use template variables.

The default permalink is /:regular.

You can enable permalinks globally for all pages:

// .vuepress/config.js
module.exports = {
  permalink: '/:year/:month/:day/:slug'
}

You can also set set a permalink for a single page only. This overrides the aforementioned global setting:

📝 hello.md:

---
title: Hello World
permalink: /hello-world
---

Hello!

Template Variables

Variable Description
:year Published year of post (4-digit)
:month Published month of post (2-digit)
:i_month Published month of post (without leading zeros)
:day Published day of post (2-digit)
:i_day Published day of post (without leading zeros)
:slug Slugified file path (without extension)
:regular Permalink generated by VuePress by default. See fileToPath.ts for details