Updating documentation

To update the documentation site, you need to:

• learn markdown in y minutes
• create a github account as the source code for docs site is hosted on github.

Browser

Update existing docs

this is the most straightforward way to update the documentation site.

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

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

3. 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.

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

5. Fill in the Open a pull request page and click the Create pull request button to open a PR.

Creating a new page

This one is a bit more involved, but similar to the previous one.

1. Go to the directory you want to create a new post. Click the Edit link button then immediately navigate to directory you’d like to edit (in this case, contributing).

2. Click the Add file > Create new file button on the top right corner. Name your file <your-filename>.md then add the frontmatter like:

---
title: <your-title>
---

currently only title is required.

3. After editing, follow the same steps as Update existing docs to create a pull request.

Local development

To run the documentation site locally, you need to:

• install node for dev server
• (optional) pnpm as faster and more space efficient alternative to node’s stock npm
• (optional) deno to format and generate automated documentation

Setup dev server

(Cataclysm-BN) $ cd doc
(Cataclysm-BN/doc) $ pnpm install # 'pnpm i' for short
(Cataclysm-BN/doc) $ pnpm dev

Or, if you’re not using pnpm:

(Cataclysm-BN) $ cd doc
(Cataclysm-BN/doc) $ npm install # 'npm i' for short
(Cataclysm-BN/doc) $ npm run dev

You will be able to access the documentation site at http://localhost:4321.

Live preview

The dev server will automatically reload when you make changes to the documentation.

Automated docs 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 and .astro files), you agree to license your contributions under AGPL 3.0.