@backstage/plugin-techdocs-backend 2.3.0-next.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @backstage/plugin-techdocs-backend
 
+## 2.3.0
+
+### Minor Changes
+
+- ee97130: Added support for `techdocs.generator.pullOptions` when pulling the TechDocs generator Docker image from private registries that require authentication.
+- 62d1a6f: Added `techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins` configuration option, allowing operators to extend the set of permitted MkDocs plugins during TechDocs generation.
+
+### Patch Changes
+
+- 932986c: Improve validation of TechDocs static content paths.
+- 736d84e: Use locale-insensitive Unicode casing for consistent string handling across environments.
+- 1b0e277: Improved path validation for TechDocs content serving.
+- Updated dependencies
+  - @backstage/integration@2.1.2
+  - @backstage/catalog-client@1.16.2
+  - @backstage/catalog-model@1.10.1
+  - @backstage/plugin-techdocs-node@2.0.0
+  - @backstage/config@1.3.9
+  - @backstage/backend-plugin-api@1.10.1
+  - @backstage/plugin-catalog-node@2.2.5
+
+## 2.3.0-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/plugin-techdocs-node@1.16.0-next.1
+  - @backstage/config@1.3.9-next.0
+  - @backstage/catalog-client@1.16.2-next.1
+  - @backstage/plugin-catalog-node@2.2.5-next.1
+  - @backstage/backend-plugin-api@1.10.1-next.1
+  - @backstage/integration@2.1.2-next.1
+
 ## 2.3.0-next.0
 
 ### Minor Changes

package/config.schema.json

@@ -83,6 +83,13 @@
                   },
                   "description": "List of additional MkDocs configuration keys to allow beyond the default safe allowlist. This can introduce security vulnerabilities.\n\nWARNING: Some MkDocs configuration keys can execute arbitrary code. For example, the 'hooks' key allows running arbitrary Python code during documentation generation. Only use this in trusted environments where all mkdocs.yml files are audited."
                 },
