代码树新

约 686 字大约 2 分钟

2025-05-02

概述

在 markdown 中，使用 ::: code-tress 容器，或者使用 @[code-tree](dir_path)，可以显示一个带有文件树的代码块区域。

相比于代码块分组，代码树可以更加清晰地展示代码文件的组织结构，以及文件的依赖关系。

启用

该功能默认不启用，你需要在 theme 配置中启用。

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    markdown: {
      codeTree: true, 
    }
  })
})

使用

主题提供了两种使用方式：

code-tree 容器

::: code-tree title="Project Name" height="400px" entry="filepath"
```lang title="filepath" :active
<!-- code content-->
```

```lang title="filepath"
<!-- code content-->
```
<!-- 更多代码块 -->
:::

使用 ::: code-tree 容器包裹多个代码块。

在 ::: code-tree 后使用 title="Project Name" 声明代码树的标题
在 ::: code-tree 后使用 height="400px" 声明代码树的高度
在 ::: code-tree 后使用 entry="filepath" 声明默认展开的文件路径
在代码块 ``` lang 后使用 title="filepath" 声明当前代码块的文件路径
如果在 ::: code-tree 未声明 entry="filepath"，可以在代码块 ``` lang 后使用 :active 声明当前代码块为展开状态
如果未指定展开的文件路径，默认展开第一个文件

代码块上为什么是 title="filepath" 而不是 filepath="filepath" ?

因为主题已经在代码块上提供了标题语法的支持，沿用已有的语法支持可以减少学习成本。

输入：

::: code-tree title="Vue App" height="400px" entry="src/main.ts"
```vue title="src/components/HelloWorld.vue"
<template>
  <div class="hello">
    <h1>Hello World</h1>
  </div>
</template>
```

```vue title="src/App.vue"
<template>
  <div id="app">
    <h3>vuepress-theme-plume</h3>
    <HelloWorld />
  </div>
</template>
```

```ts title="src/main.ts"
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')
```

```json title="package.json"
{
  "name": "Vue App",
  "scripts": {
    "dev": "vite"
  }
}
```
:::

输出：

Vue App

src

components

HelloWorld.vue

App.vue

main.ts

package.json

src/components/HelloWorld.vue
<template>
  <div class="hello">
    <h1>Hello World</h1>
  </div>
</template>
src/App.vue
<template>
  <div id="app">
    <h3>vuepress-theme-plume</h3>
    <HelloWorld />
  </div>
</template>
src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')
package.json
{
  "name": "Vue App",
  "scripts": {
    "dev": "vite"
  }
}

从目录导入 code-tree

主题支持通过以下语法从目录导入 code-tree:

<!-- 简单导入 -->
@[code-tree](dir_path)

<!-- 添加的配置 -->
@[code-tree title="Project Name" height="400px" entry="filepath"](dir_path)

dir_path: 当传入绝对路径，即以 / 开头时，从文档站点的源目录开始查找。当传入相对路径时，即以 . 开头时，表示相对于当前 markdown 文件。
title: 代码树标题，可选，默认为空
height: 代码树高度，可选，默认为空
entry: 默认展开的文件路径，可选，默认为第一个文件

输入：

<!-- 此目录为主题仓库 `docs/.vuepress/collections/` -->
@[code-tree title="Collections 配置" height="400px" entry="index.ts"](/.vuepress/collections)

输出：

Collections 配置

index.ts

theme-config.ts

theme-guide.ts

tools.ts

index.ts

theme-config.ts

theme-guide.ts

tools.ts

index.ts

en/index.ts
import { defineCollections, type ThemeCollections } from 'vuepress-theme-plume'
import { themeConfig } from './theme-config.js'
import { themeGuide } from './theme-guide.js'
import { tools } from './tools.js'

