> For the complete documentation index, see [llms.txt](https://wiki.thunderstore.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.thunderstore.io/mods/markdown-guide.md). # 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 :magic\_wand: This page shows you the syntax, not what it looks like once it's rendered. {% hint style="info" %} To see the rendered version, paste anything from this page into the [Markdown Preview tool](https://thunderstore.io/tools/markdown-preview/) and play around with it. {% endhint %} {% stepper %} {% step %} ## The basics ### Headings ```markdown # 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 ```markdown *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 ```markdown - Wear a hat - Shoot a fish - Sell the fish 1. First 2. Second 3. Third ``` Indent by two spaces for subpoints: ```markdown - 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: ```markdown [Thunderstore](https://thunderstore.io) ``` To show the URL itself, paste the full address: ```markdown https://thunderstore.io ``` ### Code blocks / Code snippets For a single word or value, use backticks: ```markdown Set `enabled = true` in the config. ``` For several lines, use three backticks: ````markdown ``` [General] enabled = true fishSpeed = 2.0 ``` ```` ### Quotes and dividers ```markdown > 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 ```markdown | 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. {% endstep %} {% step %} ## Images ```markdown ![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: {% stepper %} {% step %} Commit the image and write your README on GitHub as normal, with a relative path like `![Screenshot](screenshot.png)`. {% endstep %} {% step %} 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. {% endstep %} {% step %} Paste that address into the README that ships in your package. {% endstep %} {% endstepper %} 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. {% hint style="danger" %} **Don't use Discord links.** They expire after about a day and your images disappear. {% endhint %} {% endstep %} {% step %} ## Line breaks, read this one **Markdown reads a single Enter as a space.** These two lines: ```markdown Line one Line two ``` come out as one line: `Line one Line two` {% hint style="info" %} For a new paragraph, **leave an empty line between them**. To force a break inside a paragraph, **end the line with two spaces**. {% endhint %} A backslash at the end of the line does the same as two spaces, and it's a lot easier to spot later: ```markdown 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. {% endstep %} {% step %} ## Preview before you publish We render Markdown a bit differently from GitHub, so a README that looks fine there can still look off here. {% hint style="success" %} Run your finished README through the [Markdown Preview tool](https://thunderstore.io/tools/markdown-preview/) before you upload. {% endhint %} {% endstep %} {% step %} ## 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. {% endstep %} {% step %} ## HTML, if you're into that Basic HTML works, but only a safe list of tags. Anything outside that list, like `