docs: update images and breakout links for the "bot" section of the documentation (all-contributors#919)

* docs: update images and document how to add content to our docs

docs: update images and edit text for all intro pages

docs: clean up all pages in the general overview section

docs: add description for Ideas, projectManagement and promotion (all-contributors#829)

docs: ✏️ Add dark mode README logo (all-contributors#741)

Co-authored-by: Leah Wasser <[email protected]>
Co-authored-by: Jim Madge <[email protected]>

* enh(image): bring in dark mode compatible logo

* docs: tidy adding images section

Move path alias section up and adjust

Apply suggestions from code review

Co-authored-by: Jim Madge <[email protected]>

* style: linting fixes for emoji table and other content

* docs: fix links and breakouts in bot section

* Apply suggestions from code review

Co-authored-by: Jim Madge <[email protected]>

---------

Co-authored-by: Jim Madge <[email protected]>
Co-authored-by: Jim Madge <[email protected]>

Author: lwasser

public/images/app-install.png renamed to src/assets/app-install.png

@@ -1,21 +1,23 @@
 ---
 id: installation
-title: Bot Installation
+title: How to Install the Bot
 sidebar_label: Installation
 ---
-
+import { Picture } from "astro:assets";
+import { LinkButton } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
+import installApp from '@assets/app-install.png';
+import configureRepo from '@assets/configure-repositories.png';
 
 ## 1. Install the AllContributors GitHub App
 
-[Install the GitHub App](https://github.com/apps/allcontributors/installations/new)
+<LinkButton href="https://github.com/apps/allcontributors/installations/new">Install the GitHub App</LinkButton>
 
-<a href="https://github.com/apps/allcontributors/installations/new">
-    <img alt="App Install Screenshot" src="/images/app-install.png" width="500px">
-</a>
+<Picture src={installApp} formats={['avif', 'webp']} alt="A screenshot of the GitHub interface that appears when you click the above install the bot button. It has a list of repositories and organizations that you have access to install the bot into." />
 
 ## 2. Configure your repositories
 
-<img alt="Configure Repositories Screenshot" src="/images/configure-repositories.png" width="500px">
+<Picture src={configureRepo} formats={['avif', 'webp']} alt="A screenshot showing how to configure repositories for the AllContributors GitHub App." />
 
 ## 3. Create a `README.md`
 
@@ -41,9 +43,11 @@ For the list:
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 ```
 
-Note: Extra line is very important in order to make it work properly.
+<Aside type="caution"> The extra line is to allow the bot to properly add contributors to that block in your README file.</Aside>
+
+For the badge use the following, replacing `projectOwner` with the relevant GitHub username or organization name, and `projectName` with the relevant the GitHub repo name. 
+Style, color, and other parameters can be customized to your liking — visit [shields.io](https://shields.io/) to make a custom badge.
 
-For the badge use the following, replacing `projectOwner` with the relevant GitHub username or organization name, and `projectName` with the relevant the GitHub repo name. Style, color, and other parameters can be customized to your liking — see <https://shields.io/>.
 
 ```markdown
 [![All Contributors](https://img.shields.io/github/all-contributors/projectOwner/projectName?color=ee8449&style=flat-square)](#contributors)
@@ -63,8 +67,3 @@ For the badge use the following, replacing `projectOwner` with the relevant GitH
 ## 4. Update your Contributing documentation
 
 Consider updating your `CONTRIBUTING.md` or similar with steps on how contributors can add themselves. You can even link to the [bot usage documentation](usage).
-
-## What's next
-
-- [Using the Bot](usage)
-- [Configuring the Bot](configuration)

public/images/configure-repositories.png renamed to src/assets/configure-repositories.png

@@ -0,0 +1,24 @@
+---
+id: overview
+title: Bot Overview
+sidebar_label: Overview
+---
+import { Picture } from "astro:assets";
+import botUsage from '@assets/bot-usage.png';
+
+[![Bot Latest Release](https://img.shields.io/github/release/all-contributors/all-contributors-bot.svg)](https://github.com/all-contributors/app/releases)
+
+[![Star on Github](https://img.shields.io/github/stars/all-contributors/all-contributors-bot.svg?style=flat-square)](https://github.com/all-contributors/all-contributors-bot/stargazers)
+
+🤖 A GitHub bot to automate acknowledging contributors to your open source projects.
+
+## How the Bot Works
+
+Implementing the [All Contributors spec](/specification) by hand is a laborious process.
+
+The `@all-contributors bot` makes adding contributors for contributions of all kinds easy! 
+
+1. First, you call the bot in any github issu or pull request and ask them to add a user for a specific contribution. 
+2. Once you do this, the bot will automatically pull a user's profile image, grab the contribution type emoji, update the project README file with the new contributors and then open a Pull Request against the project.
+
+<Picture src={botUsage} formats={['avif', 'webp']} alt="A screenshot of a github comment that says please add @user for design." />

src/content/docs/bot/installation.md renamed to src/content/docs/bot/installation.mdx

@@ -1,14 +1,15 @@
 ---
 id: usage
 title: Bot Usage
-sidebar_label: Usage
+sidebar_label: Bot Commands
 ---
+import { Picture } from "astro:assets";
+import {Aside} from '@astrojs/starlight/components';
+import botUsage from '@assets/bot-usage.png';
 
-> This usage documentation assumes you have already followed the [bot installation steps](installation).
+<Aside type="tip"> This usage documentation assumes you have already followed the [bot installation steps](installation).</Aside>
 
-## Commands
-
-<AUTOGENERATED_TABLE_OF_CONTENTS>
+## Bot Commands
 
 ### `@all-contributors add`
 
@@ -34,19 +35,18 @@ please add @<username> for <contributions>.
 please add @<username> for <contributions>.
 ```
 
-**\<contribution>**: See the [Emoji Key (Contribution Types Reference)](../emoji-key) for a list of valid `contribution` types.
+**contribution:** See the [Emoji Key (Contribution Types Reference)](/emoji-key) for a list of valid `contribution` types.
 
 The bot will then create a Pull Request to add the contributor, then reply with the pull request details.
 
-<img alt="Example usage screenshot" src="/images/bot-usage.png" width="500px">
+<Picture src={botUsage} alt="Example usage screenshot" />
+
+### Natural Language Processing 
 
-> Your request to the bot doesn't need to be perfect. The bot will use [basic Natural Language Parsing](https://github.com/all-contributors/app/blob/main/lib/parse-comment.js) to determine your intent.
+Your request to the bot doesn't need to be perfect. The bot will use [basic Natural Language Parsing](https://github.com/all-contributors/app/blob/main/lib/parse-comment.js) to determine your intent.
 > For example, this will work too:
 >
 > `Jane you are crushing it in the documentation and your infrastructure work has been great too. Let's add @jane.doe23 for her contributions. cc @all-contributors`
 >
-> The bot will work best in parsing your comment correctly if you precede the contributor's username with @ as shown above. Otherwise, the bot may not correctly identify the user.
-
-## What's next
 
-- [Configuring the Bot](configuration)
+The bot will work best in parsing your comment correctly if you precede the contributor's username with @ as shown above. Otherwise, the bot may not correctly identify the user.