Skip to content
This repository was archived by the owner on May 13, 2024. It is now read-only.

Commit becf789

Browse files
committed
docs: enhancement
1 parent 4fc0f73 commit becf789

File tree

1 file changed

+35
-17
lines changed

1 file changed

+35
-17
lines changed

docs/guide/getting-started.md

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
# Getting Started
22

3+
::: tip
4+
This section is a step-by-step tutorial with some concepts, and we recommend that you read it completely before using
5+
this plugin.
6+
:::
7+
38
## Document Classifier
49

510
`Document classifier` is a set of functions that can classify pages with the same characteristics. For a blog developer, the same characteristics may exist between different pages as follows:
611

712
- Pages put in a directory (e.g. `_post`)
813
- Pages containing the same specific frontmatter key value (e.g. `tag: js`).
914

10-
Of course, both of them may be related to another common
11-
requirement, `pagination`.
15+
Of course, both of them may be related to another common requirement, `pagination`.
1216

1317
So, how to combine them skillfully? Next, let's take a look at how this plugin solve these problems.
1418

@@ -60,14 +64,14 @@ layout:
6064

6165
| url | layout |
6266
| ------------------------------------- | ---------------------- |
63-
| `/` | `IndexPost` / `Layout` |
67+
| `/` | `IndexPost` (fallback to `Layout` if not exist) |
6468
| `/2018/04/04/intro-to-vuepress/` | `Post` |
6569
| `/2019/06/08/intro-to-vuepress-next/` | `Post` |
6670

67-
This means that you need to create two layout components(`IndexPost` and `Post`) to handle the layout of index and post
71+
This means that you need to create two layout components(`IndexPost` and `Post`) to handle the layout of `index` and `post`
6872
pages.
6973

70-
You can also custom the layout component name:
74+
You can also custom the layout component:
7175

7276
```diff
7377
// .vuepress/config.js
@@ -88,7 +92,7 @@ module.exports = {
8892
}
8993
```
9094

91-
And custom the root path and the permalink:
95+
And custom the path of entry page and the permalink of posts:
9296

9397
```diff
9498
// .vuepress/config.js
@@ -113,13 +117,17 @@ module.exports = {
113117
It is noteworthy that the `path` and `itemPermalink` must be uniformly modified, and `itemPermalink` must be prefixed with
114118
`path`.
115119

116-
The default value of `itemPermalink` is `'/:year/:month/:day/:slug'`.
120+
The default value of `itemPermalink` is `'/:year/:month/:day/:slug'`,
117121
:::
118122

123+
**See also**:
124+
125+
- [Config > directories](../config/README.md#directories)
126+
119127
## Pagination
120128

121129
As your blog articles grew more and more, you began to have the need for paging. By default, this plugin integrates a
122-
very powerful pagination system that allows you to access paging functions with simple configuration.
130+
very powerful pagination system that allows you to access pagination functions with simple configuration.
123131

124132
By default, the plugin assumes that the max number of pages per page is `10`. you can also modify it like this:
125133

@@ -153,16 +161,12 @@ When the `perPagePosts` is set to `2`, this plugin will help you generate the fo
153161

154162
| url | layout |
155163
| ---------------- | -------------------------------- |
156-
| `/` | `IndexPost` / `Layout` |
157-
| `/page/2/` (New) | `DirectoryPagination` / `Layout` |
164+
| `/` | `IndexPost` (fallback to `Layout` if not exist) |
165+
| `/page/2/` (New) | `DirectoryPagination` (fallback to `Layout` if not exist) |
158166
| `/2019/06/08/a/` | `Post` |
159167
| `/2019/06/08/b/` | `Post` |
160168
| `/2018/06/08/c/` | `Post` |
161169

162-
::: tip
163-
`DirectoryPagination / Layout` means that the layout component will be downgraded to `Layout` when `DirectoryPagination` layout doesn't exist.
164-
:::
165-
166170
So how to get the matched pages in the layout component? In fact, it will be much simpler than you think.
167171

168172
If you visit `/`, current page leverages layout `IndexPost`. In this layout component, you just need to use
@@ -192,6 +196,10 @@ To save the length of docs, we omitted the data structure of the `$page` object.
192196
the data structure of `$page` at the [official documentation](https://v1.vuepress.vuejs.org/guide/global-computed.html#page).
193197
:::
194198

199+
**See also**:
200+
201+
- [Pagination Config](../pagination/README.md)
202+
195203
### Frontmatter Classifier
196204

197205
Frontmatter Classifier, which classifies pages that have the same frontmatter key values.
@@ -299,12 +307,22 @@ classification:
299307
]
300308
```
301309

302-
# Examples
310+
**See also**:
311+
312+
- [Config > frontmatters](../config/README.md#frontmatters)
313+
303314

304-
Actually, there are only 2 necessary layout components to create a blog theme:
315+
## Writing a blog theme
316+
317+
If everything is ok, you can start to write a blog theme. Actually, there are only 2 necessary layout components to
318+
create a blog theme:
305319

306320
- Layout
307321
- Post
308322
- Tag (Only required when you set up a `tag` frontmatter classification.)
309323

310-
Here is [live example](https://github.com/ulivz/70-lines-of-vuepress-blog-theme) that implements a functionally qualified VuePress theme in around 70 lines.
324+
Here are two official examples (A simple & a complex) for you:
325+
326+
- [70-lines-of-vuepress-blog-theme](https://github.com/ulivz/70-lines-of-vuepress-blog-theme): A VuePress Blog Theme implemented in around 70 lines.
327+
- [@vuepress/theme-blog](https://github.com/ulivz/vuepress-theme-blog): Default blog theme for VuePress.
328+

0 commit comments

Comments
 (0)