more docs

docs/markdown.md

@@ -1,17 +1,100 @@
 # Markdown Extensions
 
-[[toc]]
-
 ## Links
 
+- Inbound links ending in `.md` or `.html` are converted to `<router-link>` for SPA navigation.
+
+  - [Home](/)
+  - [Setup](./setup.md#quickstart)
+
+- Outbound links automatically gets `target="_blank"`: [vuejs.org](https://vuejs.org)
+
 ## Header Anchors
 
+Headers automatically get anchor links applied.
+
 ## Table of Contents
 
+**Input**
+
+``` markdown
+[[toc]]
+```
+
+**Output**
+
+[[toc]]
+
 ## Custom Containers
 
-## Configuration
+**Input**
+
+``` markdown
+::: tip
+This is a tip
+:::
+
+::: warning
+This is a warning
+:::
+
+::: danger
+This is a dangerous thing
+:::
+```
+
+**Output**
+
+::: tip
+This is a tip
+:::
+
+::: warning
+This is a warning
+:::
+
+::: danger
+This is a dangerous thing
+:::
+
+## Line Highlighting in Code Blocks
+
+**Input**
+
+```` markdown
+``` js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+``` js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Emoji
+
+**Input**
+
+``` markdown
+:tada: :100:
+```
+
+**Output**
 
-## Syntax Highlighting
+:tada: :100:
 
-Highlight lines
+## Custom Configuration

docs/using-vue.md

@@ -2,11 +2,57 @@
 
 ## Templating
 
+Each markdown file is first compiled into HTML and then passed on as a Vue component to `vue-loader`. This means you can use Vue-style interpolation in text:
+
+**Input**
+
+``` markdown
+{{ 1 + 1 }}
+```
+
+**Output**
+
+<pre><code>{{ 1 + 1 }}</code></pre>
+
+Directives also work:
+
+**Input**
+
+``` markdown
+<span v-for="i in 3">{{ i }} </span>
+```
+
+**Output**
+
+<pre><code><span v-for="i in 3">{{ i }} </span></code></pre>
+
+The compiled component does not have any private data but do have access to the [site metadata](./theming.md#site-and-page-metadata). For example:
+
+**Input**
+
+``` markdown
+{{ $page }}
+```
+
+**Output**
+
+<pre><code>{{ $page }}</code></pre>
+
+## Escaping
+
+By default, fenced code blocks are automatically wrapped with `v-pre`. If you want to display raw mustaches or Vue-specific syntax inside inline code snippets or plain text, you need to wrap a paragraph with the `v-pre` custom container:
+
+``` markdown
+::: v-pre
+`{{ This will be displayed as-is }}`
+:::
+```
+
 ## Using Components
 
 Any `*.vue` file found in `.vuepress/components` are automatically registered as global async components. For example:
 
-``` bash
+```
 .
 └── .vuepress
     └── components
@@ -22,9 +68,11 @@ Inside any markdown file you can then use the component like so:
 ```
 
 ::: warning
-Note **components must be nested inside a `<div>`**, because otherwise they'd be automatically wrapped inside a `<p>`, which can only contain inline elements.
+Note **components must be nested inside a `<div>`**, because otherwise they'd be automatically wrapped inside a `<p>`, which can only contain inline elements. If your component contains block level elements (it mostly likely does), it will cause hydration mismatch in static builds.
 :::
 
-## Style & Script
+## Script & Style Hoisting
 
 (TODO)
+
+Sometimes you may need to apply some JavaScript or CSS only to the current page. In those case 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.

lib/default-theme/styles.css

@@ -7,7 +7,7 @@ pre, pre[class*="language-"] {
   color: white;
   line-height: 1.4;
   border-radius: 5px;
-  padding: 1.25rem 1.575rem;
+  padding: 1.3rem 1.575rem;
   white-space: pre-wrap;
   word-break: break-word;
   overflow: auto;
@@ -23,13 +23,23 @@ pre code, pre[class*="language-"] code {
   background-color: #14161a;
   display: block;
   margin: 0 -1.575rem;
-  padding: 0 1.575rem;
+  padding: 0.2rem 1.575rem 0;
+}
+
+div.tip {
+  color: white;
+  background-color: green;
 }
 
 div.warning {
   background-color: yellow;
 }
 
+div.danger {
+  color: white;
+  background-color: red;
+}
+
 /*
   Copied from nprogress since it doens't
   allow programmatic configuration of color

lib/dev.js

@@ -23,8 +23,11 @@ module.exports = async function dev (sourceDir, cliOptions = {}) {
     ignored: '.vuepress/**/*.md',
     ignoreInitial: true
   })
-  pagesWatcher.on('add', () => prepare(sourceDir))
-  pagesWatcher.on('unlink', () => prepare(sourceDir))
+  const update = () => prepare(sourceDir)
+  pagesWatcher.on('add', update)
+  pagesWatcher.on('unlink', update)
+  pagesWatcher.on('addDir', update)
+  pagesWatcher.on('unlinkDir', update)
 
   // resolve webpack config
   const _config = createClientConfig(options)

lib/markdown/highlight.js

@@ -1,23 +1,31 @@
+const chalk = require('chalk')
 const prism = require('prismjs')
 const loadLanguages = require('prismjs/components/index')
 
 // required to make embedded highlighting work...
 loadLanguages(['markup', 'css', 'javascript'])
 
+function wrap (code, lang) {
+  return `<pre v-pre class="language-${lang}"><code>${code}</code></pre>`
+}
+
 module.exports = (str, lang) => {
+  if (!lang) {
+    return wrap(str, 'text')
+  }
   if (lang === 'vue' || lang === 'html') {
     lang = 'markup'
   }
   if (!prism.languages[lang]) {
     try {
       loadLanguages([lang])
     } catch (e) {
-      throw new Error(`[vuepress] Syntax highlight for language "${lang}" is not supported.`)
+      console.log(chalk.yellow(`[vuepress] Syntax highlight for language "${lang}" is not supported.`))
     }
   }
   if (prism.languages[lang]) {
-    const res = prism.highlight(str, prism.languages[lang], lang)
-    return `<pre v-pre class="language-${lang}"><code>${res}</code></pre>`
+    const code = prism.highlight(str, prism.languages[lang], lang)
+    return wrap(code, lang)
   }
-  return ''
+  return wrap(str, 'text')
 }

lib/markdown/index.js

@@ -1,6 +1,7 @@
 const highlight = require('./highlight')
 const highlightLines = require('./highlightLines')
 const convertRouterLink = require('./link')
+const emoji = require('markdown-it-emoji')
 const anchor = require('markdown-it-anchor')
 const container = require('markdown-it-container')
 const toc = require('markdown-it-table-of-contents')
@@ -10,16 +11,28 @@ const toc = require('markdown-it-table-of-contents')
 // TODO support inline demo
 
 module.exports = ({ markdown = {}}) => {
-  return require('markdown-it')({
+  const md = require('markdown-it')({
     html: true,
     typographer: true,
     highlight
   })
     .use(convertRouterLink)
     .use(highlightLines)
+    .use(emoji)
     .use(anchor, Object.assign({ permalink: true, permalinkBefore: true }, markdown.anchor))
     .use(toc, Object.assign({ includeLevel: [2, 3] }, markdown.toc))
     .use(container, 'tip')
     .use(container, 'warning')
     .use(container, 'danger')
+    .use(container, 'v-pre', {
+      render: (tokens, idx) => tokens[idx].nesting === 1
+        ? `<div v-pre>\n`
+        : `</div>\n`
+    })
+
+  if (markdown.config) {
+    markdown.config(md)
+  }
+
+  return md
 }

lib/markdown/link.js

@@ -12,7 +12,7 @@ module.exports = md => {
       const link = token.attrs[hrefIndex]
       const href = link[1]
       const isExternal = /^https?:/.test(href)
-      const isSourceLink = /\.(md|html)$/.test(href)
+      const isSourceLink = /\.(md|html)(#[\w-]*)?$/.test(href)
       if (isExternal) {
         const targetIndex = token.attrIndex('target')
         if (targetIndex < 0) {
@@ -30,7 +30,9 @@ module.exports = md => {
 
   function toRouterLink (token, link) {
     link[0] = 'to'
-    let to = link[1].replace(/\.md$/, '.html')
+    let to = link[1]
+      .replace(/\.md$/, '.html')
+      .replace(/\.md(#[\w-]*)/, '.html$1')
     // normalize links to README/index
     if (/^index|readme\.html/i.test(to)) {
       to = '/'

package.json

@@ -59,6 +59,7 @@
     "markdown-it": "^8.4.1",
     "markdown-it-anchor": "^4.0.0",
     "markdown-it-container": "^2.0.0",
+    "markdown-it-emoji": "^1.4.0",
     "markdown-it-table-of-contents": "^0.3.3",
     "mini-css-extract-plugin": "^0.4.0",
     "mkdirp": "^0.5.1",

yarn.lock

@@ -3417,6 +3417,10 @@ markdown-it-container@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/markdown-it-container/-/markdown-it-container-2.0.0.tgz#0019b43fd02eefece2f1960a2895fba81a404695"
 
+markdown-it-emoji@^1.4.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/markdown-it-emoji/-/markdown-it-emoji-1.4.0.tgz#9bee0e9a990a963ba96df6980c4fddb05dfb4dcc"
+
 markdown-it-table-of-contents@^0.3.3:
   version "0.3.3"
   resolved "https://registry.yarnpkg.com/markdown-it-table-of-contents/-/markdown-it-table-of-contents-0.3.3.tgz#b62e943c32de2c4a27d3e7c83cd63acbc2a9c4a2"