Allow for searching TechDocs by Title

Signed-off-by: Stephen A. Wilson <code@stephenawilson.ca>
2024-06-13 10:58:22 -04:00
parent 951ddd86e9
commit 605b6916cf
11 changed files with 274 additions and 5 deletions
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+'@backstage/plugin-techdocs': patch
+---
+
+Allow for searching TechDocs by entity title
@@ -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
@@ -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
@@ -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 = (
+  <EntityLayout>
+    <EntityLayout.Route path="/" title="Overview">
+      <Grid container spacing={3} alignItems="stretch">
+        <Grid item md={6}>
+          <EntityAboutCard variant="gridItem" />
+        </Grid>
+      </Grid>
+    </EntityLayout.Route>
+    <EntityLayout.Route path="/docs" title="Docs">
+      <EntityTechdocsContent />
+    </EntityLayout.Route>
+  </EntityLayout>
+);
+```
+
+Here is an example of Python code:
+
+```python
+def getUsersInGroup(targetGroup, secure=False):
+
+    if __debug__:
+        print('targetGroup=[' + targetGroup + ']')
+```
@@ -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:
+
+<!-- prettier-ignore -->
+!!! warn
+    Defining admonitions can be addicting.
+
+<!-- prettier-ignore -->
+!!! note
+    You can learn a lot about TechDocs by just visiting the Backstage web site at
+    https://backstage.io/docs.
+
+<!-- prettier-ignore -->
+!!! info
+    TechDocs is the core feature that supports documentation as code in Backstage.
+
+<!-- prettier-ignore -->
+!!! 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
+
+<!-- prettier-ignore -->
+??? note "What is the answer to life, the universe, and everything? (click me for the answer)"
+    The answer is 42.
+
+<!-- prettier-ignore -->
+??? note "What is 4 plus 4?"
+    The answer is 8.
+
+<!-- prettier-ignore -->
+???+ 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`
@@ -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. |
@@ -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.
@@ -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
@@ -85,6 +85,7 @@ export const DocsTable = (props: DocsTableProps) => {
  });

  const defaultColumns: TableColumn<DocsTableRow>[] = [
+    columnFactories.createTitleColumn({ hidden: true }),
    columnFactories.createNameColumn(),
    columnFactories.createOwnerColumn(),
    columnFactories.createKindColumn(),
@@ -24,17 +24,20 @@ function customTitle(entity: Entity): string {
  return entity.metadata.title || entity.metadata.name;
 }

+type ColumnOptions = Partial<TableColumn<DocsTableRow>>;
+
 /**
 * Not directly exported, but through DocsTable.columns and EntityListDocsTable.columns
 *
 * @public
 */
 export const columnFactories = {
-  createNameColumn(): TableColumn<DocsTableRow> {
+  createTitleColumn(overrides: ColumnOptions = {}): TableColumn<DocsTableRow> {
    return {
      title: 'Document',
-      field: 'entity.metadata.name',
+      field: 'entity.metadata.title',
      highlight: true,
+      searchable: true,
      render: (row: DocsTableRow) => (
        <SubvalueCell
          value={
@@ -43,9 +46,27 @@ export const columnFactories = {
          subvalue={row.entity.metadata.description}
        />
      ),
+      ...overrides,
    };
  },
-  createOwnerColumn(): TableColumn<DocsTableRow> {
+  createNameColumn(overrides: ColumnOptions = {}): TableColumn<DocsTableRow> {
+    return {
+      title: 'Document',
+      field: 'entity.metadata.name',
+      highlight: true,
+      searchable: true,
+      render: (row: DocsTableRow) => (
+        <SubvalueCell
+          value={
+            <Link to={row.resolved.docsUrl}>{customTitle(row.entity)}</Link>
+          }
+          subvalue={row.entity.metadata.description}
+        />
+      ),
+      ...overrides,
+    };
+  },
+  createOwnerColumn(overrides: ColumnOptions = {}): TableColumn<DocsTableRow> {
    return {
      title: 'Owner',
      field: 'resolved.ownedByRelationsTitle',
@@ -55,18 +76,21 @@ export const columnFactories = {
          defaultKind="group"
        />
      ),
+      ...overrides,
    };
  },
-  createKindColumn(): TableColumn<DocsTableRow> {
+  createKindColumn(overrides: ColumnOptions = {}): TableColumn<DocsTableRow> {
    return {
      title: 'Kind',
      field: 'entity.kind',
+      ...overrides,
    };
  },
-  createTypeColumn(): TableColumn<DocsTableRow> {
+  createTypeColumn(overrides: ColumnOptions = {}): TableColumn<DocsTableRow> {
    return {
      title: 'Type',
      field: 'entity.spec.type',
+      ...overrides,
    };
  },
 };