Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@techdocs/cli

backstage148.2kApache-2.01.9.3

Utility CLI for managing TechDocs sites in Backstage.

backstage, techdocs

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2025 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@techdocs/cli

1.9.3

Patch Changes

1.9.3-next.3

Patch Changes

1.9.3-next.2

Patch Changes

1.9.3-next.1

Patch Changes

1.9.3-next.0

Patch Changes

1.9.2

Patch Changes

1.9.2-next.2

Patch Changes

1.9.2-next.1

Patch Changes

1.9.2-next.0

Patch Changes

1.9.1

Patch Changes

1.9.1-next.2

Patch Changes

1.9.1-next.1

Patch Changes

1.9.1-next.0

Patch Changes

1.9.0

Minor Changes

  • 8de3d2d: Allow configurable optional retries for publisher AWS S3 operations.

Patch Changes

1.9.0-next.3

Patch Changes

1.9.0-next.2

Patch Changes

1.9.0-next.1

Patch Changes

1.9.0-next.0

Minor Changes

  • 8de3d2d: Allow configurable optional retries for publisher AWS S3 operations.

Patch Changes

1.8.25

Patch Changes

1.8.25-next.1

Patch Changes

1.8.25-next.0

Patch Changes

1.8.24

Patch Changes

1.8.24-next.2

Patch Changes

1.8.24-next.1

Patch Changes

1.8.24-next.0

Patch Changes

1.8.22

Patch Changes

1.8.22-next.3

Patch Changes

1.8.22-next.2

Patch Changes

1.8.22-next.1

Patch Changes

1.8.22-next.0

Patch Changes

1.8.20

Patch Changes

1.8.20-next.2

Patch Changes

1.8.20-next.1

Patch Changes

1.8.20-next.0

Patch Changes

1.8.19

Patch Changes

1.8.19-next.2

Patch Changes

1.8.19-next.1

Patch Changes

1.8.19-next.0

Patch Changes

1.8.17

Patch Changes

1.8.17-next.3

Patch Changes

1.8.17-next.2

Patch Changes

1.8.17-next.1

Patch Changes

1.8.17-next.0

Patch Changes

1.8.16

Patch Changes

1.8.16-next.1

Patch Changes

1.8.15-next.0

Patch Changes

1.8.12

Patch Changes

1.8.12-next.3

Patch Changes

1.8.12-next.2

Patch Changes

1.8.12-next.1

Patch Changes

1.8.12-next.0

Patch Changes

1.8.11

Patch Changes

1.8.11-next.1

Patch Changes

1.8.10-next.0

Patch Changes

1.8.9

Patch Changes

1.8.9-next.1

Patch Changes

1.8.9-next.0

Patch Changes

1.8.8

Patch Changes

1.8.7

Patch Changes

1.8.6

Patch Changes

1.8.6-next.2

Patch Changes

1.8.6-next.1

Patch Changes

1.8.5-next.0

Patch Changes

1.8.2

Patch Changes

1.8.2-next.3

Patch Changes

1.8.2-next.2

Patch Changes

1.8.2-next.1

Patch Changes

1.8.2-next.0

Patch Changes

1.8.1

Patch Changes

1.8.1-next.2

Patch Changes

1.8.1-next.1

Patch Changes

1.8.1-next.0

Patch Changes

1.8.0

Minor Changes

  • d15d483: Add command --runAsDefaultUser for @techdocs/cli generate to bypass running the docker builds as host user for macOS and Linux.
  • b2dccad: Support passing additional mkdocs-server CLI parameters (--dirtyreload, --strict and --clean) when run in containerized mode.

Patch Changes

1.8.0-next.3

Patch Changes

1.8.0-next.2

Patch Changes

1.8.0-next.1

Minor Changes

  • b2dccad7b3: Support passing additional mkdocs-server CLI parameters (--dirtyreload, --strict and --clean) when run in containerized mode.

Patch Changes

1.8.0-next.0

Minor Changes

  • d15d483a49: Add command --runAsDefaultUser for @techdocs/cli generate to bypass running the docker builds as host user for macOS and Linux.

Patch Changes

1.7.0

Minor Changes

  • 8600b86820: validate Docker status before running mkdocs server

Patch Changes

1.6.1-next.2

Patch Changes

1.6.1-next.1

Patch Changes

1.6.1-next.0

Patch Changes

1.6.0

Minor Changes

  • d06b30b050: Add possibility to use a mkdocs config file with a different name than mkdocs.<yaml|yml> with the serve command using the--mkdocs-config-file-name` argument

Patch Changes

1.6.0-next.2

Minor Changes

  • d06b30b050: Add possibility to use a mkdocs config file with a different name than mkdocs.<yaml|yml> with the serve command using the--mkdocs-config-file-name` argument

