I am participating in the 2022 Spring Recruitment series of activities – project experience review, click to view the details of the activity.

AntDesign UI component library, in addition to its own perfect function, good documentation support, is also a big reason why developers are happy to use.

What is the title, antDesign-like component library document written in? (Note that we are talking about document writing, not the components themselves) 😜

So we have to define here, what are the necessary elements for the document that we want?

  • Rendering of real components, interactive, preferably directly copied code
  • Support the markdown
  • Lists all the attributes (apis) of the component, including type, description, default values, and so on

According to this goal, the existing relevant frameworks on the market are as follows:

  • dumi
  • storybook
  • gitbook
  • vuepress
  • docsify

Given dumi and AntDesign’s React development and ant background, this time we’ll take a look at Dumi and see if we can achieve what we want.

The article is longer, it is suggested to like and collect first. 🤣

0, some pre-knowledge you may need (don’t point, you can come back to 🤣 when you use it)

  • Dumi website
  • AntDesign component documentation

1. Initialization

Starting from scratch, let’s initialize a Dumi project called my-Dumi-doc

mkdir my-dumi-doc && cd my-dumi-doc

yarn create @umijs/dumi-lib --site

yarn
Copy the code

Note that the Node version must be 10.13 or later. If the installation fails, switch node versions.

Run and see

yarn start
Copy the code

Home page:

Details page:

At this point, we have seen the prototype of a component document. Next you need to take a closer look at the directory structure.

In the SRC directory, component by component, default examples are generated

  • Md document (index.md)
  • Component source code (index.tsx)
  • Test file (index.test.tsx)

Those of you who have written components know that this directory structure is basically standard. But since we are focusing on documentation this time, we could have just kept the MD document.

As you can see above, the JSX and TSX code blocks in the MD document will be parsed by Dumi into React components. This brings us to the first point: rendering the actual components. 👍

2. Directory structure and routing

Let’s write two more components under SRC to see what the document looks like in the browser.

Create MyButton/index.md, MyModa/index.md,

As follows:

<! -- /src/MyButton/index.md --> ## MyButtonCopy the code
<! -- /src/MyModal/index.md --> ## MyModalCopy the code

Refresh the browser as follows:

You can see it. The navigation bar is up right now.

However, a component that takes up one level of navigation is not what we want. We use FrontMAtter syntax to make the following adjustments:

<! -- /src/MyButton/index.md --> --- nav: title: Components path: /components group: title: MyButton --- ## MyButtonCopy the code
<! -- /src/MyModal/index.md --> --- nav: title: Components path: /components group: title: MyModal --- ## MyModalCopy the code

Refresh the browser and see, well, that’s what we want.

The FrontMAtter syntax is mentioned above, and the documentation is here: d.umijs.org/zh-CN/confi…

Next, we need to simply provide the source of MyButton, MyModel two components, try to introduce in the MD document to try.

3. Complete components

Since component writing is not the focus, here we introduce Antd to inherit the Button and Modal components provided by it respectively, and quickly improve the source code.

Install Antd

yarn add antd
Copy the code

Create a new MyButton/index.tsx with the following contents:

import React from 'react'; import { Button, ButtonProps } from 'antd'; import 'antd/dist/antd.css'; export interface MyButtonProps extends ButtonProps { isMy? : boolean; } const MyButton: React.FC<MyButtonProps> = (props) => { const { children, ... restProps } = props; return ( <Button {... restProps}>{children}</Button> ); } export default MyButton;Copy the code

As you can see, we simply wrapped the Button component with an isMy attribute.

Next, introduce and use it in/SRC /MyButton/index.md.

Oops, it’s textured directly above, code block inside code block seems to display a problem. There’s the warehouse address at the end of the article. Check it out. 🤡

/ SRC /index.ts/SRC /index.ts/SRC /index.ts / SRC /index.ts is the entry file for the component.

export { default as MyButton } from './MyButton';
Copy the code

Go back to your browser and you should see the screen below.

Antd’s own Button component, has been rendered on the page, can also be normal interaction.

So in response, let’s perfect MyModal.

Create a new MyModal/index.tsx with the following content:

import React from 'react'; import { Modal, ModalProps } from 'antd'; import 'antd/dist/antd.css'; export interface MyModalProps extends ModalProps { isMy? : boolean; } const MyModal: React.FC<MyModalProps> = (props) => { const { children, ... restProps } = props; return ( <Modal {... restProps}>{children}</Modal> ); } export default MyModal;Copy the code

Introduce and use it in/SRC /MyModal/index.md

Back in the browser, Modal should be rendered as well.

Click events can also be responded to correctly.

At this point, the first two necessary elements that we initially defined have been implemented. Next comes the writing of the component API.

4. API generation

Md is already supported, and a little bit of manual writing with table syntax will do the trick.

| Name | Description | Type | Default | | -- - | -- -- -- -- -- -- -- -- -- -- -- -- - | -- -- -- -- -- -- -- -- - | -- -- -- -- -- -- -- -- - | | isMy | | custom attributes Boolean | - | |... |... |... |... |Copy the code

But that’s not what we want.

If your component follows TypeScript type definitions + JS Doc annotations, Dumi can deduce the CONTENT of the API itself.

Reference documents: d.umijs.org/zh-CN/guide…

We appended dumi’s built-in component API to the end of the MD file to render the API table.

<API></API>
Copy the code

Here’s what it looks like. It looks pretty good. Description, type, etc., have been automatically filled in for us.

Learn from the JS Doc annotations and improve the isMy attribute that we added only

Go back to the browser and refresh the page, and you can see the effect immediately, which is really convenient.

At this point, we have all three elements of the component documentation we want. Dumi is convenient in document writing, please try more.

The training project has also been uploaded to Github, see here: my-Dumi-doc

Finally, the original is not easy, welcome to wave like, comment, attention, collection.