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 Telestion logo)
└── docusaurus.config.js (configures the page in general)

Templates

The docs/_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 couple of things to get you started:

1. Guidelines for when to use the template
2. Relevant component imports and copy-/paste-able snippets that might be useful for the topic
3. Writing tips for the kind of content the topic is for

To use a template within VSCode, hold the Ctrl key and drag it into the relevant folder, rename it, and adjust it to your liking:

Link to

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 supplementary features within Markdown documentation.

For all details, please refer to their excellent documentation:

Below, you can see a quick overview of these features, 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:​

Custom MDX Components​

Apart from the elements Docusaurus natively provides, there are also some custom components for the Telestion documentation:

<Grid />​

Allows you to display several block elements next to each other, most 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:​

<Reference />​

Code:​

import { Reference } from '/components';

<Reference to="https://docusaurus.io/docs/markdown-features">
    Docusuarus Docs regarding Mardkown
</Reference>

Result:​

<FileDownload />​

Code:​

import { FileDownload } from '/components';

<FileDownload file="/img/logo.svg">XD Template</FileDownload>

Result:​

<Image />​

Code:​

import { Image } from '/components';

<Image src="/img/logo.svg" />
<Image src="/static/img/logo.svg" /> <!-- identical -->

<Image src="/img/logo.svg" alt="Telestion Logo" />
<Image src="/img/logo.svg" invertible />

Props​

prop	description
src: string	url of the image. Must not include base url (/telestion-docs). May include `/static` (this gets handled automatically)
invertible: boolean = false	Whether to invert the image for the dark theme
...	All other props get passed to the `` element itself without modification.

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

This repository stores static assets within the static folder which get served at the root of the page. You can refer to an image in static/img/logo.svg with /img/logo.svg.

Including an image​

To include an image, you can use the <Image /> component:

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 when viewed with inverted colors (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:

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)