Merge branch 'master' into add-plugin-config

Author: dacsang97

CHANGELOG.md

@@ -1,3 +1,69 @@
+<a name="0.8.3"></a>
+## [0.8.3](https://github.com/vuejs/vuepress/compare/v0.8.2...v0.8.3) (2018-04-23)
+
+
+### Bug Fixes
+
+* always write override.style ([9861deb](https://github.com/vuejs/vuepress/commit/9861deb))
+
+
+
+<a name="0.8.2"></a>
+## [0.8.2](https://github.com/vuejs/vuepress/compare/v0.8.1...v0.8.2) (2018-04-23)
+
+
+### Bug Fixes
+
+* nav-item underline use $accentColor ([#230](https://github.com/vuejs/vuepress/issues/230)) ([ddb590d](https://github.com/vuejs/vuepress/commit/ddb590d))
+
+
+### Features
+
+* expose layout slots for injecting custom content ([3814e88](https://github.com/vuejs/vuepress/commit/3814e88))
+
+
+
+<a name="0.8.1"></a>
+## [0.8.1](https://github.com/vuejs/vuepress/compare/v0.8.0...v0.8.1) (2018-04-23)
+
+
+### Bug Fixes
+
+* algolia regression (close [#228](https://github.com/vuejs/vuepress/issues/228)) ([44b1201](https://github.com/vuejs/vuepress/commit/44b1201))
+
+
+
+<a name="0.8.0"></a>
+# [0.8.0](https://github.com/vuejs/vuepress/compare/v0.7.1...v0.8.0) (2018-04-23)
+
+
+### Bug Fixes
+
+* algolia check should be checking themeConfig.algolia ([504c21d](https://github.com/vuejs/vuepress/commit/504c21d))
+* default to localhost on windows (close [#221](https://github.com/vuejs/vuepress/issues/221)) ([4d5c50e](https://github.com/vuejs/vuepress/commit/4d5c50e))
+* fix emoji not showing on sidebars ([#206](https://github.com/vuejs/vuepress/issues/206)) ([bc2c83a](https://github.com/vuejs/vuepress/commit/bc2c83a))
+* fix Sidebar link active logic ([#215](https://github.com/vuejs/vuepress/issues/215)) ([9c93d8f](https://github.com/vuejs/vuepress/commit/9c93d8f))
+* Fix the style of repo link. ([f55fa00](https://github.com/vuejs/vuepress/commit/f55fa00))
+* fix title inferrence regression (close [#208](https://github.com/vuejs/vuepress/issues/208)) ([52c20cf](https://github.com/vuejs/vuepress/commit/52c20cf))
+* renames index.js to enhanceApp.js ([#226](https://github.com/vuejs/vuepress/issues/226)) ([0170449](https://github.com/vuejs/vuepress/commit/0170449))
+* siteTitle vs pageTitle ([cd9b788](https://github.com/vuejs/vuepress/commit/cd9b788))
+
+
+### Features
+
+* Add docsRepo ([#155](https://github.com/vuejs/vuepress/issues/155)) ([716aefe](https://github.com/vuejs/vuepress/commit/716aefe))
+* add max search suggestions config ([#163](https://github.com/vuejs/vuepress/issues/163)) ([a16a5b4](https://github.com/vuejs/vuepress/commit/a16a5b4))
+* Algolia DocSearch Integration  ([#201](https://github.com/vuejs/vuepress/issues/201)) ([2f0da01](https://github.com/vuejs/vuepress/commit/2f0da01))
+* also expose siteData in enhanceApp.js ([5157c6f](https://github.com/vuejs/vuepress/commit/5157c6f))
+* expose all css pre-processor's options. (close [#169](https://github.com/vuejs/vuepress/issues/169)) ([#178](https://github.com/vuejs/vuepress/issues/178)) ([8f0755a](https://github.com/vuejs/vuepress/commit/8f0755a))
+* support built-in pug config and document using pro-processors at component ([#151](https://github.com/vuejs/vuepress/issues/151)) ([f322105](https://github.com/vuejs/vuepress/commit/f322105))
+* support excerpt extraction with `<!-- more -->` (close [#174](https://github.com/vuejs/vuepress/issues/174)) ([fa404dc](https://github.com/vuejs/vuepress/commit/fa404dc))
+* support for TOML front matter ([#141](https://github.com/vuejs/vuepress/issues/141)) ([#164](https://github.com/vuejs/vuepress/issues/164)) ([70620ba](https://github.com/vuejs/vuepress/commit/70620ba))
+* support toml config ([#138](https://github.com/vuejs/vuepress/issues/138)) ([d136e22](https://github.com/vuejs/vuepress/commit/d136e22))
+* theme index enhancment support ([#154](https://github.com/vuejs/vuepress/issues/154)) ([d026801](https://github.com/vuejs/vuepress/commit/d026801))
+
+
+
 <a name="0.7.1"></a>
 ## [0.7.1](https://github.com/vuejs/vuepress/compare/v0.7.0...v0.7.1) (2018-04-20)
 

README.md

@@ -29,7 +29,6 @@ https://vuepress.vuejs.org/
 
 VuePress is still a work in progress. There are a few things that it currently does not support but are planned:
 
-- Algolia DocSearch Integration
 - Blogging support
 
 Contributions are welcome!

docs/.vuepress/config.js

@@ -24,6 +24,7 @@ module.exports = {
     ['meta', { name: 'msapplication-TileColor', content: '#000000' }]
   ],
   serviceWorker: true,
+  theme: 'vue',
   themeConfig: {
     repo: 'vuejs/vuepress',
     editLinks: true,

docs/default-theme-config/README.md

@@ -33,7 +33,11 @@ Any additional content after the `YAML front matter` will be parsed as normal ma
 
 If you want to use a completely custom homepage layout, you can also use a [Custom Layout](#custom-layout-for-specific-pages).
 
-## Navbar Links
+## Navbar
+
+The Navbar may contain yourg  page title, [Search Box](#search-box), [Navbar Links](#navbar-links), [Languages](../guide/i18n.md) and [Repository Link](#git-repo-and-edit-links), all of them depends on your configuration.
+
+### Navbar Links
 
 You can add links to the navbar via `themeConfig.nav`:
 
@@ -86,6 +90,16 @@ module.exports = {
 }
 ```
 
+### Disable the Navbar
+
+You can disable the navbar for a specific page via `YAML front matter`:
+
+``` yaml
+---
+navbar: false
+---
+```
+
 ## Sidebar
 
 To enable the sidebar, use `themeConfig.sidebar`. The basic configuration expects an Array of links:
@@ -199,8 +213,6 @@ Make sure to define the fallback configuration last.
 VuePress checks each sidebar config from top to bottom. If the fallback configuration was first, VuePress would incorrectly match `/foo/` or `/bar/four.html` because they both start with `/`.
 :::
 
-
-
 ### Auto Sidebar for Single Pages
 
 If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use `YAML front matter` on that page:
@@ -221,6 +233,38 @@ sidebar: false
 ---
 ```
 
+## Search Box
+
+### Built-in Search
+
+You can disable the built-in search box with `themeConfig.search: false`, and customize how many suggestions to be shown with `themeConfig.searchMaxSuggestions`:
+
+``` js
+module.exports = {
+  themeConfig: {
+    search: false,
+    searchMaxSuggestions: 10
+  }
+}
+```
+
+### Algolia Search
+
+The `themeConfig.algolia` option allows you to use [Algolia DocSearch](https://community.algolia.com/docsearch/) to replace the simple built-in search. To enable it, you need to provide at least `apiKey` and `indexName`:
+
+```js
+module.exports = {
+  themeConfig: {
+    algolia: {
+      apiKey: '<API_KEY>',
+      indexName: '<INDEX_NAME>'
+    }
+  }
+}
+```
+
+For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options).
+
 ## Prev / Next Links
 
 Prev and next links are automatically inferred based on the sidebar order of the active page. You can also explicitly overwrite or disable them using `YAML front matter`:
@@ -245,9 +289,9 @@ module.exports = {
     // Customising the header label
     // Defaults to "GitHub"/"GitLab"/"Bitbucket" depending on `themeConfig.repo`
     repoLabel: 'Contribute!',
-    
+
     // Optional options for generating "Edit this page" link
- 
+
     // if your docs are in a different repo from your main project:
     docsRepo: 'vuejs/vuepress',
     // if your docs are not at the root of the repo:
@@ -289,6 +333,8 @@ pageClass: custom-page-class
 Then you can write CSS targeting that page only:
 
 ``` css
+/* .vuepress/override.styl */
+
 .theme-container.custom-page-class {
   /* page-specific rules */
 }

docs/guide/README.md

@@ -31,7 +31,6 @@ Each markdown file is compiled into HTML with [markdown-it](https://github.com/m
 
 VuePress is still a work in progress. There are a few things that it currently does not support but are planned:
 
-- Algolia DocSearch Integration
 - Blogging support
 
 Contributions are welcome!

docs/guide/basic-config.md

@@ -17,6 +17,10 @@ If you've got the dev server running, you should see the page now has a header w
 
 Consult the [Config Reference](../config/) for a full list of options.
 
+::: tip Alternative Config Formats
+You can also use YAML (`.vuepress/config.yml`) or TOML (`.vuepress/config.toml`) formats for the configuration file.
+:::
+
 ## Theme Configuration
 
 A VuePress theme is responsible for all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now) which is designed for technical documentation. It exposes a number of options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the [Default Theme Config](../default-theme-config/) page.
@@ -31,7 +35,8 @@ Since the VuePress app is a standard Vue app, you can apply app-level enhancemen
 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
+  router, // the router instance for the app
+  siteData // site metadata
 }) => {
   // ...apply enhancements to the app
 }

docs/guide/custom-themes.md

@@ -70,15 +70,16 @@ The compiled content of the current `.md` file being rendered will be available
 </template>
 ```
 
-## Theme Level Enhancements
+## App Level Enhancements
 
-Themes can extend the Vue app that VuePress uses by exposing an `index.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:
+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
+  router, // the router instance for the app
+  siteData // site metadata
 }) => {
   // ...apply enhancements to the app
 }

docs/guide/deploy.md

@@ -24,10 +24,6 @@ The following guides are based on a few shared assumptions:
 
 2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy:
 
-::: tip
-You can also run this script in your CI setup to enable automatic deployment on each push.
-:::
-
 ``` bash{13,20,23}
 #!/usr/bin/env sh
 
@@ -56,17 +52,21 @@ git commit -m 'deploy'
 cd -
 ```
 
+::: tip
+You can also run the above script in your CI setup to enable automatic deployment on each push.
+:::
+
 ## GitLab Pages and GitLab CI
 
-1. Set correct `base` in `docs/.vuepress/config.js`. 
+1. Set correct `base` in `docs/.vuepress/config.js`.
 
    If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `"/"`.
 
    If your are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, (i.e. your repository is at `https://gitlab.com/<USERNAME>/REPO>`), set `base` to `"/<REPO>/"`.
- 
+
 2. Set `dest` in `.vuepress/config.js` to `public`.
 
-3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content. 
+3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content.
 
 ```
 image: node:9.11.1
@@ -85,7 +85,7 @@ pages:
   only:
   - master
 ```
-   
+
 
 ## Netlify
 

docs/guide/i18n.md

@@ -56,6 +56,8 @@ module.exports = {
         label: 'English',
         // text for the edit-on-github link
         editLinkText: 'Edit this page on GitHub',
+        // algolia docsearch options for current locale
+        algolia: {},
         nav: [
           { text: 'Nested', link: '/nested/' }
         ],
@@ -71,6 +73,7 @@ module.exports = {
         nav: [
           { text: '嵌套', link: '/zh/nested/' }
         ],
+        algolia: {},
         sidebar: {
           '/zh/': [/* ... */],
           '/zh/nested/': [/* ... */]

docs/guide/markdown.md

@@ -1,9 +1,3 @@
----
-meta:
-- name: keywords
-  content: static docs generator vue
----
-
 # Markdown Extensions
 
 ## Header Anchors
@@ -19,15 +13,7 @@ Inbound links ending in `.md` or `.html` are converted to `<router-link>` for SP
 Each sub-directory in your static site should contain a `README.md`. It will automatically be converted to `index.html`.
 
 ::: tip
-When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404.
-
-```md
-<!-- You'll get a 404 -->
-[About Page](/about)
-
-<!-- This is correct -->
-[About Page](/about/)
-```
+When writing the relative path to a directory's `index.html`, don't forget to close it off with a `/`, otherwise you will get a 404. For example, use `/config/` instead of `/config`.
 :::
 
 If you want to link to another markdown file within a directory, remember to:
@@ -62,12 +48,12 @@ Given the following directory structure:
 
 ### External Links
 
-- Outbound links automatically gets `target="_blank"`:
+Outbound links automatically gets `target="_blank"`:
 
-  - [vuejs.org](https://vuejs.org)
-  - [VuePress on GitHub](https://github.com/vuejs/vuepress)
+- [vuejs.org](https://vuejs.org)
+- [VuePress on GitHub](https://github.com/vuejs/vuepress)
 
-## YAML Front Matter
+## Front Matter
 
 [YAML front matter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box:
 
@@ -92,6 +78,30 @@ meta:
 ---
 ```
 
+### 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"
+---
+```
+
 ## GitHub-Style Tables
 
 **Input**