export const enCollections: ThemeCollections = defineCollections([
  themeGuide,
  themeConfig,
  tools,
])
en/theme-config.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const themeConfig: ThemeCollectionItem = defineCollection({
  type: 'doc',
  title: 'Config',
  dir: 'config',
  linkPrefix: '/config/',
  sidebar: [
    {
      text: 'Configuration',
      collapsed: false,
      items: [
        'intro',
        'theme',
        'locales',
        'navbar',
        'sidebar',
        'collections',
        'markdown',
      ],
    },
    {
      text: 'Page Configuration',
      prefix: 'frontmatter',
      collapsed: false,
      items: [
        'basic',
        'home',
        'post',
        'friend',
      ],
    },
    {
      text: 'Built-in Plugins',
      prefix: 'plugins',
      collapsed: false,
      items: [
        '',
        'shiki',
        'search',
        'reading-time',
        'markdown-enhance',
        'markdown-power',
        'markdown-image',
        'markdown-math',
        'markdown-include',
        'watermark',
      ],
    },
  ],
})
en/theme-guide.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const themeGuide: ThemeCollectionItem = defineCollection({
  type: 'doc',
  dir: 'guide',
  title: 'Guide',
  linkPrefix: '/guide/',
  sidebar: [
    {
      text: 'Quick Start',
      collapsed: false,
      icon: 'carbon:idea',
      prefix: 'quick-start',
      items: [
        'intro',
        'usage',
        'project-structure',
        {
          text: 'Collection',
          link: 'collection',
          items: ['collection-post', 'collection-doc'],
        },
        'sidebar',
        'write',
        'locales',
        'deployment',
        'optimize-build',
      ],
    },
    {
      text: 'Write',
      icon: 'fluent-mdl2:edit-create',
      collapsed: false,
      items: [
        {
          text: 'markdown',
          icon: 'material-symbols:markdown-outline',
          prefix: 'markdown',
          collapsed: true,
          items: [
            'basic',
            'extensions',
            'table',
            'icons',
            'mark',
            'plot',
            'abbr',
            'annotation',
            'card',
            'steps',
            'file-tree',
            'code-tree',
            'field',
            'tabs',
            'timeline',
            'demo-wrapper',
            'flex',
            'collapse',
            'npm-to',
            'caniuse',
            'chat',
            'include',
          ],
        },
        {
          text: 'code block',
          prefix: 'code',
          icon: 'ph:code-bold',
          collapsed: true,
          items: [
            'intro',
            'features',
            'copy-code',
            'code-tabs',
            'import',
            'twoslash',
          ],
        },
        {
          text: 'code repl',
          prefix: 'repl',
          icon: 'carbon:demo',
          collapsed: true,
          items: [
            'frontend',
            'rust',
            'golang',
            'kotlin',
            'python',
            'codepen',
            'jsFiddle',
            'codeSandbox',
            'replit',
          ],
        },
        {
          text: 'charts',
          icon: 'mdi:chart-line',
          prefix: 'chart',
          collapsed: true,
          items: [
            'chart',
            'echarts',
            'mermaid',
            'flowchart',
            'markmap',
            'plantuml',
          ],
        },
        {
          text: 'resource embedded',
          icon: 'dashicons:embed-video',
          prefix: 'embed',
          collapsed: true,
          items: [
            'pdf',
            'bilibili',
            'acfun',
            'youtube',
            'artplayer',
            'audioReader',
          ],
        },
      ],
    },
    {
      text: 'Features',
      icon: 'lucide:box',
      collapsed: false,
      prefix: 'features',
      items: [
        'icon',
        'search',
        'image-preview',
        'comments',
        'bulletin',
        'encryption',
        'contributors',
        'changelog',
        'copyright',
        'watermark',
        'friend-links',
        'replace-assets',
        'seo',
        'sitemap',
      ],
    },
    {
      text: 'Component',
      prefix: 'components',
      icon: 'uiw:component',
      collapsed: false,
      items: [
        'badge',
        'icon',
        'plot',
        'card',
        'link-card',
        'image-card',
        'card-grid',
        'card-masonry',
        'home-box',
        'repo-card',
        'npm-badge',
        'swiper',
      ],
    },
    {
      text: 'Customization',
      icon: 'material-symbols:dashboard-customize-outline-rounded',
      collapsed: false,
      prefix: 'custom',
      items: [
        { text: 'Custom Homepage', link: 'home', items: ['home-hero-effect'] },
        'style',
        'slots',
        'component-overrides',
      ],
    },
    {
      text: 'API',
      icon: 'mdi:api',
      prefix: 'api',
      collapsed: false,
      items: [
        'client',
        'node',
      ],
    },
  ],
})
en/tools.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const tools: ThemeCollectionItem = defineCollection({
  type: 'doc',
  dir: 'tools',
  title: 'Theme Tools',
  linkPrefix: '/tools/',
  sidebar: [
    {
      text: 'Tools',
      icon: 'tabler:tools',
      items: [
        'custom-theme',
        'home-hero-tint-plate',
        'caniuse',
      ],
    },
  ],
})
zh/index.ts
import { defineCollections, type ThemeCollections } from 'vuepress-theme-plume'
import { themeConfig } from './theme-config.js'
import { themeGuide } from './theme-guide.js'
import { tools } from './tools.js'

