# md-tools

md-tools用于解析[Markdown](https://en.wikipedia.org/wiki/Markdown)文件，并生成React（vue）静态站点。

## 功能

`md-tools`重度参考[Bi Sheng](https://github.com/benjycui/bisheng)，并在此基础剥离React依赖。

* 引擎体系：提供React渲染引擎
* 插件体系：antd类文档网站插件，组件类文档网站插件，描述信息插件，目录插件，图片预览插件，React解析插件，代码高清插件
* 主题体系
  * 提供组件开发主题`md-tools-theme-component-react`,用于快速开发开发[一个React组件](http://git.sdp.nd/fed/component-boilerplate-single)或[bug重现简易脚手架](http://git.sdp.nd/fed/easy-demo)
  * 提供组件库开发主题`md-tools-theme-multi-component-react`,用于快速开发开发[一个React组件库](http://git.sdp.nd/fed/component-boilerplate-multi)

## 如何使用

安装依赖:

```bash
npm install -D md-tools
```

 在[npm scripts](https://docs.npmjs.com/misc/scripts)中增加`start`:

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

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

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

## 文档

### 命令

```bash
$ 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`的配置例子:

```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](https://github.com/benjycui/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](https://www.npmjs.com/package/md-tools-engine-react)

#### theme: String

> default: './theme'

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

* [md-tools-theme-component-react](https://www.npmjs.com/package/md-tools-theme-component-react)
* [md-tools-theme-multi-component-react](https://www.npmjs.com/package/md-tools-theme-multi-component-react)

#### themeConfig: any

> undefined

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

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

#### htmlTemplate: String

> default: [`md-tools/lib/template.html`](https://github.com/gem-mine/md-tools/blob/master/packages/md-tools/src/template.html)

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

**Note:** 模板引擎 [nunjucks](https://mozilla.github.io/nunjucks/), 模板中的参数:

* [`root`](#root-string)
* [htmlTemplateExtraData](#htmltemplateextradata-object)中的配置

#### iframeTemplate: String

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

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

#### htmlTemplateExtraData: Object

> default: `{}`

[htmlTemplate](#htmltemplate-string)自定义参数.

#### devServerConfig: Object

> default: {}

参见 [webpack-dev-server's documentation](https://webpack.js.org/configuration/dev-server/).

#### postcssConfig: Object

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

参见 [wenpack postcss-loader's documentation](https://webpack.js.org/loaders/postcss-loader/#options).

#### webpackConfig: (config) => config

> default: (config) => config

自定义webpack配置，参见 [this](https://github.com/ant-tool/atool-build#配置扩展).

#### transformers: Object[]

> [{ test: /\.md$/, use: [MarkdownTransformer](https://github.com/gem-mine/md-tools/blob/master/packages/md-tools/src/transformers/markdown.js)}]

Markdown转换引擎.

#### entryName: String

> default: 'index'

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

#### root: String

> default: '/'

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

## 鸣谢

* [Bi Sheng](https://github.com/benjycui/bisheng)

## License

MIT