message: Add TechDocs CLI for mkdocs build errors
diff: @@ -5,6 +5,50 @@ sidebar_label: Troubleshooting
  description: Troubleshooting for TechDocs
  ---
  -- TechDocs will fail to clone your docs if you have a git config which overrides
  - the `https` protocol with `ssh` or something else. Make sure to remove your
  - git config locally when you try TechDocs.
  +## Failure to clone
  +
  +TechDocs will fail to clone your docs if you have a git config which overrides
  +the `https` protocol with `ssh` or something else. Make sure to remove your git
  +config locally when you try TechDocs.
  +
  +## MkDocs Build Errors
  +
  +Using the [TechDocs CLI](https://github.com/backstage/techdocs-cli), you can
  +troubleshoot MkDocs build issues locally. Note this requires you have Docker
  +available to launch images. First, `git clone` the target repository locally,
  +then in the root of the repository, run:
  +
  +```
  +npx @techdocs/cli serve
  +```
  +
  +For example, if you have forgotten to put an MkDocs configuration file in your
  +repo, the resulting error will be:
  +
  +```
  +npx: installed 278 in 9.089s
  +[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
  +INFO - Building documentation...
  +
  +Config file '/content/mkdocs.yml' does not exist.
  +```
  +
  +When it works, a local copy of both Backstage and your site will be launched
  +locally:
  +
  +```
  +npx: installed 278 in 9.682s
  +[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
  +INFO - Building documentation...
  +WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
  +INFO - Cleaning site directory
  +DEBUG - Successfully imported extension module "plantuml_markdown".
  +DEBUG - Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension".
  +INFO - Documentation built in 0.23 seconds
  +[I 210115 19:00:45 server:335] Serving on http://0.0.0.0:8000
  +INFO - Serving on http://0.0.0.0:8000
  +[I 210115 19:00:45 handlers:62] Start watching changes
  +INFO - Start watching changes
  +[I 210115 19:00:45 handlers:64] Start detecting changes
  +INFO - Start detecting changes
  +```
  