Migrate to Docusaurus frontmatter & change all heading levels to use markdown

docs/advanced/accesstransformers.md

@@ -1,12 +1,14 @@
-Access Transformers
-===================
+---
+sidebar_position: 1
+---
+
+# Access Transformers
 
 Access Transformers (ATs for short) allow for widening the visibility and modifying the `final` flags of classes, methods, and fields. They allow modders to access and modify otherwise inaccessible members in classes outside their control.
 
 The [specification document][specs] can be viewed on the NeoForged GitHub.
 
-Adding ATs
-----------
+## Adding ATs
 
 Adding an Access Transformer to your mod project is as simple as adding a single line into your `build.gradle`:
 
@@ -21,13 +23,11 @@ After adding or modifying the Access Transformer, the gradle project must be ref
 
 During development, the AT file can be anywhere specified by the line above. However, when loading in a non-development environment, Forge will only search for the exact path of `META-INF/accesstransformer.cfg` in your JAR file.
 
-Comments
---------
+## Comments
 
 All text after a `#` until the end of the line will be treated as a comment and will not be parsed.
 
-Access Modifiers
-----------------
+## Access Modifiers
 
 Access modifiers specify to what new member visibility the given target will be transformed to. In decreasing order of visibility:
 
@@ -44,8 +44,7 @@ Directives only modify the method they directly reference; any overriding method
 Examples of methods that can be safely transformed are `private` methods, `final` methods (or methods in `final` classes), and `static` methods.
 :::
 
-Targets and Directives
-----------------------
+## Targets and Directives
 
 :::caution
 When using Access Transformers on Minecraft classes, the SRG name must be used for fields and methods.

docs/blockentities/ber.md

@@ -1,10 +1,12 @@
-BlockEntityRenderer
-==================
+---
+sidebar_position: 1
+---
+
+# BlockEntityRenderer
 
 A `BlockEntityRenderer` or `BER` is used to render blocks in a way that cannot be represented with a static baked model (JSON, OBJ, B3D, others). A block entity renderer requires the block to have a `BlockEntity`.
 
-Creating a BER
---------------
+## Creating a BER
 
 To create a BER, create a class that inherits from `BlockEntityRenderer`. It takes a generic argument specifying the block's `BlockEntity` class. The generic argument is used in the BER's `render` method.
 
@@ -22,7 +24,6 @@ This method is called every frame in order to render the block entity.
 * `combinedLight`: An integer of the current light value on the block entity.
 * `combinedOverlay`: An integer set to the current overlay of the block entity, usually `OverlayTexture#NO_OVERLAY` or 655,360.
 
-Registering a BER
------------------
+## Registering a BER
 
 In order to register a BER, you must subscribe to the `EntityRenderersEvent$RegisterRenderers` event on the mod event bus and call `#registerBlockEntityRenderer`.

docs/blockentities/index.md

@@ -1,5 +1,4 @@
-Block Entities
-======
+# Block Entities
 
 `BlockEntities` are like simplified `Entities` that are bound to a Block.
 They are used to store dynamic data, execute tick based tasks, and dynamic rendering.

docs/blocks/index.md

@@ -1,10 +1,8 @@
-Blocks
-======
+# Blocks
 
 Blocks are, obviously, essential to the Minecraft world. They make up all of the terrain, structures, and machines. Chances are if you are interested in making a mod, then you will want to add some blocks. This page will guide you through the creation of blocks, and some of the things you can do with them.
 
-Creating a Block
-----------------
+## Creating a Block
 
 ### Basic Blocks
 
