This repository hosts the docusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs packages. The plugin converts OpenAPI specs to MDX and the theme provides React components for rendering those docs. The demo directory shows them working together.
root
├─ packages
│ ├─ docusaurus-plugin-openapi-docs # generates MDX from OpenAPI specs
│ └─ docusaurus-theme-openapi-docs # theme components for API docs
├─ demo # example site using the plugin and theme
└─ scripts # release and helper scripts
The plugin and theme are typically used together:
OpenAPI spec ──▶ plugin ──▶ generated MDX ──▶ docs plugin ──▶ theme ──▶ website
Steps from the top-level README.md for getting started:
git clone https://github.com/<your account>/docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demoSee CONTRIBUTING.md for the full guide. Use clear commit messages so reviewers can understand what each commit does.
Run the following before committing any code changes (except documentation or comment-only updates):
yarn lint
yarn testyarn– install dependenciesyarn build-packages– compile all packages
This project uses semantic versioning and Lerna for package management. Releases are triggered automatically when version changes are merged to main.
| Bump Type | Example | When to Use |
|---|---|---|
patch |
4.5.0 → 4.5.1 |
Bug fixes, minor documentation updates |
minor |
4.5.1 → 4.6.0 |
New features, non-breaking enhancements |
major |
4.6.0 → 5.0.0 |
Breaking changes |
preminor |
4.5.1 → 4.6.0-rc.0 |
Pre-release for upcoming minor version |
prerelease |
4.6.0-rc.0 → 4.6.0-rc.1 |
Iterate on existing pre-release |
graduate |
4.6.0-rc.5 → 4.6.0 |
Promote pre-release to stable |
betamajor |
4.5.1 → 5.0.0-beta.0 |
Start a new beta major version |
betapatch |
5.0.0-beta.0 → 5.0.0-beta.1 |
Iterate on beta version |
Run the version command with the appropriate bump type:
yarn release:version <bump>This updates lerna.json and all package versions. The version is stored in lerna.json and propagated to all packages.
yarn release:changelogThis outputs a changelog template comparing commits between the latest tag and main. Copy the output and prepend it to CHANGELOG.md.
Changelog format:
The changelog uses a categorized format inspired by Docusaurus. Each release includes a high-level summary followed by categorized changes with emoji headers.
## X.Y.Z (YYYY-MM-DD)
Brief summary of the most significant changes in this release (1-3 sentences).
- Bullet points highlighting major user-facing features or fixes
#### :rocket: New Feature
- feat: description of feature ([#123](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/123))
#### :bug: Bug Fix
- fix: description of fix ([#124](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/124))
#### :house: Refactoring
- refactor: description ([#125](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/125))
#### :memo: Documentation
- docs: description ([#126](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/126))
#### :robot: Dependencies
- chore(deps): bump package from X to Y ([#127](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/127))
#### Committers: N
- Name or usernameCategory headers (include only sections with changes):
| Emoji | Category | Commit Prefix |
|---|---|---|
| 🚀 | New Feature | feat |
| 🐛 | Bug Fix | fix, bugfix |
| 🏃♀️ | Performance | perf |
| 💅 | Polish | style |
| 🏠 | Refactoring | refactor |
| 📝 | Documentation | docs |
| 🧪 | Testing | test |
| 🤖 | Dependencies | chore(deps) |
| 🔧 | Maintenance | chore |
Guidelines for changelog entries:
- Replace
TODO: Add high-level summarywith a concise summary of user-facing changes - Use ISO date format:
YYYY-MM-DD - Remove internal commits (CI changes, workflow updates) that don't affect users
- Keep the original commit message format (e.g.,
feat:,fix:) - Only include category sections that have changes
- List committers alphabetically at the end
Review and update version references in:
README.mdpackages/docusaurus-plugin-openapi-docs/README.mddemo/docs/intro.mdx
git add .
git commit -m "Prepare release vX.Y.Z"Open a pull request targeting main. The PR title should follow the format: (release) vX.Y.Z.
Once the release PR is merged to main, the release.yaml GitHub Action:
- Checks if the version tag already exists (skips if it does)
- Installs dependencies and builds packages
- Publishes packages to npm
- Creates and pushes a git tag (
vX.Y.Z)
Important: Do not manually publish or create tags. The workflow handles this automatically.
Beta releases follow a separate workflow on the v3.0.0 branch (or other designated beta branches):
- Use
betamajororbetapatchto bump versions - Generate changelog with
yarn release:changelog - Merge to the beta branch
- The
release-beta.yamlworkflow publishes with thebetanpm tag
Users install beta versions with:
npm install docusaurus-plugin-openapi-docs@beta| Issue | Solution |
|---|---|
| Release skipped | Version tag already exists; bump to a new version |
| Changelog empty | No commits between latest tag and main; verify remote is configured |
| Publish failed | Check npm token in GitHub secrets (NPM_AUTH_TOKEN) |
| Tag already exists | A previous release used this version; bump again |
- Triage each report to figure out whether it's a question, documentation request, or bug.
- Investigate carefully to confirm the problem is within this project and not caused by user error, dependency mismatches, or other external factors.
- Consider how a fix might affect existing features and avoid any regression or breaking change.
- Start by checking if the contribution updates documentation, fixes a bug, or adds or enhances a feature.
- Ensure the proposal fits the scope of the project and doesn't duplicate existing docs or functionality.
- Provide a summary of whether the pull request is ready to merge or what changes are still needed from the contributor.
- Consider how merging the pull request might affect existing features and make sure it does not introduce regressions or breaking changes.