How to format the document
A quick guide to formatting
Markdown
This is a quick overview of the markdown format. For more extensive documentation, there are plenty of resources like Markdown Guide or Fumadocs' markdown page.
Headings are made using hash signs, where more signs correspond to smaller and smaller sub-headings.
When writing for this documentation all headings start from ##, since the page title itself is
of the largest (#) size. Prefer creating a new page rather than dividing a single page into multiple parts using #.
## I am a big header
### I am a smaller header
#### I am a tiny header
I am not a header, i am normal text
_I am italic_
**I am bold**
**_I am both italic and bold_**
[I am a link](https://kth.it)
- I am part of a list
- Me too!
1. I am also part of a list
2. but with numbers!
> I am quoting you
```
this is a code block
```Frontmatter
The frontmatter is a block of YAML placed at the top of the file. It defines meta information about the page, such as its title.
---
title: The displayed title of the page. Differs from the file name, which is used for the URL
icon: Squirrel
description: A brief description of the page, displayed right under the title.
---Try to keep both titles and descriptions short. Descriptions should preferably not be longer than a sentence.
Icons can be a bit tricky but do not need to exist for all pages, especially subpages.
Lucide Icons
Most of the icons we use are from Lucide, for which you can see a full list of available icons here.
Icons are specified with their "component names", which are written in PascalCase.
To get it, either manually rewrite the icon ID (fish-off -> FishOff)
or click "Copy Component Name" under an icon on the listing website.
You may need to navigate through a dropdown menu to find the button.
If you are feeling extra fancy, and the situation is specific enough for it to be appropriate, you can add custom Icons.
To do so, export the icon as an SVG and place it under content/icons/.
Next, add the icon to lib/custom-icons.tsx.
- Import the icon
import YourIconNameHere from "content/icons/yourIconNameHere.svg"; - Add it to the list under "customIcons":
YourIconNameHere: YourIconNameHere,
Mermaid
To create consistent diagrams for our documentation we use Mermaid. It allows for creating consistent diagrams from plain-text using a custom syntax. You can find more detailed guides for the different diagram types on the official Mermaid Docs, but this will be a quick rundown.
Diagram restrictions
Our documentation uses the beautiful-mermaid library, which supports a core subset of all mermaid diagram types and features. This means that you can not blindly trust documentation for the main Mermaid library, so make sure to test on the docs site directly.
Mermaid diagrams can be created using special mermaid codeblocks.
```mermaid
<diagram code>
```The first step to creating a diagram is to specify the diagram type. Our documentation supports: Flowcharts, State, Sequence, Class, ER, and XY Charts. This quick guide will focus on flowcharts, as they are most vercetile. If you are interested in spending time with the other diagram types, then maybe OOD is for you!
In the case of flowcharts (or their alias graph) a direction is also expected.
This is typically left-right (LR) or top-bottom (TB).
```mermaidflowchart TD %% Defines a node with a label places[Places worth visiting] kistan %% Links it to two other nodes. They don't necessarily need to be defined before places --> kistan places --> tempan```The [] around the label is what defines the square shape.
There are tons of other shapes too.
```mermaidflowchart LR sA[ Example ] sB{{ Example }} sC( Example ) sD[( Example )] sA --- sB --- sC --- sD bA[[ Example ]] bB{ Example } bC(( Example )) bD(((Example))) bA --- bB --- bC --- bD```There's also a bunch of other fancy stuff you can do with connecting multiple nodes, using different connection styles, etc.
```mermaidflowchart TD a --> b & c --> d A -.-|labeled| B```