docs: Workshop documentation updates

docs/appendix/part-3-code.md

@@ -0,0 +1,59 @@
+# Part 3: Code - React Cat Preview Field Extension
+
+Below is the code for the React component that we will be creating in this exercise. This component will display a random cat picture from the Cat API.
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import { FieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react';
+import FormControl from '@material-ui/core/FormControl';
+import { Button, FormHelperText, FormLabel } from '@material-ui/core';
+
+export interface CatResult {
+  id: string;
+  url: string;
+  width: number;
+  height: number;
+}
+
+/*
+ This is the actual component that will get rendered in the form
+*/
+export const RandomCatPixExtension = ({
+  onChange,
+  rawErrors,
+  required,
+  formData,
+}: FieldExtensionComponentProps<string>) => {
+  const [catPic, setCatPic] = useState('');
+
+  const refreshPic = async () => {
+    const catResult = await fetch('https://api.thecatapi.com/v1/images/search');
+    const catData: Record<string, CatResult> = await catResult.json();
+    setCatPic(catData[0].url);
+    onChange(catData[0].url);
+  };
+
+  useEffect(() => {
+    refreshPic();
+  }, []);
+
+  return (
+    <FormControl
+      margin="normal"
+      required={required}
+      error={rawErrors?.length > 0 && !formData}
+    >
+      <FormLabel>Random Cat Picture</FormLabel>
+      <Button variant="contained" color="primary" onClick={() => refreshPic()}>
+        Refresh 😻
+      </Button>
+
+      <img src={catPic} alt="Random Cat" width={'500px'} />
+
+      <FormHelperText id="entityName">
+        Giving you a random cat picture, all day, every day.
+      </FormHelperText>
+    </FormControl>
+  );
+};
+```

docs/clean-up.md

@@ -0,0 +1,31 @@
+# Clean up
+
+??? Info "Pro tip"
+
+    You can delete via the `gh cli` as well. Run the following command to delete the repository:
+
+    ```bash
+    gh repo delete <repo-name> --confirm
+    ```
+
+    The same you can do with the Codespaces. Run the following command to delete the Codespace:
+
+    ```bash
+    gh codespace list
+    gh codespace delete -c <codespace-id>
+    ```
+
+    Be-careful with the `gh cli` as it can delete things without asking for confirmation.
+
+## Codespaces
+
+During the workshop we used GitHub Codespaces. The Codespace will be automatically stopped after 30 minutes of inactivity. But now the workshop is over, you can delete the Codespace to avoid any burning down your free tier or generate costs depending on your payment plan.
+
+Go to the [Codespace overview page](https://github.com/codespaces) and delete the Codespace created for this workshops.
+
+## Repositories
+
+During the workshops you have created several repositories. You can delete the repositories now safely as they are not needed anymore.
+
+Go to the the your user page, select the repositories tab. Next select the repository you want to delete and go to the settings. Scroll down to the danger zone and delete the repository.
+

docs/getting-started.md

@@ -2,16 +2,18 @@
 
 ## Getting Started
 
-To get started with this workshop we are going to use Codespaces to set up our
-development environment.
+To get started with this workshop we are going to use
+[Codespaces](https://github.com/features/codespaces) to set up our development
+environment.
 
 !!! tip "Codespaces plugin for VSCode"
 
     Before we start you should install the Codespaces plugin into your local VSCode
     installation, this is because we will later connect your vscode instance to the
     codespace in GitHub.
 
-To use Codespaces we can go to the code button on the workshop repository and
+To use Codespaces we can go to the code button on the
+[workshop repository](https://github.com/philips-labs/automation-workshop) and
 select the Codespaces tab. Clicking create an new Codespaces will start out the
 building and starting of your own Codespace. After a while you will have running
 and working environment which you can see from the VSCode instance in your
@@ -26,6 +28,12 @@ the files from the codespace in your local vscode.
 Once have you connected your vscode you can then continue with the rest of the
 instructions here.
 
+??? Note "Codespaces"
+
+    During the workshop we use GitHub Codespaces to provide a consistent and easy to
+    use environment for the workshop. GitHub is charging you for Codespaces usage, but
+    also provide a free tier including 120 core-hours per month. You can check the details on the [GitHub billing page](https://github.com/settings/billing/summary). To avoid you make unnecessary costs, Codespaces will be automatically stopped after 30 minutes of inactivity. Check the [Codespace settings page](https://github.com/settings/codespaces) to see your Codespaces and adjust settings.
+
 ## Creating a new Backstage app
 
 Once you have a running environment you will now need to create a new backstage
@@ -61,16 +69,27 @@ in the next step.
 Once the yarn installation is complete, you can start the app by running the
 following command:
 
+??? Note "Without Yarn 4 Migration"
+
+    If you did not migrate to yarn 4 you can run the following command to start
+    the app.
+
+    ```bash
+    cd backstage
+    yarn install
+    yarn dev
+    ```
+
+Next we start the development environment by running the following command:
 ```bash
-cd backstage
 yarn dev
 ```
 
-This should build and run the app and open a browser window for you. If it does
-not you can open a browser and navigate to `http://localhost:3000` to see the
-app running.
+Backstage will open in the browser and or VSCode pointing to `127.0.0.1` instead of `localhost`. Ensure you open the Backstage in your browser on `http://localhost:3000`.
 
-Once you have a running installation we can move to the first exercise!
+![Backstage App](./assets/getting_started_app.png) 
+
+Once you have a running installation we can move to the first exercise! In case you don't see the Backstage app running, please check the following:
 
 ??? Note "Working Directory"
 
@@ -81,9 +100,9 @@ Once you have a running installation we can move to the first exercise!
 
     Backstage is running two processes exposed in the the container on port 3000
     and 7007. The codespace is mapping the ports to your local ports. Ensure
-    you have no other processes running on those ports.
+    you have no other processes running on those ports and both ports are mapped, you may have to manually add port 7007 in the vscode UI.
 
-??? Note Node 20
+??? Note "Node 20"
 
     If you are running node 20 you will need to set the `NODE_OPTIONS=--no-node-snapshot`
     environment variable to prevent the node process from crashing.
@@ -92,16 +111,22 @@ Once you have a running installation we can move to the first exercise!
     `NODE_OPTIONS=--no-node-snapshot yarn dev` each time you start the app, or
     by adding it to the `dev` script in the `package.json`.
 
+    The Codespace is running on Node 18, so you should not have this issue.
+
 ## Authentication
 
 For this workshop we will need to authenticate with GitHub in order to create
 new repositories in organizations that you own. To do this we need a token for
 GitHub. We can re-use the token from the GitHub CLI for these purposes, this is
 the easiest way to get a token and the token is short lived.
 
+Before we can continue we need to stop the running backstage app, you can do this
+by pressing `ctrl+c` in the terminal where the app is running. Next we use the same terminal session to authenticate with GitHub.
+
 The GitHub CLI is already installed in this codespace, first you need to login.
 
 ```bash
+unset GITHUB_TOKEN
 gh auth login
 ```
 

docs/part-1.md

@@ -73,7 +73,9 @@ file. You can add a new location under `catalog.locations` like below:
 ```
 
 You can then start your backstage instance and you should see the new template
-in the templates section.
+in the [templates section](http://localhost:3000/create?filters%5Bkind%5D=template&filters%5Buser%5D=all).
+
+![Cat scanner template](./assets/part_1_cat_scanner_template.png)
 
 ## Creating a repo
 
@@ -117,7 +119,11 @@ a new repo using the `publish:github` action. Add the following to your
     on your template and then clicking the refresh button in the about card.
 
 Now, go to your template, enter the repo details and it should create a new repo
-in GitHub for you.
+in GitHub for you. Use for "owner" your GitHub handle and choose a name for the repository. Once finished the template displays a link (TAKE ME TO THE REPO) to the newly created (private) repository.
+
+![Cat scanner repo](./assets/part_1_cat_scanner_repo.png)
+
+After this point we do not need the newly created repository anymore, so you can delete it in GitHub.
 
 ??? Warning "Authentication"
 
@@ -126,5 +132,7 @@ in GitHub for you.
     section in Getting Started and ensure you have a valid token. You will only
     be able to make repos in an org that you have access to create public repos.
 
-The above package installed a lot more actions than just the `publish:github`,
-[you can browse the rest of the available templates here](http://localhost:3000/create/actions).
+!!! tip "Installed actions"
+
+    The above package installed a lot more actions than just the `publish:github`,
+    [you can browse the rest of the available templates here](http://localhost:3000/create/actions).

docs/part-2.md

@@ -73,7 +73,7 @@ backend.add(
 Now we need to export your action correctly from the plugin for the "new
 backend" system.
 
-Create a new file in your plugin called `src\module.ts` containing the following
+Create a new file in your created plugin called `backstage/plugins/<your plugin>/src/module.ts` containing the following
 code
 
 ```typescript
@@ -120,26 +120,28 @@ removing the required inputs and properties definitions. We don't need them
 (yet). Your call to `createTemplateAction` should something look like this:
 
 ```typescript
-return createTemplateAction<{
-  myParameter: string;
-}>({
-  id: "catscanner:randomcat",
-  description: "Downloads a random cat image into the workspace",
-  schema: {
-    input: {
-      type: "object",
-      required: [],
-      properties: {},
+...
+  return createTemplateAction<{
+    myParameter: string;
+  }>({
+    id: "catscanner:randomcat",
+    description: "Downloads a random cat image into the workspace",
+    schema: {
+      input: {
+        type: "object",
+        required: [],
+        properties: {},
+      },
     },
-  },
-  async handler(ctx) {
-    ctx.logger.info(
-      `Running example template with parameters: ${ctx.input.myParameter}`
-    );
+    async handler(ctx) {
+      ctx.logger.info(
+        `Running example template with parameters: ${ctx.input.myParameter}`
+      );
 
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-  },
-});
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    },
+  });
+...
 ```
 
 Now need to implement the action code in the `handler` function in
@@ -176,6 +178,12 @@ with a repo that has a single cat image in it.
 
 !!! tip "Don't forget to refresh your template!"
 
+??? tip "Hint"
+
+    Ensure you place the steps in the correct order. After running the automation you should see all the setps executed as well a link to the newly created repository.
+
+    ![Cat scanner repo with image](./assets/part_2_cat_scanner_repo.png)
+
 ## Bonus Round - Testing
 
 If you have not already you should try writing unit test for your new action

docs/part-3.md

@@ -190,13 +190,15 @@ scaffolder.
     ```
 
 Now we need to export the component from the plugin by modifying the `index.ts`
-in the `RandomCatPix` folder and in the components folder.
+in the `RandomCatPix` folder.
 
 ```typescript
 // plugins/catscanner-react/src/components/RandomCatPix/index.ts
 export { RandomCatPixFieldExtension } from "./extensions";
 ```
 
+Next we do the same in the `components` folder to export the `RandomCatPix`.
+
 ```typescript
 // plugins/catscanner-react/src/components/index.ts
 export * from "./RandomCatPix";

mkdocs.yml

@@ -4,6 +4,8 @@ theme:
   name: material
   icon:
     logo: material/robot-industrial
+  features:
+    - content.code.copy
   palette:
     # Palette toggle for automatic mode
     - media: "(prefers-color-scheme)"
@@ -33,8 +35,10 @@ nav:
       - Part 1 - Creating a template: "part-1.md"
       - Part 2 - Creating a new action: "part-2.md"
       - Part 3 - Customize the UI: "part-3.md"
+  - Clean up: "clean-up.md"
   - Appendix:
       - Part 2 - Code: "appendix/part-2-code.md"
+      - Part 3 - Code: "appendix/part-3-code.md"
 markdown_extensions:
   - admonition
   - pymdownx.details