@visdoc/vite-plugin-visdoc v2.0.0

VitePluginVisDoc

VitePluginVisDoc 是一个用于将markdown文档转为html的插件。

教程

1. 安装：

   npm install @visdoc/vite-plugin-visdoc --save-dev

2. 使用

   // vite.config.js
   import { defineConfig } from 'vite'
   import visdoc from 'vite-plugin-visdoc'
   import { resolve } from 'path'
   
   export default defineConfig({
     plugins: [visdoc()]
   })

功能配置：

/**
 * 插件配置
 */
interface ConfigOptions {
   /**
    * md文档所在的目录
    *
    * 相对于`viteConfig.build.root`目录。
    *
    * @default 'src/docs'
    */
   docsDir?: string
   /**
    * 输出目录
    *
    * 相对于`viteConfig.build.outDir`目录。
    *
    * > 注意：只能配置相对路径，不能以/开头，路径相对于`vite.config.build.outDir`路径。
    *
    * 默认为`docs`假设你没有修改vite配置中的输出目录，则打包过后的html位于`项目ROOT/dist/docs`目录下。
    *
    * @default 'docs'
    */
   outDir?: string
   /**
    * 缓存目录，用于缓存解析后的文档数据。
    *
    * @default 'node_modules/.vite/.visdoc'
    */
   cacheDir?: string
   /**
    * 站点地图配置
    */
   sitemap?: Sitemap
   /**
    * 自动打包目录下所有html文件
    *
    * `template.path`配置的模板文件除外的所有html文件都会视为入口文件，打包至`viteConfig.build.outDir`目录下。
    *
    * 该选项配合`excludeDirs`可以高效的构建项目，无需手动在`vite.config`中声明`input`入口。
    *
    * 示例：相对路径['src']，绝对路径[path.resolve(__dirname,'src')]
    *
    * @default ''
    */
   autoBuildDir?: string
   /**
    * 排除构建的文件列表
    *
    * 支持绝对路径和相对路径
    *
    * 可以是html文件或md文件。
    *
    * @default []
    */
   excludeFiles?: string[]
   /**
    * 排除构建的目录列表
    *
    * 与`autoBuildDir`配合使用。
    *
    * 仅支持一级目录，不支持多级目录，文档目录无效。
    *
    * 示例：['dist','node_modules']
    *
    * @default []
    */
   excludeDirs?: string[]
   /**
    * 国际化多语言配置
    *
    *
    * @default {enabled: false, defaultLang: 'zh'}
    */
   i18n?: I18N
   /**
    * 分组目录入口文档名称
    *
    * 入口文档不会出现在分组的子菜单中，它做为分组选项的默认呈现，通常用于分组的前言描述。
    *
    * 假设存在一个 `src/docs/zh/group/index.md` 文件，那么它的页面标题为 `group`，访问路径为 `/group`|`/group/index.html`。
    *
    * @default 'index'
    */
   index?: string
   /**
    * 模板生成与替换相关配置
    */
   template?: TemplateOptions
   /**
    * MarkdownIt 配置
    */
   markdownIt?: MarkdownItConfig
   /**
    * 根据文件名称，拆分出文章名称与访问路径。
    */
   splitNameAndUrl: (name: string) => { name: string; url: string }
   /**
    * 日期格式化
    *
    * 格式化文档创建时间和更新时间。
    *
    * @default '2024-11-24T21:42:42+08:00'
    */
   formatDate: (date: Date) => string
}

// 站点地图配置
interface Sitemap {
   /**
    * 是否启用自动生成站点地图。
    *
    * @default false
    */
   enabled: boolean
   /**
    * 域名
    *
    * 示例：https://www.visdoc.com
    */
   loc: string
   /**
    * 更改频率
    *
    * @default 'weekly'
    */
   changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
   /**
    * 优先级
    *
    * @default 0.5
    */
   priority?: number
}
// 国际化
interface I18N {
   /**
    * 是否启用国际化。
    *
    * @default false
    */
   enabled: boolean
   /**
    * 默认语言
    *
    * @default 'zh'
    */
   defaultLang?: string
}
// MarkdownIt 配置
interface MarkdownItConfig {
   /**
    * MarkdownIt 构造配置
    */
   options?: MarkdownIt.Options
   /**
    * MarkdownIt 插件列表
    */
   plugins?: MarkdownItPlugin[]
}
// 模板相关
interface TemplateOptions {
   /**
    * 模板文件路径。
    *
    * 将文档转换html注入到模板内容中，形成新的html文件
    *
    * @default 'template.html'
    */
   path?: string
   /**
    * 模板占位符匹配模式。
    */
   pattern?: (placeholder: string) => RegExp | string
   /**
    * 注入文章导航菜单代码。
    *
    * @default false
    */
   injectNavMenu?: boolean
   /**
    * 注入文章内容菜单代码。
    *
    * @default false
    */
   injectTocMenu?: boolean
   /**
    * 将`injectNavMenu`生成的代码合并到`injectTocMenu`中。
    *
    * @default false
    */
   mergeMenu?: boolean
   /**
    * 注入分页数据。
    *
    * 如果启用，则会在模板中注入上一页、下一页数据。
    *
    * @default false
    */
   injectPaginationData?: boolean
   /**
    * 占位符配置
    */
   placeholder?: Placeholder
   /**
    * 替换内容，所有打包的HTML都会被扫描替换相关的内容。
    *
    * @default {}
    */
   replace?: Record<string, string | string[]>
}
// 占位符
interface Placeholder {
   /**
    * 内容占位符
    *
    * @default 'CONTENT'
    */
   content?: string
   /**
    * 导航菜单占位符
    *
    * @default 'NAV_MENU'
    */
   navMenu?: string
   /**
    * 内容菜单占位符
    *
    * @default 'TOC_MENU'
    */
   tocMenu?: string
   /**
    * 前一页链接占位符
    *
    * @default 'PREVIOUS_PAGE_LINK'
    */
   prevPageLink: string
   /**
    * 前一页名称占位符
    *
    * @default 'PREVIOUS_PAGE_TITLE'
    */
   prevPageTitle: string
   /**
    * 下一页链接占位符
    *
    * @default 'NEXT_PAGE_LINK'
    */
   nextPageLink: string
   /**
    * 下一页名称占位符
    *
    * @default 'NEXT_PAGE_TITLE'
    */
   nextPageTitle: string
}