--- title: Writing Docs category: Contributing order: 7 --- # How To Write Docs This page documents how to add and maintain documentation. ## Overview The documentation site is generated from the **source code** and the `.md` files. There are two types of `.md` files: `README.md` and `named-md-files.md`, under the `docs folder`. The **source code** is parsed with the [TypeScript compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) with the exception of React components, which are parsed by [react-docgen](https://react-docgen.dev/). These tools parse out JSDoc comments, type information of React component props and types for functions. ## Utility functions These are in the "utilities" menu in the left navigation bar. Their JSDoc needs to be above an exported function and needs to have a `@module` annotation to be included in the docs. Our parser can handle 1 export/file. No need to define types in JSDoc, they will be parsed from the function itself. The gray-matter YAML defines meta information like which part of the side navigation this will be in (`category`). ```typescript --- type: code --- /** * --- * category: utilities/a11y * --- * @module * Documentation goes here * @param p1 the param */ function myFunc(p1: int) {} export {myFunc} ``` ## Markdown files The docs can be written in `markdown`, with some added flavor, so the docs can handle special code-display cases. ### Special Markdown Rules The only special markdown part is the `codeblock`. It can be displayed in several different ways. #### 1. code If a code example is needed with syntax highlighting: ````md --- type: code --- ```js --- type: code --- console.log("my js example comes here") ``` ```` The above code will display like this: ```js --- type: code --- console.log("my js example comes here") ``` Most common languages can be used for syntax highlight, such as `jsx`, `bash` or `md` #### 2. embed The `type: embed` will render the containing code into the page. It must be valid `javascript` ````md --- type: code --- ```js --- type: embed --- ``` ```` The above code will display like this: ```jsx --- type: embed --- ``` **_Note:_** you can use any instUI components in the examples #### 3. example The most complex type is the `type: example`. It will render as the `embed` did, but it also provides access to the code, which is editable and the changes reflect on the rendered view immediately. There are two ways these examples can be written. In the first example, a valid `ReactNode` is enough and the docs system will take care of the rendering. In the second example, a whole `component` is needed and it must be `rendered` with the built in `render` method at the very end of the example ##### Example for ReactNode ````md --- type: code --- ```js --- type: example ---
} margin="0 small 0 0" /> } shape="rectangle" />
``` ```` The above code will display like this: ```js --- type: example ---
} margin="0 small 0 0" /> } shape="rectangle" />
``` ##### Example for Component ````md --- type: code --- ```js --- type: example --- const Example = () => { const [selected, setSelected] = useState("") const [colors] = useState([ "#ffffff", "#0CBF94", "#0C89BF00", "#BF0C6D", "#BF8D0C", "#ff0000", "#576A66", "#35423A", "#35423F", ]) return (
setSelected(selected)} />
) } render() ``` ```` The above code will display like this: ```js --- type: example --- const Example = () => { const [selected, setSelected] = useState("") const [colors] = useState([ "#ffffff", "#0CBF94", "#0C89BF00", "#BF0C6D", "#BF8D0C", "#ff0000", "#576A66", "#35423A", "#35423F", ]) return (
setSelected(selected)} />
) } render() ``` **_Note:_** you should use `funcional React`. ### Purely documentation files Under the docs folder, there are additional folders, which are containing `.md` files, which are for general documentation. These need a `frontmatter`: ```md --- type: code --- --- title: Writing Docs category: Contributor Guides order: 6 --- ``` The `title` will be used as the name of the menuitem in the docs page. The `order` will determine the order under the `category` it's placed The `category` is the category under which the doc will be palced in the menu tree. If you want to add another `category`, you have to register it in two places: `packages/__docs__/src/Search/index.tsx` for the search function to work and `packages/__docs__/src/Nav/index.tsx` to determine the order of the categories ## Additional information These are automatically generated parts of the documentation, such as: - Table of content - Properties - Default Theme Variables - Usage