Merge pull request #4983 from adamdmharvey/doco-examples

techdocs: Update example documentation

.github/styles/vocab.txt

@@ -269,6 +269,7 @@ templated
 templater
 templaters
 theia
+thumbsup
 toc
 tolerations
 toolchain

plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md

@@ -4,7 +4,7 @@ This page provides some sample code which may be used in your example component.
 
 This code uses TypeScript, and the Markdown code fence to wrap the code.
 
-```tsx
+```typescript
 const DefaultEntityPage = ({ entity }: { entity: Entity }) => (
   <EntityPageLayout>
     <EntityPageLayout.Content
@@ -20,3 +20,12 @@ const DefaultEntityPage = ({ entity }: { entity: Entity }) => (
   </EntityPageLayout>
 );
 ```
+
+Here is an example of Python code:
+
+```python
+def getUsersInGroup(targetGroup, secure=False):
+
+    if __debug__:
+        print('targetGroup=[' + targetGroup + ']')
+```

plugins/techdocs-backend/examples/documented-component/docs/extensions.md

@@ -0,0 +1,82 @@
+# Plugins & Extensions
+
+Just by including the TechDocs Core Plugin to your MkDocs site included with Backstage,
+you gain the immediate use of a variety of popular plugins and extensions to MkDocs.
+
+For more information and full details of the available features, see the
+[`mkdocs-techdocs-core` repository](https://github.com/backstage/mkdocs-techdocs-core#mkdocs-plugins-and-extensions).
+
+This page provides a demonstration of some of the available features.
+
+## Admonitions
+
+Admonitions are call outs that help catch a users attention.
+
+To define an admonition simply put the following Markdown into your content:
+
+```
+!!! warn
+    Defining admonitions can be addicting.
+```
+
+And they end up looking like this:
+
+!!! warn
+Defining admonitions can be addicting.
+
+!!! note
+You can learn a lot about TechDocs by just visiting the Backstage web site at
+https://backstage.io/docs.
+
+!!! info
+TechDocs is the core feature that supports documentation as code in Backstage.
+
+!!! tip
+Don't forget to spell check your documentation.
+
+## PlantUML
+
+You can create dynamic UML diagrams on the fly by just specifying flow via text,
+using [PlantUML](https://pypi.org/project/plantuml-markdown/).
+
+```plantuml format="svg" classes="uml myDiagram" alt="Backstage sample PlantUML" title="Backstage sample PlantUML" width="500px" height="250px"
+User -> SCMProvider: stores
+TechDocs -> SCMProvider: prepares
+TechDocs -> TechDocs: generates
+TechDocs -> CloudStorage: publishes
+CloudStorage -> Backstage: displays
+```
+
+## Pymdownx Extensions
+
+Pymdownx (Python Markdown extensions) are a variety of smaller additions.
+
+### Details
+
+??? note "What is the answer to life, the universe, and everything? (click me for the answer)"
+The answer is 42.
+
+??? note "What is 4 plus 4?"
+The answer is 8.
+
+???+ note "How do I get support?"
+You can get support by opening an issue in this repository. This detail is open by default
+so it's more easily visible without requiring the user to click to open it.
+
+### Task Lists
+
+Automatic rendering of Markdown task lists.
+
+- [x] Phase 1
+- [x] Phase 2
+- [ ] Phase 3
+
+### Emojis
+
+Very nice job on documentation! :thumbsup:
+
+I've read a lot of documentation, but I love :heart: this document.
+
+Weather: :sunny: :umbrella: :cloud: :snowflake:
+
+Animals: :tiger: :horse: :turtle: :wolf: :frog:

plugins/techdocs-backend/examples/documented-component/docs/index.md

@@ -1,17 +1,27 @@
 # Welcome!
 
-This is a basic example of documentation.
+This is a basic example of documentation. It is intended as a showcase of some of the
+features that TechDocs provides out of the box.
+
+You can see also:
+
+- [A sub page](sub-page.md)
+- [Inline code examples](code/code-sample.md)
+- [Plugin & Extension examples](extensions.md) - Diagrams, emojis, visual formatting.
+
+## Basic Markdown
 
 Here is a bulleted list:
 
 - Item one
 - Item two
-- Item three
+- Item Three
 
-Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to simply create documentation.
+Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to
+simply create documentation.
 
-You can also learn more about how to configure and setup this documentation in Backstage by
-[reading up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview).
+You can also learn more about how to configure and setup this documentation in Backstage,
+[read up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview).
 
 ## Image Example
 
@@ -21,7 +31,8 @@ This documentation is powered by Backstage's TechDocs feature:
 
 ## Table Example
 
-While this documentation isn't comprehensive, in the future it should cover the following topics outlined in this example table:
+While this documentation isn't comprehensive, in the future it should cover the following
+topics outlined in this example table:
 
 | Topic   | Description                                                  |
 | ------- | ------------------------------------------------------------ |

plugins/techdocs-backend/examples/documented-component/docs/sub-page.md

@@ -4,7 +4,8 @@ This sub-page can be used to elaborate on a specific part of the component.
 
 ## Details
 
-It is linked off the main page, and due to its inclusion in the `mkdocs.yml` file, becomes part of the auto-generated site navigation.
+It is linked off the main page, and due to its inclusion in the `mkdocs.yml` file,
+becomes part of the auto-generated site navigation.
 
 ## MkDocs
 

plugins/techdocs-backend/examples/documented-component/mkdocs.yml

@@ -4,6 +4,7 @@ nav:
   - Home: index.md
   - Subpage: sub-page.md
   - 'Code Sample': code/code-sample.md
+  - Extensions: extensions.md
 
 plugins:
   - techdocs-core