Contributing to the Documentation

This is a non-exhaustive guideline for making contributions to the NeoForged Documentation repository. Contributions can be made by forking and cloning the repository and then added via a pull request, or PR, on the GitHub.

You can run the website locally using npm. It is recommended to use a Node Version Manager like nvm (Mac, Linux) or nvs (Windows) to setup and install npm and Node. From there, you can run the following commands:

nvm use # or nvs use on Windows
npm install
npm run start

Principles​

This documentation is a guide to help a modder understand and implement a given concept from Minecraft or NeoForged.

This documentation is not meant as a tutorial, allowing a modder to copy-paste the examples. If you are looking for a tutorial, there are plenty of videos and pages, which are not linked here, that you can use and follow along with.

This documentation is also not meant as documentation for a class. Providing a description of an element is unavoidable when writing a guide; however, if you would like to document a class, you should contribute to Parchment for Minecraft or NeoForge for NeoForged.

Finally, this documentation is not meant to explain Java concepts. This documentation is intended for people who already have a solid basis in Java. If a Java concept needs to be explained to better understand the concept (such as JVM Descriptors for Access Transformers), a link should be provided to the original resource. Otherwise, if you are unfamiliar with Java, there are plenty of online resources to learn from:

• JetBrains Academy
• Codeacademy
• University of Helsinki
• Oracle
• Introduction to Programming using Java by David J. Eck

Concepts​

Each page should guide a modder on a particular concept. If the concept is too large in scope, the concept should be split into separate sub-concepts, each within its own page. For example, if you are writing a cookbook, there can be a page for each recipe, rather than a single page containing all the recipes.

When describing a concept, you should first introduce what the concept is, where it is used in Minecraft, why it should be used, and how to use it. Each section within a concept should have a header. A section can also be broken into sub-sections if necessary. For example, each recipe within a cookbook can have a sub-section for ingredients and the recipe itself.

If you need to refer to other concepts, the relevant page should be linked along with a summary and/or some example to understand the application.

Examples​

Code examples should generally be pseudocode-like objects meant to enhance the understanding of a modder. For this documentation, pseudocode-like refers to code blocks written in the structure and syntax of the desired language with comments used as placeholders for specific logic that the modder may choose to implement themselves. The code blocks do not necessarily need to be compilable, but each line should have valid syntax and structure of the desired language.

When implementing a method, it is usually specific to the desired goal a modder is trying to achieve. As a guide, this documentation aims to be somewhat agnostic to a modder's specific goal, instead covering the general use case.

Let's say we are using a method called #applyDiscount to take some value off the current price. Not everyone will implement the same logic within the method. So, the pseudocode can leave a comment mentioning what to do instead:

// In some class

public float applyDiscount(float price) {
    float newPrice = price;
    // Apply discount to newPrice
    // ...
    return newPrice;
}

Minor and Patch Changes​

If a change occurs between a minor or patch versions of NeoForge, then relevant changes in the documentation should be split into separate sections or put into tabs. This maintains the accuracy of the information depending on the version the modder is currently developing for.

Tabs must be in an .mdx file, not an .md file, for proper IDE support.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs defaultValue="latest">
<!-- Value represents the last supported version of this method. -->
<!-- Label represents the version range to display to the reader. -->
<TabItem value="latest" label="Latest">

<!-- Markdown here -->
```java
public void latestMethod() {
    // ...
}
```

</TabItem>
<!-- There must be an empty line before and after the Markdown text in a tab. -->
<TabItem value="20.2.67" label="[20.2.35,20.2.67]"> 

<!-- Markdown here -->
```java
public void previousMethod() {
    // ...
}
```

</TabItem>
<TabItem value="20.2.34" label="[20.2.0,20.2.34]">

<!-- Markdown here -->
```java
public void firstMethod() {
    // ...
}
```

</TabItem>
</Tabs>

Output:

public void latestMethod() {
    // ...
}

public void previousMethod() {
    // ...
}

public void firstMethod() {
    // ...
}

