vitepress搭建markdown文档博客

VitePress剪辑

VitePress 是 VuePress 的下一代框架 ，是支持vue 3.0 的 web 网站框架。

• 基于 Vite 而不是 Webpack 所以更快的启动时间，热重载等
• 使用 Vue3 来减少 JS 的有效负载

vuePress=webpack+vue2,vitePress=vite+vue3html

目前主流搭建文档站点的方式：

• Gatsby - 以 GraphQL 为核心，功能相当完善，插件生态丰富。但学习曲线高（React）
• Docusaurus - Meta 公司出品。功能强大，与 Gatsby 相似（React）
• dumi - 一款 UmiJS 生态中的组件开发文档工具（React）
• Nextra - 一个基于 Next.js 的静态站点生成器。（React）
• VuePress - 包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题（Vue）
• VitePress - 对 VuePress 进行了不少的改进。VitePress 旨在降低当前 VuePress 的复杂性，并从其极简主义的根源重新开始。（Vue）

除了 VitePress 之外，其他都是用 Webpack 作为开发服务器。一个只有几页的简单文档站点启动开发服务器所花费的时间变得难以忍受。即使是 HMR 更新也可能需要几秒钟才能反映在浏览器中。Vite 的出现很好地解决了这些问题：近乎即时的服务器启动、仅编译所服务页面的按需编译以及闪电般快速的 HMR。

 VuePress v1 在本质上是一个 Webpack 应用程序。即便只有两个页面，它也是一个完整的正在编译的 Webpack 项目(包括全部主题源文件)。更糟糕的是，当项目有不少页面时，服务器必须首先彻底编译每一个页面，而后才能显示任何内容 Vite 很好地解决了这些问题:服务器几乎当即启动，按需编译只编译所服务的页面，以及快速的 HMR。

有了 Vite 和 Vue 3，真的是时候从新考虑“Vue 驱动的静态站点生成器（vue系列的说明文档几乎都是这样生成的）

创建博客：

mkdir blog-vitepress
cd blog-vitepress
npm init -y

npm i -D vitepress
yarn init -y

yarn add -D vitepress

将 vitepress 执行命令添加到执行脚本中

"scripts": {

  "dev": "vitepress dev docs --open",

  "build": "vitepress build docs",

  "serve": "vitepress serve docs"

}

根目录创建 docs 目录，创建第一个 md 文件（网站首页的配置和内容），可以命令行活在文件中手动创建

mkdir docs

echo '# Hello World' > docs/index.md

启动项目

npm run dev

具体文档文件结构

vite-plugin-react-pages

其实也可以通过 https://github.com/vitejs/vite-plugin-react-pages 生成

vite-plugin-react-pages(vite-pages) 是一个由 vite 提供支持的 React 应用程序框架。它非常适合：

• 博客网站
• 组件库或产品的文档站点
• React 组件的 Demo 演示

vite-pages 默认提供了三种模板，可以选择初始化app（应用）、lib（组件库）、lib-monorepo

npm init vite-pages [仓库名] --template [模板名]

我们执行 npm init vite-pages library-demo --template lib 生成了一个典型的 Vite 结构的项目，有熟悉的 vite.config.ts、pages 文件夹等

该插件所有明确的依赖包作用：

• @mdx-js/mdx MDX的实现
• @mdx-js/react 作为 MDX 的 React 实现。
• vite-plugin-mdx Vite 支持 MDX 的插件
• vite-plugin-react-pages 文档插件核心实现
• vite-pages-theme-doc 官方的文档主题。依赖 react-router-dom ^5.0.0 版本

pages 目录为文档入口。文件式路由约定用 $ 符号的文件名结尾来识别为一个文档页面

.ts|.tsx|.js|.jsx|.md|.mdx 只要 $ 是扩展名前的最后一个字符，所有文件扩展名都有效。

