From 6704ede9114f8c2d87b350b4252bc04dcaef8a70 Mon Sep 17 00:00:00 2001 From: ULIVZ <472590061@qq.com> Date: Wed, 5 Jun 2019 14:41:08 +0800 Subject: [PATCH] chore: update example --- .../2018-11-7-frontmatter-in-vuepress-2.md | 127 ++++++++++++ .../2018-11-7-frontmatter-in-vuepress-3.md | 127 ++++++++++++ .../2018-11-7-frontmatter-in-vuepress.md | 4 +- example/_posts/2018-4-4-intro-to-vuepress.md | 11 - example/_posts/2019-2-26-markdown-slot-2.md | 114 +++++++++++ example/_posts/2019-2-26-markdown-slot-3.md | 114 +++++++++++ example/_posts/2019-2-26-markdown-slot-4.md | 114 +++++++++++ example/_posts/2019-2-26-markdown-slot.md | 114 +++++++++++ .../2019-5-6-writing-a-vuepress-theme-2.md | 189 ++++++++++++++++++ .../2019-5-6-writing-a-vuepress-theme-3.md | 189 ++++++++++++++++++ .../2019-5-6-writing-a-vuepress-theme-4.md | 189 ++++++++++++++++++ .../2019-5-6-writing-a-vuepress-theme.md | 189 ++++++++++++++++++ .../_posts/2019-6-8-intro-to-vuepress-next.md | 11 - example/_posts/2019-6-8-shanghai.md | 11 - example/_posts/2019-6-8-summary.md | 12 -- example/_posts/2019-6-8-vueconf.md | 11 - 16 files changed, 1469 insertions(+), 57 deletions(-) create mode 100644 example/_posts/2018-11-7-frontmatter-in-vuepress-2.md create mode 100644 example/_posts/2018-11-7-frontmatter-in-vuepress-3.md delete mode 100644 example/_posts/2018-4-4-intro-to-vuepress.md create mode 100644 example/_posts/2019-2-26-markdown-slot-2.md create mode 100644 example/_posts/2019-2-26-markdown-slot-3.md create mode 100644 example/_posts/2019-2-26-markdown-slot-4.md create mode 100644 example/_posts/2019-2-26-markdown-slot.md create mode 100644 example/_posts/2019-5-6-writing-a-vuepress-theme-2.md create mode 100644 example/_posts/2019-5-6-writing-a-vuepress-theme-3.md create mode 100644 example/_posts/2019-5-6-writing-a-vuepress-theme-4.md create mode 100644 example/_posts/2019-5-6-writing-a-vuepress-theme.md delete mode 100644 example/_posts/2019-6-8-intro-to-vuepress-next.md delete mode 100644 example/_posts/2019-6-8-shanghai.md delete mode 100644 example/_posts/2019-6-8-summary.md delete mode 100644 example/_posts/2019-6-8-vueconf.md diff --git a/example/_posts/2018-11-7-frontmatter-in-vuepress-2.md b/example/_posts/2018-11-7-frontmatter-in-vuepress-2.md new file mode 100644 index 0000000..79f73be --- /dev/null +++ b/example/_posts/2018-11-7-frontmatter-in-vuepress-2.md @@ -0,0 +1,127 @@ +--- +date: 2018-11-7 +tag: + - frontmatter + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Front Matter in VuePress + +Any markdown file that contains a YAML front matter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The front matter must be the first thing in the markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example: + +```markdown +--- +title: Blogging Like a Hacker +lang: en-US +--- +``` + +Between these triple-dashed lines, you can set predefined variables (see [below](#predefined-variables) for a reference), or even create custom ones of your own. These variables will then be available to you to access using [$frontmatter](./global-computed.md#frontmatter) at the rest of the page, plus all custom and theming components. + +::: tip +Front matter variables are **optional** in VuePress. +::: + +## Alternative Front Matter Formats + +In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter. + +JSON front matter needs to start and end in curly braces: + +``` +--- +{ + "title": "Blogging Like a Hacker", + "lang": "en-US" +} +--- +``` + +TOML front matter needs to be explicitly marked as TOML: + +``` +---toml +title = "Blogging Like a Hacker" +lang = "en-US" +--- +``` + + +## Predefined Variables + +### title + +- Type: `string` +- Default: `h1_title || siteConfig.title` + +Title of current page. + +### lang + +- Type: `string` +- Default: `en-US` + +Language of current page. + +### description + +- Type: `string` +- Default: `siteConfig.description` + +Description of current page. + +### layout + +- Type: `string` +- Default: `Layout` + +Set the layout component of the current page. + +### permalink + +- Type: `string` +- Default: `siteConfig.permalink` + +Refer to: [Permalinks](./permalinks.md). + +### metaTitle + +- Type: `string` +- Default: \`${page.title} | ${siteConfig.title}\` + +Override the default meta title. + +### meta + +- Type: `array` +- Default: `undefined` + +Specify extra meta tags to be injected: + +``` yaml +--- +meta: + - name: description + content: hello + - name: keywords + content: super duper SEO +--- +``` + +## Predefined Variables Powered By Default Theme + +### navbar + +- Type: `boolean` +- Default: `undefined` + +See: [Default Theme Config > Disable the Navbar](../theme/default-theme-config.md#disable-the-navbar). + +### sidebar + +- Type: `boolean|'auto'` +- Default: `undefined` + +See: [Default Theme Config > Sidebar](../theme/default-theme-config.md#sidebar). diff --git a/example/_posts/2018-11-7-frontmatter-in-vuepress-3.md b/example/_posts/2018-11-7-frontmatter-in-vuepress-3.md new file mode 100644 index 0000000..79f73be --- /dev/null +++ b/example/_posts/2018-11-7-frontmatter-in-vuepress-3.md @@ -0,0 +1,127 @@ +--- +date: 2018-11-7 +tag: + - frontmatter + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Front Matter in VuePress + +Any markdown file that contains a YAML front matter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The front matter must be the first thing in the markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example: + +```markdown +--- +title: Blogging Like a Hacker +lang: en-US +--- +``` + +Between these triple-dashed lines, you can set predefined variables (see [below](#predefined-variables) for a reference), or even create custom ones of your own. These variables will then be available to you to access using [$frontmatter](./global-computed.md#frontmatter) at the rest of the page, plus all custom and theming components. + +::: tip +Front matter variables are **optional** in VuePress. +::: + +## Alternative Front Matter Formats + +In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter. + +JSON front matter needs to start and end in curly braces: + +``` +--- +{ + "title": "Blogging Like a Hacker", + "lang": "en-US" +} +--- +``` + +TOML front matter needs to be explicitly marked as TOML: + +``` +---toml +title = "Blogging Like a Hacker" +lang = "en-US" +--- +``` + + +## Predefined Variables + +### title + +- Type: `string` +- Default: `h1_title || siteConfig.title` + +Title of current page. + +### lang + +- Type: `string` +- Default: `en-US` + +Language of current page. + +### description + +- Type: `string` +- Default: `siteConfig.description` + +Description of current page. + +### layout + +- Type: `string` +- Default: `Layout` + +Set the layout component of the current page. + +### permalink + +- Type: `string` +- Default: `siteConfig.permalink` + +Refer to: [Permalinks](./permalinks.md). + +### metaTitle + +- Type: `string` +- Default: \`${page.title} | ${siteConfig.title}\` + +Override the default meta title. + +### meta + +- Type: `array` +- Default: `undefined` + +Specify extra meta tags to be injected: + +``` yaml +--- +meta: + - name: description + content: hello + - name: keywords + content: super duper SEO +--- +``` + +## Predefined Variables Powered By Default Theme + +### navbar + +- Type: `boolean` +- Default: `undefined` + +See: [Default Theme Config > Disable the Navbar](../theme/default-theme-config.md#disable-the-navbar). + +### sidebar + +- Type: `boolean|'auto'` +- Default: `undefined` + +See: [Default Theme Config > Sidebar](../theme/default-theme-config.md#sidebar). diff --git a/example/_posts/2018-11-7-frontmatter-in-vuepress.md b/example/_posts/2018-11-7-frontmatter-in-vuepress.md index e4ace21..79f73be 100644 --- a/example/_posts/2018-11-7-frontmatter-in-vuepress.md +++ b/example/_posts/2018-11-7-frontmatter-in-vuepress.md @@ -2,7 +2,9 @@ date: 2018-11-7 tag: - frontmatter - - vuepress + - vuepress +author: ULIVZ +location: Hangzhou --- # Front Matter in VuePress diff --git a/example/_posts/2018-4-4-intro-to-vuepress.md b/example/_posts/2018-4-4-intro-to-vuepress.md deleted file mode 100644 index 840d9a6..0000000 --- a/example/_posts/2018-4-4-intro-to-vuepress.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -tag: - - vue - - vuepress ---- - -# Intro to VuePress - -- Intro to VuePress -- Intro to VuePress -- Intro to VuePress diff --git a/example/_posts/2019-2-26-markdown-slot-2.md b/example/_posts/2019-2-26-markdown-slot-2.md new file mode 100644 index 0000000..9175b7c --- /dev/null +++ b/example/_posts/2019-2-26-markdown-slot-2.md @@ -0,0 +1,114 @@ +--- +date: 2019-2-26 +tag: + - markdown + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Markdown Slot + +VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component. + +## Why do I need Markdown Slot? + +First, let's review the relationship between layout components and markdown files: + + + +Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves differences before and after compilation. + +Markdown Slot is to solve this kind of problem. + +## Named Slots + +You can define a named markdown slot through the following markdown syntax: + +``` md +::: slot name + +::: +``` + +Use the `Content` component to use the slot in the layout component: + +``` vue + +``` + +::: tip +Here we are using `slot-key` instead of `slot`, because in Vue, `slot` is a reserved prop name. +::: + +## Default Slot Content + +By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component: + +``` vue + +``` + +## Example + +Suppose your layout component is as follows: + +``` vue + +``` + +If the markdown content of a page is like this: + +```md +::: slot header +# Here might be a page title +::: + +- A Paragraph +- Another Paragraph + +::: slot footer +Here's some contact info +::: +``` + +Then the rendered HTML of this page will be: + +```html +
+
+
+

Here might be a page title

+
+
+
+
+
    +
  • A Paragraph
  • +
  • Another Paragraph
  • +
+
+
+
+ +
+
+``` + +Note that: +1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot. +2. Please ensure the uniqueness of the slot defined. diff --git a/example/_posts/2019-2-26-markdown-slot-3.md b/example/_posts/2019-2-26-markdown-slot-3.md new file mode 100644 index 0000000..9175b7c --- /dev/null +++ b/example/_posts/2019-2-26-markdown-slot-3.md @@ -0,0 +1,114 @@ +--- +date: 2019-2-26 +tag: + - markdown + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Markdown Slot + +VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component. + +## Why do I need Markdown Slot? + +First, let's review the relationship between layout components and markdown files: + + + +Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves differences before and after compilation. + +Markdown Slot is to solve this kind of problem. + +## Named Slots + +You can define a named markdown slot through the following markdown syntax: + +``` md +::: slot name + +::: +``` + +Use the `Content` component to use the slot in the layout component: + +``` vue + +``` + +::: tip +Here we are using `slot-key` instead of `slot`, because in Vue, `slot` is a reserved prop name. +::: + +## Default Slot Content + +By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component: + +``` vue + +``` + +## Example + +Suppose your layout component is as follows: + +``` vue + +``` + +If the markdown content of a page is like this: + +```md +::: slot header +# Here might be a page title +::: + +- A Paragraph +- Another Paragraph + +::: slot footer +Here's some contact info +::: +``` + +Then the rendered HTML of this page will be: + +```html +
+
+
+

Here might be a page title

+
+
+
+
+
    +
  • A Paragraph
  • +
  • Another Paragraph
  • +
+
+
+
+ +
+
+``` + +Note that: +1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot. +2. Please ensure the uniqueness of the slot defined. diff --git a/example/_posts/2019-2-26-markdown-slot-4.md b/example/_posts/2019-2-26-markdown-slot-4.md new file mode 100644 index 0000000..9175b7c --- /dev/null +++ b/example/_posts/2019-2-26-markdown-slot-4.md @@ -0,0 +1,114 @@ +--- +date: 2019-2-26 +tag: + - markdown + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Markdown Slot + +VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component. + +## Why do I need Markdown Slot? + +First, let's review the relationship between layout components and markdown files: + + + +Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves differences before and after compilation. + +Markdown Slot is to solve this kind of problem. + +## Named Slots + +You can define a named markdown slot through the following markdown syntax: + +``` md +::: slot name + +::: +``` + +Use the `Content` component to use the slot in the layout component: + +``` vue + +``` + +::: tip +Here we are using `slot-key` instead of `slot`, because in Vue, `slot` is a reserved prop name. +::: + +## Default Slot Content + +By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component: + +``` vue + +``` + +## Example + +Suppose your layout component is as follows: + +``` vue + +``` + +If the markdown content of a page is like this: + +```md +::: slot header +# Here might be a page title +::: + +- A Paragraph +- Another Paragraph + +::: slot footer +Here's some contact info +::: +``` + +Then the rendered HTML of this page will be: + +```html +
+
+
+

Here might be a page title

+
+
+
+
+
    +
  • A Paragraph
  • +
  • Another Paragraph
  • +
+
+
+
+ +
+
+``` + +Note that: +1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot. +2. Please ensure the uniqueness of the slot defined. diff --git a/example/_posts/2019-2-26-markdown-slot.md b/example/_posts/2019-2-26-markdown-slot.md new file mode 100644 index 0000000..9175b7c --- /dev/null +++ b/example/_posts/2019-2-26-markdown-slot.md @@ -0,0 +1,114 @@ +--- +date: 2019-2-26 +tag: + - markdown + - vuepress +author: ULIVZ +location: Hangzhou +--- + +# Markdown Slot + +VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component. + +## Why do I need Markdown Slot? + +First, let's review the relationship between layout components and markdown files: + + + +Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves differences before and after compilation. + +Markdown Slot is to solve this kind of problem. + +## Named Slots + +You can define a named markdown slot through the following markdown syntax: + +``` md +::: slot name + +::: +``` + +Use the `Content` component to use the slot in the layout component: + +``` vue + +``` + +::: tip +Here we are using `slot-key` instead of `slot`, because in Vue, `slot` is a reserved prop name. +::: + +## Default Slot Content + +By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component: + +``` vue + +``` + +## Example + +Suppose your layout component is as follows: + +``` vue + +``` + +If the markdown content of a page is like this: + +```md +::: slot header +# Here might be a page title +::: + +- A Paragraph +- Another Paragraph + +::: slot footer +Here's some contact info +::: +``` + +Then the rendered HTML of this page will be: + +```html +
+
+
+

Here might be a page title

+
+
+
+
+
    +
  • A Paragraph
  • +
  • Another Paragraph
  • +
+
+
+
+ +
+
+``` + +Note that: +1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot. +2. Please ensure the uniqueness of the slot defined. diff --git a/example/_posts/2019-5-6-writing-a-vuepress-theme-2.md b/example/_posts/2019-5-6-writing-a-vuepress-theme-2.md new file mode 100644 index 0000000..594fff2 --- /dev/null +++ b/example/_posts/2019-5-6-writing-a-vuepress-theme-2.md @@ -0,0 +1,189 @@ +--- +date: 2019-5-6 +tag: + - theme + - blog + - vuepress +author: ULIVZ +location: Shanghai +--- + +# Writing a VuePress theme + +To write a theme, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: + +``` +. +└─ .vuepress +  └─ `theme` +    └─ Layout.vue +``` + +From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. + +## 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 + +``` + +**Also see:** + +- [Markdown Slot](../guide/markdown-slot.md) + +## Directory Structure + +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-styl), and even apply some plugins. + +So it's time to reorganize your theme, an agreed theme directory structure is as follows: + +::: vue +theme +├── `global-components` +│ └── xxx.vue +├── `components` +│ └── xxx.vue +├── `layouts` +│   ├── Layout.vue _(**Mandatory**)_ +│   └── 404.vue +├── `styles` +│   ├── index.styl +│   └── palette.styl +├── `templates` +│   ├── dev.html +│   └── ssr.html +├── `index.js` +├── `enhanceApp.js` +└── package.json +::: + +- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please refer to [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components). +- `theme/components`: Your 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 +When you publish your theme as an NPM package, if you don't have any theme configuration, that means you don't have `theme/index.js`, you'll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can correctly resolve the theme. +```json +{ + ... + "main": "layouts/Layout.vue", + ... +} +``` + +::: + +## Layout Component + +Suppose your theme 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 some pages to `AnotherLayout.vue`, you just need to update the frontmatter of this page: + +```markdown +--- +layout: AnotherLayout +--- +```` + +::: tip +Each layout component may render distinct pages. If you want to apply some global UI (e.g. global header), consider using [globalLayout](./option-api.md#globallayout)。 +::: + +## Apply plugins + +You can apply some plugins to the theme via `theme/index.js`. + +```js +module.exports = { + plugins: [ + ['@vuepress/pwa', { + serviceWorker: true, + updatePopup: true + }] + ] +} +``` + +## 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. + +## 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 +} +``` diff --git a/example/_posts/2019-5-6-writing-a-vuepress-theme-3.md b/example/_posts/2019-5-6-writing-a-vuepress-theme-3.md new file mode 100644 index 0000000..594fff2 --- /dev/null +++ b/example/_posts/2019-5-6-writing-a-vuepress-theme-3.md @@ -0,0 +1,189 @@ +--- +date: 2019-5-6 +tag: + - theme + - blog + - vuepress +author: ULIVZ +location: Shanghai +--- + +# Writing a VuePress theme + +To write a theme, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: + +``` +. +└─ .vuepress +  └─ `theme` +    └─ Layout.vue +``` + +From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. + +## 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 + +``` + +**Also see:** + +- [Markdown Slot](../guide/markdown-slot.md) + +## Directory Structure + +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-styl), and even apply some plugins. + +So it's time to reorganize your theme, an agreed theme directory structure is as follows: + +::: vue +theme +├── `global-components` +│ └── xxx.vue +├── `components` +│ └── xxx.vue +├── `layouts` +│   ├── Layout.vue _(**Mandatory**)_ +│   └── 404.vue +├── `styles` +│   ├── index.styl +│   └── palette.styl +├── `templates` +│   ├── dev.html +│   └── ssr.html +├── `index.js` +├── `enhanceApp.js` +└── package.json +::: + +- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please refer to [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components). +- `theme/components`: Your 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 +When you publish your theme as an NPM package, if you don't have any theme configuration, that means you don't have `theme/index.js`, you'll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can correctly resolve the theme. +```json +{ + ... + "main": "layouts/Layout.vue", + ... +} +``` + +::: + +## Layout Component + +Suppose your theme 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 some pages to `AnotherLayout.vue`, you just need to update the frontmatter of this page: + +```markdown +--- +layout: AnotherLayout +--- +```` + +::: tip +Each layout component may render distinct pages. If you want to apply some global UI (e.g. global header), consider using [globalLayout](./option-api.md#globallayout)。 +::: + +## Apply plugins + +You can apply some plugins to the theme via `theme/index.js`. + +```js +module.exports = { + plugins: [ + ['@vuepress/pwa', { + serviceWorker: true, + updatePopup: true + }] + ] +} +``` + +## 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. + +## 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 +} +``` diff --git a/example/_posts/2019-5-6-writing-a-vuepress-theme-4.md b/example/_posts/2019-5-6-writing-a-vuepress-theme-4.md new file mode 100644 index 0000000..594fff2 --- /dev/null +++ b/example/_posts/2019-5-6-writing-a-vuepress-theme-4.md @@ -0,0 +1,189 @@ +--- +date: 2019-5-6 +tag: + - theme + - blog + - vuepress +author: ULIVZ +location: Shanghai +--- + +# Writing a VuePress theme + +To write a theme, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: + +``` +. +└─ .vuepress +  └─ `theme` +    └─ Layout.vue +``` + +From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. + +## 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 + +``` + +**Also see:** + +- [Markdown Slot](../guide/markdown-slot.md) + +## Directory Structure + +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-styl), and even apply some plugins. + +So it's time to reorganize your theme, an agreed theme directory structure is as follows: + +::: vue +theme +├── `global-components` +│ └── xxx.vue +├── `components` +│ └── xxx.vue +├── `layouts` +│   ├── Layout.vue _(**Mandatory**)_ +│   └── 404.vue +├── `styles` +│   ├── index.styl +│   └── palette.styl +├── `templates` +│   ├── dev.html +│   └── ssr.html +├── `index.js` +├── `enhanceApp.js` +└── package.json +::: + +- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please refer to [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components). +- `theme/components`: Your 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 +When you publish your theme as an NPM package, if you don't have any theme configuration, that means you don't have `theme/index.js`, you'll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can correctly resolve the theme. +```json +{ + ... + "main": "layouts/Layout.vue", + ... +} +``` + +::: + +## Layout Component + +Suppose your theme 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 some pages to `AnotherLayout.vue`, you just need to update the frontmatter of this page: + +```markdown +--- +layout: AnotherLayout +--- +```` + +::: tip +Each layout component may render distinct pages. If you want to apply some global UI (e.g. global header), consider using [globalLayout](./option-api.md#globallayout)。 +::: + +## Apply plugins + +You can apply some plugins to the theme via `theme/index.js`. + +```js +module.exports = { + plugins: [ + ['@vuepress/pwa', { + serviceWorker: true, + updatePopup: true + }] + ] +} +``` + +## 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. + +## 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 +} +``` diff --git a/example/_posts/2019-5-6-writing-a-vuepress-theme.md b/example/_posts/2019-5-6-writing-a-vuepress-theme.md new file mode 100644 index 0000000..594fff2 --- /dev/null +++ b/example/_posts/2019-5-6-writing-a-vuepress-theme.md @@ -0,0 +1,189 @@ +--- +date: 2019-5-6 +tag: + - theme + - blog + - vuepress +author: ULIVZ +location: Shanghai +--- + +# Writing a VuePress theme + +To write a theme, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file: + +``` +. +└─ .vuepress +  └─ `theme` +    └─ Layout.vue +``` + +From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme. + +## 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 + +``` + +**Also see:** + +- [Markdown Slot](../guide/markdown-slot.md) + +## Directory Structure + +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-styl), and even apply some plugins. + +So it's time to reorganize your theme, an agreed theme directory structure is as follows: + +::: vue +theme +├── `global-components` +│ └── xxx.vue +├── `components` +│ └── xxx.vue +├── `layouts` +│   ├── Layout.vue _(**Mandatory**)_ +│   └── 404.vue +├── `styles` +│   ├── index.styl +│   └── palette.styl +├── `templates` +│   ├── dev.html +│   └── ssr.html +├── `index.js` +├── `enhanceApp.js` +└── package.json +::: + +- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please refer to [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components). +- `theme/components`: Your 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 +When you publish your theme as an NPM package, if you don't have any theme configuration, that means you don't have `theme/index.js`, you'll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can correctly resolve the theme. +```json +{ + ... + "main": "layouts/Layout.vue", + ... +} +``` + +::: + +## Layout Component + +Suppose your theme 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 some pages to `AnotherLayout.vue`, you just need to update the frontmatter of this page: + +```markdown +--- +layout: AnotherLayout +--- +```` + +::: tip +Each layout component may render distinct pages. If you want to apply some global UI (e.g. global header), consider using [globalLayout](./option-api.md#globallayout)。 +::: + +## Apply plugins + +You can apply some plugins to the theme via `theme/index.js`. + +```js +module.exports = { + plugins: [ + ['@vuepress/pwa', { + serviceWorker: true, + updatePopup: true + }] + ] +} +``` + +## 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. + +## 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 +} +``` diff --git a/example/_posts/2019-6-8-intro-to-vuepress-next.md b/example/_posts/2019-6-8-intro-to-vuepress-next.md deleted file mode 100644 index 9230501..0000000 --- a/example/_posts/2019-6-8-intro-to-vuepress-next.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -tag: - - vue - - vuepress ---- - -# Intro to VuePress Next - -- Intro to VuePress Next -- Intro to VuePress Next -- Intro to VuePress Next diff --git a/example/_posts/2019-6-8-shanghai.md b/example/_posts/2019-6-8-shanghai.md deleted file mode 100644 index 2a91eff..0000000 --- a/example/_posts/2019-6-8-shanghai.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -tag: - - vue - - shanghai ---- - -# Shanghai - -- Shanghai -- Shanghai -- Shanghai diff --git a/example/_posts/2019-6-8-summary.md b/example/_posts/2019-6-8-summary.md deleted file mode 100644 index d0eba1b..0000000 --- a/example/_posts/2019-6-8-summary.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -tag: - - vue - - summary ---- - -# Summary - -- Summary -- Summary -- Summary - diff --git a/example/_posts/2019-6-8-vueconf.md b/example/_posts/2019-6-8-vueconf.md deleted file mode 100644 index 05ff45e..0000000 --- a/example/_posts/2019-6-8-vueconf.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -tag: - - vue - - vueconf ---- - -# VueConf - -- VueConf -- VueConf -- VueConf