功能特性：
- 零配置、简单易用
- 高效、支持热加载和代码分割
- 易于定制
- 基于
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
即可启动服务器。
添加.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;
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 = ({ kind, ...props }) => (
Alert.mdx
---
name: Alert // 左侧导航显示标题
---
import { Playground, Props } from 'docz';
import { Alert } from './Alert';
# Alert
## 效果
这是提示性文字
## 属性
运行效果：
mdx.png
自定义配置
支持Typescript
只需要在doczrc.js中配置typescript:true即可。
doczrc.js
export default {
title: 'sinoui-docs', //网页页签标题
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版本中已经弃用，可使用下面的方式替换：
- 首先在根目录下添加
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' //指定站点主题下的主色调
}
}
}
此外还能支持直接对标签元素的样式定制
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属性已经移除，如果我们想要使用自定义的主题，可以在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) => 支持自定义应用程序包装器（根节点组件）
我们在写文档时，由于组件使用styled-components，所以必须提供统一的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 {props.children} ;
}
doczrc.js
export default {
wrapper: 'src/wrapper',
}
这样我们在写使用场景时就不用每次都写一遍ThemeProvider了。
但是V2版本中wrapper属性也已经移除，新的处理方式如下：
在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 (
{children}
);
};
支持自定义渲染模板
模板替换属性
indexHtml只在V1中有作用，V2版本已不支持此特性。
docz默认渲染模板在移动端使用时，连击会导致屏幕自动放大，为了禁止这种行为，我们可以指定一个渲染模板替换默认模板。
index.html
{{ title }}
{{ head }}
{{ footer }}
doczrc.js
export default {
indexHtml: "index.html"
};
参考文档：docz