Get started hosting your mod's documentation on our wiki!
This guide provides information on local development and the documentation format. For a guide on publishing docs onto our website, please see the Publishing page instead.
In order to start hosting documentation on our wiki, your mod only needs to meet a few minimal requirements:
Additionally, the person registering the project to the wiki should have Maintain or Admin access to its GitHub repository.
Start by creating a new directory inside your project. This can be located at any path of your choice.
For example, you can use docs/(your modid here) or simply docs, both are equally valid.
We also support scenarios where multiple mods' documentation is hosted in a single repository, as long as they're in
separate folders.
This is useful if you'd like to host documentation for multiple of your mods in a single place.
A minimal example folder layout may look like this:
docs
├── blocks
│ ├── generator.mds
│ └── _meta.json
├── introduction.mdx
├── _meta.json
└── sinytra-wiki.json
Here is a complete example including assets and translations.
docs
├── .assets
│ └── item
│ └── examplemod
│ └── generator.png
├── .translated
│ └── de_de
│ └── blocks
│ ├── generator.mdx
│ └── _meta.json
├── blocks
│ ├── generator.mds
│ └── _meta.json
├── introduction.mdx
├── _meta.json
└── sinytra-wiki.json
Let's talk about what each of these files does:
sinytra-wiki.json: The main metadata file, the "heart" of the documentation package, carries information about the
project. For its content format, see the complete explanation below._meta.json: Can be placed in the root folder as well as each subfolder. Provides display names for files and
folders, which are shown in the documentation navigation sidebar on the wiki, and also specifies the order in which
they are displayed. If not provided, fallback display names are generated automatically.*.mdx files: Contain documentation contents. To learn more about the MDX format, please see their
website. As MDX compiles to JavaScript, the Wiki imposes certain restrictions on what components
and tags can be used in addition to standard Markdown. For a complete description, please read below.Save yourself time manually exporting all assets using our companion Gradle plugin, which integrates with popular mod loader toolchains and can automatically generate rendered assets for you!
Assets are used to display images of items, blocks and other mod content across the website. These can be used as part of crafting recipes, sidebar information or custom components.
Assets are identified using resource locations using the same syntax as in the game itself. It's recommened to match asset names with the in-game IDs of the objects they belong to.
Rendered mod assets including both items and blocks should be placed under .assets/item/(modid) inside the
documentation directory, where modid is the namespace of each texture you wish to provide.
Each asset must be in .png format. The name of the file is up to your choice.
For example, examplemod:generator would point to (root)/.assets/item/examplemod/generator.png.
Documentation can be localized into various languages supported by the wiki. A complete list can be found in the language selection dropdown located on the right-most part of the navigation header.
Localized files must be placed under .translated/(lang) inside the documentation directory, where
(lang) is the desired language code in (lang)_(region) format. Currently, all regions match the language, so
it's sufficient to take the target language code and complete the region to be the same as the language
(e.g. German translations (de) would be placed under .translated/de_de).
The localized folder structure follows the same layout as root. Both documentation content files (.mdx) and folder
metadata (_meta.json) may be translated. Translated content takes precedence over the default locale when being
loaded. However, untranslated files will still be shown even when the locale is non-default, therefore it is
recommended to translate all files whenever possible.
The wiki provides a dedicated landing page for documentation called the "Mod homepage". By default, this shows the linked platform project's description.
If you'd like to provide your own contents instead, you can do so by creating a _homepage.mdx file in your
documentation's root folder (at the same level as sinytra-wiki.json). The file's contents follow the same
formatting as regular documentation pages, except for frontmatter metadata (e.g. title), which is ignored.
The homepage's title will always match the mod's name, whereas the sidebar will display various information about the
platform project, such as the project's authors, categories and available mc versions.
The wiki metadata file specifies project identification information, necessary for the wiki to load the project.
It must be placed in a file called sinytra-wiki.json inside the documentation root directory.
{
"id": "mffs",
"platform": "modrinth",
"slug": "mffs"
}The wiki metadata file contains the following properties, all of which are required:
id: Unique project id used to identify the project across the wiki. We recommend using your mod id
or hosting platform slug.platform: Your mod's distribution platform. Can be either of modrinth or curseforge.slug: The host platform's project slug.The project slug can be easily extracted from your mod's project page URL as shown in the examples below, where {slug}
is a placeholder for the actual value.
https://modrinth.com/mod/{slug}https://www.curseforge.com/minecraft/mc-mods/{slug}The JSON Schema specification for this file can be found here.
Provides additional information for the documentation page navigation sidebar:
To avoid potential unwanted display errors, we recommend always providing complete folder metadata in your documentation.
{
"blocks": "Blocks",
"items": "Completely custom name",
"introduction.mdx": "Introduction"
}The folder metadata json consists of string key-value pairs, where the keys represent the name of a file or a folder, and the values are their display name. When specifying a file name, the full name including the extension is required.
Folder metadata is contained in a file called _meta.json and can be placed inside any folder within the
documentation directory, including the root directory itself (e.g. at the same level as sinytra-wiki.json).
The JSON Schema specification for this file can be found here.
You can add icons for each metadata entry to display in the navigation sidebar by converting the meta value to an object and supplying the icon's name as shown below.
The supplied icon name should be a Lucide icon component name (without the Icon suffix).
More information on icon names can be found on the Format page.
{
"blocks": {
"name": "Blocks",
"icon": "Box"
}
}You can show multiple versions of your mod's documentation on the wiki by adding a versions property to your
docs metadata file, which contains a map of minecraft version names (these will be displayed in the version selector
as well as in the URL paths) to git branch names.
The documentation folder structure remains the same across all branches with contents being isolated per branch,
including assets and localization. Documentation metadata files (sinytra-wiki.json) from other branches are ignored,
as all necessary information is already contained in the default branch's file.
{
...
"versions": {
"1.19.2": "my-git-branch-name",
"1.18.2": "another-branch"
}
}We provide an excellent wiki companion Gradle plugin to help you with authoring documentation.
Its features include:
A complete usage guide can be found on its GitHub repository.
➡️ Learn more about the specifics of the MDX Documentation format.