paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 37 Packages Projects Releases Wiki Activity

Merge pull request #4112 from adamdmharvey/techdocs-troubleshooting

Browse Source 
docs: Add TechDocs troubleshooting
This commit is contained in:
Adam Harvey
2021-01-15 14:50:41 -05:00
committed by GitHub
parent 044bb0899b 33f7fbc5b2
commit 57460cda02
1 changed files with 50 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/troubleshooting.md
+50 -3
View File
@@ -5,6 +5,53 @@ 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
```