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

Merge pull request #18047 from backstage/docs/git-archive-export-ignore

Browse Source 
[Documentation] Note URL Reader `export-ignore` limitations
This commit is contained in:
Johan Haals
2023-06-02 10:14:30 +02:00
committed by GitHub
parent baa4acbded 43dc492bc4
commit 53baa25a78
2 changed files with 27 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/troubleshooting.md
+17 -4
View File
@@ -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
docs/plugins/url-reader.md
+10
View File
@@ -106,6 +106,16 @@ directly be used with a URL. Some example usages -
Catalog using the `search` method to find files for a location URL containing
a glob pattern.
Note that URL Readers which target git-based version control systems may, under
the hood, leverage the ability to create tar archives based on a specific git
commit-ish. A consequence of this is that files and directories configured with
[the `export-ignore` attribute](https://git-scm.com/docs/gitattributes#_creating_an_archive)
via `.gitattributes` will not be visible to the URL reader when using the
`readTree` or `search` methods.
Be aware of this limitation and ensure that end-users of your plugin are also
aware via, for example, documentation.
## Writing a new URL Reader
If the available URL Readers are not sufficient for your use case and you want