Document URL Reader export-ignore limitations

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
2023-05-31 18:40:00 +02:00
parent 195eaa1f2f
commit 43dc492bc4
2 changed files with 27 additions and 4 deletions
@@ -5,11 +5,24 @@ sidebar_label: Troubleshooting
 description: Troubleshooting for TechDocs
 ---

-## Failure to clone
+## Documentation not found when generating

-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.
+This may happen if you have TechDocs set up using the "out-of-the-box"
+configuration, wherein documentation is built dynamically by the TechDocs
+backend, and your TechDocs files are being pulled from a git-based source
+control management system (e.g. GitHub, BitBucket, etc).
+
+If you experience this, check that TechDocs-related files (e.g. markdown,
+assets, or the `mkdocs.yml` file) are not matched by an `export-ignore`
+attribute in a `.gitattributes` file in the relevant repository.
+
+TechDocs' backend is not able to see such files, and therefore may generate
+partial (or no) TechDocs as a result.
+
+You'll need to reconsider how you distribute tar archives based on your source
+code (and how you prevent internal documentation from being included in those
+archives). Alternatively, you could consider switching to the "recommended"
+TechDocs architecture (documentation generated and published in CI/CD).

 ## MkDocs Build Errors