Update image links to use markdown syntax
Co-authored-by: Ben Lambert <ben@blam.sh> Co-authored-by: Fredrik Adelöw <freben@users.noreply.github.com> Signed-off-by: Johan Haals <johan.haals@gmail.com>
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
|
||||
|
||||
Reference in New Issue
Block a user