PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Incompatibility with LunaticMuch/docusaurus-terminology plugin

Open
#1,135 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug reviewing :eyes:
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

  1. Bootstrap a 3.7.0 Dosusuarus site and install PAN/docusaurus-openapi-docs
  2. Add LunaticMuch/docusaurus-terminology
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.