# 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!

## Permalinks

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](https://en.wikipedia.org/wiki/Link_rot). VuePress supports a flexible way to build permalinks, allowing you to use template variables.

The default permalink is `/:regular`.

### Configure Permalinks

You can enable permalinks globally for all pages:

```js
// .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**:

```markdown
---
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](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/shared-utils/src/fileToPath.ts) for details |
