文檔到處寫好麻煩
文檔管理是個比較繁瑣的事情，如果文檔和代碼是分離的，代碼更新了還要到對應的文檔的地方做更改，很難讓人持之以恒。
有沒有一個方式是只需要在代碼的地方寫好注釋，然后自動生成可交互的文檔呢？
用 React Styleguidist 可以做到，但是配置比較繁瑣，而且也沒有中文支持，對中文用戶來說很難。
開始吧
- 安裝依賴
這里使用了 webpack-blocks, 畢竟不是每個項目都會有 webpack 配置
# 最好裝一個 npx
npm i npx -g
# 然后安裝
yarn add webpack react-styleguidist webpack-blocks --dev
- 在項目根目錄創(chuàng)建 styleguide.config.js
const { createConfig, babel, postcss } = require('webpack-blocks')
module.exports = {
webpackConfig: createConfig([babel(), postcss()]),
components: 'src/core/**/**.js' // 寫入對應目錄的文檔
}
- 啟動文檔開發(fā)模式
npx styleguidist server
# 這里是 build
npx styleguidist build
就好了，React Styleguidist 很強，會自動找所有的 src//.js 的注釋，對應的文件，然后生成一份文檔。
自定義樣式
官方推薦在 styleguide.config.js 中寫 style，并且用 React devtool 查找對應的節(jié)點，覆蓋原有樣式。
我覺得這樣的設計糟糕透了
- 寫到配置文件中不能實時查看樣式，需要重啟服務才可以看到修改結果，簡直智障
- 很費勁去尋找那個樣式 react 的組件
那其實可以換一個想法，新增一個 scss 文件，使用 css 選擇器 + !important 方式去覆蓋，在 styleguide.config.js 中配置 require 參數(shù)。
module.exports = {
...yourConfig,
// styleguide/style.scss 自行創(chuàng)建
require: path.join(__dirname, 'styleguide/style.scss'),
}
# 例如修改 sidebar 的背景顏色
[class^=rsg--sidebar] {
background-color: #fefefe !important;
}
自定義入口 index.html 入口模版
這又是另一個智障的設計，不支持通過文件模版的方式引用，只能使用 styleguide.config.js 中的 template 字段來自定義模版，而且寫法太難受了，我只想加入 loading 畫面以及飲用 icon 或者其它三方庫，需要如下寫法
module.exports = {
...yourConfig,
template: ({}) => `<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>${title}</title>
${generateCSSReferences(css, publicPath)}
<link rel="stylesheet" href="./resource/loading.css">
</head>
<body>
<div id="rsg-root"></div>
<div class="sk-folding-cube" id="loadingBg">
<div class="sk-cube1 sk-cube"></div>
<div class="sk-cube2 sk-cube"></div>
<div class="sk-cube4 sk-cube"></div>
<div class="sk-cube3 sk-cube"></div>
</div>
${generateJSReferences(js, publicPath)}
</body>
</html>
<link rel="stylesheet" integrity="sha384-mzrmE5qonljUremFsqc01SB46JvROS7bZs3IO2EmfFsd15uHvIt+Y8vEf7N7fWAU" crossorigin="anonymous">
`
}
總結
同類型的 style guide 也有不少，不過 react styleguidist 相對完善一些
Ukelli-UI 便是基于此方式來編寫文檔，雖然有些傻，但是還能接受，用 markdown 的方式來寫例子，更好維護和查看了
