diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index e537585865..cc20afaf57 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -269,6 +269,7 @@ templated templater templaters theia +thumbsup toc tolerations toolchain diff --git a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md index ed430edb15..9f8e1bd739 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md +++ b/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 }) => ( ( ); ``` + +Here is an example of Python code: + +```python +def getUsersInGroup(targetGroup, secure=False): + + if __debug__: + print('targetGroup=[' + targetGroup + ']') +``` diff --git a/plugins/techdocs-backend/examples/documented-component/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component/docs/extensions.md new file mode 100644 index 0000000000..a2b02ec866 --- /dev/null +++ b/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: diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index 5a9c23d9f6..48a903445a 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/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 | | ------- | ------------------------------------------------------------ | diff --git a/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md b/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md index 8e1870c7b4..987f5e8a95 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md +++ b/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 diff --git a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component/mkdocs.yml index 4c7d018690..2087979d22 100644 --- a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml +++ b/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