export const zhCollections: ThemeCollections = defineCollections([
  themeGuide,
  themeConfig,
  tools,
])
zh/theme-config.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const themeConfig: ThemeCollectionItem = defineCollection({
  type: 'doc',
  title: '配置',
  dir: 'config',
  linkPrefix: '/config/',
  sidebar: [
    {
      text: '配置',
      collapsed: false,
      items: [
        'intro',
        'theme',
        'locales',
        'navbar',
        'sidebar',
        'collections',
        'markdown',
      ],
    },
    {
      text: '页面配置',
      prefix: 'frontmatter',
      collapsed: false,
      items: [
        'basic',
        'home',
        'post',
        'friend',
      ],
    },
    {
      text: '内置插件',
      prefix: 'plugins',
      collapsed: false,
      items: [
        '',
        'shiki',
        'search',
        'reading-time',
        'markdown-enhance',
        'markdown-power',
        'markdown-image',
        'markdown-math',
        'markdown-include',
        'watermark',
      ],
    },
  ],
})
zh/theme-guide.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const themeGuide: ThemeCollectionItem = defineCollection({
  type: 'doc',
  dir: 'guide',
  title: '指南',
  linkPrefix: '/guide/',
  sidebar: [
    {
      text: '从这里开始',
      collapsed: false,
      icon: 'carbon:idea',
      prefix: 'quick-start',
      items: [
        'intro',
        'usage',
        'project-structure',
        {
          text: '集合',
          link: 'collection',
          items: ['collection-post', 'collection-doc'],
        },
        'sidebar',
        'write',
        'locales',
        'deployment',
        'optimize-build',
      ],
    },
    {
      text: '写作',
      icon: 'fluent-mdl2:edit-create',
      collapsed: false,
      items: [
        {
          text: 'markdown',
          icon: 'material-symbols:markdown-outline',
          prefix: 'markdown',
          collapsed: true,
          items: [
            'basic',
            'extensions',
            'table',
            'icons',
            'mark',
            'plot',
            'abbr',
            'annotation',
            'card',
            'steps',
            'file-tree',
            'code-tree',
            'field',
            'tabs',
            'timeline',
            'demo-wrapper',
            'flex',
            'collapse',
            'npm-to',
            'caniuse',
            'chat',
            'include',
          ],
        },
        {
          text: '代码块',
          prefix: 'code',
          icon: 'ph:code-bold',
          collapsed: true,
          items: [
            'intro',
            'features',
            'copy-code',
            'code-tabs',
            'import',
            'twoslash',
          ],
        },
        {
          text: '代码演示',
          prefix: 'repl',
          icon: 'carbon:demo',
          collapsed: true,
          items: [
            'frontend',
            'rust',
            'golang',
            'kotlin',
            'python',
            'codepen',
            'jsFiddle',
            'codeSandbox',
            'replit',
          ],
        },
        {
          text: '图表',
          icon: 'mdi:chart-line',
          prefix: 'chart',
          collapsed: true,
          items: [
            'chart',
            'echarts',
            'mermaid',
            'flowchart',
            'markmap',
            'plantuml',
          ],
        },
        {
          text: '资源嵌入',
          icon: 'dashicons:embed-video',
          prefix: 'embed',
          collapsed: true,
          items: [
            'pdf',
            'bilibili',
            'acfun',
            'youtube',
            'artplayer',
            'audioReader',
          ],
        },
      ],
    },
    {
      text: '功能',
      icon: 'lucide:box',
      collapsed: false,
      prefix: 'features',
      items: [
        'icon',
        'search',
        'image-preview',
        'comments',
        'bulletin',
        'encryption',
        'contributors',
        'changelog',
        'copyright',
        'watermark',
        'friend-links',
        'replace-assets',
        'seo',
        'sitemap',
      ],
    },
    {
      text: '组件',
      prefix: 'components',
      icon: 'uiw:component',
      collapsed: false,
      items: [
        'badge',
        'icon',
        'plot',
        'card',
        'link-card',
        'image-card',
        'card-grid',
        'card-masonry',
        'home-box',
        'repo-card',
        'npm-badge',
        'swiper',
      ],
    },
    {
      text: '自定义',
      icon: 'material-symbols:dashboard-customize-outline-rounded',
      collapsed: false,
      prefix: 'custom',
      items: [
        { text: '自定义首页', link: 'home', items: ['home-hero-effect'] },
        'style',
        'slots',
        'component-overrides',
      ],
    },
    {
      text: 'API',
      icon: 'mdi:api',
      prefix: 'api',
      collapsed: false,
      items: [
        'client',
        'node',
      ],
    },
  ],
})
zh/tools.ts
import type { ThemeCollectionItem } from 'vuepress-theme-plume'
import { defineCollection } from 'vuepress-theme-plume'

export const tools: ThemeCollectionItem = defineCollection({
  type: 'doc',
  dir: 'tools',
  title: '工具',
  linkPrefix: '/tools/',
  sidebar: [
    {
      text: '工具',
      icon: 'tabler:tools',
      items: [
        'custom-theme',
        'home-hero-tint-plate',
        'caniuse',
      ],
    },
  ],
})
index.ts
export * from './en/index.js'
export * from './zh/index.js'

贡献者

pengzhanbo

更新日志

2025/10/9 07:46

查看所有更新日志

38505-docs: update en docs (#708)于 2025/10/9
4d236-feat(theme)!: add collections support (#704)于 2025/10/7
31e3b-feat(plugin-md-power): add code-tree container and embed syntax, close #567 (#584)于 2025/5/2

代码树 新

概述

启用

使用

code-tree 容器

从目录导入 code-tree

贡献者

更新日志

代码树新