-Writing first: minimal setup, all you need is a markdown file.
-**Writing First**: minimal setup, all you need is a markdown file.
-Vue-powered: the layout system is a Vue app. It's also pre-rendered into static HTML. And you can register and use Vue components inside markdown content.
-**Vue-powered**: Use custom Vue components inside markdown, and develop custom themes using Vue single file components.
-Flexible: develop with full power of webpack (hot-reload, pre-processors support), generate SEO-friendly static HTML, and works as an SPA after initial page load.
-**Great Dev Experience**: enjoy the same enjoyable development experience of a Vue app. Leverage the full power of webpack (hot-reload, pre-processors), generate SEO-friendly static HTML, and works as an SPA after initial page load.
-Optimized for docs: many built-in markdown extensions and default theme features for writing great documentation.
-**Optimized for Docs**: many [built-in markdown extensions](./markdown.md) and default theme features for writing great documentation.
-GitHub friendly: pages can link to each other using relative links that ends in `.md`, auto-generates GitHub link and page edit links if a repo is provided.
-**GitHub Friendly**: source markdown files can link to each other using relative links that ends in `.md` so they are also readable on GitHub, auto-generates page edit links if a repo is provided.
VuePress uses Vue single file components for custom themes. To use a custom layout, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file:
VuePress uses Vue single file components for custom themes. To use a custom layout, create a `.vuepress/theme` directory in your docs root, and then create a `Layout.vue` file:
@@ -42,18 +42,32 @@ The compiled component does not have any private data but do have access to the
...
@@ -42,18 +42,32 @@ The compiled component does not have any private data but do have access to the
**Output**
**Output**
<pre><code>{{ $page }}</code></pre>
``` json
{
"path":"/using-vue.html",
"title":"Using Vue in Markdown",
"frontmatter":{}
}
```
## Escaping
## 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:
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:
**Input**
``` markdown
``` markdown
::: v-pre
::: v-pre
`{{ This will be displayed as-is }}`
`{{ This will be displayed as-is }}`
:::
:::
```
```
**Output**
::: v-pre
`{{ This will be displayed as-is }}`
:::
## Using Components
## Using Components
Any `*.vue` file found in `.vuepress/components` are automatically registered as global async components. For example:
Any `*.vue` file found in `.vuepress/components` are automatically registered as global async components. For example:
...
@@ -77,7 +91,7 @@ Inside any markdown file you can then directly use the components (names are inf
...
@@ -77,7 +91,7 @@ Inside any markdown file you can then directly use the components (names are inf
<OtherComponent/>
<OtherComponent/>
::: warning
::: warning IMPORTANT
Make sure a custom component's names 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.
Make sure a custom component's names 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.