--- 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 ---