Skip to main content

Writer's Guide

Folder structure

telestion-docs
.
├── 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:

Docusuarus Docs regarding Mardkown »https://docusaurus.io/docs/markdown-features

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:

MyClass.java
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 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:

topic.mdx
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:

topic.mdx
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="Telestion Logo" />
<Image src="/img/logo.svg" invertible />

Props

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

Result:

Link to Link to Link to Telestion LogoTelestion LogoLink to

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

Big image sizes

Images with a big file size affect the page's load time and, through that, also the search engine ranking. Thus, when your image is bigger than 500 kB, try to reduce its size with these steps before using them:

  1. For diagrams and other "illustration-like" images, consider using a vector format (SVG)
  2. Consider what size the image, reasonably, gets displayed at, and reduce the image's dimensions if necessary.
  3. 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:

Code:

<Image alt="Description of the image" src="/img/logo.svg" width="200" />

Result:

Link to Description of the imageDescription of the image

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:

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:

Link to

(switch to dark mode to see the effect)