Skip to main content
Version: 1.0

How to Proceed

🛠️ Building with Docusaurus: Technical Core​

Essential part of your new website will likely be new content. Below you find general hints that can help you to create the content, to format and to structure it.

Docusaurus gives you the power of Markdown for speed and React.js for unlimited flexibility. This guide gives a rough overview when to use each of them.

1. Markdown vs. React.js: When to use what?​

  • Markdown (.md): Best for 90% of your content. Use it for tutorials, manuals, and blog posts. It’s fast, readable, and standard.
  • React.js (.tsx): Use it for "Interactive" pages like your Homepage, sophisticated dashboards, or complex landing pages. It allows you to build custom UI components that Markdown cannot handle.

Both options are the base for the documents Docusaurus is "building" the static HTML-pages from.

2. Quick Intro into Markdown (.md)​

Some very basic markdown notation:

# Level 1 Header
## Level 2 Header
### Level 3 Header
#### Level 4 Header
##### Level 5 Header
###### Level 6 Header

**Bold Text**
*Inverse Text**
***Bold Inverse Text***
~~strike through~~

> Blockquoted Text
> second line of Blockquoted Text
>> Nested: Blockquoted Text
>> Nested: second line of Blockquoted Text

‎```
first line of a code block
second line of a code block
I used a hack to make the markdown for this code-block visible,
So copy and paste might not work as intended, because I added an invisble
character before the 3 backticks ``` above and below this block.
‎```

Horizontal line:
---

Lists:

- a list item (unordered list)
- another list item (unordered list)
  - Nested: a list item (unordered list)
  - Nested: another list item (unordered list)
- one more list item (unordered list)

1. a list item (ordered / numbered list)
2. another list item (ordered / numbered list)
  - Nested: a list item (unordered list)
  - Nested: another list item (unordered list)
3. one more list item (ordered / numbered list)
  1. Nested: a list item (ordered / numbered list)
  2. Nested: another list item (ordered / numbered list)


[Some Link Text](https://...)

Image:
![image alt-text](/assets/img/123.png)

Image with title:
![image alt-text](/assets/img/123.png "the title text")

Linked Image:
[![image alt-text](/assets/img/123.png)](https://...)

A Table:
| A Table Header column | Another Table Header Column |
| --------------------- | --------------------------- |
| Some column content   | Some column content         |
| Some column content   | Some column content         |
|                       | with line break             |
| Some column content   | Some column content         |
| with line break       |                             |
| Some column content   | Some column content         |

There are many more options to use markdown, detailed guides you can find in the list below. Reading the guides will show you also, how to nest different elements.

Special Tip

Important is that the first list-item below is leading to the Docussaurus Manual, and Docusaurus supports some enrichments for Markdown which are not possible with common Markdown.

Note, that many elements can be formatted in different ways, as markdown is intentionally not very strict about the syntax. Concerning the Markdown on this website it's best practice though to follow the Docusaurus Manual in doubt, for best rendering results.

3. Intro into Front-Matter​

Front-matter is the "Brain" of your Markdown file, you can use it, to give fundamental instructions, how files and folders are treated and which URL will show them.

Front-matter must be at the very top of the file between two sets of triple dashes (---). While this primarily refers to markdown-files, folders can get a special file to give file-independent instructions.

Info

The API documentation of each official plugin lists the supported attributes:

Let's start with front-matter for simple files:

---
id: intro
title: Getting Started
sidebar_position: 1
slug: /welcome
---

It tells Docusaurus how to label the page, where it sits in the sidebar, and what its URL should be. This example is already relatively deterministic, simpler is possible:

---
title: Intro
sidebar_position: 1
---

or just this:

---
sidebar_position: 1
---

For more Details, please follow the documentation, linked in the info-box above.

More about Docusaurus​

There is already some slight overlap with the Docusaurus documentation, for the more easy things you can read the beginner's tutorial on this site for more advanced info you can follow the links mentioned here