功能特性：
- 零配置、簡單易用
- 高效、支持熱加載和代碼分割
- 易于定制
- 基于
MDX- 支持插件
- 支持Typescript
安裝
yarn add docz docz-theme-default --dev
啟動配置
package.json
{
"name": "sinoui-docs",
"version": "1.0.0",
"private": true,
"license": "MIT",
"scripts": {
"docz:dev": "docz dev",
"docz:build": "docz build",
"docz:serve": "docz build && docz serve"
},
"devDependencies": {
"docz": "latest",
"react": "^16.8.2",
"react-dom": "^16.8.2"
}
}
然后運行
yarn docz:dev
即可啟動服務(wù)器。
添加.mdx文檔
Alert.tsx
import React, { SFC } from 'react';
import styled from 'sinoui-components/styles';
export type Kind = 'info' | 'positive' | 'negative' | 'warning';
export type KindMap = Record<Kind, string>;
const kinds: KindMap = {
info: '#5352ED',
positive: '#2ED573',
negative: '#FF4757',
warning: '#FFA502',
};
export interface AlertProps {
/**
* Set this to change alert kind
* @default info
*/
kind: 'info' | 'positive' | 'negative' | 'warning';
}
const AlertStyled = styled.div`
padding: 15px 20px;
background: white;
border-radius: 3px;
color: white;
background: ${({ kind = 'info' }: AlertProps) => kinds[kind]};
`;
export const Alert: SFC<AlertProps> = ({ kind, ...props }) => (
<AlertStyled {...props} kind={kind} />
);
Alert.mdx
---
name: Alert // 左側(cè)導(dǎo)航顯示標(biāo)題
---
import { Playground, Props } from 'docz';
import { Alert } from './Alert';
# Alert
## 效果
<Playground>
<Alert kind="info">這是提示性文字</Alert>
</Playground>
## 屬性
<Props of={Alert} />
運行效果：
mdx.png
自定義配置
支持Typescript
只需要在doczrc.js中配置typescript:true即可。
doczrc.js
export default {
title: 'sinoui-docs', //網(wǎng)頁頁簽標(biāo)題
typescript: true, // 支持typescript
};
一般在支持typescript時，可能會遇到編譯問題，需要添加onCreateWebpackChain配置
doczrc.js
import { resolve } from 'path';
const srcPath = resolve(__dirname, '../packages');
const nodeModulePath = resolve(__dirname, '../node_modules');
export default {
title: 'sinoui-docs',
codeSandbox: false,
typescript: true,
onCreateWebpackChain: (config) => {
config.module
.rule('ts')
.include.add(srcPath)
.end()
.exclude.add(nodeModulePath)
.end();
return config;
},
};
但是onCreateWebpackChain屬性在V2版本中已經(jīng)棄用，可使用下面的方式替換：
- 首先在根目錄下添加
tsconfig.json文件
{
"include": ["src", "types"],
"exclude": ["node_modules"],
"compilerOptions": {
"target": "es5",
"module": "esnext",
"lib": ["dom", "esnext"],
"importHelpers": true,
"declaration": true,
"sourceMap": true,
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictPropertyInitialization": true,
"noImplicitThis": true,
"alwaysStrict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"moduleResolution": "node",
"jsx": "react",
"esModuleInterop": true,
"allowJs": false,
"baseUrl": ".",
"rootDir": "./src",
"outDir": "./build",
"resolveJsonModule": true,
"incremental": true
}
}
- 在根目錄下添加
gatsby-node.js文件
const path = require('path');
const TsconfigPaths = require('tsconfig-paths-webpack-plugin');
const tsConfigFile = path.join(__dirname, '../tsconfig.json');
exports.onCreateWebpackConfig = (args) => {
args.actions.setWebpackConfig({
resolve: {
plugins: [
new TsconfigPaths({
configFile: tsConfigFile,
}),
],
},
watchOptions: {
ignored: ['node_modules', 'dist', '.cache', 'coverage', '.docz'],
},
});
};
支持自定義站點主題(v1)
使用theme或者themeConfig指定站點主題
doczrc.js
// theme
export default {
theme: '/src/my/theme/folder', //外部theme文件
}
// themeConfig
export default {
themeConfig:{
colors:{
primary:'red' //指定站點主題下的主色調(diào)
}
}
}
此外還能支持直接對標(biāo)簽元素的樣式定制
export default {
themeConfig: {
styles: {
h1: `
font-size: 80px;
margin-bottom: 10px;
`
}
}
};
支持自定義站點主題(v2)
在V2版本中我們要確保移除docz-theme-default的依賴，可使用
yarn remove docz-theme-default 或
npm uninstall docz-theme-default
移除此依賴的主要原因是因為V2啟動了自己的Gatsby主題gatsby-theme-docz。具體使用方式如下：
由于doczrc.js中的theme屬性已經(jīng)移除，如果我們想要使用自定義的主題，可以在src下新建gatsby-theme-docz/index.js:
// src/gatsby-theme-docz/index.js
import React from 'react'
import Theme from './my-custom-theme'
export default (props) => <Theme {...props} />
支持自定義應(yīng)用程序包裝器（根節(jié)點組件）
我們在寫文檔時，由于組件使用styled-components，所以必須提供統(tǒng)一的ThemeProvider,這個給我們提供很大的便利性
wrapper.js
import React from 'react';
import defaultTheme from 'sinoui-components/styles/defaultTheme';
import { ThemeProvider } from 'sinoui-components/styles';
export default function Wrapper(props) {
return <ThemeProvider theme={defaultTheme}>{props.children}</ThemeProvider>;
}
doczrc.js
export default {
wrapper: 'src/wrapper',
}
這樣我們在寫使用場景時就不用每次都寫一遍ThemeProvider了。
但是V2版本中wrapper屬性也已經(jīng)移除，新的處理方式如下：
在src下新建gatsby-theme-docz/wrapper.js:
import React from 'react';
import { ThemeProvider } from 'styled-components';
import { defaultTheme, createTheme } from '@sinoui/theme';
import { useThemeUI } from 'theme-ui';
import lightBlue from '@sinoui/theme/colors/lightBlue';
const darkTheme = createTheme({
palette: {
type: 'dark',
primary: lightBlue,
},
});
export default ({ children }) => {
const { colorMode } = useThemeUI();
return (
<ThemeProvider theme={colorMode === 'dark' ? darkTheme : defaultTheme}>
<div>{children}</div>
</ThemeProvider>
);
};
支持自定義渲染模板
模板替換屬性
indexHtml只在V1中有作用，V2版本已不支持此特性。
docz默認(rèn)渲染模板在移動端使用時，連擊會導(dǎo)致屏幕自動放大，為了禁止這種行為，我們可以指定一個渲染模板替換默認(rèn)模板。
index.html
<!DOCTYPE html>
<html lang="{{ lang }}">
<head>
<meta charset="UTF-8" />
<meta name="description" content="{{ description }}" />
<!--設(shè)置移動端不支持連擊時的自動縮放 -->
<meta
content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0;"
name="viewport"
/>
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>{{ title }}</title>
{{ head }}
</head>
<body>
<div id="root" />
{{ footer }}
</body>
</html>
doczrc.js
export default {
indexHtml: "index.html"
};
參考文檔：docz
