Merge branch 'master' into algolia-docsearch

Author: ulivz

README.md

@@ -17,6 +17,7 @@ https://vuepress.vuejs.org/
 - [Vue-powered custom theme system](https://vuepress.vuejs.org/guide/custom-themes.html)
 - Service Worker Integration
 - Google Analytics Integration
+- Multi-Language Support
 - A default theme with:
   - Responsive layout
   - Optional Homepage
@@ -28,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:
 
-- Multi-Language Support
 - Algolia DocSearch Integration
 - Blogging support
 

docs/guide/custom-themes.md

@@ -66,6 +66,20 @@ The compiled content of the current `.md` file being rendered will be available
 </template>
 ```
 
+## Theme 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:
+
+``` 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
+}) => {
+  // ...apply enhancements to the app
+}
+```
+
 ## Using Theme from a Dependency
 
 Themes can be published on npm in raw Vue SFC format as `vuepress-theme-xxx`.

docs/guide/using-vue.md

@@ -121,6 +121,35 @@ Inside any markdown file you can then directly use the components (names are inf
 Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
 :::
 
+### Using Pre-processors
+
+VuePress has built-in webpack config for the following pre-processors: `sass`, `scss`, `less`, `stylus` and `pug`. All you need to do is installing the corresposnding dependencies. For example, to enable `sass`, install the following in your project:
+ 
+``` bash
+yarn add -D sass-loader node-sass
+```
+
+Now you can use the following in markdown and theme components:
+
+``` vue
+<style lang="sass">
+.title
+  font-size: 20px
+</style>
+```
+
+Using `<template lang="pug">` requires installing `pug` and `pug-plain-loader`:
+
+``` bash
+yarn add -D pug pug-plain-loader
+```
+
+::: tip
+If you are a Stylus user, you don't need to install `stylus` and `stylus-loader` in your project because VuePress uses Stylus internally.
+  
+For pre-processors that do not have built-in webpack config support, you will need to [extend the internal webpack config](../config/#configurewebpack) in addition to installing the necessary dependencies.
+:::
+
 ## Script & Style Hoisting
 
 Sometimes you may need to apply some JavaScript or CSS only to the current page. In those cases you can directly write root-level `<script>` or `<style>` blocks in the markdown file, and they will be hoisted out of the compiled HTML and used as the `<script>` and `<style>` blocks for the resulting Vue single-file component.

docs/zh/guide/using-vue.md

@@ -121,6 +121,37 @@ export default {
 请确保一个自定义组件的名字包含连接符或者是 PascalCase，否则，它将会被视为一个内联元素，并被包裹在一个 `<p>` 标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定， `<p>` 标签中不允许放置任何块级元素。
 :::
 
+
+## 使用预处理器
+
+VuePress 对以下预处理器已经内置相关的 webpack 配置：`sass`、`scss`、`less`、`stylus` 和 `pug`。要使用它们你只需要在项目中安装对应的依赖即可。例如，要使用 `sass`，需要安装：
+
+```bash
+yarn add -D sass-loader node-sass
+```
+ 
+然后你就可以在 Markdown 或是组件中使用如下代码：
+
+```vue
+<style lang="sass">
+  .title
+    font-size: 20px
+</style>
+```
+
+要在组件中使用 `<template lang="pug">`，则需要安装 `pug` 和 `pug-plain-loader`:
+
+```bash
+yarn add -D pug pug-plain-loader
+```
+
+::: tip
+需要指出的是，如果你是一个 `stylus` 用户，你并不需要在你的项目中安装 `stylus` 和 `stylus-loader`，因为 VuePress 已经内置了它们。
+  
+对于那些没有内置的预处理器，除了安装对应的依赖，你还需要 [拓展内部的 Webpack 配置](../config/#configurewebpack)。
+:::
+
+
 ## 脚本和样式提升
 
 有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中使用原生的 `<script>` 或者 `<style>` 标签，它们将会从编译后的 HTML 文件中提取出来，并作为生成的 Vue 单文件组件的 `<script>` 和 `<style>` 标签。

lib/app/app.js

@@ -7,6 +7,7 @@ import NotFound from '@notFound'
 import { routes } from '@temp/routes'
 import { siteData } from '@temp/siteData'
 import enhanceApp from '@temp/enhanceApp'
+import themeEnhanceApp from '@temp/themeEnhanceApp'
 
 // suggest dev server restart on base change
 if (module.hot) {
@@ -75,7 +76,8 @@ export function createApp () {
   })
 
   const options = {}
-
+  
+  themeEnhanceApp({ Vue, options, router })
   enhanceApp({ Vue, options, router })
 
   const app = new Vue(

lib/default-theme/styles/code.styl

@@ -23,7 +23,7 @@
     code
       color #fff
       padding 0
-      background-color none
+      background-color transparent
       border-radius 0
     &:before
       position absolute
@@ -34,8 +34,8 @@
   .highlighted-line
     background-color rgba(0, 0, 0, 66%)
     display block
-    margin 0.1rem -1.5rem 0
-    padding 0.1rem 1.5rem
+    margin 0 -1.5rem
+    padding 0 1.5rem
 
 pre[class="language-js"], pre[class="language-javascript"]
   &:before

lib/prepare.js

@@ -2,6 +2,7 @@ const path = require('path')
 const fs = require('fs-extra')
 const globby = require('globby')
 const yamlParser = require('js-yaml')
+const tomlParser = require('toml')
 const yaml = require('yaml-front-matter')
 const createMarkdown = require('./markdown')
 const tempPath = path.resolve(__dirname, 'app/.temp')
@@ -52,15 +53,21 @@ if (!Object.assign) Object.assign = require('object-assign')`
     await writeTemp(`override.styl`, hasUserOverride ? `@import(${JSON.stringify(overridePath)})` : ``)
   }
 
