Docz使用总结

功能特性：

零配置、简单易用

高效、支持热加载和代码分割

易于定制

基于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<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  // 左侧导航显示标题
---

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', //网页页签标题
  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) => <Theme {...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 <ThemeProvider theme={defaultTheme}>{props.children}</ThemeProvider>;
}

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 (
    <ThemeProvider theme={colorMode === 'dark' ? darkTheme : defaultTheme}>
      <div>{children}</div>
    </ThemeProvider>
  );
};

支持自定义渲染模板

模板替换属性indexHtml只在V1中有作用，V2版本已不支持此特性。

docz默认渲染模板在移动端使用时，连击会导致屏幕自动放大，为了禁止这种行为，我们可以指定一个渲染模板替换默认模板。

index.html

<!DOCTYPE html>
<html lang="{{ lang }}">
  <head>
    <meta charset="UTF-8" />
    <meta name="description" content="{{ description }}" />
    <!--设置移动端不支持连击时的自动缩放 -->
    <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