Merge branch 'master' of github.com:backstage/backstage into adamdmharvey/fix-docs

Signed-off-by: Adam Harvey <adaharve@cisco.com>

docs/features/techdocs/how-to-guides.md

@@ -491,7 +491,7 @@ plugins:
 
 The `docs/index.md` can for example have the following content:
 
-```
+```markdown
 # ${{ values.component_id }}
 
 ${{ values.description }}
@@ -509,8 +509,8 @@ Done! You now have support for TechDocs in your own software template!
 
 ## How to enable iframes in TechDocs
 
-TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to sanitize
-HTML and prevent XSS attacks.
+TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to
+sanitize HTML and prevent XSS attacks.
 
 It's possible to allow some iframes based on a list of allowed hosts. To do
 this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts`
@@ -530,20 +530,20 @@ This way, all iframes where the host in the src attribute is in the
 
 ## How to add Mermaid support in TechDocs
 
-To add `Mermaid` support in Techdocs, you can use [`kroki`](https://kroki.io)
+To add `Mermaid` support in TechDocs, you can use [`kroki`](https://kroki.io)
 that creates diagrams from Textual descriptions. It is a single rendering
 gateway for all popular diagrams-as-a-code tools. It supports an enormous number
 of diagram types.
 
-1. **Create and Publish docker image:** Create the docker image from the
-   following Dockerfile and publish it to DockerHub.
+1. **Create and Publish Docker image:** Create the Docker image from the
+   following `Dockerfile` and publish it to DockerHub.
 
 ```docker
-FROM python:3.8-alpine
+FROM python:3.10-alpine
 
 RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig
 
-RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.1.7
+RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0
 
 RUN pip install mkdocs-kroki-plugin
 
@@ -551,7 +551,7 @@ ENTRYPOINT [ "mkdocs" ]
 ```
 
 Create a repository in your DockerHub and run the below command in the same
-folder where your Dockerfile is present:
+folder where your `Dockerfile` is present:
 
 ```shell
 docker build . -t dockerHub_Username/repositoryName:tagName
@@ -559,7 +559,7 @@ docker build . -t dockerHub_Username/repositoryName:tagName
 
 Once the docker image is ready, push it to DockerHub.
 
-2. **Update app-config.yaml:** So that when your app generates techdocs, it will
+2. **Update app-config.yaml:** So that when your app generates TechDocs, it will
    pull your docker image from DockerHub.
 
 ```python
@@ -573,7 +573,7 @@ techdocs:
     type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
 ```
 
-3. **Add the `kroki` plugin in mkdocs.yml:**
+3. **Add the `kroki` plugin in `mkdocs.yml`:**
 
 ```yml
 plugins:
@@ -588,7 +588,7 @@ plugins:
 > instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config)
 > for more plugin configuration details.
 
-4. **Add mermaid code into techdocs:**
+4. **Add mermaid code into TechDocs:**
 
 ````md
 ```kroki-mermaid

docs/features/techdocs/troubleshooting.md

@@ -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