From 1cc6c19fcf347947e504ffe297f74fae0574241d Mon Sep 17 00:00:00 2001 From: ULIVZ <472590061@qq.com> Date: Sat, 6 Oct 2018 02:46:41 +0800 Subject: [PATCH] docs: some enhancements --- packages/docs/docs/config/README.md | 9 +- packages/docs/docs/plugin/official.md | 20 +- packages/docs/docs/theme/README.md | 7 - packages/docs/docs/zh/config/README.md | 23 ++ packages/docs/docs/zh/plugin/official.md | 18 +- packages/docs/docs/zh/theme/README.md | 306 +++++++++++++++++------ 6 files changed, 269 insertions(+), 114 deletions(-) diff --git a/packages/docs/docs/config/README.md b/packages/docs/docs/config/README.md index 3fa4d9e6..fff7381b 100644 --- a/packages/docs/docs/config/README.md +++ b/packages/docs/docs/config/README.md @@ -130,8 +130,7 @@ Create a `.vuepress/style/index.styl` file and it will be applied as global styl **Also see:** -- [Why can't `palette.styl` and `index.styl` merge into one API?](faq/#why-can-t-palette-styl-and-index-styl-merge-into-one-api) -- [Why can't `palette.styl` and `index.styl` merge into one API?](faq/#why-can-t-palette-styl-and-index-styl-merge-into-one-api) +- [Why can't `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api) ## Theming @@ -160,11 +159,7 @@ Provide config options to the used theme. The options will vary depending on the - Type: `Object|Array` - Default: `undefined` -For default usage, please refer to [plugin API](../plugin/README.md). - -::: tip -There is a hidden feature. `.vuepress/config.js` also supports all [options](../plugin/README.md#options) of Plugin API. -::: +Please refer to [plugin API > Using a plugin](../plugin/README.md#using-a-plugin) to leran how to use a plugin. ## Markdown diff --git a/packages/docs/docs/plugin/official.md b/packages/docs/docs/plugin/official.md index 0bf7b6a1..446190ed 100644 --- a/packages/docs/docs/plugin/official.md +++ b/packages/docs/docs/plugin/official.md @@ -2,43 +2,41 @@ sidebar: auto --- -- TODO - # Official Plugins ## @vuepress/search -### Options +- TODO ## @vuepress/pwa -### Options +- TODO ## @vuepress/blog -### Options +- TODO ## @vuepress/pagination -### Options +- TODO ## @vuepress/google-analytics -### Options +- TODO ## @vuepress/i18n-ui -### Options +- TODO ## @vuepress/last-updated -### Options +- TODO ## @vuepress/medium-zoom -### Options +- TODO ## @vuepress/back-to-top -### Options +- TODO diff --git a/packages/docs/docs/theme/README.md b/packages/docs/docs/theme/README.md index 6b4fb859..3746c3e9 100644 --- a/packages/docs/docs/theme/README.md +++ b/packages/docs/docs/theme/README.md @@ -240,10 +240,3 @@ The plugin whose name starts with `@vuepress/theme-` is an officially maintained - Default: undefined See: [Config > plugins](../config/README.md#plugins). - -### palette - -- Type: `String|Object` -- Default: undefined - -See: [Config > palette](../config/README.md#palette). diff --git a/packages/docs/docs/zh/config/README.md b/packages/docs/docs/zh/config/README.md index 4810b9fb..46d00ab7 100644 --- a/packages/docs/docs/zh/config/README.md +++ b/packages/docs/docs/zh/config/README.md @@ -115,6 +115,20 @@ module.exports = { 一个函数，用来控制对于哪些文件，是需要生成 `` 资源提示的。请参考 [shouldPrefetch](https://ssr.vuejs.org/zh/api/#shouldpreload)。 +## 样式 + +### palette.styl + +创建一个 `.vuepress/style/palette.styl` 文件，其会被自动注册为全局调色板。 + +### index.styl + +创建一个 `.vuepress/style/index.styl` 文件， 其会被自动应用为全局样式 + +**Also see:** + +- [Why can't `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api) + ## 主题 ### theme @@ -135,6 +149,15 @@ module.exports = { - [默认主题](../theme/default-theme-config.md)。 +## Pluggable + +### plugins + +- Type: `Object|Array` +- Default: `undefined` + +请参考 [plugin API > Using a plugin](../plugin/README.md#using-a-plugin) 来使用一个插件。 + ## Markdown ### markdown.lineNumbers diff --git a/packages/docs/docs/zh/plugin/official.md b/packages/docs/docs/zh/plugin/official.md index 714bba90..446190ed 100644 --- a/packages/docs/docs/zh/plugin/official.md +++ b/packages/docs/docs/zh/plugin/official.md @@ -6,37 +6,37 @@ sidebar: auto ## @vuepress/search -### Options +- TODO ## @vuepress/pwa -### Options +- TODO ## @vuepress/blog -### Options +- TODO ## @vuepress/pagination -### Options +- TODO ## @vuepress/google-analytics -### Options +- TODO ## @vuepress/i18n-ui -### Options +- TODO ## @vuepress/last-updated -### Options +- TODO ## @vuepress/medium-zoom -### Options +- TODO ## @vuepress/back-to-top -### Options +- TODO diff --git a/packages/docs/docs/zh/theme/README.md b/packages/docs/docs/zh/theme/README.md index 5dec1560..3746c3e9 100644 --- a/packages/docs/docs/zh/theme/README.md +++ b/packages/docs/docs/zh/theme/README.md @@ -2,95 +2,241 @@ sidebar: auto --- -# 主题 +# Theme -## Background - -Before 1.x.x, vuepress retrieves all markdown files in the documents source directory and defines the page links based on the file hierarchy. e.g. if you have the following file structure: - -``` -├── package.json -└── source - ├── _post - │   └── intro-vuepress.md - ├── index.md - └── tags.md -``` - -Then you will get following available pages: - -``` -/source/ -/source/tags.html -/source/_post/intro-vuepress.html -``` - -However, for a blog system, we hope that the link of a post can be customized. VuePress started supporting this feature from `1.0.0`. which is known as `permalink`. Then, the actual pages would be: - -``` -/source/ -/source/tags/ -/source/2018/4/1/intro-vuepress.html -``` - -It seems that we have seen the shadow of the blog. Let's continue to look down. - -## Permalinks - -A permalink is a URL that is intended to remain unchanged for many years into the future, yielding a hyperlink that is less susceptible to link rot[1]. VuePress supports a flexible way to build permalinks, allowing you to leverage various template variables. - -The default permalink is `/:regular`. - -### Configure Permalinks - -You can configure globally to apply it for all pages: - -```js -// .vuepress/config.js -module.exports = { - permalink: '/:year/:month/:day/:slug' -} -``` - -Alternatively, you can also set permalink on a page only, and it will have a higher priority than the global settings. - -📝 __hello.md__: - -```markdown ---- -title: Hello World -permalink: /hello-world ---- - -Hello! -``` - -### Template Variables - -| Variable | Description | -|---|---| -|:year|Published year of posts (4-digit)| -|:month|Published month of posts (2-digit)| -|:i_month|Published month of posts (Without leading zeros)| -|:day|Published day of posts (2-digit)| -|:i_day|Published day of posts (Without leading zeros)| -|:slug|Slugified file path (Without extension)| -|:regular| Permalink generated by VuePress by default, for implementation see [here](https://github.com/vuejs/vuepress/blob/next/packages/%40vuepress/shared-utils/lib/fileToPath.js) | +::: tip +Theme components are subject to the same [browser API access restrictions](../guide/using-vue.md#browser-api-access-restrictions). +::: ## Writing a theme -TODO. integrate with the old docs. +To write a theme, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: -## Theme API +::: vue +. +└─ .vuepress +  └─ `theme` +    └─ Layout.vue +::: -### layout +From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. -TODO +### Directory Structure -### notFound +Just one `Layout.vue` might not be enough, and you might also want to define more layout components in the theme for using on different pages. You may also want to customize the [palette](../config/README.md#palette), and even apply some plugins. -TODO +So it's time to reorganize your theme, an agreed theme directory structure is as follows: + +::: vue +theme +├── `components` _(**Optional**)_ +│ └── xxx.vue +├── `layouts` +│   ├── Layout.vue _(**Required**)_ +│   └── 404.vue _(**Optional**)_ +├── `styles` _(**Optional**)_ +│   ├── index.styl +│   └── palette.styl +├── `templates` _(**Optional**)_ +│   ├── dev.html +│   └── ssr.html +├── `index.js` _(**Optional**)_ +├── `enhanceApp.js` _(**Optional**)_ +└── package.json +::: + +- `theme/components`: Theme components are not automatically registered as global components. You can use [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components) register them as global components. +- `theme/layouts`: Layout components of the theme, where `Layout.vue` is required. +- `theme/styles`: Global style and palette. +- `theme/templates`: Modify default template. +- `theme/index.js`: Entry file of theme configuration. +- `theme/enhanceApp.js`: Theme level enhancements. + +::: warning Note +Considering backward compatibility, Vue components located at theme root directory will also be automatically registered as layout components. But the recommended is placing them under `layouts` directory, which looks more clearer. +::: + +### Layout Component + +Suppose your topic Layouts folder is as follows: + +::: vue +theme +└── `layouts` +    ├── Layout.vue +    ├── AnotherLayout.vue +    └── 404.vue +::: + +Then, all the pages will use `Layout.vue` as layout component by default, while the routes not matching will use `404.vue`. + +If you want to switch the layout of the some page to `AnotherLayout.vue`, you just need to update the frontmatter of this page: + +```markdown +--- +layout: AnotherLayout +--- +```` + +### Apply plugins + +You can apply some plugins to the theme via `theme/index.js`. + +```js +module.exports = { + plugins: [ + '@vuepress/pwa', + { + serviceWorker: true, + updatePopup: true + } + ] +} +``` + +For themes that need to be released to NPM, please do not forget to add it to `dependencies`: + +```json +{ + "dependencies": { + "@vuepress/plugin-pwa": "^x.x.x", + } +} +``` + +### Site and Page Metadata + +The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively as `this.$site` and `this.$page` properties which are injected into every component in the app. + +This is the value of `$site` of this very website: + +``` json +{ + "title": "VuePress", + "description": "Vue-powered Static Site Generator", + "base": "/", + "pages": [ + { + "lastUpdated": 1524027677000, + "path": "/", + "title": "VuePress", + "frontmatter": {} + }, + ... + ] +} +``` + +`title`, `description` and `base` are copied from respective fields in `.vuepress/config.js`. `pages` contains an array of metadata objects for each page, including its path, page title (explicitly specified in [YAML front matter](../guide/markdown.md#front-matter) or inferred from the first header on the page), and any YAML front matter data in that file. + +This is the `$page` object for this page you are looking at: + +``` json +{ + "lastUpdated": 1524847549000, + "path": "/guide/custom-themes.html", + "title": "Custom Themes", + "headers": [/* ... */], + "frontmatter": {} +} +``` + +If the user provided `themeConfig` in `.vuepress/config.js`, it will also be available as `$site.themeConfig`. You can use this to allow users to customize behavior of your theme - for example, specifying categories and page order. You can then use these data together with `$site.pages` to dynamically construct navigation links. + +Finally, don't forget that `this.$route` and `this.$router` are also available as part of Vue Router's API. + +::: tip + `lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated). +::: + +### Content Excerpt + +If a markdown file contains a `` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts. + +### Content Outlet + +The compiled content of the current `.md` file being rendered will be available as a special `` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content: + +``` html + +``` + +### App Level Enhancements + +Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks: + +``` js +export default ({ + Vue, // the version of Vue being used in the VuePress app + options, // the options for the root Vue instance + router, // the router instance for the app + siteData // site metadata +}) => { + // ...apply enhancements to the app +} +``` + +## Using a theme + +Using a theme is almost same as using a plugin. + +### Use plugins from a dependency + +Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`. + +``` js +module.exports = { + plugins: [ 'vuepress-theme-xx' ] +} +``` + +### Theme Shorthand + +If you prefix the plugin with `vuepress-theme-`, you can use a shorthand to leave out that prefix: + +``` js +module.exports = { + plugins: [ 'xxx' ] +} +``` + +Same with: + +``` js +module.exports = { + plugins: [ 'vuepress-theme-xxx' ] +} +``` + +This also works with [Scoped Packages](https://docs.npmjs.com/misc/scope): + +``` js +module.exports = { + plugins: [ '@org/vuepress-theme-xxx', '@vuepress/theme-xxx' ] +} +``` + +Shorthand: + +``` js +module.exports = { + plugins: [ '@org/xxx', '@vuepress/xxx' ] +} +``` + +::: warning Note +The plugin whose name starts with `@vuepress/theme-` is an officially maintained theme. +::: + +## Options ### plugins -TODO +- Type: `Array|Object` +- Default: undefined + +See: [Config > plugins](../config/README.md#plugins).