Patch Changes

1.5.2-next.1

Patch Changes

1.5.2-next.0

Patch Changes

1.5.0

Minor Changes

  • 10a86bd4ae12: Add optional config and cli option for techdocs to specify default mkdocs plugins.

Patch Changes

1.5.0-next.3

Patch Changes

1.5.0-next.2

Patch Changes

1.5.0-next.1

Minor Changes

  • 10a86bd4ae12: Add optional config and cli option for techdocs to specify default mkdocs plugins.

Patch Changes

1.4.7-next.0

Patch Changes

1.4.5

Patch Changes

1.4.5-next.2

Patch Changes

1.4.5-next.1

Patch Changes

1.4.5-next.0

Patch Changes

1.4.4

Patch Changes

1.4.4-next.0

Patch Changes

1.4.3

Patch Changes

1.4.3-next.2

Patch Changes

1.4.3-next.1

Patch Changes

1.4.3-next.0

Patch Changes

1.4.2

Patch Changes

1.4.2-next.1

Patch Changes

1.4.2-next.0

Patch Changes

1.4.1

Patch Changes

1.4.1-next.3

Patch Changes

1.4.1-next.2

Patch Changes

1.4.1-next.1

Patch Changes

1.4.1-next.0

Patch Changes

1.4.0

Minor Changes

  • 8e465ce52e2: Running @techdocs/cli generate with the --verbose flag will now print the mkdocs output.
  • ea2bbef1b16: Added support for an HTTPS proxy for techdocs AWS S3 requests

Patch Changes

1.4.0-next.2

Patch Changes

1.4.0-next.1

Minor Changes

  • 8e465ce52e2: Running @techdocs/cli generate with the --verbose flag will now print the mkdocs output.
  • ea2bbef1b16: Added support for an HTTPS proxy for techdocs AWS S3 requests

Patch Changes

1.3.3-next.0

Patch Changes

1.3.2

Patch Changes

  • dd1e37649f: Deprecated getMkDocsYml in favor of getMkdocsYml (lowercase 'd')

  • dcacf94912: Fix proxying to mkdocs

    The domain localhost may point to both 127.0.0.1 and ::1, ipv4 and ipv6 and when node tries to lookup localhost it might prefer ipv6 while mkdocs is only listening on ipv4. This tells node-proxy to target the ipv4 address instead of relying on localhost hostname lookup.

  • 339d9a5b5c: Added support for using a default mkdocs.yml configuration file when none is provided

  • 6e0b6a0d50: Fixed publish command missing awsBucketRootPath option. Fixed publish command having the gcsBucketRootPath option misconfigured, previously returning a boolean vs a string.
  • Updated dependencies

1.3.2-next.2

Patch Changes

1.3.2-next.1

Patch Changes

1.3.2-next.0

Patch Changes

1.3.0

Minor Changes

  • bc18c902a2: Add --preview-app-bundle-path and --preview-app-port options to the serve command enabling previewing with apps other than the provided one

Patch Changes

1.3.0-next.2

Minor Changes

  • bc18c902a2: Add --preview-app-bundle-path and --preview-app-port options to the serve command enabling previewing with apps other than the provided one

Patch Changes

1.2.5-next.1

Patch Changes

1.2.5-next.0

Patch Changes

1.2.4

Patch Changes

1.2.4-next.3

Patch Changes

1.2.4-next.2

Patch Changes

1.2.4-next.1

Patch Changes

1.2.4-next.0

Patch Changes

1.2.3

Patch Changes

1.2.3-next.1

Patch Changes

1.2.3-next.0

Patch Changes

1.2.2

Patch Changes

1.2.2-next.2

Patch Changes

1.2.2-next.1

Patch Changes

1.2.2-next.0

Patch Changes

1.2.1

Patch Changes

1.2.1-next.2

Patch Changes

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • 855952db53: Added CLI option --docker-option to allow passing additional options to the docker run command executed my serve and serve:mkdocs.

Patch Changes

1.2.0-next.2

Minor Changes

  • 855952db53: Added CLI option --docker-option to allow passing additional options to the docker run command executed my serve and serve:mkdocs.

1.1.4-next.1

Patch Changes

1.1.4-next.0

Patch Changes

1.1.3

Patch Changes

1.1.3-next.1

Patch Changes

1.1.3-next.0

Patch Changes

1.1.2

Patch Changes

1.1.2-next.2

Patch Changes

1.1.2-next.1

Patch Changes

1.1.2-next.0

Patch Changes

1.1.1

Patch Changes

1.1.1-next.2

