Contribute¶

This wiki is happy for any contributions it gets to keep the info shown updated.
This page acts as a source of info regarding how you can contribute changes and what to look out for.

Requirements¶

This wiki is build using ProperDocs and the following additional dependencies:

MaterialX for MkDocs

Provides the Material theme used for this site alongside various QoL features.
PyMdown Extensions

Various Extensions used on this Site.
MkDocs-Macros

Used for creating Jinja2 macros which are used for features like displaying crafting recipes and advancements.
MkDocs GLightbox

Adds the ability to click an image to view in a gallery.
mkdocs-redirects

Adds the ability to create redirects from old (non-existant) pages to new ones.
mkdocs-categories-plugin

Currently using a Fork for additional config options.
Allows to add pages to categories and auto-generate them.
mkdocs-awesome-nav

Adds a more advanced way of creating a nav, allowing more automated structuring.

To contribute to the wiki, we suggest to fork the repository, clone it to your desktop and install the necessary dependencies.
The easiest way to install all necessary dependencies, is by running pip install -r requirements.txt in the folder where the properdocs.yml is located in.

Formatting¶

This Wiki has some special ways of formatting certain content to provide what it is currently offering.

Links¶

The wiki supports wikimedia-inspired links:

Format	Description
`[[Page]]`	to link to a page.
`[[Page\|Text]]`	to link to a page with a custom text displayed.
`[[mc:Page]]`	to link to an external page (in this example to the Minecraft Wiki).
`[[mc:Page\|Text]]`	to link to an external page with a custom text displayed.

Links to unknown Wiki pages will be displayed as non-clickable red-links. Example: [[Unknown]] shows as Unknown.
External sites are defined in the properdocs.yml in the interwiki section under extra.

Recipes¶

Macros for displaying crafting, smelting and smithing recipes have been created that are implemented using the following formats:

Format	Description
`{{ crafting_recipe("namespace:id") }}`	Displays a Crafting recipe from the provided namespaced ID.
`{{ smelting_recipe("namespace:id") }}`	Displays a Smelting recipe from the provided namespaced ID.
`{{ smithing_recipe("namespace:id") }}`	Displays a Smithing recipe from the provided namespaced ID.

Notes

The namespace can be omitted in which case the minecraft one is assumed.
An optional header and footer option exist to enable the prepending and appending of a table start (header row) and table end respectively. Default is True.

In order for a recipe to be displayed, are certain criterias to be met:

A JSON file matching the id exists in a folder matching namespace in docs/assets/items/
The JSON file contains a crafting, smelting or smithing section with their respective required options, based on what macros is used.
Additional JSON files for ingredient items exist. This is primarely to display their images.

Advancements¶

A Macros has been made to display advancements with an icon, name, description and optional requirements.
The format is {{ advancement("namespace:id") }} with an optional header and footer option existing to enable the creation of a table start (header row) and table end respectively. Default is True.

In order for an advancement to be displayed, are certain criterias to be met:

A JSON file matching the id exists in a folder matching namespace in docs/assets/advancements/
The JSON file contains a name, icon and description.

Structure¶

The site has a very distinct structure that needs to be followed:

docs/<modname>/ contains the individual wikipages for the respective mod.
docs/assets/advancements/ contains JSON files with Advancement Data for the respective mods.
docs/assets/img/ contains images used for various parts in the Wiki, such as recipe displays.
docs/assets/items/ contains assets - primarely JSON files - related to Items used in crafting recipes and similar.

Adding pages¶

Pages added to existing sub-directories should not require any modifications to the .nav.yml file within the docs/ directory.
Any pages added that are not part of such sub-directiories should be added to the nav.

If a new mod is added, is the following structure to be followed in the nav section:

nav:
  # Other entries
  - Modname:
    - modname/index.md
    - modname/*

This ensures that the index page is at the top of the nav to be used as the section index page, while every other page of the sub-folder is added afterwards.

Adding Categories¶

Categories are added to the page by adding entries to its categories frontmatter:

categories:
  - modname
  - modname/subcategory

For mod pages are you required to always add a category matching the display name of the mod, including capitalization.
Optional sub-categories may be added by using the mod name followed by a / and the name of the sub-category.

Note

Newly created Categories need to have their pages added to the .nav.yml file to avoid warnings in the console.
The Categories plugin always creates separate pages for each category, with text being lowercased and / and spaces being replaced by -.

The following should be added to the nav section when adding a new category:

nav:
  # Other entries
  - Categories:
    - categories/index.md
    # Other entries
    - Mod Name:
      - categories/modname*.md