diff --git a/examples/github-appcards/README.md b/examples/github-appcards/README.md
index 347497077..914784664 100644
--- a/examples/github-appcards/README.md
+++ b/examples/github-appcards/README.md
@@ -1,82 +1,53 @@
-## GitHub app cards
+# GitHub App Cards Miro app
This full-stack example shows how to build an integration with GitHub that syncs data between GitHub issues and Miro app cards.
-💡 Check the complete tutorial: [Enable 2-way sync between app cards and GitHub cards](https://developers.miro.com/docs/enable-2-way-sync-between-app-cards-and-github-cards)
+# 👨🏻💻 App Demo
-** ℹ Note**:
+# 📒 Table of Contents
-- We recommend a Chromium-based web browser for local development with HTTP. \
- Safari enforces HTTPS; therefore, it doesn't allow localhost through HTTP.
-- All examples use `npm` as a package manager and `npx` as a package runner. \
- If you prefer, you can install and use equivalent alternatives, such as `yarn` or `pnpm`.
-- For more information about implementing [drag and drop](https://developers.miro.com/docs/add-drag-and-drop-to-your-app), visit our [developer documentation](https://developers.miro.com).
+- [Included Features](#features)
+- [Tools and Technologies](#tools)
+- [Prerequisites](#prerequisites)
+- [Associated Developer Tutorial](#tutorial)
+- [Run the app locally](#run)
+- [Folder Structure](#folder)
+- [Contributing](#contributing)
+- [License](#license)
-### About the app
+# ⚙️ Included Features
-This full-stack app shows how to build an integration with GitHub Projects that enables a 2-way sync data flow between GitHub issues and Miro app cards.
+- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference)
+ - [miro.board.getById()](https://developers.miro.com/docs/board_board#getbyid)
+ - [miro.board.ui.openPanel(options)](https://developers.miro.com/docs/ui_boardui#openpanel)
+ - [miro.board.ui.closeModal()](https://developers.miro.com/docs/ui_boardui#closemodal)
+ - [miro.board.createAppCard()](https://developers.miro.com/docs/websdk-reference-board#createappcard)
+ - [miro.board.getInfo()](https://developers.miro.com/docs/websdk-reference-board#getinfo)
+ - [miro.board.viewport.zoomTo()](https://developers.miro.com/docs/websdk-reference-viewport#zoomto)
-This app is bootstrapped using [create-miro-app](https://www.npmjs.com/package/create-miro-app). It uses React, Typescript, and Vite.
+# 🛠️ Tools and Technologies
-To modify the `vite.config.js` configuration, see the [Vite documentation](https://vitejs.dev/guide/).
+- [React](https://react.dev/)
+- [Netlify](https://www.netlify.com/)
+- [Vite](https://vitejs.dev/)
-### How to start locally
+# ✅ Prerequisites
-1. Run `npm install` to install dependencies.
-2. Add a `.env` file with the required environment variables (See example at the end of this article).
-3. Run `npm start` to start developing. \
- Your URL should be similar to this example:
- ```
- http://localhost:3000
- ```
-4. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro).\
- In the app manifest editor, configure the app as follows:
- - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \
- It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on.
- - [`redirectUris`](https://developers.miro.com/docs/app-manifest#redirecturis): assign `http://localhost:3000/authorize` as a value for this property. \
- It defines the redirect URL that starts the OAuth 2.0 code grant flow for the REST API.
- - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \
- To enable the app to read from and write to the board, add the following permissions:
- - `boards:read`
- - `boards:write`
-5. Open a board: you should see your app in the apps toolbar or in the apps panel.
+- You have a [Miro account](https://miro.com/signup/).
+- You're [signed in to Miro](https://miro.com/login/).
+- Your Miro account has a [Developer team](https://developers.miro.com/docs/create-a-developer-team).
+- Your development environment includes [Node.js 14.13](https://nodejs.org/en/download) or a later version.
+- GitHub Account and [access token](https://github.com/settings/tokens).
+- [Supabase account](https://supabase.com/) and database.
-### How to build the app
+# 📖 Associated Developer Tutorial
-- Run `npm run build`. \
- This generates a static output inside `dist/`, which you can host on a static hosting service.
+> To view a more in depth developer tutorial
+> of this app (including code explanations) see the [GitHub app cards 2-way sync tutorial](https://developers.miro.com/docs/enable-2-way-sync-between-app-cards-and-github-cards) on Miro's Developer documentation.
-### Folder structure
+# 🏃🏽♂️ Run the app locally
-The structure below outlines the most important files in the project used for its core functionality.
-
-```
-.
-├── .github
-├── netlify
-├── src
-│ └── assets
-│ └── style.css <-- CSS styles for the app.
-| └── components <-- Folder of all UI components used in the app.
-| └── utils
-│ └── github.ts <-- Utility functions for interacting with the GitHub API.
-│ miro.ts <-- Utility functions for interacting with the Miro Web SDK and REST API.
-│ supabase.ts <-- Main entry for interacting with Supabase.
-│ └── app.tsx <-- The main entry. Contains structure for the sidebar when launched.
-│ appcard-modal.tsx <-- The main entry for the modal that appears when an app card is expanded.
-│ constants.ts <-- A collection of static variables used throughout the app.
-│ index.ts <-- Initializes app, and contains logic for opening the app from the sidebar and expanding an app card.
-│ modal.tsx <-- The main entry for the modal that appears when selecting a GitHub issue to import.
-├── app.html <-- The app itself. This is loaded on the board inside 'app.tsx'.
-├── appcard-modal.html <-- The app card modal itself. This is loaded on the board inside the 'appcard-modal.tsx'.
-├── index.html <-- The app entry point. This is the value you assign to 'sdkUri' in the app manifest file.
-└── modal.html <-- The modal itself. This is loaded on the board inside the 'modal.tsx'.
-```
-
-## Required Environment Variables
-
-To run the app, Vite loads an `.env` file with the [environment variables](https://vitejs.dev/guide/env-and-mode.html#env-files).
-Use the commented example below to create your `.env` file.
+1. Create a `.env` file and add in the associated env variables as documented below:
```.env
# Generate an access token in GitHub, and enter the value here.
@@ -115,3 +86,68 @@ MIRO_CLIENT_SECRET=
# https://developers.miro.com/reference/authorization-flow-for-expiring-access-tokens
MIRO_REDIRECT_URI=
```
+
+2. Run `npm install` to install dependencies.
+3. Run `npm start` to start developing. \
+ Your URL should be similar to this example:
+ ```
+ http://localhost:3000
+ ```
+4. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \
+ In the app manifest editor, configure the app as follows and then `click save`.
+
+```yaml
+# See https://developers.miro.com/docs/app-manifest on how to use this
+appName: GitHub App Cards
+sdkUri: "http://localhost:3000"
+redirectUris:
+ - http://localhost:3000/authorize
+scopes:
+ - boards:read
+ - boards:write
+```
+
+5. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. In the video we install a different app, but the process is the same regardless of the app.
+
+> ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️
+
+https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf
+
+6. Go to your developer team, and open your boards.
+7. Click on the plus icon from the bottom section of your left sidebar. If you hover over it, it will say `More apps`.
+8. Search for your app `GitHub App Cards` or whatever you chose to name it. Click on your app to use it, as shown in the video below. In the video we search for a different app, but the process is the same regardless of the app.
+
+https://github.com/horeaporutiu/app-examples-template/assets/10428517/b23d9c4c-e785-43f9-a72e-fa5d82c7b019
+
+# 🗂️ Folder structure
+
+```
+.
+├── .github
+├── netlify
+├── src
+│ └── assets
+│ └── style.css <-- CSS styles for the app.
+| └── components <-- Folder of all UI components used in the app.
+| └── utils
+│ └── github.ts <-- Utility functions for interacting with the GitHub API.
+│ miro.ts <-- Utility functions for interacting with the Miro Web SDK and REST API.
+│ supabase.ts <-- Main entry for interacting with Supabase.
+│ └── app.tsx <-- The main entry. Contains structure for the sidebar when launched.
+│ appcard-modal.tsx <-- The main entry for the modal that appears when an app card is expanded.
+│ constants.ts <-- A collection of static variables used throughout the app.
+│ index.ts <-- Initializes app, and contains logic for opening the app from the sidebar and expanding an app card.
+│ modal.tsx <-- The main entry for the modal that appears when selecting a GitHub issue to import.
+├── app.html <-- The app itself. This is loaded on the board inside 'app.tsx'.
+├── appcard-modal.html <-- The app card modal itself. This is loaded on the board inside the 'appcard-modal.tsx'.
+├── index.html <-- The app entry point. This is the value you assign to 'sdkUri' in the app manifest file.
+└── modal.html <-- The modal itself. This is loaded on the board inside the 'modal.tsx'.
+```
+
+# 🫱🏻🫲🏽 Contributing
+
+If you want to contribute to this example, or any other Miro Open Source project, please review [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md).
+
+# 🪪 License
+
+[MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE).