TechDocs CLI

管理 TechDocs 站点的实用命令行界面Backstage.

https://backstage.io/docs/features/techdocs/

功能

支持在 CI/CD 工作流程中生成和发布文档网站。

techdocs-cli --help
Usage: techdocs-cli [options] [command]

Options:
  -V, --version output the version number
  -h, --help display help for command

Commands:
  generate|build [options]  Generate TechDocs documentation site using mkdocs.
  publish [options]         Publish generated TechDocs site to an external storage AWS S3,
                            Google GCS, etc.
  serve:mkdocs [options]    Serve a documentation project locally using mkdocs serve.
  serve [options]           Serve a documentation project locally in a Backstage app-like
                            environment
  help [command]            display help for command

安装

您可以随时使用npx运行最新版本的techdocs-cli-

npx @techdocs/cli [command]

或者使用npm-

npm install -g @techdocs/cli
techdocs-cli [command]

使用方法

###在类似 Backstage 的环境中本地预览 TechDocs 站点

techdocs-cli serve

A preview of techdocs-cli serve command

默认情况下，Docker 和技术文档容器来确保所有依赖项都已安装。不过，可以使用--no-docker旗子

该命令启动两个本地服务器--端口为 8000 的 MkDocs 预览服务器和端口为 3000 的 Backstage 应用程序服务器。 Backstage 应用程序有一个自定义的 TechDocs API 实现，它使用 MkDocs 预览服务器作为代理来获取生成的文档文件和资产。

Backstage 实例的外观和行为可能与提供的预览应用程序不同。要使用不同的应用程序预览文档，请使用--preview-app-bundle-path通常情况下，一个dist或build目录。

注意：当使用自定义techdocsdocker 映像，确保入口点也是ENTRYPOINT ["mkdocs"]或用--docker-entrypoint.

命令参考：

Usage: techdocs-cli serve [options]

Serve a documentation project locally in a Backstage app-like environment

Options:
  -i, --docker-image <DOCKER_IMAGE>           The mkdocs docker container to use (default: "spotify/techdocs")
  --docker-entrypoint <DOCKER_ENTRYPOINT>     Override the image entrypoint
  --docker-option <DOCKER_OPTION...>          Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
                                              (can be added multiple times).
  --no-docker Do not use Docker, use MkDocs executable in current user environment.
  --mkdocs-parameter-clean Pass "--clean" parameter to mkdocs server running in containerized environment.
  --mkdocs-parameter-dirtyreload Pass "--dirtyreload" parameter to mkdocs server running in containerized environment.
  --mkdocs-parameter-strict Pass "--strict" parameter to mkdocs server running in containerized environment.
  --mkdocs-port <PORT>                        Port for MkDocs server to use (default: "8000")
  --preview-app-bundle-path <PATH_TO_BUNDLE>  Preview documentation using a web app other than the included one.
  --preview-app-port <PORT>                   Port where the preview will be served.
                                              Can only be used with "--preview-app-bundle-path". (default: "3000")
  -c, --mkdocs-config-file-name <FILENAME>    Yaml file to use as config by mkdocs.
  -v --verbose Enable verbose output. (default: false)
  -h, --help display help for command

从文件项目生成 TechDocs 站点

techdocs-cli generate

别名：techdocs-cli build

生成命令使用@backstage/plugin-techdocs-nodeBackstage 应用程序还可以生成和发布 TechDocs 站点，前提是techdocs.builder设置为'local'于app-config.yaml请看配置参考.

默认情况下，该命令使用 Docker 和技术文档容器但可以使用--no-docker旗子

命令参考：

techdocs-cli generate --help
Usage: techdocs-cli generate|build [options]

Generate TechDocs documentation site using MkDocs.

Options:
  --source-dir <PATH>             Source directory containing mkdocs.yml and docs/ directory. (default: ".")
  --output-dir <PATH>             Output directory containing generated TechDocs site. (default: "./site/")
  --docker-image <DOCKER_IMAGE>   The mkdocs docker container to use (default: "spotify/techdocs:v1.0.3")
  --no-pull Do not pull the latest docker image
  --no-docker Do not use Docker, use MkDocs executable and plugins in current user environment.
  --techdocs-ref <HOST_TYPE:URL>  The repository hosting documentation source files e.g.
                                  url:https://ghe.mycompany.net.com/org/repo.
                                  This value is same as the backstage.io/techdocs-ref annotation of the corresponding
                                  Backstage entity.
                                  It is completely fine to skip this as it is only being used to set repo_url in mkdocs.yml
                                  if not found.
  --etag <ETAG>                   A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
                                  in techdocs_metadata.json.
  --defaultPlugin <PLUGIN_NAME>   Plugins which should be added automatically to the mkdocs.yaml file. (default: [])
  --omitTechdocsCoreMkdocsPlugin An option to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
                                  Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
  --legacyCopyReadmeMdToIndexMd Attempt to ensure an index.md exists falling back to using <docs-dir>/README.md or README.md
                                  in case a default <docs-dir>/index.md is not provided. (default: false)
  --runAsDefaultUser Bypass setting the container user as the same user and group id as host for Linux and MacOS (default: false)
  -v --verbose Enable verbose output. (default: false)
  -h, --help display help for command

发布生成的 TechDocs 站点

techdocs-cli publish --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --entity <namespace/kind/name>

生成 TechDocs 站点后，使用techdocs-cli generate然后，使用发布命令将静态生成的文件上传到云存储(AWS/GCS)桶或(Azure)容器中，您的 Backstage 应用程序可以读取这些文件。