+  async function writeEnhanceTemp (destName, srcPath, isEnhanceExist) {
+    await writeTemp(
+      destName,
+      isEnhanceExist
+        ? `export { default } from ${JSON.stringify(srcPath)}`
+        : `export default function () {}`
+    )
+  }
+
   // 6. handle enhanceApp.js
-  const enhancePath = path.resolve(sourceDir, '.vuepress/enhanceApp.js')
-  const hasEnhancePath = fs.existsSync(enhancePath)
-  await writeTemp(
-    'enhanceApp.js',
-    hasEnhancePath
-      ? `export { default } from ${JSON.stringify(enhancePath)}`
-      : `export default function () {}`
-  )
+  const enhanceAppPath = path.resolve(sourceDir, '.vuepress/enhanceApp.js')
+  writeEnhanceTemp('enhanceApp.js', enhanceAppPath, fs.existsSync(enhanceAppPath))
+
+  // 7. handle the theme index.js
+  writeEnhanceTemp('themeEnhanceApp.js', options.themeApp, fs.existsSync(options.themeApp))
 
   return options
 }
@@ -69,12 +76,14 @@ async function resolveOptions (sourceDir) {
   const vuepressDir = path.resolve(sourceDir, '.vuepress')
   const configPath = path.resolve(vuepressDir, 'config.js')
   const configYmlPath = path.resolve(vuepressDir, 'config.yml')
+  const configTomlPath = path.resolve(vuepressDir, 'config.toml')
 
   delete require.cache[configPath]
   let siteConfig = {}
   if (fs.existsSync(configYmlPath)) {
-    const content = await fs.readFile(configYmlPath, 'utf-8')
-    siteConfig = yamlParser.safeLoad(content)
+    siteConfig = await parseConfig(configYmlPath)
+  } else if (fs.existsSync(configTomlPath)) {
+    siteConfig = await parseConfig(configTomlPath)
   } else if (fs.existsSync(configPath)) {
     siteConfig = require(configPath)
   }
@@ -150,6 +159,11 @@ async function resolveOptions (sourceDir) {
     } else {
       options.notFoundPath = path.resolve(__dirname, 'default-theme/NotFound.vue')
     }
+
+    const themeApp = path.resolve(themeDir, 'index.js')
+    if (fs.existsSync(themeApp)) {
+      options.themeApp = themeApp
+    }
   }
 
   // resolve pages
@@ -283,3 +297,31 @@ function sort (arr) {
     return 0
   })
 }
+
+async function parseConfig (file) {
+  const content = await fs.readFile(file, 'utf-8')
+  const [extension] = /.\w+$/.exec(file)
+  let data
+
+  switch (extension) {
+  case '.yml':
+  case '.yaml':
+    data = yamlParser.safeLoad(content)
+    break
+
+  case '.toml':
+    data = tomlParser.parse(content)
+    // reformat to match config since TOML does not allow different data type
+    // https://github.com/toml-lang/toml#array
+    const format = []
+    Object.keys(data.head).forEach(meta => {
+      data.head[meta].forEach(values => {
+        format.push([meta, values])
+      })
+    })
+    data.head = format
+    break
+  }
+
+  return data || {}
+}

lib/webpack/createBaseConfig.js

@@ -71,6 +71,13 @@ module.exports = function createBaseConfig ({
           }
         })
 
+  config.module
+    .rule('pug')
+    .test(/\.pug$/)
+    .use('pug-plain-loader')
+      .loader('pug-plain-loader')
+      .end()
+
   if (!siteConfig.evergreen) {
     const libDir = path.join(__dirname, '..')
     config.module

package.json

@@ -79,6 +79,7 @@
     "semver": "^5.5.0",
     "stylus": "^0.54.5",
     "stylus-loader": "^3.0.2",
+    "toml": "^2.3.3",
     "url-loader": "^1.0.1",
     "vue": "^2.5.16",
     "vue-loader": "^15.0.0-rc.1",

yarn.lock

@@ -6141,6 +6141,10 @@ to-regex@^3.0.1, to-regex@^3.0.2:
     regex-not "^1.0.2"
     safe-regex "^1.1.0"
 
+toml@^2.3.3:
+  version "2.3.3"
+  resolved "https://registry.yarnpkg.com/toml/-/toml-2.3.3.tgz#8d683d729577cb286231dfc7a8affe58d31728fb"
+
 [email protected]:
   version "2.0.2"
   resolved "https://registry.yarnpkg.com/topo/-/topo-2.0.2.tgz#cd5615752539057c0dc0491a621c3bc6fbe1d182"