md-tools

md-tools用于解析Markdown文件，并生成React（vue）静态站点。

功能

md-tools重度参考Bi Sheng，并在此基础剥离React依赖。

• 引擎体系：提供React渲染引擎
• 插件体系：antd类文档网站插件，组件类文档网站插件，描述信息插件，目录插件，图片预览插件，React解析插件，代码高清插件
• 主题体系
  • 提供组件开发主题md-tools-theme-component-react,用于快速开发开发一个React组件或bug重现简易脚手架
  • 提供组件库开发主题md-tools-theme-multi-component-react,用于快速开发开发一个React组件库

如何使用

安装依赖:

npm install -D md-tools

在npm scripts中增加start:

{
  "scripts": {
    "start": "md-tools start"
  }
}

增加配置文件 md-tools.config.js, 默认配置:

module.exports = {
  source: './posts',
  output: './_site',
  theme: './_theme',
  port: 8000,
};

文档

命令

$ npm install -g md-tools
$ md-tools -h
  用法: md-tools [command] [options]

  Commands:

    start [options]     开发模式：启动服务
    build [options]     生产模式：生产模式：构建输出静态文件
    help [cmd]          显示帮助信息

  Options:

    -h, --help     显示帮助信息
    -V, --version  显示版本号
    -c,--config    start,build命令设置配置文件路径，默认： md-tools-theme-component-react/md-tool.config.js

配置文件

md-tools 默认使用md-tools.config.js作为配置,可以通过 --config修改配置文件路径，如： md-tools --config another.config.js。

md-tools.config.js的配置例子:

module.exports = {
  port: 8000,
  source: './posts',
  output: './site',
  engine: 'md-tools-engine-react',
  theme: './theme',
  htmlTemplate: path.join(__dirname, '../template.html'),
  devServerConfig: {},
  webpackConfig(config) {
    return config;
  },

  entryName: 'index',
  root: '/',
};

port: Number

default: 8000

开发模式下启动的服务端口号，如果端口被占用，会自动寻找未使用的端口

source: String | Array[String] | Object{ [category]: String | Array[String]}

default: './posts'

需要转换的Markdown文件所在路径.

Markdown文件内容会转换为插件体系预处理用到的Markdown数据，数据结构见 mark-twain。

exclude: RegExp

default: null

需要例外的Markdown文件

output: String

default: './site'

md-tools构建输出的路径.

engine: String

default: 'md-tools-engine-react'

文档系统源码路径（引擎体系），可以是npm依赖包名称

• md-tools-engine-react

theme: String

default: './theme'

文档系统源码路径（主题体系），可以是npm依赖包名称

• md-tools-theme-component-react
• md-tools-theme-multi-component-react

themeConfig: any

undefined

主题个性配置, 主题源文件可以从props.themeConfig读取改配置。

备注: themeConfig传递过程使用了 JSON.stringify，所以无法在这里配置function/RegExp.

htmlTemplate: String

default: md-tools/lib/template.html

文档系统入口html文件模板，如果配置的引擎带有htmlTemplate，则默认值为引擎中的模板.

Note: 模板引擎 nunjucks, 模板中的参数:

• root
• htmlTemplateExtraData中的配置

iframeTemplate: String

default: md-tools-plugin-antd/lib/template.html

文档系统入口html文件模板（Markdown文档中配置iframe=[number]时）。

htmlTemplateExtraData: Object

default: {}

htmlTemplate自定义参数.

devServerConfig: Object

default: {}

参见 webpack-dev-server's documentation.

postcssConfig: Object

default: {
    plugins: [
      rucksack(),
      autoprefixer({
        browsers: ['last 2 versions', 'Firefox ESR', '> 1%', 'ie >= 9', 'iOS >= 8', 'Android >= 4'],
      }),
    ],
  }

参见 wenpack postcss-loader's documentation.

webpackConfig: (config) => config

default: (config) => config

自定义webpack配置，参见 this.

transformers: Object[]

[{ test: /.md$/, use: MarkdownTransformer}]

Markdown转换引擎.

entryName: String

default: 'index'

webpack构建入口文件名, 如 [entryName].js & [entryName].css。

root: String

default: '/'

发布目录。默认根目录，如果需要发布到二级目录，配置相应目录即可。

鸣谢

• Bi Sheng

License

MIT