的值为--entity必须是生成的 TechDocs 站点所属的 Backstage 实体。您可以在实体的catalog-info.yaml文件中缺少命名空间。catalog-info.yaml使用default存储桶中使用的目录结构是namespace/kind/name/<files>.

请注意，数值是区分大小写的，例如--entity是default/Component/<entityName>.

命令参考：

Usage: techdocs-cli publish [options]

Publish generated TechDocs site to an external storage AWS S3, Google GCS, etc.

Options:
  --publisher-type <TYPE>                                       (Required always) awsS3 | googleGcs | azureBlobStorage | openStackSwift - same as techdocs.publisher.type in Backstage app-config.yaml
  --storage-name <BUCKET/CONTAINER NAME>                        (Required always) In case of AWS/GCS, use the bucket name. In case of Azure, use container name. Same as
                                                                techdocs.publisher.[TYPE].bucketName
  --entity <NAMESPACE/KIND/NAME>                                (Required always) Entity uid separated by / in namespace/kind/name order (case-sensitive). Example: default/Component/myEntity
  --legacyUseCaseSensitiveTripletPaths Publishes objects with cased entity triplet prefix when set (e.g. namespace/Kind/name). Only use if your TechDocs backend is configured
                                                                the same way. (default: false)
  --azureAccountName <AZURE ACCOUNT NAME>                       (Required for Azure) specify when --publisher-type azureBlobStorage
  --azureAccountKey <AZURE ACCOUNT KEY>                         Azure Storage Account key to use for authentication. If not specified, you must set AZURE_TENANT_ID, AZURE_CLIENT_ID &
                                                                AZURE_CLIENT_SECRET as environment variables.
  --awsRoleArn <AWS ROLE ARN>                                   Optional AWS ARN of role to be assumed.
  --awsEndpoint <AWS ENDPOINT>                                  Optional AWS endpoint to send requests to.
  --awsProxy <HTTPS Proxy>                                      Optional Proxy to use for AWS requests.
  --awsS3sse <AWS SSE>                                          Optional AWS S3 Server Side Encryption.
  --awsS3ForcePathStyle Optional AWS S3 option to force path style.
  --awsBucketRootPath <AWS BUCKET ROOT PATH>                    Optional sub-directory to store files in Amazon S3
  --osCredentialId <OPENSTACK SWIFT APPLICATION CREDENTIAL ID>  (Required for OpenStack) specify when --publisher-type openStackSwift
  --osSecret <OPENSTACK SWIFT APPLICATION CREDENTIAL SECRET>    (Required for OpenStack) specify when --publisher-type openStackSwift
  --osAuthUrl <OPENSTACK SWIFT AUTHURL>                         (Required for OpenStack) specify when --publisher-type openStackSwift
  --osSwiftUrl <OPENSTACK SWIFT SWIFTURL>                       (Required for OpenStack) specify when --publisher-type openStackSwift
  --gcsBucketRootPath <GCS BUCKET ROOT PATH>                    Optional sub-directory to store files in Google cloud storage
  --directory <PATH>                                            Path of the directory containing generated files to publish (default: "./site/")
  -h, --help display help for command

从代理后面发布

对于试图在代理后发布 TechDocs 内容的用户，TechDocs CLI 可利用global-agent以导航代理成功连接到该位置。要启用global-agent在运行 techdocs-cli 命令之前，需要设置以下变量：

export GLOBAL_AGENT_HTTPS_PROXY=${HTTP_PROXY}
export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}

为不区分大小写的访问迁移内容

在测试版 TechDocs (v[0.11.0])，TechDocs 使用区分大小写的实体三元组(例如default/API/name/index.html这就造成了一种限制，即要读取/渲染 TechDocs 内容，必须在 Backstage URL 中使用这种确切的情况。截至v[0.11.0]在 TechDocs 插件中，允许在 URL 中使用任何大小写(例如："......")。default/api/name)，与目录插件的行为相匹配。

使用 TechDocs 创建的Backstage实例v[0.11.0]或更高版本的 TechDocs 升级到此版本时，则不需要此命令。migrate命令可在部署前使用，以确保文档仍可访问，而无需重建所有文档。

在升级到v[0.11.0]或更大，运行此命令可将所有资产复制为小写的三字母等价物，就像这样：

techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose

一旦完成迁移并部署了升级版的 Backstage 插件，就可以通过重新运行命令来清理遗留的、大小写敏感的三联体文件，并使用--removeOriginal标记通过，这移动(注意：这会删除文件，因此是一种破坏性操作，应谨慎执行。

techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose

之后，将 TechDocs CLI 更新为v[0.7.0]以确保进一步发布时使用小写实体三元组。

注意：该命令的参数与publish命令，具体取决于您选择的存储提供商。运行techdocs-cli migrate --help了解详情。

验证

您需要确保您的环境能够与目标云提供商进行身份验证。techdocs-cli使用 AWS (v3)、Google Cloud 和 Azure 提供的官方 Node.js 客户端。您可以使用环境变量和/或其他方式进行身份验证 (~/.aws/credentials,~/.config/gcloud等等)。

根据您的云存储提供商，请参阅以下文档中的身份验证部分。

Google Cloud Storage * AWS S3 * Azure Blob Storage

发展

欢迎您为 TechDocs CLI 做出贡献，以改进它并支持新功能！查看项目阅读说明了解更多信息。

功能​

安装​

使用方法​

从文件项目生成 TechDocs 站点​

发布生成的 TechDocs 站点​

从代理后面发布​

为不区分大小写的访问迁移内容​

验证​

发展​

功能

安装

使用方法

从文件项目生成 TechDocs 站点

发布生成的 TechDocs 站点

从代理后面发布

为不区分大小写的访问迁移内容

验证

发展