CommandAPI published documentation

The CommandAPI's documentation is created using mdBook, a command-line tool to create static web "books" with Markdown.

JorelAli's mdBook fork

At the time of writing (Feb 2023), mdBook uses FontAwesome 4.7.0. We want to use a higher version of FontAwesome, but doing that reliably requires making changes to the mdBook source code. JorelAli has a fork of mdBook which has support for more updated versions of FontAwesome (FontAwesome 5 and FontAwesome 6.2.0).

Acquiring a copy of JorelAli's mdBook fork can be done from here. The Releases page will have various executables (at the time of writing, mdbook-fa6 and mdbook-fa6.exe for Linux and Windows respectively). If any of these executables don't work for you, you can build JorelAli's mdBook fork manually:

• Clone the mdBook fork repo:

  git clone https://github.com/JorelAli/mdBook.git

• Checkout the relevant FontAwesome branch (e.g. for FontAwesome 6, use fa6):

  git checkout fa6

• Build the executable with cargo (information about installing cargo can be found here) using the following command:

  cargo build --release

• Use the executable mdBook from mdbook/target/release.

mdbook-linkcheck

To validate links in the CommandAPI's documentation, the CommandAPI makes use of the mdbook-linkcheck preprocessor. mdbook-linkcheck can be installed from source (this may take a while) using the following command:

cargo install mdbook-linkcheck

Or you can grab an executable from the GitHub Releases page here

Building the CommandAPI's documentation

1. Grab a copy of JorelAli's mdBook fork (see above)
2. Grab a copy of mdbook-linkcheck
3. Go to the docssrc folder
4. Run mdbook build (or mdbook-fa6.exe build or whatever your mdBook executable is called)

The resulting documentation is found in docs/X.X.X/html, where X.X.X is specified in the book.toml file's build-dir in the docssrc folder.

Publishing the CommandAPI's documentation

Due to mdbook-linkcheck generating its own folder, we have to move some folders out of the way:

1. Build the documentation using the instructions above
2. Move the contents of docs/X.X.X/html to docs/X.X.X
3. Delete the folders docs/X.X.X/html and docs/X.X.X/linkcheck

Linking to code in the CommandAPI's documentation

The CommandAPI's documentation pulls in code written in commandapi-documentation-code to ensure we can have compile checks for code in the documentation. When adding code to commandapi-documentation-code:

• Use spaces, not tabs
• Sort methods in alphabetical order
• Method names should match the page name
• Anchors should also match the page name (capitalization/underscores etc. follow Java's variable style)
• Anchors end with a number indication their position in the documentation

Code written in the Markdown document can be written to support multiple languages by wrapping multiple code blocks in a multi-pre div. Multi-pre divs use normal code block conventions, except the language name should be followed by a comma and some text which will be used as the tab heading for that language. To add spaces in the tab text, use underscores. Code snippets are included using mdBook's anchors for including portions of a file.

<div class="multi-pre">

```java,Java
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentLocations1}}
```

```kotlin,Kotlin
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentLocations1}}
```

```kotlin,Kotlin_DSL
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentLocations1}}
```

</div>