Patch Changes

1.1.1-next.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • 733187987b: Removed an undocumented, broken behavior where README.md files would be copied to index.md if it did not exist, leading to broken links in the TechDocs UI.

    WARNING: If you notice 404s in TechDocs after updating, check to make sure that all markdown files referenced in your mkdocs.ymls' nav sections exist. The following flag may be passed to the generate command to temporarily revert to the broken behavior.

    techdocs-cli generate --legacyCopyReadmeMdToIndexMd

Patch Changes

1.1.0-next.1

Minor Changes

  • bcf1a2496c: BREAKING: The default Techdocs behavior will no longer attempt to copy docs/README.md or README.md to docs/index.md (if not found). To retain this behavior in your instance, you can set the following config in your app-config.yaml:

    techdocs:
  generator:
    mkdocs:
      legacyCopyReadmeMdToIndexMd: true

Patch Changes

1.0.1-next.0

Patch Changes

1.0.0

Major Changes

  • b58c70c223: This package has been promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.

Patch Changes

0.8.17

Patch Changes

0.8.17-next.0

Patch Changes

0.8.16

Patch Changes

0.8.15

Patch Changes

  • ed78516480: chore(deps-dev): bump cypress from 7.3.0 to 9.5.0
  • 209fd128e6: Updated usage of github: location types in docs to use url: instead.
  • 61ff215e08: - Adds cypress and cypress-plugin-snapshots as dependencies for integration and visual regression tests.
    • Updates README documentation with instructions for how to run tests.
    • Clarifies output text for prepack script.
  • Updated dependencies

0.8.14

Patch Changes

0.8.13

Patch Changes

0.8.13-next.0

Patch Changes

0.8.12

Patch Changes

0.8.12-next.1

Patch Changes

0.8.12-next.0

Patch Changes

  • 14472509a3: Use a local file dependency for techdocs-cli-embedded-app, to ensure that it's always pulled out of the workspace

0.8.11

Patch Changes

0.8.11-next.0

Patch Changes

0.8.10

Patch Changes

0.8.9

Patch Changes

0.8.8

Patch Changes

0.8.7

Patch Changes

0.8.6

Patch Changes

0.8.5

Patch Changes

  • Reunified the techdocs-cli monorepo code back into the main backstage repo

    See 7288). The changes include some internal refactoring that do not affect functionality beyond the local development setup.

0.8.4

Patch Changes

  • 8333394: The change updated the @backstage/techdocs-common from version 0.9.0 to 0.10.2 and one of the intermediate versions, the 0.10.0, introduced the use of search in context that requires an implementation for the Search API.

    Created a custom techdocs page to disable search in the Reader component, preventing it from using the Search API, as we don't want to provide search in preview mode.

0.8.3

Patch Changes

  • edbb988: Upgrades the techdocs common page to the latest version 0.10.2.

    See @backstage/techdocs-common changelog.

  • db4ebfc: Add an etag flag to the generate command that is stored in the techdocs_metadata.json file.

0.8.2

Patch Changes

  • 8fc7384: Allow to execute techdocs-cli serve using docker techdocs-container on Windows

0.8.1

Patch Changes

  • 0187424: Separate build and publish release steps

0.8.0

Minor Changes

Patch Changes

  • 05f0409: Merge Jobs for Release Pull Requests and Package Publishes

0.7.0

Minor Changes

  • 9d1f8d8: The techdocs-cli publish command will now publish TechDocs content to remote storage using the lowercase'd entity triplet as the storage path. This is in line with the beta release of the TechDocs plugin (v0.11.0).

    If you have been running techdocs-cli prior to this version, you will need to follow this migration guide.

0.6.2

Patch Changes

  • f1bcf1a: Changelog (from v0.6.1 to v0.6.2)

    :bug: Bug Fix

    • techdocs-cli
      • #105 Add azureAccountKey parameter back to the publish command (@emmaindal)

    :house: Internal

    • techdocs-cli-embedded-app
      • #122 chore(deps-dev): bump @types/node from 12.20.20 to 16.7.1 in /packages/techdocs-cli-embedded-app (@dependabot[bot])
      • #120 chore(deps-dev): bump @types/react-dom from 16.9.14 to 17.0.9 in /packages/techdocs-cli-embedded-app (@dependabot[bot])
      • #119 chore(deps-dev): bump @testing-library/user-event from 12.8.3 to 13.2.1 in /packages/techdocs-cli-embedded-app (@dependabot[bot])
      • #118 chore(deps-dev): bump @testing-library/react from 10.4.9 to 12.0.0 (@dependabot[bot])
    • Other

    Committers: 3

    Thank you for contributing ❤️