From 02d78290a5ba9d49f5e16944bb3923e301a7fd00 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 15:58:54 -0500 Subject: [PATCH 1/4] Enhance example documented-component Signed-off-by: Adam Harvey --- .changeset/techdocs-kind-seals-fix.md | 5 ++++ .../docs/code/code-sample.md | 22 ++++++++++++++ .../docs/images/backstage-logo-cncf.svg | 1 + .../documented-component/docs/index.md | 29 ++++++++++++++++++- .../documented-component/docs/sub-page.md | 10 +++++++ .../examples/documented-component/mkdocs.yml | 5 ++-- 6 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 .changeset/techdocs-kind-seals-fix.md create mode 100644 plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md create mode 100644 plugins/techdocs-backend/examples/documented-component/docs/images/backstage-logo-cncf.svg diff --git a/.changeset/techdocs-kind-seals-fix.md b/.changeset/techdocs-kind-seals-fix.md new file mode 100644 index 0000000000..b0ac18c744 --- /dev/null +++ b/.changeset/techdocs-kind-seals-fix.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs-backend': patch +--- + +Enhanced the example documented-component to better demonstrate TechDocs features 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 new file mode 100644 index 0000000000..ed430edb15 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component/docs/code/code-sample.md @@ -0,0 +1,22 @@ +# Sample Code + +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 +const DefaultEntityPage = ({ entity }: { entity: Entity }) => ( + + } + /> + } + /> + +); +``` diff --git a/plugins/techdocs-backend/examples/documented-component/docs/images/backstage-logo-cncf.svg b/plugins/techdocs-backend/examples/documented-component/docs/images/backstage-logo-cncf.svg new file mode 100644 index 0000000000..b5ff591d1b --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component/docs/images/backstage-logo-cncf.svg @@ -0,0 +1 @@ +05 Logo_Black \ No newline at end of file diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index bf0895710f..c22dd18208 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -1,3 +1,30 @@ -# example docs +# Welcome! This is a basic example of documentation. + +Here is a bulleted list: + +- Item one +- Item two +- Item Three + +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, +[read up on the TechDocs Overview](https://backstage.io/docs/features/techdocs/techdocs-overview). + +## Image Example + +This documentation is powered by Backstage's TechDocs feature: + +![Backstage Logo](images/backstage-logo-cncf.svg) + +## Table Example + +While this documentation isn't comprehensive, in the future it should cover the following topics outlined in this example table: + +| Topic | Description | +| ------- | ------------------------------------------------------------ | +| Topic 1 | An introductory topic to help you learn about the topic. | +| Topic 2 | A more detailed topic that explains more information. | +| Topic 3 | A final topic that provides conclusions and lessons learned. | 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 bbd98558e0..62de70a273 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/sub-page.md @@ -1 +1,11 @@ # Another page in our documentation + +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 it's inclusion in the `mkdocs.yml` file, becomes part of the auto-generated site navigation. + +## MkDocs + +Visit https://www.mkdocs.org for more information about the MkDocs tool. diff --git a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component/mkdocs.yml index 3b48e8edff..4c7d018690 100644 --- a/plugins/techdocs-backend/examples/documented-component/mkdocs.yml +++ b/plugins/techdocs-backend/examples/documented-component/mkdocs.yml @@ -1,8 +1,9 @@ -site_name: 'example-docs' +site_name: 'Example Documentation' nav: - Home: index.md - - SubPage: sub-page.md + - Subpage: sub-page.md + - 'Code Sample': code/code-sample.md plugins: - techdocs-core From c149b14009bc836af92f08b8bd11582223390d66 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 18:51:34 -0500 Subject: [PATCH 2/4] Fix typo Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/sub-page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 62de70a273..8e1870c7b4 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,7 @@ 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 it's 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 From 2daa65a18b4c7800e2d96e114e1cfda916df9d58 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 18:51:57 -0500 Subject: [PATCH 3/4] Change wording Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index c22dd18208..14d09ff2fc 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -25,6 +25,6 @@ While this documentation isn't comprehensive, in the future it should cover the | Topic | Description | | ------- | ------------------------------------------------------------ | -| Topic 1 | An introductory topic to help you learn about the topic. | +| Topic 1 | An introductory topic to help you learn about the component. | | Topic 2 | A more detailed topic that explains more information. | | Topic 3 | A final topic that provides conclusions and lessons learned. | From a9d7c123fbc093c5d9f6fb9042010d0148892a12 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 18:53:39 -0500 Subject: [PATCH 4/4] Wording tweaks Signed-off-by: Adam Harvey --- .../examples/documented-component/docs/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/techdocs-backend/examples/documented-component/docs/index.md b/plugins/techdocs-backend/examples/documented-component/docs/index.md index 14d09ff2fc..5a9c23d9f6 100644 --- a/plugins/techdocs-backend/examples/documented-component/docs/index.md +++ b/plugins/techdocs-backend/examples/documented-component/docs/index.md @@ -6,12 +6,12 @@ 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. -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). +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). ## Image Example