The Godot Barn ~ Help / Markdown

# Markdown explained
The Godot Barn uses markdown for all formatting. In addition to regular/classic markdown, you also have the ability to use special blocks and extra options. All supported blocks, features and how to use them are explained below.

Markdown is regular text, enhanced with intuitive symbols that allows formatting. To format text, you use formatting symbols to make text **bold**, _italic_ or **_bold and italic_**. In addition, you can ==mark words== in ==yellow==, ==green=={.green}, ==blue=={.blue} or ==red=={.red} and even ~~strike out~~ words.

::: hint Code examples
Throughout this guide, code examples will show you how to achieve the explained effect. For instance, the code example to write the paragraph above will look like this:
```md
Markdown is regular text, enhanced with intuitive symbols that allows formatting using **bold**, _italic_ or **_bold and italic_**. In addition, you can ==mark words== in ==yellow==, ==green=={.green}, ==blue=={.blue} or ==red=={.red} and even ~~strike out~~ words.
```

Many code examples are shown in the text that explains it, using `highlighted text` to show you what to type.
:::

In markdown, text is split into paragraphs by adding a blank line.

You can also add single new lines of text within the same paragraph by simply adding it
on a new line. However, multiple blank lines will still only add one blank space between paragraphs.

# Emojis :wink:
You can use any emojis you like by simply adding them to the text. In addition, you can use emoji short-codes if you don't have that emoji available. For instance, if you write `:smile:` in your text, it becomes :smile: when shown.

# Quotes
You can create a quoted block by adding a `>` at the start of one or more lines:
```md
> This is a one line quote

> This quote spans
> three lines.
> It ends here.
```
> This is a one line quote

> This quote spans
> three lines.
> It ends here.

# Headers
It's very common to structure content in sections, separated by headers. You can add headers and sub-headers by prefixing them with one or more `#`, depending on the level:
```md
# This is a big header
## This is a sub-header (level 2)
### This is a level 3 header
#### This is a level 4 header
##### This is a level 5 header
###### This is a level 6 header
```

You can also make certain headers stand out by making them block headers. You do this by adding a `{.block}` attribute at the end:
```md
## This header will be a block header{.block}
```

# Attributes
You can enhance some parts of the page using attributes. Attributes lets you add custom class names or identifiers to specific parts of the text. For instance, adding `{.block}` at the end of a header as explained above adds the `block` class to the header, which makes it stand out. Other supported attributes are identifiers `{#my-identifier}` which is explained in the next section.

If you need to combine several attributes (for instance an identifier and a block), you just add them both inside the same attribute list, separated by a space:
```md
## This is a block header with an identifier{.block #my-block-header}
```

## Table of contents
When formatting your content using headers, a table of contents will automatically be generated from headers with level 1 or level 2. This table of contents will be shown in the right sidebar, as you can see on this page.