@@ -25,8 +23,7 @@ Blocks have no setter for their `CreativeModeTab`. This is handled by the [`Buil
 
 Of course, the above only allows for extremely basic blocks. If you want to add functionality, like player interaction, a custom class is required. However, the `Block` class has many methods and unfortunately not every single one can be documented here. See the rest of the pages in this section for things you can do with blocks.
 
-Registering a Block
--------------------
+## Registering a Block
 
 Blocks must be [registered][registering] to function.
 
@@ -40,8 +37,7 @@ When a block is registered, *only* a block is registered. The block does not aut
 
 In the past there have been several mods that have allowed users to disable blocks/items in a configuration file. However, you shouldn't do this. There is no limit on the amount of blocks that can be register, so register all blocks in your mod! If you want a block to be disabled through a configuration file, you should disable the crafting recipe. If you would like to disable the block in the creative tab, use a `FeatureFlag` when building the contents within [`BuildCreativeModeTabContentsEvent`][creativetabs].
 
-Further Reading
----------------
+## Further Reading
 
 For information about block properties, such as those used for vanilla blocks like fences, walls, and many more, see the section on [blockstates].
 

docs/blocks/states.md

@@ -1,8 +1,10 @@
-Block States
-============
+---
+sidebar_position: 1
+---
 
-Legacy Behavior
----------------------------------------
+# Block States
+
+## Legacy Behavior
 
 In Minecraft 1.7 and previous versions, blocks which need to store placement or state data that did not have BlockEntities used **metadata**. Metadata was an extra number stored with the block, allowing different rotations, facings, or even completely separate behaviors within a block.
 
@@ -20,8 +22,7 @@ switch (meta) {
 
 Because the numbers carry no meaning by themselves, no one could know what they represent unless they had access to the source code and comments.
 
-Introduction of States
----------------------------------------
+## Introduction of States
 
 In Minecraft 1.8 and above, the metadata system, along with the block ID system, was deprecated and eventually replaced with the **block state system**. The block state system abstracts out the details of the block's properties from the other behaviors of the block.
 
@@ -31,8 +32,7 @@ A unique pair can be constructed from the `Block` and a map of the `Property<?>`
 
 The previous system of meaningless metadata values were replaced by a system of block properties, which are easier to interpret and deal with. Previously, a stone button which is facing east and is powered or held down is represented by "`minecraft:stone_button` with metadata `9`. Now, this is represented by "`minecraft:stone_button[facing=east,powered=true]`".
 
-Proper Usage of Block States
----------------------------------------
+## Proper Usage of Block States
 
 The `BlockState` system is a flexible and powerful system, but it also has limitations. `BlockState`s are immutable, and all combinations of their properties are generated on startup of the game. This means that having a `BlockState` with many properties and possible values will slow down the loading of the game, and befuddle anyone trying to make sense of your block logic.
 
@@ -45,8 +45,7 @@ A good rule of thumb is: **if it has a different name, it should be a separate b
 An example is making chair blocks: the *direction* of the chair should be a *property*, while the different *types of wood* should be separated into different blocks.
 An "Oak Chair" facing east (`oak_chair[facing=east]`) is different from a "Spruce Chair" facing west (`spruce_chair[facing=west]`).
 
-Implementing Block States
----------------------------------------
+## Implementing Block States
 
 In your Block class, create or reference `static final` `Property<?>` objects for every property that your Block has. You are free to make your own `Property<?>` implementations, but the means to do that are not covered in this article. The vanilla code provides several convenience implementations:
 
@@ -87,8 +86,7 @@ Because `BlockState`s are immutable, and all combinations of their properties ar
 
 Because all possible `BlockState`s are generated at startup, you are free and encouraged to use the reference equality operator (`==`) to check if two `BlockState`s are equal.
 
-Using `BlockState`'s
----------------------
+## Using `BlockState`'s
 
 You can get the value of a property by calling `BlockState#getValue(Property<?>)`, passing it the property you want to get the value of.
 If you want to get a `BlockState` with a different set of values, simply call `BlockState#setValue(Property<T>, T)` with the property and its value.

docs/concepts/events.md

@@ -1,5 +1,8 @@
-Events
-======
+---
+sidebar_position: 3
+---
+
+# Events
 
 Forge uses an event bus that allows mods to intercept events from various Vanilla and mod behaviors.
 
@@ -11,8 +14,7 @@ Every event is fired on one of these busses: most events are fired on the main f
 
 An event handler is some method that has been registered to an event bus.
 
-Creating an Event Handler
--------------------------
+## Creating an Event Handler
 
 Event handlers methods have a single parameter and do not return a result. The method could be static or instance depending on implementation.
 
@@ -88,36 +90,31 @@ public class MyStaticClientOnlyEventHandler {
 This does not register an instance of the class; it registers the class itself (i.e. the event handling methods must be static).
 :::
 
-Canceling
----------
+## Canceling
 
 If an event can be canceled, it will be marked with the `@Cancelable` annotation, and the method `Event#isCancelable()` will return `true`. The cancel state of a cancelable event may be modified by calling `Event#setCanceled(boolean canceled)`, wherein passing the boolean value `true` is interpreted as canceling the event, and passing the boolean value `false` is interpreted as "un-canceling" the event. However, if the event cannot be canceled (as defined by `Event#isCancelable()`), an `UnsupportedOperationException` will be thrown regardless of the passed boolean value, since the cancel state of a non-cancelable event event is considered immutable.
 
 :::danger
 Not all events can be canceled! Attempting to cancel an event that is not cancelable will result in an unchecked `UnsupportedOperationException` being thrown, which is expected to result in the game crashing! Always check that an event can be canceled using `Event#isCancelable()` before attempting to cancel it!
 :::
 
-Results
--------
+## Results
 
 Some events have an `Event$Result`. A result can be one of three things: `DENY` which stops the event, `DEFAULT` which uses the Vanilla behavior, and `ALLOW` which forces the action to take place, regardless if it would have originally. The result of an event can be set by calling `#setResult` with an `Event$Result` on the event. Not all events have results; an event with a result will be annotated with `@HasResult`.
 
 :::caution
 Different events may use results in different ways, refer to the event's JavaDoc before using the result.
 :::
 
-Priority
---------
+## Priority
 
 Event handler methods (marked with `@SubscribeEvent`) have a priority. You can set the priority of an event handler method by setting the `priority` value of the annotation. The priority can be any value of the `EventPriority` enum (`HIGHEST`, `HIGH`, `NORMAL`, `LOW`, and `LOWEST`). Event handlers with priority `HIGHEST` are executed first and from there in descending order until `LOWEST` events which are executed last.
 
-Sub Events
-----------
+## Sub Events
 
 Many events have different variations of themselves. These can be different but all based around one common factor (e.g. `PlayerEvent`) or can be an event that has multiple phases (e.g. `PotionBrewEvent`). Take note that if you listen to the parent event class, you will receive calls to your method for *all* subclasses.
 
-Mod Event Bus
--------------
+## Mod Event Bus
 
 The mod event bus is primarily used for listening to lifecycle events in which mods should initialize. Each event on the mod bus is required to implement `IModBusEvent`. Many of these events are also ran in parallel so mods can be initialized at the same time. This does mean you can't directly execute code from other mods in these events. Use the `InterModComms` system for that.
 

docs/concepts/internationalization.md

@@ -1,14 +1,18 @@
-Internationalization and Localization
-=====================================
+---
+sidebar_position: 6
+---
+
+# Internationalization
+
+# Internationalization and Localization
 
 Internationalization, i18n for short, is a way of designing code so that it requires no changes to be adapted for various languages. Localization is the process of adapting displayed text to the user's language.
 
 I18n is implemented using _translation keys_. A translation key is a string that identifies a piece of displayable text in no specific language. For example, `block.minecraft.dirt` is the translation key referring to the name of the Dirt block. This way, displayable text may be referenced with no concern for a specific language. The code requires no changes to be adapted in a new language.
 
 Localization will happen in the game's locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is `en_us`. A list of available locales can be found on the [Minecraft Wiki][langs].
 
-Language files
---------------
+## Language files
 
 Language files are located by `assets/[namespace]/lang/[locale].json` (e.g. all US English translations provided by `examplemod` would be within `assets/examplemod/lang/en_us.json`). The file format is simply a json map from translation keys to values. The file must be encoded in UTF-8. Old .lang files can be converted to json using a [converter][converter].
 
@@ -20,8 +24,7 @@ Language files are located by `assets/[namespace]/lang/[locale].json` (e.g. all
 }
 ```
 
-Usage with Blocks and Items
----------------------------
+## Usage with Blocks and Items
 
 Block, Item and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding `#getDescriptionId`. Item also has `#getDescriptionId(ItemStack)` which can be overridden to provide different translation keys depending on ItemStack NBT.
 
@@ -37,8 +40,7 @@ By default, `#getDescriptionId` will return `block.` or `item.` prepended to the
 The only purpose of a translation key is internationalization. Do not use them for logic. Use registry names instead.
 :::
 
-Localization methods
---------------------
+## Localization methods
 
 :::caution
 A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.

docs/concepts/lifecycle.md

@@ -1,5 +1,8 @@
-Mod Lifecycle
-==============
+---
+sidebar_position: 4
+---
+
+# Mod Lifecycle
 
 During the mod loading process, the various lifecycle events are fired on the mod-specific event bus. Many actions are performed during these events, such as [registering objects][registering], preparing for [data generation][datagen], or [communicating with other mods][imc].
 
@@ -28,8 +31,7 @@ Most of the lifecycle events are fired in parallel: all mods will concurrently r
 Mods *must* take care to be thread-safe, like when calling other mods' APIs or accessing vanilla systems. Defer code for later execution via `ParallelDispatchEvent#enqueueWork`.
 :::
 
-Registry Events
----------------
+## Registry Events
 
 The registry events are fired after the mod instance construction. There are three: `NewRegistryEvent`, `DataPackRegistryEvent$NewRegistry` and `RegisterEvent`. These events are fired synchronously during mod loading.
 
@@ -39,23 +41,19 @@ The registry events are fired after the mod instance construction. There are thr
 
 `RegisterEvent` is for [registering objects][registering] into the registries. The event is fired for each registry. 
 
-Data Generation
----------------
+## Data Generation
 
 If the game is setup to run [data generators][datagen], then the `GatherDataEvent` will be the last event to fire. This event is for registering mods' data providers to their associated data generator. This event is also fired synchronously.
 
-Common Setup
-------------
+## Common Setup
 
 `FMLCommonSetupEvent` is for actions that are common to both physical client and server, such as registering [capabilities][capabilities].
 
-Sided Setup
------------
+## Sided Setup
 
 The sided-setup events are fired on their respective [physical sides][sides]: `FMLClientSetupEvent` on the physical client, and `FMLDedicatedServerSetupEvent` for the dedicated server. This is where physical side-specific initialization should occur, such as registering client-side key bindings.
 
-InterModComms
--------------
+## InterModComms
 
 This is where messages can be sent to mods for cross-mod compatibility. There are two events: `InterModEnqueueEvent` and `InterModProcessEvent`.
 

docs/concepts/registries.md

@@ -1,14 +1,16 @@
-Registries
-==========
+---
+sidebar_position: 1
+---
+
+# Registries
 
 Registration is the process of taking the objects of a mod (such as items, blocks, sounds, etc.) and making them known to the game. Registering things is important, as without registration the game will simply not know about these objects, which will cause unexplainable behaviors and crashes. 
 
 Most things that require registration in the game are handled by the Forge registries. A registry is an object similar to a map that assigns values to keys. Forge uses registries with [`ResourceLocation`][ResourceLocation] keys to register objects. This allows the `ResourceLocation` to act as the "registry name" for objects.
 
 Every type of registrable object has its own registry. To see all registries wrapped by Forge, see the `ForgeRegistries` class. All registry names within a registry must be unique. However, names in different registries will not collide. For example, there's a `Block` registry, and an `Item` registry. A `Block` and an `Item` may be registered with the same name `example:thing` without colliding; however, if two different `Block`s or `Item`s were registered with the same exact name, the second object will override the first.
 
-Methods for Registering
-------------------
+## Methods for Registering
 
 There are two proper ways to register objects: the `DeferredRegister` class, and the `RegisterEvent` lifecycle event.
 
@@ -73,8 +75,7 @@ public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_
 ```
 :::
 
-Referencing Registered Objects
-------------------------------
+## Referencing Registered Objects
 
 Registered objects should not be stored in fields when they are created and registered. They are to be always newly created and registered whenever `RegisterEvent` is fired for that registry. This is to allow dynamic loading and unloading of mods in a future version of Forge.
 
@@ -145,8 +146,7 @@ class Holder {
 }
 ```
 
-Creating Custom Forge Registries
---------------------------------
+## Creating Custom Forge Registries
 
 Custom registries can usually just be a simple map of key to value. This is a common style; however, it forces a hard dependency on the registry being present. It also requires that any data that needs to be synced between sides must be done manually. Custom Forge Registries provide a simple alternative for creating soft dependents along with better management and automatic syncing between sides (unless told otherwise). Since the objects also use a Forge registry, registration becomes standardized in the same way.
 
@@ -174,8 +174,7 @@ The `DeferredRegister` method is once again another wrapper around the above eve
 `DeferredRegister#makeRegistry` must be called before the `DeferredRegister` is added to the mod event bus via `#register`. `#makeRegistry` also uses the `#register` method to create the registry during `NewRegistryEvent`.
 :::
 
-Handling Missing Entries
-------------------------
+## Handling Missing Entries
 
 There are cases where certain registry objects will cease to exist whenever a mod is updated or, more likely, removed. It is possible to specify actions to handle the missing mapping through the third of the registry events: `MissingMappingsEvent`. Within this event, a list of missing mappings can be obtained either by `#getMappings` given a registry key and mod id or all mappings via `#getAllMappings` given a registry key.