Markdown Guide

A short Markdown guide for mod authors writing their package README.

A short Markdown guide for mod authors writing their package README.

Your README is what people usually read before they hit download. It's written in Markdown, which is just plain text with a few symbols that turn into formatting 🪄

This page shows you the syntax, not what it looks like once it's rendered.

To see the rendered version, paste anything from this page into the Markdown Preview tool and play around with it.

1

The basics

Headings

# Big heading
## Smaller heading
### Smaller still
#### Quite small
##### Very small
###### Way too small

Leave a space after the #. As an example #Heading will not work.

Headings are also the easiest way to break a long README into sections, so you don't need dividers everywhere.

Bold and italic

*italic*
**bold**
~~strikethrough~~

_italic_ and __bold__ work the same way. If part of your text goes italic by accident, wrap it in backticks or escape it with \.

Lists

- Wear a hat
- Shoot a fish
- Sell the fish

1. First
2. Second
3. Third

Indent by two spaces for subpoints:

- Suspicious Fishing rods
  - Paranormal wooden rod
    - Slow but cheap
  - Golden rod

Watch the line right after a list. Text written directly under the last item gets pulled into it instead of starting a new paragraph. Leave an empty line between them.

Links

For a link with your own text:

[Thunderstore](https://thunderstore.io)

To show the URL itself, paste the full address:

https://thunderstore.io

Code blocks / Code snippets

For a single word or value, use backticks:

Set `enabled = true` in the config.

For several lines, use three backticks:

```
[General]
enabled = true
fishSpeed = 2.0
```

Quotes and dividers

> Works with the latest game version.

---

A > quote block pulls a line out of the normal text, which works well for a compatibility note or a warning you don't want people to miss.

--- on its own line draws a line across the page. It's handy when you want a clean break between two parts of your README that don't need titles of their own.

If the parts do need titles, a heading does both jobs at once. # and ## split the page and label the section while they're at it, which is why most mod pages end up using headings for structure and --- only here and there.

Tables

| Setting   | Default | What it does           |
| --------- | ------- | ---------------------- |
| enabled   | true    | Turns the mod on       |
| propSpeed | 2.0     | How fast the prop moves|

That line of dashes is required. Without it you just get a wall of pipes. Lining the columns up is optional, it just makes the file easier to read while you write it.

2

Images

![A screenshot of the mod](https://example.com/screenshot.png)

Images have to be hosted somewhere public and linked with a full https:// address. Images inside your package zip won't show up, and neither will relative paths like ./images/screenshot.png.

Keep your screenshots reasonable. They get scaled to fit the page, so a 4000px file just makes the page slower to load without looking any better. Around 1000 to 1500px is plenty. Gifs can be quite heavy, so it's good to keep that in mind.

Where to host them

Use your GitHub repo. If your image host dies later, the images on your mod page break and you need to fix the image URLs.

The easy way, if your mod already has a repo:

1

Commit the image and write your README on GitHub as normal, with a relative path like ![Screenshot](screenshot.png).

2

Grab the image address, whichever way you prefer:

• Open the README on GitHub, right click the image and pick Copy image address.

  • Or open the image file in your repo, click Raw, and copy the address from your browser.

3

Paste that address into the README that ships in your package.

Imgur works too if you'd rather not use GitHub. Good to remember: it's blocked in some countries, so some people will just see nothing, and Imgur has wiped old anonymous uploads before. Uploading while logged in is recommended over uploading anonymously.

Don't use Discord links. They expire after about a day and your images disappear.

3

Line breaks, read this one

Markdown reads a single Enter as a space. These two lines:

Line one
Line two

come out as one line: Line one Line two

For a new paragraph, leave an empty line between them. To force a break inside a paragraph, end the line with two spaces.

A backslash at the end of the line does the same as two spaces, and it's a lot easier to spot later:

Line one\
Line two

Backslash also cancels formatting. \_not italic\_ shows the underscores instead of turning the text italic, which is handy for names that have them.

Long paragraphs wrap on their own, so there's no need to break lines manually.

4

Preview before you publish

We render Markdown a bit differently from GitHub, so a README that looks fine there can still look off here.

Run your finished README through the Markdown Preview tool before you upload.

5

Stuff that doesn't work

These may be common elsewhere, but here they just show up as plain text:

• Task lists, - [ ] and - [x]

• Footnotes

• Emoji shortcodes like :fih:. Paste the actual emoji instead.

• Embedded videos, iframes and audio players. Link to the video instead, or use a YouTube thumbnail as a clickable image.

• Anchor links to headings inside your README, like [Features](#features). These work on GitHub, but not here.

6

HTML, if you're into that

Basic HTML works, but only a safe list of tags. Anything outside that list, like <script>, <iframe> and <video>, shows up on your page as plain text instead of doing anything. class and style get ignored too, so you can't style things yourself.

Handy things that do work:

<details>
<summary>Full changelog</summary>

Everything in here is hidden until someone clicks it.

</details>

**Details**

<img src="https://example.com/screenshot.png" width="600">

<p align="center">Centered text</p>

Leave an empty line between the HTML tags and any Markdown inside them, like in the example above. Without it the Markdown stays as plain text. This is what usually breaks collapsible sections.

Also fine: <kbd> for keys, <sub> and <sup>, <mark> for highlights.

Not sure if something survives the filter? Test first in the preview tool.

7

A README you can copy and edit

# Mod Name

One sentence on what the mod does.

![Screenshot](https://raw.githubusercontent.com/you/yourmod/main/screenshot.png)

## Features

- Thing it does
- Other thing it does

## Configuration

| Setting   | Default | What it does           |
| --------- | ------- | ---------------------- |
| enabled   | true    | Turns the mod on       |
| propSpeed | 2.0     | How fast the prop moves|

## Known issues

- Does not work with X yet

## Credits

Thanks to whoever helped.

This guide should get you started on your Markdown journey!