Merge pull request #16489 from backstage/mob/docs2
microsite: Update image links to use markdown syntax
This commit is contained in:
Johan Haals
@@ -290,9 +290,7 @@ The figure below shows the relationship between
|
||||
<span class="textPurple" className="textPurple"> FooApi</span> via the
|
||||
<span class="textRed" className="textRed"> fooApiRef</span>.
|
||||
|
||||
<div className="textAlignCenter" class="textAlignCenter">
|
||||
<img src="../assets/utility-apis-fig1.svg" alt="Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them" />
|
||||
</div>
|
||||
|
||||
|
||||
The current method for connecting Utility API providers and consumers is via the
|
||||
React tree using an `ApiProvider`, which is added to the `AppProvider` of the
|
||||
|
||||
@@ -74,7 +74,7 @@ Backend modules are used to extend [plugins](../architecture/04-plugins.md) with
|
||||
additional features or change existing behavior. They must always be installed
|
||||
in the same backend instance as the plugin that they extend, and may only extend
|
||||
a single plugin. Modules interact with their target plugin using the [extension
|
||||
points](./05-extension-points.md) registered by the plugin, while also being
|
||||
points](../architecture/05-extension-points.md) registered by the plugin, while also being
|
||||
able to depend on the [services](../architecture/03-services.md) of that plugin.
|
||||
That last point is worth reiterating: injected `plugin` scoped services will be
|
||||
the exact
|
||||
|
||||
@@ -9,7 +9,9 @@ to support a wide variety of search engines, while providing a simple developer
|
||||
experience for plugin developers, and a good out-of-the-box experience for
|
||||
Backstage end-users.
|
||||
|
||||
<img data-zoomable src="../../assets/search/architecture.drawio.svg" alt="Search Architecture" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
At a base-level, we want to support the following:
|
||||
|
||||
|
||||
@@ -39,7 +39,9 @@ representative of physical spaces in the TechDocs UI:
|
||||
- `Component`: A [proposed-but-not-yet-implemented](https://github.com/backstage/backstage/issues/11109)
|
||||
virtual location, aimed at simplifying a common type of Addon.
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/addon-locations.png" alt="TechDocs Addon Location Guide" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
### Addon Registry
|
||||
|
||||
|
||||
@@ -9,7 +9,9 @@ description: Documentation on TechDocs Architecture
|
||||
When you deploy Backstage (with TechDocs enabled by default), you get a basic
|
||||
out-of-the box experience.
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/architecture-basic.drawio.svg" alt="TechDocs Architecture diagram" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
> Note: See below for our recommended deployment architecture which takes care
|
||||
> of stability, scalability and speed. Also look at the
|
||||
@@ -42,7 +44,9 @@ storage system (e.g. AWS S3, GCS or Azure Blob Storage). Read more in
|
||||
|
||||
This is how we recommend deploying TechDocs in a production environment.
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/architecture-recommended.drawio.svg" alt="TechDocs Architecture diagram" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
The key difference in the recommended deployment approach is where the docs are
|
||||
built.
|
||||
|
||||
@@ -89,11 +89,15 @@ const AppRoutes = () => {
|
||||
|
||||
I know, you're curious to see how it looks, aren't you? See the image below:
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/report-issue-addon.png" alt="TechDocs Report Issue Add-on" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
By clicking the open new issue button, you will be redirected to the new issue page according to the source code provider you are using:
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/report-issue-template.png" alt="TechDocs Report Issue Template" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
That's it! Now, we need the TechDocs Backend plugin for the frontend to work.
|
||||
|
||||
|
||||
@@ -136,9 +136,7 @@ frontend, in our tutorial it would be `http://localhost:3000`. The
|
||||
`Authorization callback URL` will point to the auth backend, which will most
|
||||
likely be `http://localhost:7007/api/auth/github/handler/frame`.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/gh-oauth.png' alt='Screenshot of the GitHub OAuth creation page' />
|
||||
</p>
|
||||
|
||||
|
||||
Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`,
|
||||
and add your `clientId` and `clientSecret` to this file. It should end up
|
||||
@@ -214,9 +212,7 @@ name to identify this token and put it in the notes field. Choose a number of
|
||||
days for expiration. If you have a hard time picking a number, we suggest to go
|
||||
for 7 days, it's a lucky number.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/gh-pat.png' alt='Screenshot of the GitHub Personal Access Token creation page' />
|
||||
</p>
|
||||
|
||||
|
||||
Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project.
|
||||
|
||||
@@ -262,21 +258,18 @@ otherwise something went terribly wrong.
|
||||
- Register a new component, by going to `create` and choose
|
||||
`Register existing component`
|
||||
|
||||
<p align='center'>
|
||||
<img data-zoomable src='../assets/getting-started/b-existing-1.png' alt='Software template main screen, with a blue button to add an existing component' />
|
||||
</p>
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
- As URL use `https://github.com/backstage/demo/blob/master/catalog-info.yaml`.
|
||||
This is used by our [demo site](https://demo.backstage.io).
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/b-existing-2.png' alt='Register a new component wizard, asking for an URL to the existing component YAML file' />
|
||||
</p>
|
||||
- Hit `Analyze` and review the changes. Apply them if correct
|
||||
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/b-existing-3.png' alt='Register a new component wizard, showing the metadata for the component YAML we use in this tutorial' />
|
||||
</p>
|
||||
- Hit `Analyze` and review the changes. Apply them if correct.
|
||||
|
||||
|
||||
|
||||
- You should receive a message that your entities have been added.
|
||||
- If you go back to `Home`, you should be able to find `demo`. You should be
|
||||
@@ -286,14 +279,12 @@ otherwise something went terribly wrong.
|
||||
|
||||
- Go to `create` and choose to create a website with the `Example Node.js Template`
|
||||
- Type in a name, let's use `tutorial` and click `Next Step`
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/b-scaffold-1.png' alt='Software template deployment input screen asking for a name' />
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
- You should see the following screen:
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/b-scaffold-2.png' alt='Software template deployment input screen asking for the GitHub username, and name of the new repo to create' />
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
- For host, it should default to github.com
|
||||
- As owner, type your GitHub username
|
||||
|
||||
@@ -34,9 +34,7 @@ npx @backstage/create-app
|
||||
This will create a new Backstage App inside the current folder. The name of the
|
||||
app-folder is the name that was provided when prompted.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/create-app_output.png' width='600' alt='create app' />
|
||||
</p>
|
||||
|
||||
|
||||
Inside that directory, it will generate all the files and folder structure
|
||||
needed for you to run your app.
|
||||
|
||||
@@ -82,16 +82,9 @@ const routes = (
|
||||
|
||||
Let's update the route for "Home" in the Backstage sidebar to point to the new homepage. We'll also add a Sidebar item to quickly open Catalog.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th><img data-zoomable src="../assets/getting-started/sidebar-without-catalog.png" alt="Sidebar without Catalog" /></th>
|
||||
<th><img data-zoomable src="../assets/getting-started/sidebar-with-catalog.png" alt="Sidebar with Catalog" /></th>
|
||||
</tr>
|
||||
<tr align="center">
|
||||
<td>Before</td>
|
||||
<td>After</td>
|
||||
</tr>
|
||||
</table>
|
||||
| Before | After |
|
||||
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
|  |  |
|
||||
|
||||
The code for the Backstage sidebar is most likely inside your [`packages/app/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/Root/Root.tsx).
|
||||
|
||||
@@ -121,7 +114,9 @@ export const Root = ({ children }: PropsWithChildren<{}>) => (
|
||||
|
||||
That's it! You should now have _(although slightly boring)_ a homepage!
|
||||
|
||||
<img data-zoomable src="../assets/getting-started/simple-homepage.png" alt="Screenshot of a blank homepage" />
|
||||
<!-- todo: Needs zoomable plugin -->
|
||||
|
||||
|
||||
|
||||
In the next steps, we will make it interesting and useful!
|
||||
|
||||
|
||||
@@ -54,9 +54,7 @@ npx @backstage/create-app@latest
|
||||
|
||||
The wizard will ask you for the name of the app, which will also be the name of the directory
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/wizard.png' alt='Screenshot of the wizard asking for a name for the app.' />
|
||||
</p>
|
||||
|
||||
|
||||
### Run the Backstage app
|
||||
|
||||
@@ -69,9 +67,7 @@ cd my-backstage-app
|
||||
yarn dev
|
||||
```
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/startup.png' alt='Screenshot of the command output, with the message web pack compiled successfully.'/>
|
||||
</p>
|
||||
|
||||
|
||||
It might take a little while, but as soon as the message
|
||||
`[0] webpack compiled successfully` appears, you can open a browser and directly
|
||||
@@ -80,9 +76,7 @@ You can start exploring the demo immediately. Please note that the in-memory
|
||||
database will be cleared when you restart the app, so you'll most likely want to
|
||||
carry on with the database steps.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/portal.png' alt='Screenshot of the Backstage portal.'/>
|
||||
</p>
|
||||
|
||||
|
||||
In the next part of this tutorial, you'll learn how to change to a persistent
|
||||
database, configure authentication, and add your first integration. Continue
|
||||
|
||||
@@ -218,9 +218,9 @@ module.exports = {
|
||||
'<p style="text-align:center"><a href="https://spotify.github.io/">Made with ❤️ at Spotify</a></p><p class="copyright">Copyright © 2022 Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage</p>',
|
||||
},
|
||||
algolia: {
|
||||
appId: 'AZYC4ZFNTN',
|
||||
apiKey: '7dbd2089b0d445ee0d87db71abfc794f',
|
||||
indexName: 'backstage',
|
||||
apiKey: '1f0ba86672ccfc3576faa94583e5b318',
|
||||
indexName: 'crawler_Backstage Docusaurus 2',
|
||||
appId: 'JCMFNHCHI8',
|
||||
searchParameters: {},
|
||||
},
|
||||
},
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
{
|
||||
"releases": {
|
||||
"Release Notes": [
|
||||
"releases/v1.11.0",
|
||||
"releases/v1.10.0",
|
||||
"releases/v1.9.0",
|
||||
"releases/v1.8.0",
|
||||
"releases/v1.7.0",
|
||||
"releases/v1.6.0",
|
||||
@@ -85,7 +88,8 @@
|
||||
"features/kubernetes/installation",
|
||||
"features/kubernetes/configuration",
|
||||
"features/kubernetes/authentication",
|
||||
"features/kubernetes/troubleshooting"
|
||||
"features/kubernetes/troubleshooting",
|
||||
"features/kubernetes/proxy"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -101,6 +105,7 @@
|
||||
"features/software-templates/writing-custom-actions",
|
||||
"features/software-templates/writing-custom-field-extensions",
|
||||
"features/software-templates/writing-custom-step-layouts",
|
||||
"features/software-templates/testing-scaffolder-alpha",
|
||||
"features/software-templates/migrating-from-v1beta2-to-v1beta3"
|
||||
]
|
||||
},
|
||||
@@ -199,7 +204,8 @@
|
||||
"label": "GitLab",
|
||||
"items": [
|
||||
"integrations/gitlab/locations",
|
||||
"integrations/gitlab/discovery"
|
||||
"integrations/gitlab/discovery",
|
||||
"integrations/gitlab/org"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -237,8 +243,7 @@
|
||||
"plugins/proxying",
|
||||
"plugins/backend-plugin",
|
||||
"plugins/call-existing-api",
|
||||
"plugins/url-reader",
|
||||
"plugins/new-backend-system"
|
||||
"plugins/url-reader"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -361,6 +366,43 @@
|
||||
"architecture-decisions/adrs-adr012",
|
||||
"architecture-decisions/adrs-adr013"
|
||||
],
|
||||
"FAQ": ["FAQ"]
|
||||
"FAQ": ["FAQ"],
|
||||
"Experimental Backend System": [
|
||||
"backend-system/index",
|
||||
{
|
||||
"type": "category",
|
||||
"label": "Architecture",
|
||||
"items": [
|
||||
"backend-system/architecture/index",
|
||||
"backend-system/architecture/services",
|
||||
"backend-system/architecture/plugins",
|
||||
"backend-system/architecture/extension-points",
|
||||
"backend-system/architecture/modules",
|
||||
"backend-system/architecture/naming-patterns"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "Building Backends",
|
||||
"items": [
|
||||
"backend-system/building-backends/index",
|
||||
"backend-system/building-backends/migrating"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "Building Plugins & Modules",
|
||||
"items": [
|
||||
"backend-system/building-plugins-and-modules/index",
|
||||
"backend-system/building-plugins-and-modules/testing",
|
||||
"backend-system/building-plugins-and-modules/migrating"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "Core Services",
|
||||
"items": ["backend-system/core-services/index"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user