WSO2 Integrator Docs

Documentation source for WSO2 Integrator, built with Docusaurus.

Repository Layout

• docs-integrator/en - Docusaurus site source
• issue_template.md - issue template
• pull_request_template.md - PR template

Prerequisites

• Node.js >= 20 (project is tested with Node 20)
• npm >= 10

Quick Start

cd en
npm install
npm run start

Then open the local URL printed in the terminal (usually http://localhost:3000).

Common Commands

Run these from en:

npm run start      # local dev server (hot reload)
npm run build      # production build in ./build
npm run serve      # serve built site locally
npm run typecheck  # TypeScript checks
npm run clear      # clear Docusaurus cache

Contributing Guide

1) Create a Branch

git checkout -b docs/<short-topic>

2) Make Changes

Typical files:

• Markdown docs: docs-integrator/en
• Site config: docs-integrator/en/docusaurus.config.ts
• Sidebar structure: docs-integrator/en/sidebars.ts
• Styling overrides: docs-integrator/en/src/css/custom.css

3) Validate Locally

cd en
npm run typecheck
npm run build

Use npm run start while editing for quick preview.

4) Commit

Use clear, scoped commit messages.

Examples:

• docs(api): clarify OAuth token rotation steps
• docs(nav): reorganize integration examples sidebar
• style: improve table readability on mobile

5) Open a Pull Request

• Fill in pull_request_template.md
• Link related issue(s)
• Add screenshots for UI/styling changes
• Call out breaking or structural doc changes

Content Quality Checklist

Before opening a PR, confirm:

• Links work and are not broken
• Headings are consistent and scannable
• Code snippets are complete and tested where possible
• New pages are added to sidebar/navigation if needed
• Build and type checks pass

Working with AI Agents

AI-assisted contributions are welcome.

Rules for Agent-Assisted Changes

• Treat AI output as a draft; a human reviewer remains responsible
• Verify technical accuracy against source code and official docs
• Do not commit secrets, tokens, or internal-only data
• Keep changes small and reviewable
• Include a short "AI usage note" in the PR description

Suggested AI Prompt Template

Task: <what to change>
Scope: <exact files/folders allowed>
Constraints: <style, terminology, version, formatting>
Validation: run `npm run typecheck` and `npm run build`
Output: summarize changed files and rationale

AI Usage Note (for PR description)

AI-assisted: Yes
Tool: <Codex/Claude/Copilot/Other>
How used: <drafting/editing/refactoring/checking>
Human verification: <what you manually validated>

Troubleshooting

• npm run dev fails: this project uses npm run start for local development.
• Dependency issues: delete node_modules and package-lock.json, then run npm install.
• Node version mismatch: run nvm use 20.

License

Apache 2.0. See LICENSE.