Skip to content

Latest commit

 

History

History
158 lines (105 loc) · 5.22 KB

docs.md

File metadata and controls

158 lines (105 loc) · 5.22 KB
title
Updating documentation

To update the documentation site, you need to:

Browser

Update existing docs

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

edit page

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

github web editor

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

image

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

Create new file

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

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

Local development

:::note

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

:::

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.