Writer's Guide
Folder structureโ
.
โโโ components
โ โโโ index.js (exports all components)
โโโ docs (most of your work happens here!)
โ โโโ _templates (templates for specific topic types)
โ โ โโโ tutorial.mdx
โ โโโ category
โ โ โโโ _category.yml_ (a category configuration file)
โ โ โโโ topic1.mdx
โ โ โโโ topic2.mdx
โ โโโ intro.mdx (the documentation "home page")
โโโ src
โ โโโ css
โ โ โโโ custom.css (custom styles)
โ โโโ pages (general / non-docs pages)
โ โโโ writers-guide.mdx (accessible at /writers-guide, you are here :P)
โโโ static (contents served directly under the base url
โ โโโ img (images)
โ โโโ drawio-diagrams (images that contain DrawIO metadata)
โ โโโ excalidraw-diagrams (same as DrawIO, but for Excalidraw)
โ โโโ logo.svg (the Server State logo)
โโโ docusaurus.config.js (configures the page in general)
Templates
The _templates
folder contains templates for all commonly used page types of
the documentation.
All templates, aside from laying down a general structure that you have to fill in, contain a few things to get you started:
- Guidelines for when to use the template
- Relevant component imports and copy/pastable snippets that might be useful for the topic
- Writing tips for the type of content the topic is for
To use a template within VSCode, simply Ctrl+Drag it into the relevant folder, rename it, and adjust it to your liking:

General Writing Guidelinesโ
- Write in the present tense
- Use neutral pronouns (they/them instead of he/she and him/her)
- Be respectful to everyone
- Be aware of the potential for cultural misunderstandings
Docusaurus Markdown Componentsโ
Docusaurus provides a bunch of additional functionality within our Markdown documentation.
For all details, please refer to their excellent documentation:
Docusuarus Docs regarding Mardkown ยปhttps://docusaurus.io/docs/markdown-featuresAdditionally, we'll describe essential elements here, as well:
Code Blocksโ
Code:โ
```java title='MyClass.java' {3}
class MyClass {
MyClass(String message) {
System.out.println(message);
}
}
```
Result:โ
class MyClass {
MyClass(String message) {
System.out.println(message);
}
}
Admonitionsโ
Code:โ
:::note Optional Title
Content
:::
:::tip Optional Title
Content
:::
:::info Optional Title
Content
:::
:::caution Optional Title
Content
:::
:::danger Optional Title
Content
:::
Result:โ
Optional Title
Content
Optional Title
Content
Optional Title
Content
Optional Title
Content
Optional Title
Content
Custom MDX Componentsโ
Apart from the elements Docusaurus natively provides, there are also a few custom components for the Server State documentation:
<Grid />
โ
Allows to display several block elements next to each other, especially useful
in combination with <Reference />
Code:โ
import { Grid } from '/components';
<Grid cols={2}>
:::danger First note
Note content
:::
:::caution Another Note
Note content
:::
</Grid>
Result:โ
First note
Note content
Another Note
Note content
<Reference />
โ
Code:โ
import { Reference } from '/components';
<Reference to="https://docusaurus.io/docs/markdown-features">
Docusuarus Docs regarding Mardkown
</Reference>
Result:โ
Docusuarus Docs regarding Mardkown ยปhttps://docusaurus.io/docs/markdown-features<FileDownload />
โ
Code:โ
import { FileDownload } from '/components';
<FileDownload file="/img/logo.svg">XD Template</FileDownload>
Result:โ
XD Template<Image />
โ
Code:โ
import { Image } from '/components';
<Image src="/img/logo.svg" />
<Image src="/static/img/logo.svg" /> <!-- identical -->
<Image src="/img/logo.svg" alt="Server State Logo" />
<Image src="/img/logo.svg" invertible />
Propsโ
prop | description |
src: string | May include `/static` (this gets handled automatically) |
invertible: boolean = false | Whether the image may be inverted for the dark theme |
... | All other props get passed to the ` |
Result:โ
Markdown content inside MDX componentsโ
To write Markdown content inside MDX components, leave a blank line before and after your content and do not indent the content:
<MyComponent>
<MyChildComponent>
Some Markdown Content
</MyChildComponent>
</MyComponent>
Static Assets (images, videos and other files)โ
Static assets are stored within the static
folder and served at the root of
the repository, i.e., an image in static/img/logo.svg
can be referenced using
/img/logo.svg
.
Including an imageโ
Big image sizes
Images with a big file size affect the page's load time and, through that, also the search engine ranking. Therefore, when your image is bigger than 500 kB, try to reduce its size with these steps before using them:
- For diagrams and other "illustration-like" images, consider using a vector format (SVG)
- Consider what size the image has to, reasonably, be displayed at, and reduce the image's dimensions if necessary.
- Run your JPEG and PNG files through https://tinypng.com/ to reduce their file size without changing the image itself
To include an image, you can use the <Image />
component from above:
Code:โ
<Image alt="Description of the image" src="/img/logo.svg" width="200" />
Result:โ
Images and dark modeโ
If your image has no problems with being inverted (light becomes dark and vice
versa), you can set the invertible
attribute and allow the website to invert
them when users open the website in dark mode:
tip
One example of a well-supported image type is a diagram that only contains black text/shapes on a white/transparent background.
Code:โ
<Image
src="/static/img/drawio-diagrams/conventional-commits/conventional-commits-decision-table.drawio.svg"
invertible
/>
Result:โ
(switch to dark mode to see the effect)