@omtty/doc

简介

任何的项目都需要构建文档，一般我们前端的文档都是用markdown构建的，同时我们一般还要创建可以直接交互的demo，这样子会更加直观，我们在写文档的时候需要写demo事例代码，同样构建可直接交互的demo 时也要写demo事例代码，这就带来了重复的工作，为了减少工作量，我们创建了omt-doc，它可以解析markdown文档的代码块并生成可交互的demo，同时把markdown文档转化为静态网站。

整体流程

md 文档 ----> markdown 解析生成 js 对象 ----> 读取 js 对象生成网页

运行demo

进入_demo目录执行如下命令

yarn install
npm run dev

Demo 效果图

效果图

用法

yarn add @omtty/doc

添加 script 命令

{
  "dev": "omt-doc dev", // 开发模式
  "build": "omt-doc build", // 编译线上代码
  "server": "omt-doc server" // 启动server，用于线上环境
}

在项目根目录下面创建.omt.doc.js 配置文件

module.exports = {
  docEntry: {
    components: "src/components" // markdown文件目录
  },
  entry: "./site/index.js", // 网站入口文件
  outputPath: "./dist" // 输出目录
};

markdown文档编写说明

API文档整体格式如下：

文档头

文档说明

文档 API

文档头格式如下：

---

category: 文档分类，必填

title: 文档名称

sort: 排序顺序

cols: 文档样例显示列数，默认为2

---

上面这些为默认提供的头属性，用户可以自定义属性值

文档说明:

文档说明可以为任意的 markdown

文档 API：

API 文档必须是如下格式：

## API

你的文档在这里

Demo 文档整体格式如下：

Demo 头

Demo 说明

Demo 代码块

Demo 头格式如下：

---

title: Demo名称

sort: 排序顺序

---

上面这些为默认提供的头属性，用户可以自定义属性值

Demo 说明:

Demo 说明可以为任意的 markdown

Demo 代码块

Demo 代码块必须是如下格式：

```jsx omt-doc-jsx

import React from "react";

class Demo extends React.Component { // todo }

ReactDOM.render();

```

Demo解析的代码块必须以```jsx omt-doc-jsx开头，然后以```结束

文档

.omt.doc.js 是 omt-doc 的配置文件，需要放在项目的根目录下面

名称	描述	类型	默认值
entry	项目入口	string | array	必填
outputPath	项目输出目录	string	dist
appSrc	项目存放代码的目录	string	src
appPublic	项目的公共资源目录	string	public
disableCssModules	是否禁用css modules功能	boolean	false, 默认开启css modules
publicPath	获取chunk资源的根目录，必须以/结尾，这里可以为URL地址，如果指定了一个错误的值，则在加载这些资源时会收到 404 错误	string	/
externals	防止将某些 import 的包(package)打包到 bundle 中，而是在运行时(runtime)再去从外部获取这些扩展依赖，点击这里查看更多	string array object function regex	选填
resolveAlias	创建 import 或 require 的别名，来确保模块引入变得更简单具体查看这里	object	选填
extraResolveExtensions	自动解析确定的扩展	array	选填
extraBabelPresets	babel-loader的options.presets具体查看这里	array	选填
extraBabelPlugins	babel-loader的options.plugins具体查看这里	array	选填
extraModuleRules	创建模块时，匹配请求的规则数组。这些规则能够修改模块的创建方式，具体查看这里	array	选填
extraJsLoaders	额外的js和jsx loader	string object	选填
extraTsLoaders	额外的ts和tsx loader	string object	选填
lessModifyVars	less modify vars	object	选填
docEntry	md文档入口文件	object	必填
server	参考devServer	object	选填

其他配置和omt-webpack的配置一致

.omt.doc.js 配置样例

const path = require("path");
const compression = require("compression");
const CleanWebpackPlugin = require("clean-webpack-plugin");

module.exports = {
  docEntry: {
    components: "./components"
  },
  entry: "index.js",
  appSrc: "src",
  appPublic: "public",
  outputPath: "./dist",
  resolveAlias: {
  },
  extraTsLoaders: [
    {
      loader: require.resolve("react-docgen-typescript-loader"),
      options: {
        docgenCollectionName: "DJ_REACT_CLASSES"
      }
    }
  ],
  extraBabelPlugins: [
    "transform-runtime",
    [
      "import",
      [
        {
          libraryName: "antd",
          style: true
        }
      ]
    ],
    "transform-decorators-legacy"
  ],
  devServer: {
    port: 8000,
    index: "public/index.html",
    before: app => {
      //添加你的中间件
    }
  },
  server: {
    port: 8000,
    index: "public/index.html",
    before: app => {
      app.use(compression());
    }
  },
  disableCssModules: true,
  lessModifyVars: {
    "font-size-base": "12px"
  },
  extraPlugins: [new CleanWebpackPlugin()]
};