## Add New Contributors in Seconds
@@ -59,7 +45,6 @@ so you can focus on your project instead of managing your ReadMe.
@@ -89,7 +74,7 @@ so you can focus on your project instead of managing your ReadMe.
{/* Left: Image */}
-
+
-
-
Start adding contributors to your project today
+
+
Install the Bot
Read the Docs
diff --git a/src/content/docs/overview.mdx b/src/content/docs/overview.mdx
index e855f200..b9ca5901 100644
--- a/src/content/docs/overview.mdx
+++ b/src/content/docs/overview.mdx
@@ -3,16 +3,15 @@ id: overview
title: Overview
sidebar_label: Overview
---
+import { Picture } from "astro:assets";
+import { Aside } from '@astrojs/starlight/components';
+import contributorsTableSmall from '@assets/contributors-table-small.png';
-> Call for translators! [We're looking for translators](https://github.com/all-contributors/all-contributors/issues/143) to help translate this spec for everyone!
+[](https://github.com/all-contributors/all-contributors)
-
Start adding contributors to your project today
- 
-
-
-Star
+
-This is a specification for recognizing contributors to an open-source project in a way that rewards every contribution, not just code.
+All-contributors is a specification for recognizing contributors to an open-source project in a way that rewards every contribution, not just code.
The basic idea is this:
@@ -22,16 +21,11 @@ People are giving themselves and their free time to contribute to open source pr
## The All Contributors Table
-Below is an example of how using the all-contributors spec table can recognize all contributors
-
-
- 
+Below is an example of how using the all-contributors spec table can recognize all contributors.
+` utility to add images to our documentation. This utility supports a web compression feature that will automatically convert images to formats like webp and avif upon rendering.
+
+To use the Picture utility,
+
+1. First import the utility at the top of the `.mdx` file like this
+ ```markdown
+ import { Picture } from "astro:assets";
+ ```
+2. Optionally, define an alias for your image path at the top of the MDX file.
+ You can also call it directly using a path.
+ The image below has an alias of contributorsTableSmall and it's located in the assets directory of the site:
+ ```markdown
+ import contributorsTableSmall from '@assets/contributors-table-small.png';
+ ```
+3. Use the `Picture` utility in your MDX page like this
+ ```markdown
+
+Below is an example of how using the all-contributors spec table can recognize all contributors.
+
+
-> You can use [the @all-contributors bot 🤖](bot/overview) to automate acknowledging contributors to your open source projects
-
-## What's next
-
-- [The all contributors specification](specification)
-- [Emoji Key (Contribution Types Reference)](emoji-key)
-- [Notes for repository maintainers](repository-maintainers)
-- [Automating the process using tools](tooling)
+
diff --git a/src/content/docs/project/development.mdx b/src/content/docs/project/development.mdx
new file mode 100644
index 00000000..deff3634
--- /dev/null
+++ b/src/content/docs/project/development.mdx
@@ -0,0 +1,90 @@
+---
+id: development
+title: Development Guide
+sidebar_label: development
+---
+import { Aside } from '@astrojs/starlight/components';
+
+Welcome to the development guide for the All Contributors documentation site!
+
+## How to Work On Our Documentation
+
+Our docs are built using [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) theme.
+Astro is a javascript based static site generator.
+It is is designed for building fast, modern websites with a focus on performance and flexibility.
+It allows us to write components in multiple frameworks.
+Astro ships only the minimal JavaScript needed.
+
+We use the [Starlight theme with Astro](https://starlight.astro.build/).
+Starlight provides a beautiful, accessible, and feature-rich documentation platform out of the box.
+It handles navigation, search, dark mode, and supports [Tailwind CSS](https://tailwindcss.com/docs).
+
+## MDX Files
+
+Our documentation pages are largely written using the **MDX** (`.mdx`) format. This format supports Markdown with the additional ability to include components and custom elements directly in the content. This allows us to embed images, asides, and other interactive elements easily.
+
+
+
+## Images paths and aliases
+
+All images live in the assets directory.
+We defined an alias to the assets directory in the site configuration file (`astro.config.mjs`) to make referencing items easier.
+
+To see how this is defined, go to `astro.config.mjs`.
+The alias for assets (@assets) is defined there:
+
+```js
+vite: {
+ plugins: [tailwindcss()],
+ resolve: {
+ alias: {
+ '@assets': '/src/assets',
+ },
+ },
+```
+
+
+## Adding Images to the Docs
+
+We use the `
-
+
+
-
-
-### All Contributors CLI
-
-If you prefer command-line tools, you can instead use the [all-contributors CLI tool](cli/overview) to help automate adding contributor acknowledgements.
diff --git a/src/content/docs/tooling.mdx b/src/content/docs/tooling.mdx
new file mode 100644
index 00000000..4e20db90
--- /dev/null
+++ b/src/content/docs/tooling.mdx
@@ -0,0 +1,25 @@
+---
+id: tooling
+title: Automating Updates with Tooling
+sidebar_label: Tooling
+---
+import { Picture } from "astro:assets";
+import botUsage from '@assets/bot-usage.png';
+
+## Why We Created the All Contributors Bot and CLI
+
+Implementing the [All Contributors spec](specification) by hand is a laborious process. To add contributors who have not contributed code to your project but have contributed in other ways requires manually editing your README file to add their name, profile link, and the appropriate contribution type emoji.
+
+Further, you'd have to keep track of who has contributed what over time. This is a lot to manage, especially for larger projects with many contributors.
+
+### All Contributors Bot
+
+The [@all-contributors bot 🤖](bot/overview), makes the process of adding contributors of all kinds simple. When called to add a user, the bot will automatically pull a user's profile image, grab the contribution type emoji, update your project's README file and then open a Pull Request against the project with the updated README file. ✨
+
+
+
+
+
## Mandatory
@@ -25,7 +30,7 @@ Open source projects should include the following mandatory items to support the
- The order of contributors is immaterial to the spec. Order them how you wish.
3. Projects should define contributors as those who contribute to a project in any of the Contribution Categories at any level of contribution. This specification is, by definition, inclusive of all contributions. In cases where projects deviate from the Contribution Categories or require a specific contribution level to meet criteria as a project contributor, the project should provide explicit documentation of the definitions that satisfy the project contributor criteria in the CONTRIBUTING document or a similar prominent public document at the top level of the project repository. This specification recommends against the exclusion of an individual from the Contributor list based upon the perceived level of contribution. Instead, projects should use indicators of effort within a list that remains inclusive of all contributors to the project at any level of effort. If used, these effort indicators are at the discretion of the project and are not currently specified.
-> **Pro tip:** You can use [the @all-contributors bot 🤖](bot/overview) to automate acknowledging contributors to your open source projects ✨
+
## Optional
@@ -33,9 +38,3 @@ Projects should consider the following optional items as part of their commitmen
1. The user's avatar can be included and is recommended.
2. An optional link from the Contribution Category indicator to the category-specific contribution(s) can be included to provide additional information about the project contribution(s) as detailed in the section below.
-
-## What's next
-
-- [Emoji Key (Contribution Types Reference)](emoji-key)
-- [Notes for repository maintainers](repository-maintainers)
-- [Automating the process using tools](tooling)
diff --git a/src/content/docs/tooling.md b/src/content/docs/tooling.md
deleted file mode 100644
index a5f25391..00000000
--- a/src/content/docs/tooling.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-id: tooling
-title: Automating Updates with Tooling
-sidebar_label: Tooling
----
-
-## Motivation
-
-Implementing the [All Contributors spec](specification) by hand is a laborious process.
-
-### All Contributors Bot
-
-Enter the [@all-contributors bot 🤖](bot/overview)! The bot will automatically pull a user's profile, grab the contribution type emoji, update the project README and then open a Pull Request against the project ✨
-
-
-
-
-### All Contributors CLI
-
-If you prefer command-line tools, you can instead use the [all-contributors CLI tool](cli/overview) to help automate adding contributor acknowledgements.
diff --git a/src/content/docs/tooling.mdx b/src/content/docs/tooling.mdx
new file mode 100644
index 00000000..4e20db90
--- /dev/null
+++ b/src/content/docs/tooling.mdx
@@ -0,0 +1,25 @@
+---
+id: tooling
+title: Automating Updates with Tooling
+sidebar_label: Tooling
+---
+import { Picture } from "astro:assets";
+import botUsage from '@assets/bot-usage.png';
+
+## Why We Created the All Contributors Bot and CLI
+
+Implementing the [All Contributors spec](specification) by hand is a laborious process. To add contributors who have not contributed code to your project but have contributed in other ways requires manually editing your README file to add their name, profile link, and the appropriate contribution type emoji.
+
+Further, you'd have to keep track of who has contributed what over time. This is a lot to manage, especially for larger projects with many contributors.
+
+### All Contributors Bot
+
+The [@all-contributors bot 🤖](bot/overview), makes the process of adding contributors of all kinds simple. When called to add a user, the bot will automatically pull a user's profile image, grab the contribution type emoji, update your project's README file and then open a Pull Request against the project with the updated README file. ✨
+
+
+
+
+### All Contributors CLI
+
+If you prefer command-line tools, you can instead use the all-contributors CLI tool to help automate adding contributor acknowledgements. [Read more about the All-Contributor bot CLI here](cli/overview).
diff --git a/src/content/docs/repository-maintainers.md b/src/content/docs/usage-tips.mdx
similarity index 69%
rename from src/content/docs/repository-maintainers.md
rename to src/content/docs/usage-tips.mdx
index ddba5906..6c737adc 100644
--- a/src/content/docs/repository-maintainers.md
+++ b/src/content/docs/usage-tips.mdx
@@ -1,15 +1,22 @@
---
id: repository-maintainers
-title: Notes for Repository Maintainers
+title: "How to Use the Bot: Tips for Repository Maintainers"
sidebar_label: Repository Maintainers
---
+import { Aside } from '@astrojs/starlight/components';
+
+## When to add a contributor
Contributors should be recognised as soon as the contribution is discovered to help ensure their efforts are not
overlooked when the list gets updated at a later date. This can be difficult for contributions that are not the result of a commit to the repository but do your best to minimise the time between the contribution and updating the list.
-> **Pro tip:** If your project is configured for [the @all-contributors bot 🤖](bot/overview) simply write a comment on an issue or pull request to recognise their contribution. For example:
->
+
+
+## Encourage contributors to add themselves using the bot
Being the owner or a maintainer of the repository does not mean you are solely responsible for keeping the list of
contributors up to date. You should encourage contributors to add themselves to the list as much as possible.
@@ -18,12 +25,12 @@ This can be in the form of a comment on the issue, blog or answer, or through mo
Many contributors may not realise that their efforts are sufficient for recognition in the contributors list.
This might be because they have not read or understood the definition of a contributor as set out in this specification,
or because they do not feel like it is significant enough. In these cases, you should still encourage them to add themselves,
-but it may be necessary for you to add the contributor yourself (though it's a good idea to do so in the form of a pull
-request to make sure they're ok with being added).
+but it may be necessary for you to add the contributor yourself.
+
+
In the end, there are no hard and fast rules for when a contribution has to be added to the list,
just do your best to be fair and to ensure all contributors are recognised.
-
-## What's next
-
-- [Automating the process using tools](tooling)