[RFC] plugin-blog & theme-blog [WIP]

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: '<email>',
+      location: '<location>',
+      organization: '<organization>',
+      avatar: '<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).