pages 目录中还存在一个特殊的入口 _theme.tsx 用来配置当前文档的主题，vite-pages 默认使用了 vite-pages-theme-doc 官方主题。如果自定义需求不大，可以通过配置官方主题的参数来实现常规的功能。比如配置 logo、顶部链接、左侧菜单等。

具体阅读：https://vitejs.github.io/vite-plugin-react-pages/

项目配置

创建一个配置文件，在docs中新建一个 .vitepress 文件夹，里面创建一个 config.js 文件(VitePress 站点的基本文件是.VitePress/config.js，它应该导出一个 JavaScript 对象：) 查看配置参考以得到完整的选项列表

// vitepress/config.js
module.exports = {
  title: "我的博客",// 网站标题
  description: '我的vitepress博客.', //网站描述
  base: '/', //  部署时的路径 默认 /  可以使用二级地址 /base/
  // lang: 'en-US', //语言
  // 网页头部配置，引入需要图标，css，js
  head: [
    // 改变title的图标
    [
      'link',
      {
        rel: 'icon',
        href: '/img/linktolink.png',//图片放在public文件夹下
      },
    ],
  ],
  // 主题配置
  themeConfig: {
    repo: 'vuejs/vitepress', // 你的 github 仓库地址，网页的右上角会跳转
    //   头部导航
    nav: [
      { text: '首页', link: '/' },
      { text: '介绍', items:[{ text: '关于', link: '/brief/about/' },] }, // items 可以一直嵌套
      { text: '关于', link: '/about/' },
    ],
    //   侧边导航
    sidebar:{
    "/":[
        {
            text:"简介",
            link:'/intro/index'
        },
        {
            text:"新手入门",
            children:[
                {
                    text:'安装与使用',
                    link:'/intro/install-and-usage'
                },
            ]
        },
        {
            text:"命令",
            children:[
                {
                    text:'命令使用',
                    link:'/intro/command-info'
                },
                {
                    text:'自定义命令',
                    link:'/intro/custom-command'
                }
            ]
        },
    ]
}
  }
}

博客开发注意事项

基础路径

若是站点部署到非根 URL，则须要在.vitepress/config.js 中设置 base 选项。例如，若是您计划将站点部署到https://foo.github.io/bar/，则应将base设置为“/bar/”（始终以斜杠开头和结尾）。

对于基本 URL，要在公共场合引用图像，必须使用/bar/image.png 这样的 URL。但若是你决定改变基础，这是脆弱的。为了帮助实现这一点，VitePress 提供了一个内置的助手$withBase（注入到 Vue 的原型中），它能够生成正确的路径：

<img :src="$withBase('/foo.png')" alt="foo" />

Markdown 拓展

内部链接

内部连接转换为路由器连接，用于 SPA 导航。此外，每一个子目录中包含的每一个 index.md 都将自动转换为 index.html，并带有相应的 URL/。

例如，给定如下目录结构：

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

提供其中之一 foo/one.md

[Home](/) <!-- 跳转到根部的 README.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three.md) <!-- 具体文件可使用 .md 结尾（推荐） -->
[bar - four](../bar/four.html) <!-- 也能够用 .html -->

页面后缀

默认状况下，生成的页面和内部连接的后缀是.html。

外部连接

出站的连接自动得到target=" blank" rel="noopener noreferrer

YAML frontmatter 

具体查看：https://jekyllrb.com/docs/front-matter/

注意的是采用三虚线必须放置在 markdown 文件的 最上面

---
title: Blogging Like a Hacker
lang: en-US
---

frontmatter

可供选择的 frontmatter 格式

---
title: tags
date: 2019-08-13 09:39:50
type: tags
layout: tag
---
# Hello VitePress

# }

任何包含 YAML frontmatter 块的 Markdown 文件都将被 gray matter 处理。frontmatter 必须位于 Markdown 文件的顶部，而且必须采用三条虚线之间的有效 YAML 集的形式。例子：

