satisfactorymodding / documentation

Documentation for SML and Unreal modding.

Satisfactory Modding Documentation

Documentation for Satisfactory Mod Loader (SML) and Satisfactory modding. Master branch is live on https://docs.ficsit.app/. Please contact us on the Satisfactory Modding Discord Server with questions and suggestions, or contribute via PRs (see below).

We attempt to use Semantic Line Break format in the source files, but this is only loosely followed.

An overview of Asciidoc syntax can be found here.

Pull requests should target the Dev branch.

Before you submit changes, you should probably follow the Development Setup directions below to verify that the pages are displaying as expected.

Documentation for other mods is also served through the same site. If you have written documentation for your mod and would like it to be added, contact us.

Contributing

We greatly appreciate any contributions you may have to the docs. Even if you only have the rough outline of a page done, feel free to contact us on the Discord and we'll help you turn it into a full page.

The easiest way to contribute is to make a fork of the repo, then use a Pull Request targeting the Dev branch for us to review the changes.

Send us a message on the Discord if we don't review it within a day or two.

Development Setup

Devcontainer

If you already have Visual Studio Code and Docker installed, we offer a devcontainer for the repository that will be auto-detected when you open the folder in VSCode.

This also means that Github Codespaces is a pretty convenient way to test out other people's PRs.

Make sure you have the Remote Containers extension and Docker Desktop installed.

Remember to turn off Docker starting with system startup and to close Docker after you're done using it. It reserves a lot of system memory even when not actively in use.

If it doesn't automatically prompt you, press Ctrl+Shift+P to open the Command Palette, then type "Reopen in Container" and select the option that appears.

The container will automatically serve the built content upon opening for preview in your browser or within VSCode, as well as a file watcher to automatically rebuild the preview upon detecting changes. You will still have to manually refresh your browser, though...

If you are switching between container and local dev you may have to delete the node_modules and/or .pnpm_store folder.

Manual

If you don't want to use the preconfigured devcontainer, or Codespaces, follow the directions below.

Although you can edit the .adoc files with just about any editor out there, we suggest either Visual Studio Code (with the Asciidoc and Code Spell Checker plugins) or IntelliJ.

In order to see what the pages will look like on the live site before being deployed, follow the below directions.

Installing

1. Install Node.js (the CI uses 16 but newer should be fine) and pnpm Package Manager through your preferred method.

2. Clone the repository

3. Use pnpm to install dependencies

pnpm install

Building

To set up a development watch server that will automatically rebuild the docs when you make changes:

pnpm run watch:dev

To build the docs for SML and all other hosted mods (slow):

pnpm run build

To build the docs for just SML (much faster):

pnpm run build:dev

The output HTML files for both commands can be found in \build\site.

Previewing

To preview the content, you can open the output HTML files in your browser, ex. build/site/satisfactory-modding/latest/index.html

You can also run pnpm run serve which will start a local webserver.

Link Checker

The CI will also run the lychee link checker to check for broken links. Its reports can be found in the the Actions tab of the repo. You can optionally install the tool yourself if you want to run it locally by following the lychee documentation.

Adding Docs for Another Mod

If you'd like, you can write docs for other mods and have them be included on the live site.

Mods that have done this include FicsIt-Networks, Refined Power, Ficsit Remote Monitoring, TweakIt, and more.

Contact us for more details if you'd like to set this up. The general steps are below:

• Create a repository with your documentation files
• Enable github actions on your repository
• Edit the antora-playbook-ci.yml and antora-playbook.yml files to add your repo as a Source. Follow the format of the other mods already listed there
• Make sure you can build this docs repo locally with your site added as a source. Run the build task defined in package.json to do this. Consider temporarily commenting out other mods' repos to speed this up.
• If you want the deployed copy to automatically update when you push changes to your repo, you should set up an Actions file similar to this one and contact us on the Discord to get a token to add to your secrets so the Actions file can function.
• PR the Dev branch with your changes to the playbook files.

Sub-mod documentation sites are currently still subject to the Lychee link checker run by our CI, so if you have broken links in your docs, the build will fail and your site will not be updated. You can check the Actions for this repo to see if/why they failed. Mod docs updates are started by the SatisfactoryModdingBot github user under the action name mod-docs-update.

Adding new version branches

We typically create new version branches once a new major or minor version of SML has released. The goal is to provide a point of reference in the docs for working with older versions.

In order to add a new frozen version branch of the docs:

1. Create a branch on a commit following the name format vX.X.X, for example, v3.1.1
2. Add the branch name to the branches list in antora-playbook.yml and antora-playbook-ci.yml
3. Edit antora.yml on the branch to have a version that matches the branch name (instead of latest). Here's an explanation of why that needs to happen.
4. You're good to go - CI will take care of deploying it for you.