From 605b6916cf153ea41106e3a09ef4b33fd42abc4f Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Thu, 13 Jun 2024 10:58:22 -0400 Subject: [PATCH 1/6] Allow for searching TechDocs by Title Signed-off-by: Stephen A. Wilson --- .changeset/fuzzy-socks-do.md | 6 + app-config.yaml | 3 + .../catalog-info.yaml | 12 ++ .../docs/code/code-sample.md | 31 +++++ .../docs/extensions.md | 112 ++++++++++++++++++ .../docs/images/backstage-logo-cncf.svg | 1 + .../docs/index.md | 55 +++++++++ .../docs/sub-page.md | 12 ++ .../mkdocs.yml | 12 ++ .../src/home/components/Tables/DocsTable.tsx | 1 + .../src/home/components/Tables/columns.tsx | 34 +++++- 11 files changed, 274 insertions(+), 5 deletions(-) create mode 100644 .changeset/fuzzy-socks-do.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md create mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml diff --git a/.changeset/fuzzy-socks-do.md b/.changeset/fuzzy-socks-do.md new file mode 100644 index 0000000000..02d2e4dca9 --- /dev/null +++ b/.changeset/fuzzy-socks-do.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs-backend': patch +'@backstage/plugin-techdocs': patch +--- + +Allow for searching TechDocs by entity title diff --git a/app-config.yaml b/app-config.yaml index cb70170541..69145cd896 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -297,6 +297,9 @@ catalog: # Example component for TechDocs - type: file target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml + # Example component for TechDocs with a title + - type: file + target: ../../plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml # Example component for ADRs - type: file target: ../../plugins/adr/examples/component/catalog-info.yaml diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml b/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml new file mode 100644 index 0000000000..1a1d65ba39 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml @@ -0,0 +1,12 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: documented-with-title + title: Fizzbuzz Docs + description: A TechDocs with a title different than it's name + annotations: + backstage.io/techdocs-ref: dir:. +spec: + type: service + lifecycle: experimental + owner: user:guest diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md new file mode 100644 index 0000000000..f41ab1d506 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md @@ -0,0 +1,31 @@ +# 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. + +```typescript +const serviceEntityPage = ( + + + + + + + + + + + + +); +``` + +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-with-title/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md new file mode 100644 index 0000000000..eb9abca74a --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md @@ -0,0 +1,112 @@ +# 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: + +### Attributes + +[A Download Link](./images/backstage-logo-cncf.svg){: download } + +![A Scaled Image](./images/backstage-logo-cncf.svg){: style="width: 100px" } + +### MDX truly sane lists + +- `attributes` + +- `customer` + - `first_name` + - `test` + - `family_name` + - `email` +- `person` + - `first_name` + - `family_name` + - `birth_date` +- `subscription_id` + +- `request` diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg b/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg new file mode 100644 index 0000000000..b5ff591d1b --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/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-with-title/docs/index.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md new file mode 100644 index 0000000000..6295a69406 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md @@ -0,0 +1,55 @@ +# Welcome! + +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 + +Headings: + +# h1 + +## h2 + +### h3 + +#### h4 + +##### h5 + +###### h6 + +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/). + +## 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 component. | +| 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-with-title/docs/sub-page.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md new file mode 100644 index 0000000000..987f5e8a95 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md @@ -0,0 +1,12 @@ +# 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 its 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-with-title/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml new file mode 100644 index 0000000000..1a159a4d12 --- /dev/null +++ b/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: 'Example Documentation' +repo_url: https://github.com/backstage/backstage +edit_uri: edit/master/plugins/techdocs-backend/examples/documented-component/docs + +nav: + - Home: index.md + - Subpage: sub-page.md + - 'Code Sample': code/code-sample.md + - Extensions: extensions.md + +plugins: + - techdocs-core diff --git a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx index c0b39878cd..59abd9b278 100644 --- a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -85,6 +85,7 @@ export const DocsTable = (props: DocsTableProps) => { }); const defaultColumns: TableColumn[] = [ + columnFactories.createTitleColumn({ hidden: true }), columnFactories.createNameColumn(), columnFactories.createOwnerColumn(), columnFactories.createKindColumn(), diff --git a/plugins/techdocs/src/home/components/Tables/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx index bc85bb7a63..3deb4d9b33 100644 --- a/plugins/techdocs/src/home/components/Tables/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -24,17 +24,20 @@ function customTitle(entity: Entity): string { return entity.metadata.title || entity.metadata.name; } +type ColumnOptions = Partial>; + /** * Not directly exported, but through DocsTable.columns and EntityListDocsTable.columns * * @public */ export const columnFactories = { - createNameColumn(): TableColumn { + createTitleColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Document', - field: 'entity.metadata.name', + field: 'entity.metadata.title', highlight: true, + searchable: true, render: (row: DocsTableRow) => ( ), + ...overrides, }; }, - createOwnerColumn(): TableColumn { + createNameColumn(overrides: ColumnOptions = {}): TableColumn { + return { + title: 'Document', + field: 'entity.metadata.name', + highlight: true, + searchable: true, + render: (row: DocsTableRow) => ( + {customTitle(row.entity)} + } + subvalue={row.entity.metadata.description} + /> + ), + ...overrides, + }; + }, + createOwnerColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Owner', field: 'resolved.ownedByRelationsTitle', @@ -55,18 +76,21 @@ export const columnFactories = { defaultKind="group" /> ), + ...overrides, }; }, - createKindColumn(): TableColumn { + createKindColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Kind', field: 'entity.kind', + ...overrides, }; }, - createTypeColumn(): TableColumn { + createTypeColumn(overrides: ColumnOptions = {}): TableColumn { return { title: 'Type', field: 'entity.spec.type', + ...overrides, }; }, }; From edcd757d14708cb8de75278dd28a7d9c68a6dbe0 Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Thu, 13 Jun 2024 11:13:36 -0400 Subject: [PATCH 2/6] remove techdocs-backend from changeset Signed-off-by: Stephen A. Wilson --- .changeset/fuzzy-socks-do.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.changeset/fuzzy-socks-do.md b/.changeset/fuzzy-socks-do.md index 02d2e4dca9..aabc10f0cd 100644 --- a/.changeset/fuzzy-socks-do.md +++ b/.changeset/fuzzy-socks-do.md @@ -1,5 +1,4 @@ --- -'@backstage/plugin-techdocs-backend': patch '@backstage/plugin-techdocs': patch --- From e9551a759824d57c4c8a62dd832de4e65e27d253 Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Thu, 13 Jun 2024 13:05:09 -0400 Subject: [PATCH 3/6] revert changes to match prior work in CatalogTable Signed-off-by: Stephen A. Wilson --- plugins/techdocs/api-report.md | 14 ++++++++++++++ .../src/home/components/Tables/columns.tsx | 18 ++++++------------ 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index ebd6adcd3c..90834c6fcb 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -78,6 +78,13 @@ export type DocsGroupConfig = { export const DocsTable: { (props: DocsTableProps): React_2.JSX.Element | null; columns: { + createTitleColumn( + options?: + | { + hidden?: boolean | undefined; + } + | undefined, + ): TableColumn; createNameColumn(): TableColumn; createOwnerColumn(): TableColumn; createKindColumn(): TableColumn; @@ -142,6 +149,13 @@ export type EntityListDocsGridPageProps = { export const EntityListDocsTable: { (props: EntityListDocsTableProps): React_2.JSX.Element; columns: { + createTitleColumn( + options?: + | { + hidden?: boolean | undefined; + } + | undefined, + ): TableColumn; createNameColumn(): TableColumn; createOwnerColumn(): TableColumn; createKindColumn(): TableColumn; diff --git a/plugins/techdocs/src/home/components/Tables/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx index 3deb4d9b33..b9d22705d3 100644 --- a/plugins/techdocs/src/home/components/Tables/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -24,18 +24,17 @@ function customTitle(entity: Entity): string { return entity.metadata.title || entity.metadata.name; } -type ColumnOptions = Partial>; - /** * Not directly exported, but through DocsTable.columns and EntityListDocsTable.columns * * @public */ export const columnFactories = { - createTitleColumn(overrides: ColumnOptions = {}): TableColumn { + createTitleColumn(options?: { hidden?: boolean }): TableColumn { return { title: 'Document', field: 'entity.metadata.title', + hidden: options?.hidden, highlight: true, searchable: true, render: (row: DocsTableRow) => ( @@ -46,10 +45,9 @@ export const columnFactories = { subvalue={row.entity.metadata.description} /> ), - ...overrides, }; }, - createNameColumn(overrides: ColumnOptions = {}): TableColumn { + createNameColumn(): TableColumn { return { title: 'Document', field: 'entity.metadata.name', @@ -63,10 +61,9 @@ export const columnFactories = { subvalue={row.entity.metadata.description} /> ), - ...overrides, }; }, - createOwnerColumn(overrides: ColumnOptions = {}): TableColumn { + createOwnerColumn(): TableColumn { return { title: 'Owner', field: 'resolved.ownedByRelationsTitle', @@ -76,21 +73,18 @@ export const columnFactories = { defaultKind="group" /> ), - ...overrides, }; }, - createKindColumn(overrides: ColumnOptions = {}): TableColumn { + createKindColumn(): TableColumn { return { title: 'Kind', field: 'entity.kind', - ...overrides, }; }, - createTypeColumn(overrides: ColumnOptions = {}): TableColumn { + createTypeColumn(): TableColumn { return { title: 'Type', field: 'entity.spec.type', - ...overrides, }; }, }; From e10c75aebfdc030ea3dac888ac165d93cd75d032 Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Sat, 22 Jun 2024 15:52:58 -0400 Subject: [PATCH 4/6] Remove duplicated docs Signed-off-by: Stephen A. Wilson --- .../catalog-info.yaml | 12 -- .../docs/code/code-sample.md | 31 ----- .../docs/extensions.md | 112 ------------------ .../docs/images/backstage-logo-cncf.svg | 1 - .../docs/index.md | 55 --------- .../docs/sub-page.md | 12 -- .../mkdocs.yml | 12 -- .../documented-component/catalog-info.yaml | 2 +- 8 files changed, 1 insertion(+), 236 deletions(-) delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md delete mode 100644 plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml b/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml deleted file mode 100644 index 1a1d65ba39..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: backstage.io/v1alpha1 -kind: Component -metadata: - name: documented-with-title - title: Fizzbuzz Docs - description: A TechDocs with a title different than it's name - annotations: - backstage.io/techdocs-ref: dir:. -spec: - type: service - lifecycle: experimental - owner: user:guest diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md deleted file mode 100644 index f41ab1d506..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/docs/code/code-sample.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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. - -```typescript -const serviceEntityPage = ( - - - - - - - - - - - - -); -``` - -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-with-title/docs/extensions.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md deleted file mode 100644 index eb9abca74a..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/docs/extensions.md +++ /dev/null @@ -1,112 +0,0 @@ -# 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: - -### Attributes - -[A Download Link](./images/backstage-logo-cncf.svg){: download } - -![A Scaled Image](./images/backstage-logo-cncf.svg){: style="width: 100px" } - -### MDX truly sane lists - -- `attributes` - -- `customer` - - `first_name` - - `test` - - `family_name` - - `email` -- `person` - - `first_name` - - `family_name` - - `birth_date` -- `subscription_id` - -- `request` diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg b/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg deleted file mode 100644 index b5ff591d1b..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/docs/images/backstage-logo-cncf.svg +++ /dev/null @@ -1 +0,0 @@ -05 Logo_Black \ No newline at end of file diff --git a/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md deleted file mode 100644 index 6295a69406..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/docs/index.md +++ /dev/null @@ -1,55 +0,0 @@ -# Welcome! - -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 - -Headings: - -# h1 - -## h2 - -### h3 - -#### h4 - -##### h5 - -###### h6 - -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/). - -## 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 component. | -| 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-with-title/docs/sub-page.md b/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md deleted file mode 100644 index 987f5e8a95..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/docs/sub-page.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 its 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-with-title/mkdocs.yml b/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml deleted file mode 100644 index 1a159a4d12..0000000000 --- a/plugins/techdocs-backend/examples/documented-component-with-title/mkdocs.yml +++ /dev/null @@ -1,12 +0,0 @@ -site_name: 'Example Documentation' -repo_url: https://github.com/backstage/backstage -edit_uri: edit/master/plugins/techdocs-backend/examples/documented-component/docs - -nav: - - Home: index.md - - Subpage: sub-page.md - - 'Code Sample': code/code-sample.md - - Extensions: extensions.md - -plugins: - - techdocs-core diff --git a/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml b/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml index e6d14025e1..6b30213a60 100644 --- a/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml +++ b/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml @@ -2,7 +2,7 @@ apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: documented-component - title: Documented Component + title: Example Docs description: A Service with TechDocs documentation annotations: backstage.io/techdocs-ref: dir:. From d1488caaa309df834095bde5a48bf9f99ad797af Mon Sep 17 00:00:00 2001 From: Stephen Date: Mon, 24 Jun 2024 08:52:29 -0400 Subject: [PATCH 5/6] Revert change to app-config.yaml Signed-off-by: Stephen --- app-config.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/app-config.yaml b/app-config.yaml index 69145cd896..cb70170541 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -297,9 +297,6 @@ catalog: # Example component for TechDocs - type: file target: ../../plugins/techdocs-backend/examples/documented-component/catalog-info.yaml - # Example component for TechDocs with a title - - type: file - target: ../../plugins/techdocs-backend/examples/documented-component-with-title/catalog-info.yaml # Example component for ADRs - type: file target: ../../plugins/adr/examples/component/catalog-info.yaml From 1ba55321bfea5911cec426452868f8d7e50edb2c Mon Sep 17 00:00:00 2001 From: "Stephen A. Wilson" Date: Wed, 3 Jul 2024 20:17:30 -0400 Subject: [PATCH 6/6] Fix linting errors Signed-off-by: Stephen A. Wilson --- plugins/techdocs/src/home/components/Tables/DocsTable.tsx | 2 +- plugins/techdocs/src/home/components/Tables/columns.tsx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx index e2904374a0..b1537affdb 100644 --- a/plugins/techdocs/src/home/components/Tables/DocsTable.tsx +++ b/plugins/techdocs/src/home/components/Tables/DocsTable.tsx @@ -58,7 +58,7 @@ const defaultColumns: TableColumn[] = [ columnFactories.createKindColumn(), columnFactories.createTypeColumn(), ]; - + /** * Component which renders a table documents * diff --git a/plugins/techdocs/src/home/components/Tables/columns.tsx b/plugins/techdocs/src/home/components/Tables/columns.tsx index 08c190c26b..ef22f6d288 100644 --- a/plugins/techdocs/src/home/components/Tables/columns.tsx +++ b/plugins/techdocs/src/home/components/Tables/columns.tsx @@ -31,12 +31,12 @@ function customTitle(entity: Entity): string { */ export const columnFactories = { createTitleColumn(options?: { hidden?: boolean }): TableColumn { - const nameCol = columnFactories.createNameColumn() + const nameCol = columnFactories.createNameColumn(); return { ...nameCol, field: 'entity.metadata.title', hidden: options?.hidden, - } + }; }, createNameColumn(): TableColumn { return {