PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
Incompatibility with LunaticMuch/docusaurus-terminology plugin
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.1k
- Forks
- 315
- Avg merge
- 7d 5h
- Merged PRs (30d)
- 7
Description
Describe the bug
docusaurus-openapi-docs appears to be incompatible with LunaticMuch/docusaurus-terminology plugin. Although I don't assume the root cause is in PAN/docusuarus-openapi-docs, the fault reported is from here, and so I report here first.
Link to Terminology Plugin: https://github.com/LunaticMuch/docusaurus-terminology
I have raised an issue on docusaurus-terminology: https://github.com/LunaticMuch/docusaurus-terminology/issues/35
Expected behavior
Expect both plugins to work together
Current behavior
PAN/docusaurus-openapi-docs works fine under Docusaurus 3.7.0, however once LunaticMuch/docusaurus-terminology is installed, openapi-docs fails to build
[ERROR] TypeError: sections[sectionIndex].startsWith is not a function
at clean (/Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/utils.js:57:37)
at createHeading (/Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createHeading.js:14:41)
at Object.createInfoPageMD [as info] (/Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/index.js:68:43)
at /Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:230:56
at Array.map (<anonymous>)
at generateApiDocs (/Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:226:17)
at async /Users/user/3.7Test/core/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:498:15
[INFO] Docusaurus version: 3.7.0
Node version: v22.11.0
verbose 2.866127917 Error: Command failed with exit code 1.
at ProcessTermError.ExtendableBuiltin (/usr/local/lib/node_modules/yarn/lib/cli.js:721:66)
at ProcessTermError.MessageError (/usr/local/lib/node_modules/yarn/lib/cli.js:750:123)
at new ProcessTermError (/usr/local/lib/node_modules/yarn/lib/cli.js:790:113)
at /usr/local/lib/node_modules/yarn/lib/cli.js:34408:30
at Generator.throw (<anonymous>)
at step (/usr/local/lib/node_modules/yarn/lib/cli.js:310:30)
at /usr/local/lib/node_modules/yarn/lib/cli.js:323:13
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
error Command failed with exit code 1.
The LunaticMuch/docusaurus-terminology plugin appears to work as intended to create the glossary etc
Steps to reproduce
- Bootstrap a 3.7.0 Dosusuarus site and install PAN/docusaurus-openapi-docs
- Add LunaticMuch/docusaurus-terminology
- Build docusuarus-openapi-docs as per standard and observe above error
Context
I run a site which is primarily used for API documentation and as such openapi-docs is critical. However as the site is very domain specific there is a large amount of domain specific terminology. Currently I have a glossary which is injected at the bottom of each page, however it would be great to have the ability to hover and having a terminology pop-up would be an amazing improvement in the user documentation
For now, having terminology pop up on the static MD pages is a good start. Ultimately though I would love to have the ability to inject terminology popup's into the API docs as well - thus if we have a specific term in the API, we can provided a definition as a hover popup
Your Environment
- Version used: docusaurus-openapi-docs: 4.3.7; Docusaurus 3.7.0; docusaurus-terminology: 1.5.0
- Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Node.js 22.14.0
- Operating System and version (desktop or mobile):
- Link to your project:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the failure with Docusaurus 3.7.0, docusaurus-openapi-docs 4.3.7, and docusaurus-terminology 1.5.0, then inspect lib/markdown/utils.js and lib/markdown/createHeading.js around the reported clean and createHeading calls. Done means the site builds successfully with both plugins while preserving the terminology plugin behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100