Skip to main content

Contributing to Docs

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

Quick suggestions​

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​

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​

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

Code samples

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

Terminology

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

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​

  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​

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​

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

Next steps​