Style Guide
This website uses an extended version of markdown for page content. These extensions are used to enhance project documentation. This page attempts to document most of these features. We recommend reading the Markdown Syntax and the Starlight Guide guide in addition to this guide to fully master the format.
Asides
Asides are used to draw the readers attention towards something. There are several types of asides which have a specific color, icon, and meaning.
Types
note
- A useful note that the reader should keep in mind.tip
- A tip that can help the user out.caution
- A warning for the user that should help keep them going in the right direction.danger
- A strict warning for the user. This should be for things that could have serious consequences.
Examples
:::note[Optional Title]The contents of the aside.:::
:::tipAsides can contain markdown elements as well.- like lists- **bold text**- [and links](https://docs.darkhax.net):::
:::cautionDon't go overboard with asides and their contents. It may distract the user.:::
:::dangerYour documentation may be rejected if you abuse asides.:::
Blockquotes
Quotes can be useful when you want to embed something that was said somewhere else without explicitly linking to it. They should not be used to warn the user or give the user examples. You should use asides and code blocks for that instead.
Examples
> Hello World>> You use a `>` to include text in the quote.
Hello WorldYou use a
>
to include text in the quote.
Code Blocks
Code blocks should be used to include examples for code, scripts, config files, data pack files, and anything else that is kind of code like. This site uses expressive code which greatly extends code blocks. Code blocks should always define a file name and language if possible, as this helps the user contextualize what they are reading.
Language
```js// Syntax highlighting requires a language to be set.// In this case we use js which means JavaScript.// Other formats like json, java, and yaml are also supported.const timer = 5```
// Syntax highlighting requires a language to be set.// In this case we use js which means JavaScript.// Other formats like json, java, and yaml are also supported.const timer = 5
File Name
The file name is set using the title. A file name should almost always be used, especially when referencing a datapack file. This will help users know where to find/put the files.
```json title="data/examplemod/tags/items/example.json"{ "replace": false, "values": [ "minecraft:stick" ]}```
{ "replace": false, "values": [ "minecraft:stick" ]}
Line Highlights
You can specify lines and ranges of lines to highlight. This should be done when you are referencing a specific property to help the user find it easier. You can also highlight additions and removals.
```json {4, 6-7} ins={8} del={9}{ "replace": false, "values": [ "minecraft:stick", "minecraft:apple", "#minecraft:pickaxes", "#minecraft:wool" "minecraft:gold_ingot", "minecraft:golden_ingot" ]}```
{ "replace": false, "values": [ "minecraft:stick", "minecraft:apple", "#minecraft:pickaxes", "#minecraft:wool", "minecraft:gold_ingot", "minecraft:golden_ingot" ]}
Tabs
In some situations you may want to show alternative information based on a users selection. For example showing code for fabric vs forge. This can be done using tabs. The syntax for this is a bit complex but the results are worth it.
<Tabs> <TabItem label="Forge"> ```java public boolean isModLoaded(String modId) { return ModList.get().isLoaded(modId); } ``` </TabItem> <TabItem label="Fabric"> ```java public boolean isModLoaded(String modId) { return FabricLoader.getInstance().isModLoaded(modId); } ``` </TabItem></Tabs>
public boolean isModLoaded(String modId) { return ModList.get().isLoaded(modId);}
public boolean isModLoaded(String modId) { return FabricLoader.getInstance().isModLoaded(modId);}
File Tree
File trees are an interesting way to drive home the location of a file.
<FileTree> - data - examplemod - loot_tables/ - recipes/ - tags - items - **my_tag.json** The target file</FileTree>
Directorydata
Directoryexamplemod
Directoryloot_tables/
- …
Directoryrecipes/
- …
Directorytags
Directoryitems
- my_tag.json The target file
Steps
If a process involves a linked series of steps the steps feature should be used.
<Steps>1. Download the mod file from CurseForge.2. Place the file in your mods folder. <FileTree> - config/ - **mods/** - resourcepacks/ - saves </FileTree>3. Run the game!</Steps>
- Download the mod file from CurseForge.
- Place the file in your mods folder.
Directory.minecraft
Directoryconfig/
- …
Directorymods/
- …
Directoryresourcepacks/
- …
- saves
- Run the game!
CurseForge Project Embed
CurseForge Project Banner
We have a custom markdown plugin that will embed a banner for a project on CurseForge. This should be used at the top of any page that documents a specific project. This will hopefully help prevent readers confusing what mod the documentation is for.
All Banner Options
Property | Example | Default | Functionality |
---|---|---|---|
p or projectId | p=2228525 | NONE | Sets the ID of the CurseForge project to generate a banner for. |
Examples
::cf-banner[]{p=228525}::cf-banner[]{p=353928}::cf-banner[]{p=242195}
YouTube Embeds
We have a custom markdown plugin that allows us to embed videos. There are a lot of options but they generally should not be needed or used.
::youtube[]{v=fGUdgi5TW0E}
- Simple 16:9 video embed.::youtube[]{v=fGUdgi5TW0E start=5}
- Starts the video at 5 seconds.::youtube[]{v=fGUdgi5TW0E vertical=1}
- Shows a vertical 9:16 video, like a short.
All YouTube Embed Options
Property | Example | Default | Functionality |
---|---|---|---|
v or video | v=fGUdgi5TW0E | NONE | Sets the ID of the video to embed. You can use either property name. |
autoplay | autoplay=1 | 0 | Toggles if the video should start playing automatically. |
color | color=white | red | Changes the player accent color. The only options allowed are white or red. |
controls | controls=1 | 1 | Toggles if the player controls are enabled. |
disablekb | disablekb=1 | 0 | Toggles if the player can be controlled using keyboard shortcuts. |
start | start=5 | 0 | Sets the start time of the video. Time is in seconds and matches nearest keyframe. |
end | end=15 | -1 | Sets the end time of the video. -1 uses the videos natural end time. Time is in seconds and matches nearest keyframe. |
fs | fs=1 | 1 | Toggles if the user can make the video full screen or not. |
loop | loop=1 | 0 | Toggles if the video should loop back to the start when it is finished. |
rel | rel=1 | 0 | Toggles the types of recommended videos YouTube shows after the video has ended. 0 = same channel as the original. 1 = any channel. |
pip | pip=1 | 0 | Toggles if picture-in-picture is allowed for the video. |
vertical | vertical=1 | 0 | Sets the video to 9:16 aspect ratio like a short or tiktok. |
YouTube Embed CSS Classes
The embedded iframe will always be wrapped in a div with the yt-embed-container
class. It will also have yt-embed-h
or yt-embed-v
if vertical=1
was set. The embedded iframe will have the yt-embed-video
class.
Starlight sets the height of iframe to auto which doesn’t work well with youtube videos. This is fixed by forcing the height to 100%.
.yt-embed-video { height: 100% !important;}
To control the aspect ratio we’re using the tailwind aspect ratio plugin.
.yt-embed-h { @apply aspect-w-16 aspect-h-9;}
.yt-embed-v { @apply aspect-w-9 aspect-h-16;}
Examples
Horizontal
Vertical
Custom Fonts
We package some additional fonts that can be used in pages. These should be used sparingly and for demonstration purposes.
<div className={"runelic"}> This text will use the Runelic font.</div>
This text will use the Runelic font.