TechDocs: documentation template (#1954)

* feat(docs-template): Add docs template to create a standalone docs project

* fix(docs-template): add docs template to mock data

* fix(docs-template): owner of template

* add techdocs-ref to cookiecutter docs project

* delete unused cookiecutter json file

* update docs in default index.md file

* rename from .yaml to .yml to be consistent to docs

* update techdocs-ref to use github protocol

plugins/scaffolder-backend/sample-templates/docs-template/template.yaml

@@ -0,0 +1,29 @@
+apiVersion: backstage.io/v1alpha1
+kind: Template
+metadata:
+  name: docs-template
+  title: Documentation Template
+  description: Create a new standalone documentation project
+  tags:
+    - Experimental
+    - TechDocs
+    - MkDocs
+spec:
+  owner: spotify/techdocs-core
+  templater: cookiecutter
+  type: documentation
+  path: '.'
+  
+  schema:
+    required: 
+      - component_id
+    properties:
+      component_id:
+        title: Name
+        type: string
+        description: Unique name of the component
+      description:
+        title: Description
+        type: string
+        description: Description of the component
+   

plugins/scaffolder-backend/sample-templates/docs-template/{{cookiecutter.component_id}}/component-info.yaml

@@ -0,0 +1,12 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: {{cookiecutter.component_id}}
+  description: {{cookiecutter.description}}
+  annotations:
+    github.com/project-slug: {{cookiecutter.storePath}}
+    backstage.io/techdocs-ref: github:https://github.com/{{cookiecutter.storePath}}
+spec:
+  type: documentation
+  lifecycle: experimental
+  owner: {{cookiecutter.owner}}

plugins/scaffolder-backend/sample-templates/docs-template/{{cookiecutter.component_id}}/docs/index.md

@@ -0,0 +1,28 @@
+## {{ cookiecutter.component_id }}
+
+{{ cookiecutter.description }}
+
+## Getting started
+
+Start write your documentation by adding more markdown (.md) files to this folder (/docs) or replace the content in this file.
+
+## Table of Contents
+
+The Table of Contents on the right is generated automatically based on the hierarchy
+of headings. Only use one H1 (`#` in Markdown) per file.
+
+## Site navigation
+
+For new pages to appear in the left hand navigation you need edit the `mkdocs.yml`
+file in root of your repo. The navigation can also link out to other sites.
+
+Alternatively, if there is no `nav` section in `mkdocs.yml`, a navigation section
+will be created for you. However, you will not be able to use alternate titles for
+pages, or include links to other sites.
+
+Note that MkDocs uses `mkdocs.yml`, not `mkdocs.yaml`, although both appear to work.
+See also <https://www.mkdocs.org/user-guide/configuration/>.
+
+## Support
+
+That's it. If you need support, reach out in [#docs-like-code](https://discord.com/channels/687207715902193673/714754240933003266) on Discord.

plugins/scaffolder-backend/sample-templates/docs-template/{{cookiecutter.component_id}}/mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: {{cookiecutter.component_id}}
+site_description: {{cookiecutter.description}}
+
+nav: 
+  - Introduction: index.md
+
+plugins:
+  - techdocs-core

plugins/scaffolder-backend/scripts/mock-data.sh

@@ -4,6 +4,7 @@ for URL in \
   'react-ssr-template' \
   'springboot-grpc-template' \
   'create-react-app' \
+  'docs-template' \
 ; do \
   curl \
     --location \

plugins/techdocs-backend/src/techdocs/stages/prepare/dir.ts

@@ -43,7 +43,8 @@ export class DirectoryPreparer implements PreparerBase {
 
     const parsedGitLocation = parseGitUrl(target);
     const repositoryTmpPath = path.join(
-      os.tmpdir(),
+      // fs.realpathSync fixes a problem with macOS returning a path that is a symlink
+      fs.realpathSync(os.tmpdir()),
       'backstage-repo',
       parsedGitLocation.source,
       parsedGitLocation.owner,

plugins/techdocs-backend/src/techdocs/stages/prepare/github.ts

@@ -43,7 +43,8 @@ export class GithubPreparer implements PreparerBase {
 
     const parsedGitLocation = parseGitUrl(target);
     const repositoryTmpPath = path.join(
-      os.tmpdir(),
+      // fs.realpathSync fixes a problem with macOS returning a path that is a symlink
+      fs.realpathSync(os.tmpdir()),
       'backstage-repo',
       parsedGitLocation.source,
       parsedGitLocation.owner,