橙子的文档站 | Orange Docs

Nólëbase 集成

双向链接

安装

shell

npm install @nolebase/markdown-it-bi-directional-links -D

配置

在 VitePress 的配置文件中（通常为 docs/.vitepress/config.mts，文件路径和拓展名也许会有区别），将 @nolebase/markdown-it-bi-directional-links 作为一个插件导入，并将其作为 markdown 选项的 markdown-it 插件使用：

typescript

import { defineConfigWithTheme } from 'vitepress'
+import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'

export default defineConfigWithTheme({
  lang: 'zh-CN',
  title: '网站名称', // 仅供参考，请不要直接复制
  description: '某些介绍', // 仅供参考，请不要直接复制
  themeConfig: {
    // 其他各种配置...
  },
  markdown: {
    config: (md) => {
+      md.use(BiDirectionalLinks()) 
    },
  },
})

功能支持

✔️ 基本语法
✔️ 支持处理 hash tags #
✔️ 支持处理 query strings ?
✔️ 图片双链
✔️ 自定义文案
✔️ 自定义 HTML 属性
✔️ 同名文件语法
✔️ 绝对路径语法

渲染效果

基本形式: 双向链接示例页面

自定义文案：自定义文案

自定义文案中使用 Markdown 语法

markdown

[[Test/双向链接示例页面|`代码块（前缀）` 中间的内容 `代码块（后缀）`]]

[[Test/双向链接示例页面|**粗体（前缀）** 中间的内容 **粗体（后缀）**]]

[[Test/双向链接示例页面|*斜体（前缀）* 中间的内容 *斜体（后缀）*]]

[[Test/双向链接示例页面|~~删除线（前缀）~~ 中间的内容 ~~删除线（后缀）~~]]
[[Test/双向链接示例页面|`代码块（前缀）` 中间的内容 `代码块（后缀）`]]

粗体（前缀） 中间的内容 粗体（后缀）

斜体（前缀） 中间的内容 斜体（后缀）

~~删除线（前缀）~~ 中间的内容 ~~删除线（后缀）~~

自定义文案中使用 HTML 语法

markdown

[[Test/双向链接示例页面|<span style="color: red;">自定义 HTML</span>]]

[[Test/双向链接示例页面|<span style="color: red;">自定义 HTML</span> 中间的内容 <span style="color: blue;">自定义 HTML</span>]]

自定义 HTML

自定义 HTML 中间的内容自定义 HTML

兼容 `markdown-it-attrs` 修改 HTML 属性（Attribute）

改颜色

markdown

[[双向链接示例页面]]{style="color: red;"}

双向链接示例页面

绝对路径

markdown

[[某个完整路径]]

Test/双向链接示例页面

图片配合绝对路径

markdown

![[Vitepress/images/duoduo.jpg]]

绝对路径和自定义文案

markdown

[[某个文件夹|自定义文案]]

自定义文案

音频配合绝对路径

markdown

![[Vitepress/images/在你的身边.mp3]]

视频配合绝对路径

markdown

![[Vitepress/images/duoduo.mp4]]

阅读增强

安装

shell

npm install @nolebase/vitepress-plugin-enhanced-readabilities -D

为 VitePress 配置

配置分为两个大步骤：

添加 Vite 相关的配置
添加 VitePress 主题相关的配置

添加 Vite 相关的配置

首先，请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.mts，文件路径和拓展名也许会有区别）的根字段中添加 Vite 与 SSR 服务端渲染相关的配置。

将阅读增强的插件包 @nolebase/vitepress-plugin-enhanced-readabilities 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖：

typescript

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
+  vite: { 
+    optimizeDeps: {
+      exclude: [ 
+        '@nolebase/vitepress-plugin-enhanced-readabilities/client', 
+      ], 
+    },
+    ssr: { 
+      noExternal: [ 
+        // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可
+        '@nolebase/vitepress-plugin-enhanced-readabilities', 
+      ], 
+    }, 
+  }, 
  lang: 'zh-CN',
  title: '网站标题',
  themeConfig: {
    // 其他的配置...
  }
  // 其他的配置...
})

添加 VitePress 主题相关的配置

在 VitePress 的主题配置文件中（注意不是配置文件，通常为 docs/.vitepress/theme/index.mts，文件路径和拓展名也许会有区别），将 @nolebase/vitepress-plugin-enhanced-readabilities 导入，并且将其添加到 Layout 的拓展中：

