From a0d5916923eb05bde4ce92ebe2178f8ad76f74b3 Mon Sep 17 00:00:00 2001 From: "Mr.Hope" Date: Thu, 25 Jul 2024 13:28:18 +0800 Subject: [PATCH] docs: update markdown docs --- docs/README.md | 8 ++++++++ docs/guide/markdown.md | 22 ++++++++++++++++------ docs/zh/README.md | 8 ++++++++ docs/zh/guide/markdown.md | 30 +++++++++++++++++++++--------- 4 files changed, 53 insertions(+), 15 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7b9e9880..4b49d110 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,21 +6,29 @@ actions: - text: Get Started link: /guide/getting-started.html type: primary + - text: Introduction link: /guide/introduction.html type: secondary + features: - title: Simplicity First details: Minimal setup with markdown-centered project structure helps you focus on writing. + - title: Vue-Powered details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue. + - title: Performant details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. + - title: Themes details: Providing a default theme out of the box. You can also choose a community theme or create your own one. + - title: Plugins details: Flexible plugin API, allowing plugins to provide lots of plug-and-play features for your site. + - title: Bundlers details: Recommended bundler is Vite, while Webpack is also supported. Choose the one you like! + footer: MIT Licensed | Copyright © 2018-present VuePress Community --- diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index e1195ba5..d2628b43 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -156,7 +156,7 @@ Config reference: [markdown.toc](../reference/config.md#markdown-toc) Following code blocks extensions are implemented during markdown parsing in Node side. That means, the code blocks won't be processed in client side. -Notice that some of the code blocks features require theme support. The default theme of VuePress supports all of them, but community themes might not. You'd better check the theme documentation before using them. +With [@vuepress/plugin-prismjs][prismjs] and [@vuepress/plugin-shiki][shiki], you can highlight code blocks with [Prism](https://prismjs.com/) or [Shiki](https://shiki.style/). #### Code Title @@ -194,7 +194,11 @@ export default defineUserConfig({ }) ``` -It can be used in combination with the other marks below. Please leave a space between them. +::: tip + +Code title is supported by highlight plugins by default. It can be used in combination with the other marks below. Please leave a space between them. + +::: #### Line Highlighting @@ -239,9 +243,11 @@ Examples for line ranges mark: - Combined: `{4,7-13,16,23-27,40}` ::: tip -This line highlighting extension is supported by our built-in plugin, which is forked and modified from [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines). -Config reference: [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines) +Line highlighting extension is supported by highlighter plugins. + +Config reference: [prism line highlighting](https://ecosystem.vuejs.press/plugins/markdown/prismjs.html#highlightlines) and [shiki highlighting](https://ecosystem.vuejs.press/plugins/markdown/shiki.html#highlightlines). + ::: #### Line Numbers @@ -281,9 +287,11 @@ const line3 = 'This is line 3' ``` ::: tip -This line numbers extension is supported by our built-in plugin. -Config reference: [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers) +Line numbers extension is supported by highlighter plugins. + +Config reference: [prism line numbers](https://ecosystem.vuejs.press/plugins/markdown/prismjs.html#linenumbers) and [shiki line numbers](https://ecosystem.vuejs.press/plugins/markdown/shiki.html#linenumbers). + ::: #### Wrap with v-pre @@ -346,9 +354,11 @@ const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} ``` ::: tip + This v-pre extension is supported by our built-in plugin. Config reference: [markdown.vPre.block](../reference/config.md#markdown-vpre-block) + ::: ### Import Code Blocks diff --git a/docs/zh/README.md b/docs/zh/README.md index 008124c5..f54edcac 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -6,21 +6,29 @@ actions: - text: 快速上手 link: /zh/guide/getting-started.html type: primary + - text: 项目简介 link: /zh/guide/introduction.html type: secondary + features: - title: 简洁至上 details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。 + - title: Vue 驱动 details: 享受 Vue 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。 + - title: 高性能 details: VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。 + - title: 主题 details: 提供了一个开箱即用的默认主题。你也可以挑选一个社区主题，或者创建一个你自己的主题。 + - title: 插件 details: 灵活的插件API，使得插件可以为你的站点提供许多即插即用的功能。 + - title: 打包工具 details: 推荐的打包工具是 Vite ，但也同样支持使用 Webpack 。选一个你喜欢的来使用吧！ + footer: MIT 协议 | 版权所有 © 2018-至今 VuePress 社区 --- diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md index b287d59a..b0bd0803 100644 --- a/docs/zh/guide/markdown.md +++ b/docs/zh/guide/markdown.md @@ -155,15 +155,15 @@ Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-e ### 代码块 -下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。 +下列代码块扩展都是在 Node 端进行 Markdown 解析时实现的，也就是代码块并不会在客户端被处理。 -需要注意的是，部分代码块功能需要主题支持。VuePress 默认主题支持所有这些功能，但社区主题有可能不支持。请查看你使用的主题文档来确认是否支持这些功能。 +通过 [@vuepress/plugin-prismjs][prismjs] 和 [@vuepress/plugin-shiki][shiki]，你可以通过 [Prism](https://prismjs.com/) 或 [Shiki](https://shiki.tmrs.site/) 来高亮代码块。 #### 代码标题 你可以在代码块添加一个 `title` 键值对来为代码块设置标题。 -**Input** +**输入** ````md ```ts title=".vuepress/config.ts" @@ -180,7 +180,7 @@ export default defineUserConfig({ ``` ```` -**Output** +**输出** ```ts title=".vuepress/config.ts" import { defaultTheme } from '@vuepress/theme-default' @@ -195,7 +195,11 @@ export default defineUserConfig({ }) ``` -它可以和下列的其他标记一起使用。请在它们之间使用空格分隔。 +::: tip + +代码标题是通过高亮器插件默认支持的。它可以和下列的其他标记一起使用。请在它们之间使用空格分隔。 + +::: #### 行高亮 @@ -240,9 +244,11 @@ export default defineUserConfig({ - 组合： `{4,7-13,16,23-27,40}` ::: tip -行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines)。 -配置参考： [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines) +行高亮扩展是通过高亮器插件默认支持的。 + +配置参考：[prism 行高亮](https://ecosystem.vuejs.press/zh/plugins/markdown/prismjs.html#highlightlines) 和 [shiki 行高亮](https://ecosystem.vuejs.press/zh/plugins/markdown/shiki.html#highlightlines) + ::: #### 行号 @@ -282,9 +288,11 @@ const line3 = 'This is line 3' ``` ::: tip -行号扩展是由我们的内置插件支持的。 -配置参考： [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers) +行号扩展是通过高亮器插件默认支持的。 + +配置参考：[prism 行号](https://ecosystem.vuejs.press/zh/plugins/markdown/prismjs.html#linenumbers) 和 [shiki 行号](https://ecosystem.vuejs.press/zh/plugins/markdown/shiki.html#linenumbers) + ::: #### 添加 v-pre @@ -296,9 +304,11 @@ const line3 = 'This is line 3' 你可以在代码块添加 `:v-pre` / `:no-v-pre` 标记来覆盖配置项中的设置。 ::: warning + 模板语法的字符有可能会被语法高亮器解析，比如 "Mustache" 语法（即双花括号）。因此，就像下面的例子一样，在某些语言中 `:no-v-pre` 可能并不能生效。 如果你无论如何都想在这种语言中使用 Vue 语法，你可以尝试禁用默认的语法高亮，然后在客户端实现你的自定义代码高亮。 + ::: **输入** @@ -347,9 +357,11 @@ const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} ``` ::: tip + v-pre 扩展是由我们的内置插件支持的。 配置参考： [markdown.vPre.block](../reference/config.md#markdown-vpre-block) + ::: ### 导入代码块