frontmatter 很重要，vitePress 只识别这个----三条虚线块有且只有一个</strong></p><p>在三虚线之间，您能够设置预约义的变量，甚至建立您本身的自定义变量。这些变量能够经过frontmatter 变量来使用。这里有一个例子，你能够在你的 Markdown 文件中使用它

JSON 前端语法

VitePress 还支持 JSON 前端语法，以花括号开始和结束【俩种写法不能共存】

---


# {{ $frontmatter.title }}

预约义的变量

具体查看：https://vitepress.vuejs.org/guide/frontmatter.html#title

代码展示

Prism 网站上有有效语言的列表上有的，都支持

```js{1,4,6-7}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

module.exports = {
  markdown: {
    // markdown-it-anchor 的选项
    anchor: { permalink: false },
    // markdown-it-toc 的选项

    toc: { includeLevel: [1, 2] },
    config: (md) => {

      // 使用更多的 markdown-it 插件!

      md.use(require('markdown-it-xxx'))

    }

  }

}

module.exports = {

  themeConfig: {

    algolia: {

      apiKey: 'your_api_key',

      indexName: 'index_name'

    }

  }}

npm install -D vitepress-theme-demoblock
# or
yarn add -D vitepress-theme-demoblock

module.exports = {
  markdown: {
    config: (md) => {
      const { demoBlockPlugin } = require('vitepress-theme-demoblock')
      md.use(demoBlockPlugin)
    }
  }
}

"scripts": {
  "register:components": "vitepress-rc"
}

// docs/.vitepress/theme/index.ts
// 导入vitepress-theme-demoblock主题，并注册组件(包含主题中默认的组件)。

import Theme from 'vitepress/dist/client/theme-default'
// 导入主题样式

import 'vitepress-theme-demoblock/theme/styles/index.css'

// 想引入全局自己的 css 文件，也可以在这里引入
// 导入插件的主题

import { registerComponents } from './register-components.js'
export default {

  ...Theme,

  enhanceApp({ app }) {

    registerComponents(app)

  }

}

# Button 按钮

:::demo 使用type，plain，round来定义 Button 的样式
<template>
  <my-button style="color: red">按钮1</my-button>
  Middle
  <my-button type="size">按钮2</my-button>
  Large
  <my-button>按钮3</my-button>
  Disabled
  <my-button disabled>按钮4</my-button>
</template>
:::</code></pre></div></div><p>默认支持 vue 语法， 想修改的话需要修改配置：</p><div class="rno-markdown-code"><div class="rno-markdown-code-toolbar"><div class="rno-markdown-code-toolbar-info"><div class="rno-markdown-code-toolbar-item is-type"><span class="is-m-hidden">代码语言：</span>javascript</div></div><div class="rno-markdown-code-toolbar-opt"><div class="rno-markdown-code-toolbar-copy"><i class="icon-copy"></i><span class="is-m-hidden">复制</span></div></div></div><div class="developer-code-block"><pre class="prism-token token line-numbers language-javascript"><code class="language-javascript" style="margin-left:0">md.use(demoBlockPlugin, {  lang: &#39;ts&#39;})</code></pre></div></div><p>但是这里有个限制，智能识别一种语法结构，想到会有 js、 ts、 json 等多种语法，所以改了下解析结构，改成了数组</p><p>参考文章：</p><p>https://miyauchi.dev/posts/start-vitepress/</p><p>使用 vitepress + github Pages搭建自己的博客网站 https://juejin.cn/post/7038581771503403022</p><p>「VitePress」极简博客搭建   https://juejin.cn/post/6896382276389732359</p><p>基于 vite 的组件文档编写神器，又快又省心 https://jishuin.proginn.com/p/763bfbd72e9c</p><p> VitePress 学习(全面拥抱vite)---翻译 https://juejin.cn/post/6965510644007665671</p><p>转载本站文章《vitepress搭建markdown文档博客》,
请注明出处：https://www.zhoulujun.cn/html/tools/Bundler/vite/8773.html</p>