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

Commit fc203a3

Browse files
ulivzulivz
committed
docs: enhance docs
1 parent 5622380 commit fc203a3

File tree

11 files changed

+409
-324
lines changed

11 files changed

+409
-324
lines changed

‎docs/.vuepress/config.js‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,25 @@ module.exports = {
44
themeConfig: {
55
repo: 'ulivz/vuepress-plugin-blog',
66
nav: [
7+
{ text: 'Guide', link: '/guide/' },
78
{ text: 'Config', link: '/config/' },
9+
{ text: 'Pagination', link: '/pagination/' },
810
{ text: 'Components', link: '/components/' },
911
],
1012
sidebarDepth: 3,
11-
sidebar: [
12-
'/config/',
13-
'/pagination/'
14-
],
13+
sidebar: {
14+
'/guide/': [
15+
{
16+
title: 'Guide',
17+
collapsable: false,
18+
19+
children: [
20+
'',
21+
'getting-started',
22+
],
23+
},
24+
],
25+
},
1526
},
1627
}
1728

‎docs/.vuepress/public/logo.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/.vuepress/public/pagination.png‎

16 KB
Loading

‎docs/.vuepress/public/simple-pagination.png‎

13.9 KB
Loading

‎docs/.vuepress/styles/index.styl‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#app
2+
.hero img
3+
width 220px
4+
5+
header
6+
#main-title
7+
display none
8+
.description
9+
font-size 1.85rem

‎docs/README.md‎

Lines changed: 15 additions & 319 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
---
2-
sidebar: auto
3-
title: Getting Started
4-
---
5-
6-
# @vuepress/plugin-blog
2+
home: true
3+
heroImage:
4+
actionText: Getting Started →
5+
actionLink: /guide/
6+
features:
7+
- title: Classification
8+
details: Powerful classification system lets you quickly classify your posts.
9+
- title: Pagination
10+
details: Pagination runs through the entire plugin, and it has never been so simple.
11+
- title: Client APIs
12+
details: Simple client APIs make it easier for you to write a blog theme.
713