typescript

// docs/.vitepress/theme/index.mts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
+import { 
+  NolebaseEnhancedReadabilitiesMenu, 
+  NolebaseEnhancedReadabilitiesScreenMenu, 
} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'

+import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'

import './styles/vars.css'
import './styles/main.css'


export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {
+      // 为较宽的屏幕的导航栏添加阅读增强菜单
+      'nav-bar-content-after': () => h(NolebaseEnhancedReadabilitiesMenu), 
+      // 为较窄的屏幕（通常是小于 iPad Mini）添加阅读增强菜单
+      'nav-screen-content-after': () => h(NolebaseEnhancedReadabilitiesScreenMenu), 
    })
  },
  enhanceApp() {
    // 其他的配置...
  },
}

export default Theme

效果演示

看到右上角的📖按钮了吗？你可以使用鼠标悬浮在上面来看到支持的功能，点选一个你感兴趣的功能来看看效果吧！

功能支持

✔️ 布局切换
✔️ 聚光灯

行内链接预览

安装

shell

npm install @nolebase/vitepress-plugin-inline-link-preview -D

用法

将行内链接预览插件集成到 VitePress 项目中包括两个主要步骤：

配置 markdown-it 插件（语法转换与数据处理相关配置）
添加 VitePress 主题相关的配置（UI 显示相关配置）

配置 `markdown-it` 插件

首先，请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.mts，文件路径和拓展名也许会有区别）的根字段中，注册所需的 markdown-it 插件：

typescript

import { defineConfig } from 'vitepress'
+import { 
+  InlineLinkPreviewElementTransform 
+} from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  lang: 'en',
  title: 'Site Name',
  themeConfig: {
    // 剩余的选项...
  },
+  markdown: { 
+    config(md) { 
+      // 其他 markdown-it 配置...
+      md.use(InlineLinkPreviewElementTransform) 
+    } 
+  } 
  // 剩余的选项...
})

添加 VitePress 主题相关的配置

在 VitePress 的主题配置文件中（注意不是配置文件，通常为 docs/.vitepress/theme/index.mts，文件路径和拓展名也许会有区别），将行内链接预览插件的组件注册到 VitePress 主题中：

typescript

// .vitepress/theme/index.mts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
+import { 
+  NolebaseInlineLinkPreviewPlugin, 
+} from '@nolebase/vitepress-plugin-inline-link-preview/client'

+import '@nolebase/vitepress-plugin-inline-link-preview/client/style.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    // 其他配置...
  },
+  enhanceApp({ app }) { 
+    app.use(NolebaseInlineLinkPreviewPlugin) 
+  }, 
}

export default Theme

BUG

要在此处加上'@nolebase/*'否则在构建的时候会报错 .vue

typescript

//config.mts 
ssr: {
      noExternal: [
        // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可
        '@nolebase/vitepress-plugin-enhanced-readabilities',
        '@nolebase/vitepress-plugin-highlight-targeted-heading',
        '@nolebase/*'
      ],
    },

功能支持

✔️ 布局切换
✔️ 聚光灯
✔️ 与双向链接一起搭配更佳
✔️ 预览任何页面
✔️ 隐藏页面内元素
✔️ 智能判断浮床位置
✔️ 自动判断外链
✔️ 原生与 VitePress 样式兼容
✔️ 遵循 Nolebase Integrations 国际化规范标准
✔️ 无障碍最佳实践

闪烁高亮当前的目标标题

安装

shell

npm install @nolebase/vitepress-plugin-highlight-targeted-heading -D

为 VitePress 配置

配置分为两个大步骤：

添加 Vite 相关的配置

将高亮插件包 @nolebase/vitepress-plugin-highlight-targeted-heading 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖：

typescript

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
+  vite: { 
+    ssr: { 
+      noExternal: [ 
+        // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可
+        '@nolebase/vitepress-plugin-highlight-targeted-heading', 
+      ], 
+    }, 
+  }, 
  lang: 'zh-CN',
  title: '网站标题',
  themeConfig: {
    // 其他的配置...
  }
  // 其他的配置...
})

添加 VitePress 主题相关的配置

在 VitePress 的主题配置文件中（注意不是配置文件，通常为 docs/.vitepress/theme/index.mts，文件路径和拓展名也许会有区别），将 @nolebase/vitepress-plugin-highlight-targeted-heading 导入，并且将其添加到 Layout 的拓展中：