# Links
Most links in your text are auto-detected - for instance, typing `https://www.google.com` will automatically turn it into the link https://www.google.com which the user can click. Sometimes you probably want to show a different text to the user than the actual link. This is achieved with a link syntax such as this:
```md
[The text that the user sees](https://www.google.com)
```
The example above will show up as [The text that the user sees](https://www.google.com), but the link will still point to https://www.google.com

## Linking to other parts of the page
If you have a long page, you may want to add a link straight to a different part of your page. You can link to a point anywhere on the page by placing an _identifier_ and then adding a link to that identifier. Identifiers are created by placing an identifier mark: `{#name-of-identifier}` anywhere after a special element. For example, if you want to link to a section of the page with a header, you add an identifier after the header:
```md
## My header{#my-header}
```
and then add a link to to that identifier anywhere you like:
```md
[Clicking this link goes straight to the header](#my-header)
```

## Youtube and Twitch links
Lots of Godot content is available on YouTube and Twitch. To make these links stand out, you can *prefix* the link _text_ with `youtube:` or `twitch:` - this will turn the link into a special-formatted video-link. This also lets you specify the author, which makes the link stand out even more:
```md
https://www.youtube.com/watch?v=dQw4w9WgXcQ
[An inspiring YouTube video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[youtube:An inspiring YouTube video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[youtube:An inspiring YouTube video](https://www.youtube.com/watch?v=dQw4w9WgXcQ){data-author="Rick Astley"}

https://www.twitch.tv/videos/1110069047
[An inspiring Twitch video](https://www.twitch.tv/videos/1110069047)
[twitch:An inspiring Twitch video](https://www.twitch.tv/videos/1110069047)
[twitch:An inspiring Twitch video](https://www.twitch.tv/videos/1110069047){data-author="Rick Astley"}
```
https://www.youtube.com/watch?v=dQw4w9WgXcQ
[An inspiring Music video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[youtube:An inspiring Music video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[youtube:An inspiring Music video](https://www.youtube.com/watch?v=dQw4w9WgXcQ){data-author="Rick Astley"}

> [!IMPORTANT]
> Enhanced links only work when you use the markdown syntax *and* prefix your link _text_ with `youtube:` or `twitch:` as shown in the example above. Plain links without the markdown syntax will only show up as normal links.

# Embedding videos
You can embed videos directly into your content by using the special `video:` prefix in your link text, similar to how you embed a Youtube video or Twitch video (see the example above).

To embed a video, simply add the `video:` prefix to your link text, like this:
```md
[video:My video](https://example.com/video.mp4)
```

# Lists
You can create both non-ordered and ordered lists by simply placing a `*` at the start of a line, or the number followed by a dot:
```md
* List item one
* Item two
* The third item

1. The first item
2. The second item
3. The third item
```
* List item one
* Item two
* The third item

1. The first item
2. The second item
3. The third item

# Images
You can link to any image by using an image link:
```md
![Image description](https://link.to/image.jpg)
```
The `Image description` in the example above will show up as helper text for people who are using screen readers.

You can always drag an image onto any markdown text to upload the image and insert it automatically. When writing content, the image list is available in the right-had sidebar. Clicking the *Copy markdown*{.button .secondary style="display: inline-flex;"} button copies an image link that you can add to your text.

# Code examples
You have two ways to show code examples using Markdown syntax, either inline or with code blocks.

## Inline code
Inline code examples are created by adding a `\`` on both sides of the part of the text you want to highlight as a code:
```md
In Godot you can create classes by placing the `class` keyword at the start of the line.
```
Inline code is not syntax highlighted, but shown using a monospaced coding font.

## Code blocks
For longer blocks of code, use code blocks. Code blocks are also syntax highlighted. If you don't specify a language, the code block will be highlighted as GDScript by default, but you can highlight code using most of the regular programming languages.

You create a code block by starting a line with three backticks: \`\`\`, optionally followed by the name of the language you want to use for syntax highlighting.

The code block ends with three backticks on a separate line \`\`\` (without any language indicator):

````
```
# This code block is highlighted with a GDScript syntax highlighter.
class AnswerButton
extends Button

@export var answer: String = ''
```
````

````csharp
```csharp
# This code block is highlighted with a C# syntax highlighter.
public void AnswerButton(string answer)
{
    GD.Print(answer);
}
```
````

> [!NOTE]
> When the code block is shown on the page, the backticks are removed - they are only visible here to show you how to use them.

> [!TIP]
> The syntax highlighter is using [HighlightJS](https://highlightjs.org) which supports many different languages in addition to *GDScript* and *C#*
> You can see the full list here: [HighlightJS - examples](https://highlightjs.org/examples)

# Tables
To create a table use a vertical line `|` to separate each column, and use three or more dashes `---` to separate headers from the content. Add a vertical line `|` at both ends of the row:
```md
| Game console  | Release date      |
| ------------- | ----------------- |
| Wii U         | November 12, 2012 |
| Playstation 4 | November 15, 2013 |
| Xbox One      | November 22, 2013 |
```
This will create a table looking like this:
| Game console  | Release date      |
| ------------- | ----------------- |
| Wii U         | November 12, 2012 |
| Playstation 4 | November 15, 2013 |
| Xbox One      | November 22, 2013 |

> [!TIP]
> You don't have to align the width of the table characters as shown in the example above. The only thing that matters is that the `|` characters are present between the columns and at the beginng and end of each row.

> [!NOTE]
> You can use basic formatting for text in tables such as links, emphasis, and inline code (not code blocks).
> Advanced code blocks or text that is split across multiple lines are not supported in tables.

## Table cell alignment
You can specify how to align the content of the cells in a column by adding a colon `:` to the left, right, or on both side of the dashes `---` in the header separator:

```md
| Game console  | Release date      |
| :------------ | ----------------: |
| Wii U         | November 12, 2012 |
| Playstation 4 | November 15, 2013 |
| Xbox One      | November 22, 2013 |
```
| Game console  | Release date      |
| :------------ | ----------------: |
| Wii U         | November 12, 2012 |
| Playstation 4 | November 15, 2013 |
| Xbox One      | November 22, 2013 |

`:--` left aligns the content in the column, `--:` right aligns the content and `:-:` centers the content in that column.

# Info boxes
You can create info boxes to show important or useful information as well as tips and tricks.

## Github info box syntax
The Godot Barn supports the Github markdown syntax to create simple info boxes. The info boxes can contain simple text formatting as explained in the first paragraph, but cannot contain block content such as code block or other multi-line elements.

The Github syntax allows you to create helpful info boxes in either of the five variants available: `NOTE`, `TIP`, `IMPORTANT`, `WARNING` or `CAUTION`. The syntax to create them are identical, and the keyword used defines the style of the info box:
```md
> [!NOTE]
> A useful note about the content

> [!TIP]
> Tips about things that matter

> [!IMPORTANT]
> Something that is more important than just an information block

> [!WARNING]
> Warning the user about something important.

> [!CAUTION]
> More than a warning
```
> [!NOTE]
> A useful note about the content

> [!TIP]
> Tips about things that matter

> [!IMPORTANT]
> Something that is more important than just an information block

> [!WARNING]
> Warning the user about something important.

> [!CAUTION]
> More than a warning

## Enhanced info box syntax
Sometimes you may want to show more advanced content, including list or block elements in your info boxes. When this is the case, you use the enhanced info box syntax. The enhanced info box syntax comes in three variants (keywords), which specifies their styling: `hint`, `warning` and `error`.

The enhanced info box variants lets you specify a title - if you don't specify one, they will default to the keywords you used. The optional title is placed on the first line (after the keyword), and the content is placed between the first line but before the closing line (a single line with `:::` or `!!!` at the start, depending on the variant).
````md
::: hint
This is an info box in the hint style, without a custom title. It can contain code examples:
```gdscript
class AnswerButton
extends Button
```
:::

::: hint My custom hint box
This is an info box in the hint style, with a custom title.
:::
````

::: hint
This is an info box in the hint style, without a custom title. It can contain code examples:
```gdscript
class AnswerButton
extends Button
```
:::

::: hint My custom hint box
This is an info box in the hint style, with a custom title.
:::

The warning and error variants use three `!!!` as their starting characters, followed by either `warning` or `error`. End the info box with `!!!` on a separate line.
```md
!!! warning
This is a warning.

It has two paragraphs
!!!

!!! error This is a custom error box
It has two paragraphs as well.

This is the second paragraph.
!!!
```
!!! warning
This is a warning.

It has two paragraphs
!!!

!!! error This is a custom error box
It has two paragraphs as well.

This is the second paragraph.
!!!

# Expandable guide
If you want to create an expandable guide (for example with multiple links to different content), you can use the `??? guide` syntax. Anything after the title will be collapsed by default, but can be expanded by clicking on it. End the guide by placing three `???` on a separate line:
```md
??? guide Relevant links
[An inspiring YouTube video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[An inspiring Twitch video](https://www.twitch.tv/videos/1110069047)
???
```
??? guide Relevant links
[An inspiring YouTube video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[An inspiring Twitch video](https://www.twitch.tv/videos/1110069047)
???

# Tabs
Tabs are a powerful feature which lets you group different sections and let the user choose which ones to show. A typical usecase for tabs is when you want to display different variants of a code based on which version of Godot is being used.

You create tabs by placing content inside a `::: tabs` section, before ending the tabs section with `:::` on a separate line, similar to the `::: info` box syntax. To create a tab, put `@tab` at the start of a line, followed by the title of the tab. To specify which tab that starts as the active tab, use `@tab:active`.

Here is an example of a `::: tabs` section:
```md
::: tabs
@tab:active Godot 2.x, 3.x
To enable logging in the Godot editor, go to: **Projects > Project Settings > Logging > File Logging** and check **Enable File Logging**. This will start placing logs in your project's user data folder.

@tab Godot 4.x
To enable logging in the Godot editor, go to: **Projects > Project Settings > Debug > File Logging** and check **Enable File Logging**. This will start placing logs in your project's user data folder.
:::
```
::: tabs
@tab:active Godot 2.x, 3.x
To enable logging in the Godot editor, go to: **Projects > Project Settings > Logging > File Logging** and check **Enable File Logging**. This will start placing logs in your project's user data folder.