+                "dangerouslyAllowAdditionalPlugins": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "List of additional MkDocs plugins to allow beyond the default set. Plugins not in this list or the default set will be removed from mkdocs.yml before documentation generation.\n\nWARNING: Some MkDocs plugins can make outbound HTTP requests or execute arbitrary code during documentation generation. Only allow plugins that have been audited for use in your environment, including the configuration options that documentation authors can supply."
+                },
                 "disableExternalFonts": {
                   "type": "boolean",
                   "description": "Disable external fonts for all TechDocs sites. If not set, the default value is false. If set to true, the external font will be disabled for all TechDocs sites. If set to false, the external font will be enabled for all TechDocs sites."

package/dist/service/DocsSynchronizer.cjs.js

@@ -154,7 +154,7 @@ class DocsSynchronizer {
       "techdocs.legacyUseCaseSensitiveTripletPaths"
     ) || false;
     const tripletPath = `${namespace}/${kind}/${name}`;
-    const entityTripletPath = `${legacyPathCasing ? tripletPath : tripletPath.toLocaleLowerCase("en-US")}`;
+    const entityTripletPath = `${legacyPathCasing ? tripletPath : tripletPath.toLowerCase()}`;
     try {
       const [sourceMetadata, cachedMetadata] = await Promise.all([
         this.publisher.fetchTechDocsMetadata({ namespace, kind, name }),

package/dist/service/DocsSynchronizer.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"DocsSynchronizer.cjs.js","sources":["../../src/service/DocsSynchronizer.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DEFAULT_NAMESPACE,\n  Entity,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { NotFoundError, toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport {\n  GeneratorBuilder,\n  PreparerBuilder,\n  PublisherBase,\n} from '@backstage/plugin-techdocs-node';\nimport pLimit, { Limit } from 'p-limit';\nimport { PassThrough } from 'node:stream';\nimport * as winston from 'winston';\nimport { TechDocsCache } from '../cache';\nimport {\n  BuildMetadataStorage,\n  DocsBuilder,\n  shouldCheckForUpdate,\n} from '../DocsBuilder';\nimport { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';\n\nexport type DocsSynchronizerSyncOpts = {\n  log: (message: string) => void;\n  error: (e: Error) => void;\n  finish: (result: { updated: boolean }) => void;\n};\n\nexport class DocsSynchronizer {\n  private readonly publisher: PublisherBase;\n  private readonly logger: LoggerService;\n  private readonly buildLogTransport?: winston.transport;\n  private readonly config: Config;\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n  private readonly cache: TechDocsCache | undefined;\n  private readonly buildLimiter: Limit;\n\n  constructor({\n    publisher,\n    logger,\n    buildLogTransport,\n    config,\n    scmIntegrations,\n    cache,\n  }: {\n    publisher: PublisherBase;\n    logger: LoggerService;\n    buildLogTransport?: winston.transport;\n    config: Config;\n    scmIntegrations: ScmIntegrationRegistry;\n    cache: TechDocsCache | undefined;\n  }) {\n    this.config = config;\n    this.logger = logger;\n    this.buildLogTransport = buildLogTransport;\n    this.publisher = publisher;\n    this.scmIntegrations = scmIntegrations;\n    this.cache = cache;\n\n    // Single host/process: limit concurrent builds up to 10 at a time.\n    this.buildLimiter = pLimit(10);\n  }\n\n  async doSync({\n    responseHandler: { log, error, finish },\n    entity,\n    preparers,\n    generators,\n  }: {\n    responseHandler: DocsSynchronizerSyncOpts;\n    entity: Entity;\n    preparers: PreparerBuilder;\n    generators: GeneratorBuilder;\n  }) {\n    // create a new logger to log data to the caller\n    const taskLogger = winston.createLogger({\n      level: process.env.LOG_LEVEL || 'info',\n      format: winston.format.combine(\n        winston.format.colorize(),\n        winston.format.timestamp(),\n        winston.format.simple(),\n      ),\n      defaultMeta: {},\n    });\n\n    // create an in-memory stream to forward logs to the event-stream\n    const logStream = new PassThrough();\n    logStream.on('data', async data => {\n      log(data.toString().trim());\n    });\n\n    taskLogger.add(new winston.transports.Stream({ stream: logStream }));\n    if (this.buildLogTransport) {\n      taskLogger.add(this.buildLogTransport);\n    }\n\n    // check if the last update check was too recent\n    if (!shouldCheckForUpdate(entity.metadata.uid!)) {\n      finish({ updated: false });\n      return;\n    }\n\n    let foundDocs = false;\n\n    try {\n      const docsBuilder = new DocsBuilder({\n        preparers,\n        generators,\n        publisher: this.publisher,\n        logger: taskLogger,\n        entity,\n        config: this.config,\n        scmIntegrations: this.scmIntegrations,\n        logStream,\n        cache: this.cache,\n      });\n\n      const interval = setInterval(() => {\n        taskLogger.info(\n          'The docs building process is taking a little bit longer to process this entity. Please bear with us.',\n        );\n      }, 10000);\n      const updated = await this.buildLimiter(() => docsBuilder.build());\n      clearInterval(interval);\n\n      if (!updated) {\n        finish({ updated: false });\n        return;\n      }\n    } catch (e) {\n      const buildError = toError(e);\n      const msg = `Failed to build the docs page for entity ${stringifyEntityRef(\n        entity,\n      )}: ${buildError.message}`;\n      taskLogger.error(msg);\n      this.logger.error(msg, buildError);\n      error(buildError);\n      return;\n    }\n\n    // With a maximum of ~5 seconds wait, check if the files got published and if docs will be fetched\n    // on the user's page. If not, respond with a message asking them to check back later.\n    // The delay here is to make sure GCS/AWS/etc. registers newly uploaded files which is usually <1 second\n    for (let attempt = 0; attempt < 5; attempt++) {\n      if (await this.publisher.hasDocsBeenGenerated(entity)) {\n        foundDocs = true;\n        break;\n      }\n      await new Promise(r => setTimeout(r, 1000));\n    }\n    if (!foundDocs) {\n      this.logger.error(\n        'Published files are taking longer to show up in storage. Something went wrong.',\n      );\n      error(\n        new NotFoundError(\n          'Sorry! It took too long for the generated docs to show up in storage. Are you sure the docs project is generating an `index.html` file? Otherwise, check back later.',\n        ),\n      );\n      return;\n    }\n\n    finish({ updated: true });\n  }\n\n  async doCacheSync({\n    responseHandler: { finish },\n    discovery,\n    token,\n    entity,\n  }: {\n    responseHandler: DocsSynchronizerSyncOpts;\n    discovery: DiscoveryService;\n    token: string | undefined;\n    entity: Entity;\n  }) {\n    // Check if the last update check was too recent.\n    if (!shouldCheckForUpdate(entity.metadata.uid!) || !this.cache) {\n      finish({ updated: false });\n      return;\n    }\n\n    // Fetch techdocs_metadata.json from the publisher and from cache.\n    const baseUrl = await discovery.getBaseUrl('techdocs');\n    const namespace = entity.metadata?.namespace || DEFAULT_NAMESPACE;\n    const kind = entity.kind;\n    const name = entity.metadata.name;\n    const legacyPathCasing =\n      this.config.getOptionalBoolean(\n        'techdocs.legacyUseCaseSensitiveTripletPaths',\n      ) || false;\n    const tripletPath = `${namespace}/${kind}/${name}`;\n    const entityTripletPath = `${\n      legacyPathCasing ? tripletPath : tripletPath.toLocaleLowerCase('en-US')\n    }`;\n    try {\n      const [sourceMetadata, cachedMetadata] = await Promise.all([\n        this.publisher.fetchTechDocsMetadata({ namespace, kind, name }),\n        fetch(\n          `${baseUrl}/static/docs/${entityTripletPath}/techdocs_metadata.json`,\n          {\n            headers: token ? { Authorization: `Bearer ${token}` } : {},\n          },\n        ).then(\n          f =>\n            f.json().catch(() => undefined) as ReturnType<\n              PublisherBase['fetchTechDocsMetadata']\n            >,\n        ),\n      ]);\n\n      // If build timestamps differ, merge their files[] lists and invalidate all objects.\n      if (sourceMetadata.build_timestamp !== cachedMetadata.build_timestamp) {\n        const files = [\n          ...new Set([\n            ...(sourceMetadata.files || []),\n            ...(cachedMetadata.files || []),\n          ]),\n        ].map(f => `${entityTripletPath}/${f}`);\n        await this.cache.invalidateMultiple(files);\n        finish({ updated: true });\n      } else {\n        finish({ updated: false });\n      }\n    } catch (e) {\n      // In case of error, log and allow the user to go about their business.\n      this.logger.error(\n        `Error syncing cache for ${entityTripletPath}: ${toError(e).message}`,\n      );\n      finish({ updated: false });\n    } finally {\n      // Update the last check time for the entity\n      new BuildMetadataStorage(entity.metadata.uid!).setLastUpdated();\n    }\n  }\n}\n"],"names":["pLimit","winston","PassThrough","shouldCheckForUpdate","DocsBuilder","toError","stringifyEntityRef","NotFoundError","DEFAULT_NAMESPACE","BuildMetadataStorage"],"mappings":"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"}
+{"version":3,"file":"DocsSynchronizer.cjs.js","sources":["../../src/service/DocsSynchronizer.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  DEFAULT_NAMESPACE,\n  Entity,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { NotFoundError, toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport {\n  GeneratorBuilder,\n  PreparerBuilder,\n  PublisherBase,\n} from '@backstage/plugin-techdocs-node';\nimport pLimit, { Limit } from 'p-limit';\nimport { PassThrough } from 'node:stream';\nimport * as winston from 'winston';\nimport { TechDocsCache } from '../cache';\nimport {\n  BuildMetadataStorage,\n  DocsBuilder,\n  shouldCheckForUpdate,\n} from '../DocsBuilder';\nimport { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';\n\nexport type DocsSynchronizerSyncOpts = {\n  log: (message: string) => void;\n  error: (e: Error) => void;\n  finish: (result: { updated: boolean }) => void;\n};\n\nexport class DocsSynchronizer {\n  private readonly publisher: PublisherBase;\n  private readonly logger: LoggerService;\n  private readonly buildLogTransport?: winston.transport;\n  private readonly config: Config;\n  private readonly scmIntegrations: ScmIntegrationRegistry;\n  private readonly cache: TechDocsCache | undefined;\n  private readonly buildLimiter: Limit;\n\n  constructor({\n    publisher,\n    logger,\n    buildLogTransport,\n    config,\n    scmIntegrations,\n    cache,\n  }: {\n    publisher: PublisherBase;\n    logger: LoggerService;\n    buildLogTransport?: winston.transport;\n    config: Config;\n    scmIntegrations: ScmIntegrationRegistry;\n    cache: TechDocsCache | undefined;\n  }) {\n    this.config = config;\n    this.logger = logger;\n    this.buildLogTransport = buildLogTransport;\n    this.publisher = publisher;\n    this.scmIntegrations = scmIntegrations;\n    this.cache = cache;\n\n    // Single host/process: limit concurrent builds up to 10 at a time.\n    this.buildLimiter = pLimit(10);\n  }\n\n  async doSync({\n    responseHandler: { log, error, finish },\n    entity,\n    preparers,\n    generators,\n  }: {\n    responseHandler: DocsSynchronizerSyncOpts;\n    entity: Entity;\n    preparers: PreparerBuilder;\n    generators: GeneratorBuilder;\n  }) {\n    // create a new logger to log data to the caller\n    const taskLogger = winston.createLogger({\n      level: process.env.LOG_LEVEL || 'info',\n      format: winston.format.combine(\n        winston.format.colorize(),\n        winston.format.timestamp(),\n        winston.format.simple(),\n      ),\n      defaultMeta: {},\n    });\n\n    // create an in-memory stream to forward logs to the event-stream\n    const logStream = new PassThrough();\n    logStream.on('data', async data => {\n      log(data.toString().trim());\n    });\n\n    taskLogger.add(new winston.transports.Stream({ stream: logStream }));\n    if (this.buildLogTransport) {\n      taskLogger.add(this.buildLogTransport);\n    }\n\n    // check if the last update check was too recent\n    if (!shouldCheckForUpdate(entity.metadata.uid!)) {\n      finish({ updated: false });\n      return;\n    }\n\n    let foundDocs = false;\n\n    try {\n      const docsBuilder = new DocsBuilder({\n        preparers,\n        generators,\n        publisher: this.publisher,\n        logger: taskLogger,\n        entity,\n        config: this.config,\n        scmIntegrations: this.scmIntegrations,\n        logStream,\n        cache: this.cache,\n      });\n\n      const interval = setInterval(() => {\n        taskLogger.info(\n          'The docs building process is taking a little bit longer to process this entity. Please bear with us.',\n        );\n      }, 10000);\n      const updated = await this.buildLimiter(() => docsBuilder.build());\n      clearInterval(interval);\n\n      if (!updated) {\n        finish({ updated: false });\n        return;\n      }\n    } catch (e) {\n      const buildError = toError(e);\n      const msg = `Failed to build the docs page for entity ${stringifyEntityRef(\n        entity,\n      )}: ${buildError.message}`;\n      taskLogger.error(msg);\n      this.logger.error(msg, buildError);\n      error(buildError);\n      return;\n    }\n\n    // With a maximum of ~5 seconds wait, check if the files got published and if docs will be fetched\n    // on the user's page. If not, respond with a message asking them to check back later.\n    // The delay here is to make sure GCS/AWS/etc. registers newly uploaded files which is usually <1 second\n    for (let attempt = 0; attempt < 5; attempt++) {\n      if (await this.publisher.hasDocsBeenGenerated(entity)) {\n        foundDocs = true;\n        break;\n      }\n      await new Promise(r => setTimeout(r, 1000));\n    }\n    if (!foundDocs) {\n      this.logger.error(\n        'Published files are taking longer to show up in storage. Something went wrong.',\n      );\n      error(\n        new NotFoundError(\n          'Sorry! It took too long for the generated docs to show up in storage. Are you sure the docs project is generating an `index.html` file? Otherwise, check back later.',\n        ),\n      );\n      return;\n    }\n\n    finish({ updated: true });\n  }\n\n  async doCacheSync({\n    responseHandler: { finish },\n    discovery,\n    token,\n    entity,\n  }: {\n    responseHandler: DocsSynchronizerSyncOpts;\n    discovery: DiscoveryService;\n    token: string | undefined;\n    entity: Entity;\n  }) {\n    // Check if the last update check was too recent.\n    if (!shouldCheckForUpdate(entity.metadata.uid!) || !this.cache) {\n      finish({ updated: false });\n      return;\n    }\n\n    // Fetch techdocs_metadata.json from the publisher and from cache.\n    const baseUrl = await discovery.getBaseUrl('techdocs');\n    const namespace = entity.metadata?.namespace || DEFAULT_NAMESPACE;\n    const kind = entity.kind;\n    const name = entity.metadata.name;\n    const legacyPathCasing =\n      this.config.getOptionalBoolean(\n        'techdocs.legacyUseCaseSensitiveTripletPaths',\n      ) || false;\n    const tripletPath = `${namespace}/${kind}/${name}`;\n    const entityTripletPath = `${\n      legacyPathCasing ? tripletPath : tripletPath.toLowerCase()\n    }`;\n    try {\n      const [sourceMetadata, cachedMetadata] = await Promise.all([\n        this.publisher.fetchTechDocsMetadata({ namespace, kind, name }),\n        fetch(\n          `${baseUrl}/static/docs/${entityTripletPath}/techdocs_metadata.json`,\n          {\n            headers: token ? { Authorization: `Bearer ${token}` } : {},\n          },\n        ).then(\n          f =>\n            f.json().catch(() => undefined) as ReturnType<\n              PublisherBase['fetchTechDocsMetadata']\n            >,\n        ),\n      ]);\n\n      // If build timestamps differ, merge their files[] lists and invalidate all objects.\n      if (sourceMetadata.build_timestamp !== cachedMetadata.build_timestamp) {\n        const files = [\n          ...new Set([\n            ...(sourceMetadata.files || []),\n            ...(cachedMetadata.files || []),\n          ]),\n        ].map(f => `${entityTripletPath}/${f}`);\n        await this.cache.invalidateMultiple(files);\n        finish({ updated: true });\n      } else {\n        finish({ updated: false });\n      }\n    } catch (e) {\n      // In case of error, log and allow the user to go about their business.\n      this.logger.error(\n        `Error syncing cache for ${entityTripletPath}: ${toError(e).message}`,\n      );\n      finish({ updated: false });\n    } finally {\n      // Update the last check time for the entity\n      new BuildMetadataStorage(entity.metadata.uid!).setLastUpdated();\n    }\n  }\n}\n"],"names":["pLimit","winston","PassThrough","shouldCheckForUpdate","DocsBuilder","toError","stringifyEntityRef","NotFoundError","DEFAULT_NAMESPACE","BuildMetadataStorage"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CO,MAAM,gBAAA,CAAiB;AAAA,EACX,SAAA;AAAA,EACA,MAAA;AAAA,EACA,iBAAA;AAAA,EACA,MAAA;AAAA,EACA,eAAA;AAAA,EACA,KAAA;AAAA,EACA,YAAA;AAAA,EAEjB,WAAA,CAAY;AAAA,IACV,SAAA;AAAA,IACA,MAAA;AAAA,IACA,iBAAA;AAAA,IACA,MAAA;AAAA,IACA,eAAA;AAAA,IACA;AAAA,GACF,EAOG;AACD,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,iBAAA,GAAoB,iBAAA;AACzB,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AACjB,IAAA,IAAA,CAAK,eAAA,GAAkB,eAAA;AACvB,IAAA,IAAA,CAAK,KAAA,GAAQ,KAAA;AAGb,IAAA,IAAA,CAAK,YAAA,GAAeA,wBAAO,EAAE,CAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,MAAA,CAAO;AAAA,IACX,eAAA,EAAiB,EAAE,GAAA,EAAK,KAAA,EAAO,MAAA,EAAO;AAAA,IACtC,MAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACF,EAKG;AAED,IAAA,MAAM,UAAA,GAAaC,mBAAQ,YAAA,CAAa;AAAA,MACtC,KAAA,EAAO,OAAA,CAAQ,GAAA,CAAI,SAAA,IAAa,MAAA;AAAA,MAChC,MAAA,EAAQA,mBAAQ,MAAA,CAAO,OAAA;AAAA,QACrBA,kBAAA,CAAQ,OAAO,QAAA,EAAS;AAAA,QACxBA,kBAAA,CAAQ,OAAO,SAAA,EAAU;AAAA,QACzBA,kBAAA,CAAQ,OAAO,MAAA;AAAO,OACxB;AAAA,MACA,aAAa;AAAC,KACf,CAAA;AAGD,IAAA,MAAM,SAAA,GAAY,IAAIC,uBAAA,EAAY;AAClC,IAAA,SAAA,CAAU,EAAA,CAAG,MAAA,EAAQ,OAAM,IAAA,KAAQ;AACjC,MAAA,GAAA,CAAI,IAAA,CAAK,QAAA,EAAS,CAAE,IAAA,EAAM,CAAA;AAAA,IAC5B,CAAC,CAAA;AAED,IAAA,UAAA,CAAW,GAAA,CAAI,IAAID,kBAAA,CAAQ,UAAA,CAAW,OAAO,EAAE,MAAA,EAAQ,SAAA,EAAW,CAAC,CAAA;AACnE,IAAA,IAAI,KAAK,iBAAA,EAAmB;AAC1B,MAAA,UAAA,CAAW,GAAA,CAAI,KAAK,iBAAiB,CAAA;AAAA,IACvC;AAGA,IAAA,IAAI,CAACE,yCAAA,CAAqB,MAAA,CAAO,QAAA,CAAS,GAAI,CAAA,EAAG;AAC/C,MAAA,MAAA,CAAO,EAAE,OAAA,EAAS,KAAA,EAAO,CAAA;AACzB,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,SAAA,GAAY,KAAA;AAEhB,IAAA,IAAI;AACF,MAAA,MAAM,WAAA,GAAc,IAAIC,mBAAA,CAAY;AAAA,QAClC,SAAA;AAAA,QACA,UAAA;AAAA,QACA,WAAW,IAAA,CAAK,SAAA;AAAA,QAChB,MAAA,EAAQ,UAAA;AAAA,QACR,MAAA;AAAA,QACA,QAAQ,IAAA,CAAK,MAAA;AAAA,QACb,iBAAiB,IAAA,CAAK,eAAA;AAAA,QACtB,SAAA;AAAA,QACA,OAAO,IAAA,CAAK;AAAA,OACb,CAAA;AAED,MAAA,MAAM,QAAA,GAAW,YAAY,MAAM;AACjC,QAAA,UAAA,CAAW,IAAA;AAAA,UACT;AAAA,SACF;AAAA,MACF,GAAG,GAAK,CAAA;AACR,MAAA,MAAM,UAAU,MAAM,IAAA,CAAK,aAAa,MAAM,WAAA,CAAY,OAAO,CAAA;AACjE,MAAA,aAAA,CAAc,QAAQ,CAAA;AAEtB,MAAA,IAAI,CAAC,OAAA,EAAS;AACZ,QAAA,MAAA,CAAO,EAAE,OAAA,EAAS,KAAA,EAAO,CAAA;AACzB,QAAA;AAAA,MACF;AAAA,IACF,SAAS,CAAA,EAAG;AACV,MAAA,MAAM,UAAA,GAAaC,eAAQ,CAAC,CAAA;AAC5B,MAAA,MAAM,MAAM,CAAA,yCAAA,EAA4CC,+BAAA;AAAA,QACtD;AAAA,OACD,CAAA,EAAA,EAAK,UAAA,CAAW,OAAO,CAAA,CAAA;AACxB,MAAA,UAAA,CAAW,MAAM,GAAG,CAAA;AACpB,MAAA,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,GAAA,EAAK,UAAU,CAAA;AACjC,MAAA,KAAA,CAAM,UAAU,CAAA;AAChB,MAAA;AAAA,IACF;AAKA,IAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,GAAU,CAAA,EAAG,OAAA,EAAA,EAAW;AAC5C,MAAA,IAAI,MAAM,IAAA,CAAK,SAAA,CAAU,oBAAA,CAAqB,MAAM,CAAA,EAAG;AACrD,QAAA,SAAA,GAAY,IAAA;AACZ,QAAA;AAAA,MACF;AACA,MAAA,MAAM,IAAI,OAAA,CAAQ,CAAA,CAAA,KAAK,UAAA,CAAW,CAAA,EAAG,GAAI,CAAC,CAAA;AAAA,IAC5C;AACA,IAAA,IAAI,CAAC,SAAA,EAAW;AACd,MAAA,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,QACV;AAAA,OACF;AACA,MAAA,KAAA;AAAA,QACE,IAAIC,oBAAA;AAAA,UACF;AAAA;AACF,OACF;AACA,MAAA;AAAA,IACF;AAEA,IAAA,MAAA,CAAO,EAAE,OAAA,EAAS,IAAA,EAAM,CAAA;AAAA,EAC1B;AAAA,EAEA,MAAM,WAAA,CAAY;AAAA,IAChB,eAAA,EAAiB,EAAE,MAAA,EAAO;AAAA,IAC1B,SAAA;AAAA,IACA,KAAA;AAAA,IACA;AAAA,GACF,EAKG;AAED,IAAA,IAAI,CAACJ,0CAAqB,MAAA,CAAO,QAAA,CAAS,GAAI,CAAA,IAAK,CAAC,KAAK,KAAA,EAAO;AAC9D,MAAA,MAAA,CAAO,EAAE,OAAA,EAAS,KAAA,EAAO,CAAA;AACzB,MAAA;AAAA,IACF;AAGA,IAAA,MAAM,OAAA,GAAU,MAAM,SAAA,CAAU,UAAA,CAAW,UAAU,CAAA;AACrD,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,QAAA,EAAU,SAAA,IAAaK,8BAAA;AAChD,IAAA,MAAM,OAAO,MAAA,CAAO,IAAA;AACpB,IAAA,MAAM,IAAA,GAAO,OAAO,QAAA,CAAS,IAAA;AAC7B,IAAA,MAAM,gBAAA,GACJ,KAAK,MAAA,CAAO,kBAAA;AAAA,MACV;AAAA,KACF,IAAK,KAAA;AACP,IAAA,MAAM,cAAc,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,IAAI,IAAI,IAAI,CAAA,CAAA;AAChD,IAAA,MAAM,oBAAoB,CAAA,EACxB,gBAAA,GAAmB,WAAA,GAAc,WAAA,CAAY,aAC/C,CAAA,CAAA;AACA,IAAA,IAAI;AACF,MAAA,MAAM,CAAC,cAAA,EAAgB,cAAc,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,QACzD,KAAK,SAAA,CAAU,qBAAA,CAAsB,EAAE,SAAA,EAAW,IAAA,EAAM,MAAM,CAAA;AAAA,QAC9D,KAAA;AAAA,UACE,CAAA,EAAG,OAAO,CAAA,aAAA,EAAgB,iBAAiB,CAAA,uBAAA,CAAA;AAAA,UAC3C;AAAA,YACE,OAAA,EAAS,QAAQ,EAAE,aAAA,EAAe,UAAU,KAAK,CAAA,CAAA,KAAO;AAAC;AAC3D,SACF,CAAE,IAAA;AAAA,UACA,OACE,CAAA,CAAE,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM,KAAA,CAAS;AAAA;AAGlC,OACD,CAAA;AAGD,MAAA,IAAI,cAAA,CAAe,eAAA,KAAoB,cAAA,CAAe,eAAA,EAAiB;AACrE,QAAA,MAAM,KAAA,GAAQ;AAAA,UACZ,uBAAO,GAAA,CAAI;AAAA,YACT,GAAI,cAAA,CAAe,KAAA,IAAS,EAAC;AAAA,YAC7B,GAAI,cAAA,CAAe,KAAA,IAAS;AAAC,WAC9B;AAAA,UACD,GAAA,CAAI,CAAA,CAAA,KAAK,GAAG,iBAAiB,CAAA,CAAA,EAAI,CAAC,CAAA,CAAE,CAAA;AACtC,QAAA,MAAM,IAAA,CAAK,KAAA,CAAM,kBAAA,CAAmB,KAAK,CAAA;AACzC,QAAA,MAAA,CAAO,EAAE,OAAA,EAAS,IAAA,EAAM,CAAA;AAAA,MAC1B,CAAA,MAAO;AACL,QAAA,MAAA,CAAO,EAAE,OAAA,EAAS,KAAA,EAAO,CAAA;AAAA,MAC3B;AAAA,IACF,SAAS,CAAA,EAAG;AAEV,MAAA,IAAA,CAAK,MAAA,CAAO,KAAA;AAAA,QACV,2BAA2B,iBAAiB,CAAA,EAAA,EAAKH,cAAA,CAAQ,CAAC,EAAE,OAAO,CAAA;AAAA,OACrE;AACA,MAAA,MAAA,CAAO,EAAE,OAAA,EAAS,KAAA,EAAO,CAAA;AAAA,IAC3B,CAAA,SAAE;AAEA,MAAA,IAAII,yCAAA,CAAqB,MAAA,CAAO,QAAA,CAAS,GAAI,EAAE,cAAA,EAAe;AAAA,IAChE;AAAA,EACF;AACF;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-backend",
-  "version": "2.3.0-next.0",
+  "version": "2.3.0",
   "description": "The Backstage backend plugin that renders technical documentation for your components",
   "backstage": {
     "role": "backend-plugin",
@@ -75,15 +75,15 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "1.10.1-next.0",
-    "@backstage/catalog-client": "1.16.2-next.0",
-    "@backstage/catalog-model": "1.10.0",
-    "@backstage/config": "1.3.8",
-    "@backstage/errors": "1.3.1",
-    "@backstage/integration": "2.1.2-next.0",
-    "@backstage/plugin-catalog-node": "2.2.5-next.0",
-    "@backstage/plugin-techdocs-node": "1.16.0-next.0",
-    "@backstage/types": "1.2.2",
+    "@backstage/backend-plugin-api": "^1.10.1",
+    "@backstage/catalog-client": "^1.16.2",
+    "@backstage/catalog-model": "^1.10.1",
+    "@backstage/config": "^1.3.9",
+    "@backstage/errors": "^1.3.1",
+    "@backstage/integration": "^2.1.2",
+    "@backstage/plugin-catalog-node": "^2.2.5",
+    "@backstage/plugin-techdocs-node": "^2.0.0",
+    "@backstage/types": "^1.2.2",
     "express": "^4.22.0",
     "express-promise-router": "^4.1.0",
     "fs-extra": "^11.2.0",
@@ -92,9 +92,9 @@
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-defaults": "0.17.9-next.0",
-    "@backstage/backend-test-utils": "1.11.7-next.0",
-    "@backstage/cli": "0.36.6-next.0",
+    "@backstage/backend-defaults": "^0.18.0",
+    "@backstage/backend-test-utils": "^1.11.7",
+    "@backstage/cli": "^0.36.6",
     "@types/express": "^4.17.6",
     "msw": "^2.0.0",
     "supertest": "^7.0.0"