paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

Merge pull request #10836 from backstage/emmaindal/update-techdocs-how-to-guides

Browse Source 
[TechDocs] update techdocs how to guides
This commit is contained in:
Emma Indal
2022-04-15 09:35:50 +02:00
committed by GitHub
parent 1af8e20f53 3a146bb50d
commit 3e066ab5f5
2 changed files with 23 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/README.md
+8 -6
View File
@@ -92,14 +92,16 @@ Some of the following items are coming soon and some are potential ideas.
## Tech stack
| Stack | Location |
| ----------------------------------------------- | -------------------------------------------------------- |
| Frontend Plugin | [`@backstage/plugin-techdocs`][techdocs/frontend] |
| Backend Plugin | [`@backstage/plugin-techdocs-backend`][techdocs/backend] |
| CLI (for local development and generating docs) | [`@techdocs/cli`][techdocs/cli] |
| Docker Container (for generating docs) | [`techdocs-container`][techdocs/container] |
| Stack | Location |
| ----------------------------------------------- | --------------------------------------------------------------- |
| Frontend Plugin | [`@backstage/plugin-techdocs`][techdocs/frontend] |
| Frontend Plugin Library | [`@backstage/plugin-techdocs-react`][techdocs/frontend-library] |
| Backend Plugin | [`@backstage/plugin-techdocs-backend`][techdocs/backend] |
| CLI (for local development and generating docs) | [`@techdocs/cli`][techdocs/cli] |
| Docker Container (for generating docs) | [`techdocs-container`][techdocs/container] |
[techdocs/frontend]: https://github.com/backstage/backstage/blob/master/plugins/techdocs
[techdocs/frontend-library]: https://github.com/backstage/backstage/blob/master/plugins/techdocs-react
[techdocs/backend]: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend
[techdocs/container]: https://github.com/backstage/techdocs-container
[techdocs/cli]: https://github.com/backstage/techdocs-cli
docs/features/techdocs/how-to-guides.md
+15 -36
View File
@@ -162,20 +162,11 @@ The `techDocsPage` is a default techdocs reader page which lives in
having to set anything up.
```tsx
<TechDocsPage>
{({ techdocsMetadataValue, entityMetadataValue, entityRef, onReady }) => (
<>
<TechDocsPageHeader
techDocsMetadata={techdocsMetadataValue}
entityMetadata={entityMetadataValue}
entityRef={entityRef}
/>
<Content data-testid="techdocs-content">
<Reader onReady={onReady} entityRef={entityRef} />
</Content>
</>
)}
</TechDocsPage>
<TechDocsReaderPage>
<TechDocsReaderPageHeader />
<TechDocsReaderPageSubheader />
<TechDocsReaderPageContent />
</TechDocsReaderPage>
```
If you would like to compose your own `techDocsPage`, you can do so by replacing
@@ -183,42 +174,30 @@ the children of TechDocsPage with something else. Maybe you are _just_
interested in replacing the Header:
```tsx
<TechDocsPage>
{({ entityRef, onReady }) => (
<>
<Header type="documentation" title="Custom Header" />
<Content data-testid="techdocs-content">
<Reader onReady={onReady} entityRef={entityRef} />
</Content>
</>
)}
</TechDocsPage>
<TechDocsReaderPage>
<Header type="documentation" title="Custom Header" />
<TechDocsReaderPageContent />
</TechDocsReaderPage>
```
Or maybe you want to disable the in-context search
```tsx
<TechDocsPage>
{({ entityRef, onReady }) => (
<>
<Header type="documentation" title="Custom Header" />
<Content data-testid="techdocs-content">
<Reader onReady={onReady} entityRef={entityRef} withSearch={false} />
</Content>
</>
)}
</TechDocsPage>
<TechDocsReaderPage>
<Header type="documentation" title="Custom Header" />
<TechDocsReaderPageContent withSearch={false} />
</TechDocsReaderPage>
```
Or maybe you want to replace the entire TechDocs Page.
```tsx
<TechDocsPage>
<TechDocsReaderPage>
<Header type="documentation" title="Custom Header" />
<Content data-testid="techdocs-content">
<p>my own content</p>
</Content>
</TechDocsPage>
</TechDocsReaderPage>
```
## How to migrate from TechDocs Alpha to Beta