typescript

// docs/.vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'

+import {  
+  NolebaseHighlightTargetedHeading,  
+} from '@nolebase/vitepress-plugin-highlight-targeted-heading/client'

+import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'*

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
     return h(DefaultTheme.Layout, null, {
      // 其他的配置...
+      'layout-top': () => [ 
+        h(NolebaseHighlightTargetedHeading), 
+      ], 
     })
  },
  enhanceApp() {
     // 其他的配置...
  },
}

export default Theme

效果演示

基于 Git 的页面历史

安装

shell

npm install @nolebase/vitepress-plugin-git-changelog -D

使用

这是配置最复杂的插件之一！

请注意以下配置和步骤，以开始使用基于 Git 的页面历史插件。与其他插件相比，这并不是那么简单。

将基于 Git 的页面历史插件集成到您的 VitePress 项目中包括两个主要步骤：

配置 Vite 插件（数据获取、日志聚合）
与 VitePress 集成（UI 和组件）

配置 Vite 插件

在 VitePress 的配置文件中配置 Vite 插件

请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.mts，文件路径和拓展名也许会有区别）的根字段中添加 Vite 选项，并导入并配置 GitChangelog（数据获取）和 GitChangelogMarkdownSection（小部件嵌入）插件：

typescript

import { defineConfig } from 'vitepress'
+import { 
+  GitChangelog, 
+  GitChangelogMarkdownSection, 
+} from '@nolebase/vitepress-plugin-git-changelog/vite'

// https://vitepress.dev/reference/site-config
export default defineConfig({
+  vite: { 
+    plugins: [ 
+      GitChangelog({ 
+        // 填写在此处填写您的仓库链接
+        repoURL: () => 'https://github.com/MGHYGitHub/docs', 
+      }), 
+      GitChangelogMarkdownSection(), 
+    ],
+  }, 
  lang: 'zh-CN',
  title: '站点名称',
  themeConfig: {
    // rest of the options...
  }
  // rest of the options...
})

与 VitePress 主题集成

现在，让我们将基于 Git 的页面历史 UI 小部件集成到您的 VitePress 项目中。

在 VitePress 的主题配置文件（请注意，这与上面提及的配置文件并非是一个文件，主题配置文件通常位于 docs/.vitepress/theme/index.ts，文件路径和扩展名可能会有所不同），安装 Vue 插件并使用组件：

typescript

// docs/.vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
+import { 
+  NolebaseGitChangelogPlugin 
+} from '@nolebase/vitepress-plugin-git-changelog/client'

+import '@nolebase/vitepress-plugin-git-changelog/client/style.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    // 其他配置
  },
  enhanceApp({ app }) {
+    app.use(NolebaseGitChangelogPlugin)  
  },
}

export default Theme

在 GitHub Actions 上进行构建

在与 Github Actions 一同使用的时候，我们只需要在 actions/checkout 的 with 参数中添加 fetch-depth: 0 的配置就可以确保在 CI/CD 环境中获取的 Git 日志是包含全部信息的了：

yml

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
# .github/workflows/deploy.yml
name: 将VitePress网站部署到页面

on:
  # 在针对 `main` 分支的推送上运行。如果您
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许您从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # 构建工作
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: npm/action-setup@v2 # 如果使用 pnpm，请取消注释
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: |
          npm run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: .vitepress/dist # 确保这是构建输出的正确路径

  # 部署工作
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

功能

✔️ Git 日志就是您所需要的一切。无需额外的服务费用、在线数据库或额外配置。 ✔️ 在构建时生成页面历史和贡献者章节 ✔️ 即时快速可靠 ✔️ 支持配置作者名称别名、电子邮件别名、昵称映射等自定义选项 ✔️ 原生与 VitePress 样式兼容 ✔️ 遵循 Nolebase Integrations 国际化规范标准 ✔️ 无障碍最佳实践

代码折叠块

安装

shell

npm i vitepress-plugin-codeblocks-fold

typescript

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';
+import { useData, useRoute } from 'vitepress';
+import codeblocksFold from 'vitepress-plugin-codeblocks-fold'; // 导入方法
+import 'vitepress-plugin-codeblocks-fold/style/index.css'; // 导入样式