8-
> Official blog plugin for VuePress.
9-
10-
Note that this plugin has been deeply integrated into [@vuepress/theme-blog](https://github.com/ulivz/vuepress-theme-blog).
14+
footer: MIT Licensed | Copyright © 2018-present Evan You
15+
---
1116

1217
## Install
1318

@@ -19,324 +24,15 @@ yarn add -D @vuepress/plugin-blog
1924
## Usage
2025

2126
```javascript
27+
// .vuepress/config.js
2228
module.exports = {
2329
plugins: [
2430
'@vuepress/blog',
2531
{
2632
/* options */
2733
},
2834
],
29-
// Please keep looking down to see the available options.
30-
}
31-
```
32-
33-
## Tutorials
34-
35-
### Document Classifier
36-
37-
`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:
38-
39-
- Pages put in a directory (e.g. `_post`)
40-
- Pages containing the same specific frontmatter key value (e.g. `tag: js`).
41-
42-
Of course, both of them may be related to another common
43-
requirement, `pagination`.
44-
45-
So, how to combine them skillfully? Next, let's take a look at how this plugin solve these problems.
46-
47-
### Directory Classifier
48-
49-
Directory Classifier, that classifies the source pages placed in a same directory.
50-
51-
Suppose you have the following files structure:
52-
53-
```vue
54-
.
55-
└── _posts   
56-
├── 2018-4-4-intro-to-vuepress.md   
57-
└── 2019-6-8-intro-to-vuepress-next.md
58-
```
59-
60-
In the traditional VuePress site, the converted page URLs will be:
61-
62-
- `_posts/2018-4-4-intro-to-vuepress.html`
63-
- `_posts/2019-6-8-intro-to-vuepress-next.html`
64-
65-
It doesn't seem blogging, so it's time to use this plugin:
66-
67-
```js
68-
// .vuepress/config.js
69-
module.exports = {
70-
plugins: [
71-
[
72-
'@vuepress/blog',
73-
{
74-
directories: [
75-
{
76-
// Unique ID of current classification
77-
id: 'post',
78-
// Target directory
79-
dirname: '_posts',
80-
// Path of the `entry page` (or `list page`)
81-
path: '/',
82-
},
83-
],
84-
},
85-
],
86-
],
87-
}
88-
```
89-
90-
Then the plugin will help you to generate following pages, and automatically leverage corresponding
91-
layout:
92-
93-
| url | layout |
94-
| ------------------------------------- | ---------------------- |
95-
| `/` | `IndexPost` / `Layout` |
96-
| `/2018/04/04/intro-to-vuepress/` | `Post` |
97-
| `/2019/06/08/intro-to-vuepress-next/` | `Post` |
98-
99-
This means that you need to create two layout components(`IndexPost` and `Post`) to handle the layout of index and post
100-
pages.
101-
102-
You can also custom the layout component name:
103-
104-
```diff
105-
// .vuepress/config.js
106-
module.exports = {
107-
plugins: [
108-
['@vuepress/blog', {
109-
directories: [
110-
{
111-
id: 'post',
112-
dirname: '_posts',
113-
path: '/',
114-
+ layout: 'MyIndexPost',
115-
+ itemLayout: 'MyPost',
116-
},
117-
],
118-
}]
119-
]
120-
}
121-
```
122-
123-
And custom the root path and the permalink:
124-
125-
```diff
126-
// .vuepress/config.js
127-
module.exports = {
128-
plugins: [
129-
['@vuepress/blog', {
130-
directories: [
131-
{
132-
id: 'post',
133-
dirname: '_posts',
134-
- path: '/',
135-
+ path: '/post/',
136-
+ itemPermalink: '/post/:year/:month/:day/:slug',
137-
},
138-
],
139-
}]
140-
]
141-
}
142-
```
143-
144-
::: warning
145-
It is noteworthy that the `path` and `itemPermalink` must be uniformly modified, and `itemPermalink` must be prefixed with
146-
`path`.
147-
148-
The default value of `itemPermalink` is `'/:year/:month/:day/:slug'`.
149-
:::
150-
151-
### Pagination
152-
153-
As your blog articles grew more and more, you began to have the need for paging. By default, this plugin integrates a
154-
very powerful pagination system that allows you to access paging functions with simple configuration.
155-
156-
By default, the plugin assumes that the max number of pages per page is `10`. you can also modify it like this:
157-
158-
```diff
159-
// .vuepress/config.js
160-
module.exports = {
161-
plugins: [
162-
['@vuepress/blog', {
163-
directories: [
164-
{
165-
id: 'post',
166-
dirname: '_posts',
167-
path: '/',
168-
+ pagination: {
169-
+ perPagePosts: 2,
170-
+ },
171-
},
172-
],
173-
}]
174-
]
175-
}
176-
```
177-
178-
Suppose you have 3 pages at `_posts` direcotry:
179-
180-
- `_posts/2018-6-8-a.md`
181-
- `_posts/2019-6-8-b.md`
182-
- `_posts/2019-6-8-c.md`
183-
184-
When the `perPagePosts` is set to `2`, this plugin will help you generate the following pages:
185-
186-
| url | layout |
187-
| ---------------- | -------------------------------- |
188-
| `/` | `IndexPost` / `Layout` |
189-
| `/page/2/` (New) | `DirectoryPagination` / `Layout` |
190-
| `/2019/06/08/a/` | `Post` |
191-
| `/2019/06/08/b/` | `Post` |
192-
| `/2018/06/08/c/` | `Post` |
193-
194-
::: tip
195-
`DirectoryPagination / Layout` means that the layout component will be downgraded to `Layout` when `DirectoryPagination` layout doesn't exist.
196-
:::
197-
198-
So how to get the matched pages in the layout component? In fact, it will be much simpler than you think.
199-
200-
If you visit `/`, current page leverages layout `IndexPost`. In this layout component, you just need to use
201-
`this.$pagination.pages` to get the matched pages. In the above example, the actual value of `this.$pagination.pages` will
202-
be:
203-
204-
```json
205-
[
206-
{ "relativePath": "_posts/2019-6-8-a.md", "path": "/2019/06/08/a/" ... },
207-
{ "relativePath": "_posts/2019-6-8-b.md", "path": "/2019/06/08/b/" ... },
208-
]
209-
```
210-
211-
If you visit `/`, current page leverages layout `DirectoryPagination`, you can also use
212-
`this.$pagination.pages` to access it:
213-
214-
```json
215-
[
216-
{ "relativePath": "_posts/2019-6-8-c.md", "path": "/2019/06/08/c/" ... },
217-
]
218-
```
219-
220-
Isn't this very natural experience? You just need to care about the style of your layout component, not the complicated and boring logic behind it.
221-
222-
::: tip
223-
To save the length of docs, we omitted the data structure of the `$page` object. You can get more information about
224-
the data structure of `$page` at the [official documentation](https://v1.vuepress.vuejs.org/guide/global-computed.html#page).
225-
:::
226-
227-
### Frontmatter Classifier
228-
229-
Frontmatter Classifier, which classifies pages that have the same frontmatter key values.
230-
231-
Suppose you have three pages:
232-
233-
- `a.md`:
234-
235-
```mardkown
236-
---
237-
tag: vue
238-
---
239-
```
240-
241-
- `b.md`:
242-
243-
```mardkown
244-
---
245-
tag: vue
246-
---
247-
```
248-
249-
- `c.md`:
250-
251-
```mardkown
252-
---
253-
tag: js
254-
---
255-
```
256-
257-
If you want to easily classify them, you can config like this:
258-
259-
```js
260-
module.exports = {
261-
plugins: [
262-
[
263-
'@vuepress/blog',
264-
{
265-
frontmatters: [
266-
{
267-
// Unique ID of current classification
268-
id: 'tag',
269-
// Decide that the frontmatter keys will be grouped under this classification
270-
keys: ['tag'],
271-
// Path of the `entry page` (or `list page`)
272-
path: '/tag/',
273-
// Layout of the `entry page`
274-
layout: 'Tag',
275-
},
276-
],
277-
},
278-
],
279-
],
28035
}
28136
```
28237

283-
Then the plugin will help you to generate the following extra pages, and automatically leverage
284-
the corresponding layout:
285-
286-
| url | layout |
287-
| ----------- | ---------------------------------- |
288-
| `/tag/` | `Tag` |
289-
| `/tag/vue/` | `FrontmatterPagination` / `Layout` |
290-
| `/tag/js/` | `FrontmatterPagination` / `Layout` |
291-
292-
In the `Tags` component, you can use `this.$tag.list` to get the tag list. The value would be like:
293-
294-
```json
295-
[
296-
{
297-
"name": "vue",
298-
"path": "/tag/vue/",
299-
"pages": [
300-
{ "relativePath": "b.md", "path": "/b.html" ... },
301-
{ "relativePath": "a.md", "path": "/a.html" ... },
302-
]
303-
},
304-
{
305-
"name": "js",
306-
"path": "/tag/js/",
307-
"pages": [
308-
{ "relativePath": "c.md", "path": "/c.html" ... },
309-
]
310-
}
311-
]
312-
```
313-
314-
In the `FrontmatterPagination` component, you can use `this.$pagination.pages` to get the matched pages in current tag
315-
classification:
316-
317-
- If you visit `/tag/vue/`, the `this.$pagination.pages` will be:
318-
319-
```json
320-
[
321-
{ "relativePath": "b.md", "path": "/b.html" ... },
322-
{ "relativePath": "a.md", "path": "/a.html" ... },
323-
]
324-
```
325-
326-
- If you visit `/tag/js/`, the `this.$pagination.pages` will be:
327-
328-
```json
329-
[
330-
{ "relativePath": "c.md", "path": "/c.html" ... },
331-
]
332-
```
333-
334-
## Examples
335-
336-
Actually, there are only 2 necessary layout components to create a blog theme:
337-
338-
- Layout
339-
- Post
340-
- Tag (Only required when you set up a `tag` frontmatter classification.)
341-
342-
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.
38+
All available options are [here](./config/README.md).

0 commit comments

Comments
 (0)