Style Guide​

This documentation uses Docusaurus, which internally uses MDX, to generate the pages. You can find more detailed information about available features on their pages. This style guide will be more focused towards common features and formatting we use in the Markdown files.

Front Matter​

Front matter defines metadata fields which can affect how the page is rendered. This is denoted using ---, similar to a code block. The only front matter that should usually be defined is sidebar_position, which determines where the page should be rendered on the sidebar.

There are other metadata fields like title and description, but those are typically parsed from the page itself.

<!-- Second page in the sidebar -->
---
sidebar_position: 2
---

<!-- sidebar_position 1 and 2 are defined, but this page should go in-between them -->
---
sidebar_position: 1.5
---

Categories​

Categories are folders within the documentation. They inherit titles and positional data from index.md. If an index.md is not within a subfolder, a _category_.json file should be created, specifying the label representing the name of the section, and position representing where on the sidebar it should go.

{
    // Name of the category to display
    "label": "Example Title",

    // This will be rendered as the third element on the sidebar at the current level.
    "position": 3
}

Titles​

Titles are defined using up to six hashtags (#) to define each section. Titles should capitalize everything but unimportant words.

<!-- There should only be one title with a single '#'. -->
# Guide For Contributing to This Documentation

### Building and Testing Your Mod

Diction​

Spelling, grammar, and syntax should follow those in American English. Avoid using contractions in sentences; use two separate words ('is not' instead of 'isn't'). Additionally, avoid using pronouns (e.g. I, me, you) when possible, unless you need to directly refer to the reader. Demonstratives (e.g. this, that, its) should be used sparingly to avoid confusing the reader. Prefer using the actual object or noun being referred to.

Paragraphs​

Paragraphs should be a continuous block, separated by a newline. Paragraphs should not have each sentence be on a new line.

This is my first paragraph. See how the next sentence is on the same line? You can use word wrapping in your editor to stop the line from going off the screen.

This is my next paragraph. It is separated by a new line.

Indentation​

When indenting lines, use four spaces instead of tabs. Most markdown features require four spaces to recognize indentation, so it allows consistency across the document.

- Hello World
    - Four Spaces In

Importance​

Emphasizing words should be done using bold or italics. Please use two asterisks (**) for bold and an underscore (_) for italics to make the separation in Markdown more distinct.

This is a **bolded** word.

This is an _italicized_ word.

Lists​

Unordered lists should always use - for every level while ordered lists should always start with 1..

- This is an unordered list.
- This is a second element.
    - This is a subelement.

1. This is an ordered list.
1. This is a second element.
    1. This is a subelement.

Code References​

When referencing elements outside of code blocks, they should be surrounded with backticks (`). Classes should use their simple name. Methods and fields should specify the class name followed by a #. If the class name is implied, the method or field can simply be prefixed with #. Inner classes should specify the name of the outer class followed by a ..

<!-- Classes -->
`MyClass`
`MyClass.InnerClass`

<!-- Method and Fields -->
`MyClass#foo`
`MyClass.InnerClass#bar`
`#SOME_CONSTANT`

Code blocks should specify the language after the triple backtick (```). When writing a JSON block, the JSON5 (json5) syntax highlighter should be used to allow comments.

<!-- Java Code Block -->
```java
public void run() {
    //...
}
```

<!-- JSON Code Block -->
```json5
{
    // Comments are allowed here
    "text": "Hiya"
}
```

Links​

All links should use brackets ([]) to refer to a link specified on the bottom of the markdown page. The second pair of brackets can be omitted if the name between the first pair of brackets is used.

<!-- Somewhere on a page -->
There are [two] different types of [link references][linkref].

<!-- At the bottom of a page -->
[two]: https://linkrefwithoutref.donotclick
[linkref]: https://linkref.donotclick

Admonitions​

Admonitions can be specified on the page using three colons (:::) and by specifying its type. Admonition formatting can be found on the Docusaurus wiki.

:::note
I'm within an admonition!
:::