Updating documentation

To update the documentation site, you need to:

Browser

edit page

  1. Click the Edit page button at the bottom of the page.

alt text

  1. You will be redirected to the github page of the documentation site. You can edit and preview your changes here.

Note

  • .md in CONTRIBUTING.md stands for markdown files
  • .mdx in docs.mdx stands for MarkDown eXtended
    • it's a superset of markdown with javascript and jsx component support
    • they are a bit more complicated but allows to use interactive components

propose changes window

  1. Click the Commit changes... button on the top right corner to commit your changes. Make sure to
  • Write a short and descriptive Commit message
  • Check the Create a new branch for this commit and start a pull request checkbox.

comparing changes page

  1. You will be redirected to the Comparing changes page. Click the Create pull request button to create a pull request.

open a pull request page

  1. Click the Create pull request button to open a PR. It's okay to leave the PR body empty for small changes.

Local development

Note

This section assumes you have some knowledge of git and javascript. Of course, you can learn them as you go.

To run the documentation site locally, you need to:

  • install deno to format and generate automated documentation

Setup dev server

(Cataclysm-BN) $ cd docs
(Cataclysm-BN/docs) $ deno task serve

You will be able to access the documentation site at http://localhost:3000. The dev server will automatically reload when you make changes to the documentation.

Automated page generation

Lua and CLI docs are generated automatically from the source code. To generate them, go to project root and run:

(Cataclysm-BN) $ deno task docs

License

  • By contributing to markdown files (including, but not limited to .md and .mdx files), you agree to license your contributions under CC-BY-SA 3.0, the same license as the game.

  • By contributing to source code of documentation page (including, but not limited to .ts files), you agree to license your contributions under AGPL 3.0.