export default {
    ...DefaultTheme,
+    enhanceApp(ctx) {
+        DefaultTheme.enhanceApp(ctx);
        // ...
    },
+    setup() {
+        // 获取前言和路由
+        const { frontmatter } = useData();
+        const route = useRoute();
+        // 基础使用
+        codeblocksFold({ route, frontmatter }, true, 400);
    }
};



// 本人自用修改过后的文件
// -----分割线--------
export default {
  // 指定要继承的主题，并基于此主题进行二次扩展
  extends: escookTheme,
  setup() {
    // 获取前言和路由
    const { frontmatter } = useData();
    const route = useRoute();
    // 基础使用
    codeblocksFold({ route, frontmatter }, true, 400);
  },
  Layout: () => {
    return h(escookTheme.Layout, null, {
      // 为较宽的屏幕的导航栏添加阅读增强菜单
      'nav-bar-content-after': () => h(NolebaseEnhancedReadabilitiesMenu),
      // 为较窄的屏幕（通常是小于 iPad Mini）添加阅读增强菜单
      'nav-screen-content-after': () => h(NolebaseEnhancedReadabilitiesScreenMenu),
      'layout-top': () => [
        h(NolebaseHighlightTargetedHeading),
      ],
      // https://vitepress.dev/guide/extending-default-theme#layout-slots
    })
  },
  enhanceApp({ app, router, ctx }) {
    // 在这里执行第一个 enhanceApp 函数的内容;
    app.use(NolebaseGitChangelogPlugin)
    app.use(NolebaseInlineLinkPreviewPlugin)
    app.component('Busuanzi', Busuanzi)
    // app.component('PageInfo', PageInfo); // 注册 PageInfo 组件
    if (inBrowser) {
      router.onAfterRouteChanged = () => {
        busuanzi.fetch();
      };
    }
    // 将 ctx 参数传递给 escookTheme.enhanceApp 函数
    escookTheme.enhanceApp({ app, router, ctx });
    // 可以在这里继续扩展自定义的功能...
  }
}

贡献者

MGHYGitHub

页面历史

最后编辑于大约 1 年前

查看完整历史

Nólëbase 集成 ​

双向链接 ​

安装 ​

配置 ​

功能支持 ​

渲染效果 ​

自定义文案中使用 Markdown 语法 ​

自定义文案中使用 HTML 语法 ​

兼容 markdown-it-attrs 修改 HTML 属性（Attribute） ​

改颜色 ​

绝对路径 ​

图片配合绝对路径 ​

绝对路径和自定义文案 ​

音频配合绝对路径 ​

视频配合绝对路径 ​

阅读增强 ​

安装 ​

为 VitePress 配置 ​

添加 Vite 相关的配置 ​

添加 VitePress 主题相关的配置 ​

效果演示 ​

功能支持 ​

行内链接预览 ​

安装 ​

用法 ​

配置 markdown-it 插件 ​

添加 VitePress 主题相关的配置 ​

BUG ​

功能支持 ​

闪烁高亮当前的目标标题 ​

安装 ​

为 VitePress 配置 ​

添加 Vite 相关的配置 ​

添加 VitePress 主题相关的配置 ​

效果演示 ​

基于 Git 的页面历史 ​

安装 ​

使用 ​

配置 Vite 插件 ​

在 VitePress 的配置文件中配置 Vite 插件 ​

与 VitePress 主题集成 ​

在 GitHub Actions 上进行构建 ​

功能 ​

代码折叠块 ​

安装 ​

贡献者

页面历史

Nólëbase 集成

双向链接

安装

配置

功能支持

渲染效果

自定义文案中使用 Markdown 语法

自定义文案中使用 HTML 语法

兼容 `markdown-it-attrs` 修改 HTML 属性（Attribute）

改颜色

绝对路径

图片配合绝对路径

绝对路径和自定义文案

音频配合绝对路径

视频配合绝对路径

阅读增强

安装

为 VitePress 配置

添加 Vite 相关的配置

添加 VitePress 主题相关的配置

效果演示

功能支持

行内链接预览

安装

用法

配置 `markdown-it` 插件

添加 VitePress 主题相关的配置

BUG

功能支持

闪烁高亮当前的目标标题

安装

为 VitePress 配置

添加 Vite 相关的配置

添加 VitePress 主题相关的配置

效果演示

基于 Git 的页面历史

安装

使用

配置 Vite 插件

在 VitePress 的配置文件中配置 Vite 插件

与 VitePress 主题集成

在 GitHub Actions 上进行构建

功能

代码折叠块

安装