diff --git a/rfcs/001.blog-plugin.md b/rfcs/001.blog-plugin.md new file mode 100644 index 0000000000..0c8bbc78d4 --- /dev/null +++ b/rfcs/001.blog-plugin.md @@ -0,0 +1,286 @@ +- Start Date: 2019-03-06 +- RFC PR: (leave this empty) +- VuePress Issue: (leave this empty) + +# Summary + +- `@vuepress/plugin-blog`, featured with tags, categories, drafting, timeline, pagination and multi-authors +- `@vuepress/theme-blog`, featured with + +# Basic example + +See [detailed design](#detailed-design) section. + +# Motivation + +With popular demand, VuePress will provide some official blog supports, including a blog plugin and an atomic blog theme. + +See: [#36](https://github.com/vuejs/vuepress/issues/36) + +# Blog Plugin + +## Pagination + +We can specify a pagination through following interface: + +```js +module.exports = { + themeConfig: { + pagination: { + postsFilter (postA, index) { + // default: Array.prototype.filter + }, + postsSorter (postA, postB) { + // default: Array.prototype.sort + }, + pageUrl: 'page/:index/', + postsPerPage: 10, + layout: 'Pagination', + }, + } +} +``` + +- `/page/1/` (same with `/`) +- `/page/2/` +- ...... + +## Tags + +```md +--- +tags: + - foo + - bar +--- +``` + +```js +module.exports = { + themeConfig: { + tagUrl: 'tags', + } +} +``` + +- `/tags/` +- `/tags/foo/` +- `/tags/bar/` +- `/tags/bar/page/2/` +- ...... + +## Categories + +```md +--- +category: cat +--- +``` + +```js +module.exports = { + themeConfig: { + categoryUrl: 'categories', + } +} +``` + +- `/categories/` +- `/categories/cat/` +- `/categories/dog/` +- `/categories/dog/page/2/` +- ...... + +## Authoring + +### With Only One Author + +```js +module.exports = { + themeConfig: { + authors: { + nickname: 'Shigma', + description: 'Hello VuePress', + email: '', + location: '', + organization: '', + avatar: '', + sns: { + github: 'https://github.com/Shigma', + // and more + }, + }, + } +} +``` + +### With Mulitple Authors + +```md +--- +author: shigma +contributors: + - ulivz +--- +``` + +```js +module.exports = { + themeConfig: { + authors: [ + { /* one author */ }, + { /* another author */ }, + ], + authorsUrl: 'authors' // default + } +} +``` + +If there are more than one authors: + +- `/authors/` +- `/authors/shigma/` +- `/authors/ulivz/` +- `/authors/ulivz/page/2/` +- ...... + +## Drafting + +```md +--- +draft: true +--- +``` + +And this page will only be rendered under dev mode. + +## Timeline + +```md +--- +createTime: 2019-03-06 +--- +``` + +```js +module.exports = { + themeConfig: { + timeline: { + interval: 'month', + formatUrl (month) { + // default: `timeline/${month}/` + }, + } + } +} +``` + +- `/timeline/2019-03/` +- `/timeline/2019-02/` +- `/timeline/2019-02/page/2/` +- ...... + +If a post has its category, its previous/next page will be posts next to it under the same category. + +## Meta Information and Git Workflow + +And meta information can be accessed by computed properties: + +```js +const { + createTime, + updateTime, + author, + contributors, +} = this.$page +``` + +With the aid of `@vuepress/plugin-git-log` (in another RFC), these meta informations can all be automatically generated. + +## Directory-level Configuration + +Tags, categories, drafting and authors can also be specified via `config.js`: + +```js +module.exports = { + themeConfig: { + directories: [ + { + path: 'drafts', + draft: true, + }, + { + path: 'frontend', + tags: ['CS'], + category: 'frontend', + }, + { + path: 'authors', + layout: 'About', + permalink: '/authors/:slug/', + }, + ] + } +} +``` + +And the configuration above follows several rules: + +- Tags will be automatically merged into an array, while other properties will override each other. +- Configurations below override configurations above. + +# Blog Theme + +## Thumbnails + +```md +--- +thumbnail: /image.png +--- +``` + +This will show as background image of title, and will be displayed together with excerpt in the pagination view. + +## Markdown Syntax + +- custom containers designed for blog + +## Sidebar on the Right + +There will be a sidebar on the right, which contains: + +- table of contents +- author information +- back-to-top button + +All of them are optional, but provided by default. + +# Drawbacks + +N/A + +# Alternatives + +N/A + +# Adoption strategy + + + +# How we teach this + + + +# Unresolved questions + +## Page redirection fails due to SSR mismatch + +When using pagination, VuePress will automatically generate pages with urls like this: + +- `/foo/` +- `/foo/page/1/` +- `/foo/page/2/` + +The problem is, if we want both `/foo/` and `/foo/page/1/` at the same time, redirection may fails due to SSR mismatch. How should we solve this problem? + +See [#1382](https://github.com/vuejs/vuepress/issues/1382).