> For the complete documentation index, see [llms.txt](https://bluwhale.gitbook.io/bluwhaleai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluwhale.gitbook.io/bluwhaleai/oceanum-oxn/resources/contributing-to-docs.md).

# Contributing to Docs

The Oceanum (OXN) documentation is a living resource — corrections, additions, and clarifications from the community are welcome.

### Quick suggestions <a href="#quick-suggestions" id="quick-suggestions"></a>

Every page has a "Suggest an edit" link at the bottom (points to the source `.md` file on GitHub). For small fixes — typos, broken links, wrong version numbers — this is the fastest path.

### Local development <a href="#local-development" id="local-development"></a>

To work on the docs locally:

```
git clone https://github.com/oxn-network/oxn-docs
cd oxn-docs
npm install
npm start                # dev server at http://localhost:3000
npm run build            # production build
npm run serve            # serve the built site
```

The build supports both English and Chinese locales. Preview Chinese:

```
npm start -- --locale zh-CN
```

### Style guide <a href="#style-guide" id="style-guide"></a>

**Voice**

* Direct, active voice. "Set `gasLimit` to 500,000" beats "The `gasLimit` should be set to 500,000".
* Second person for instructions. "You'll need Node.js 18+" beats "One needs Node.js 18+".
* Assume the reader knows Ethereum but is new to Oceanum (OXN).

**Code samples**

* Complete and runnable when possible. Fragmented snippets frustrate readers.
* Include imports and pragma lines in Solidity examples.
* Include `gasLimit` on every Oceanum (OXN) transaction example.
* Prefer `paris` compiler settings.

**Terminology**

* **Oceanum (OXN)** — the chain, the brand.
* **BLUAI** / **TBLUAI** — native token symbols displayed in wallets. `TBLUAI` on testnet (no economic value), `BLUAI` on mainnet. Use `BLUAI` when describing the token concept, `TBLUAI` when describing concrete testnet display.
* **`0x…`** — EVM addresses. **`oxn1…`** — native addresses.
* **Encrypted call** — a transaction with an encrypted CBOR envelope.
* **Signed query** — an authenticated `eth_call` that populates `msg.sender`.

Be consistent with the [Glossary](https://docs.bout.network/introduction/glossary).

**Formatting**

* Use Markdown tables for reference data.
* Use `:::info`, `:::warning`, `:::danger` callouts for important notes.
* Fence code blocks with the language for syntax highlighting.
* Left-hand sidebar order is set by `sidebar_position` in frontmatter.

### Adding a new page <a href="#adding-a-new-page" id="adding-a-new-page"></a>

1. Create a new `.md` file in the appropriate section folder under `docs/`.
2. Add frontmatter (`title`, `sidebar_position`, `description`).
3. Write content.
4. Create the corresponding translated file under `i18n/zh-CN/docusaurus-plugin-content-docs/current/<section>/`.
5. Build locally to verify no broken links.
6. Submit a PR.

### PR review process <a href="#pr-review-process" id="pr-review-process"></a>

Reviewers check:

* Technical accuracy.
* Consistency with style guide.
* Both locales present (if adding new pages).
* Build passes locally.
* Cross-links to related pages.

### Getting help with contributions <a href="#getting-help-with-contributions" id="getting-help-with-contributions"></a>

For non-trivial contributions — new pages, larger reorganizations — open a discussion issue first to align on scope.

### Next steps <a href="#next-steps" id="next-steps"></a>

* [**Support Channels**](https://docs.bout.network/resources/support)
* [**FAQ**](https://docs.bout.network/resources/faq)

[Edit this page](https://github.com/oxn-network/oxn-docs/edit/main/docs/14-resources/contributing.md)[PreviousSupport Channels](https://docs.bout.network/resources/support)