docs: update, reword, fix dead links

Author: lishaduck

.gitignore

@@ -55,4 +55,6 @@ apps/cli-playground/*
 !apps/cli-playground/tsconfig.json
 
 # tsx trash files
-apps/sheriff-webservices/undefined
+apps/sheriff-webservices/undefined
+
+README.md

.prettierignore

@@ -43,5 +43,3 @@ pnpm-lock.yaml
 
 # MDX v3
 *.mdx
-
-README.md

CONTRIBUTING.md

@@ -20,77 +20,75 @@ Sheriff thrives on community input. If you have ideas for new rules to implement
 
 ### Requirements
 
-- make sure Git is installed in your system
-- make sure Nodejs 20.10.X is installed in your system
-- make sure [Pnpm is installed](https://pnpm.io/installation) in your system. If you are not sure how to install it, use corepack:
+- Ensure Git is installed in your system.
+- Ensure Node.js 20.10.x is installed in your system.
+- Ensure [pnpm is installed](https://pnpm.io/installation) in your system. If you are not sure how to install it, use Corepack:
 
-  ```bash
+  ```sh
   corepack enable
   ```
 
 ### Step-by-Step Guide
 
 1. Start by forking this repository to your own GitHub account.
-2. Clone your fork locally with:
+1. Clone your fork locally with:
 
-   ```bash
+   ```sh
    git clone https://github.com/<your-username>/sheriff.git
    ```
 
-3. Install all required dependencies using:
+1. Install all required dependencies using:
 
-   ```bash
+   ```sh
    pnpm i
    ```
 
-4. Create a new branch for your feature or fix:
+1. Create a new branch for your feature or fix:
 
-   ```bash
+   ```sh
    git checkout -b new-feature
    ```
 
-5. Implement your changes in the codebase.
+1. Implement your changes in the codebase.
 
    - If you need to update the documentation website, you can run it locally with:
 
-     ```bash
+     ```sh
      pnpm dev:norebuild
      ```
 
      The website will be available at `http://localhost:3000`.
 
    - If you need test the CLI, you can run:
 
-     ```bash
+     ```sh
      pnpm playground
      ```
 
      or:
 
-     ```bash
-       pnpm playground:mimic-monorepo
+     ```sh
+     pnpm playground:mimic-monorepo
      ```
 
-6. Add a `changeset`:
+1. Add a `changeset`:
 
-   ```bash
+   ```sh
    pnpm changeset
    ```
 
-7. Write clear, concise commit messages. Make sure to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification:
+1. Write clear, concise commit messages. Make sure to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification:
 
-   ```bash
+   ```sh
    git commit -am 'feat(context): added feature'
    ```
 
-8. Push your branch to your fork:
+1. Push your branch to your fork:
 
-   ```bash
+   ```sh
    git push origin new-feature
    ```
 
-9.
-
-10. **Open a Pull Request**: Submit your changes by creating a pull request to the main repository.
+1. **Open a Pull Request**: Submit your changes by creating a pull request to the main repository.
 
 Thank you for helping make Sheriff a better project for everyone!

README.md

@@ -1,42 +1,55 @@
 <div align="center">
   <a href="https://www.eslint-config-sheriff.dev">
-      <img src="https://github.com/AndreaPontrandolfo/sheriff/blob/master/apps/docs-website/static/img/sheriff-logo.svg" width="240">
+    <img alt="Sheriff logo" src="https://github.com/AndreaPontrandolfo/sheriff/blob/master/apps/docs-website/static/img/sheriff-logo.svg" width="240" />
     <h1 align="center">Sheriff</h1>
   </a>
   <p align="center">
     ✨ A comprehensive and opinionated TypeScript-first ESLint configuration ✨
   </p>
-  <div>
+<div>
 
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?color=1A786D)](CODE_OF_CONDUCT.md)
-[![npm downloads](https://img.shields.io/npm/dm/eslint-config-sheriff.svg?label=npm%20downloads&color=1A786D)](https://www.npmjs.com/package/eslint-config-sheriff)
+[![Contributor Covenant][conduct-badge]](CODE_OF_CONDUCT.md)
+[![npm downloads][downloads-badge]][config-pkg]
 
   </div>
 </div>
 
-
 ## 🥳 Overview
 
-This repository is a monorepo that hosts the sourcecode of the following projects:
+This repository is a monorepo that hosts the source code of the following projects:
 
-| Link                                                                           | Source                                                                                                            | Description                                                           | Version                                                                                                                                                  |
-| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Sheriff docs website](https://www.eslint-config-sheriff.dev)                          | [docs-website](https://github.com/AndreaPontrandolfo/sheriff/tree/master/apps/docs-website)                       | Sheriff documentation website                                         | |
-| [`eslint-config-sheriff`](https://www.npmjs.com/package/eslint-config-sheriff) | [eslint-config-sheriff](https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/eslint-config-sheriff) | A comprehensive and opinionated TypeScript-first ESLint configuration | [![npm](https://img.shields.io/npm/v/eslint-config-sheriff.svg?color=1A786D)](https://www.npmjs.com/package/eslint-config-sheriff)                                    |
-| [`@sherifforg/create-config`](https://www.npmjs.com/package/@sherifforg/create-config) | [sheriff-create-config](https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/sheriff-create-config) | Package used to create Sheriff-based ESLint configs                             | [![npm](https://img.shields.io/npm/v/@sherifforg/create-config.svg?color=1A786D)](https://www.npmjs.com/package/@sherifforg/create-config)                                    |
-| [`@sherifforg/cli`](https://www.npmjs.com/package/@sherifforg/cli) | [sheriff-cli](https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/sheriff-cli) | The Sheriff CLI. Used to manage Sheriff-based ESLint configs                             | [![npm](https://img.shields.io/npm/v/@sherifforg/cli.svg?color=1A786D)](https://www.npmjs.com/package/@sherifforg/cli)                                    |
+| Link                                      | Source                              | Description                                                           | Version                            |
+| ----------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- | ---------------------------------- |
+| [Sheriff docs website][docs]              | [docs-website][docs-dir]            | Sheriff documentation website                                         |                                    |
+| [`eslint-config-sheriff`][config-pkg]     | [eslint-config-sheriff][config-dir] | A comprehensive and opinionated TypeScript-first ESLint configuration | [![npm][config-badge]][config-pkg] |
+| [`@sherifforg/create-config`][create-pkg] | [sheriff-create-config][create-dir] | Package used to create Sheriff-based ESLint configs                   | [![npm][create-badge]][create-pkg] |
+| [`@sherifforg/cli`][cli-pkg]              | [sheriff-cli][cli-dir]              | The Sheriff CLI. Used to manage Sheriff-based ESLint configs          | [![npm][cli-badge]][cli-pkg]       |
 
 ## 🚀 Getting Started
 
-Visit the [official docs](https://www.eslint-config-sheriff.dev) to get started with Sheriff.
+Visit the [official docs][docs] to get started with Sheriff.
 
 ## 📝 Updates
 
 You can follow the latest updates on the project in the [official blog](https://www.eslint-config-sheriff.dev/blog).
 
 ## 💌 Acknowledgments
 
-For some of this configuration, [eslint-config-red](https://github.com/GrosSacASac/JavaScript-Set-Up/blob/master/js/red-javascript-style-guide/index.js) was partially used as a base.<br>
-Additionally, inspiration was drawn from [eslint-config-airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb) for some of the rules in `no-restricted-syntax`.<br>
-I don't take any attribution for the rules in the various eslint-plugins used here (except for the few that I personally created). Please consider starring the respective projects for the awesome work their authors made. Sheriff wouldn't be possible without their efforts.<br>
+For some of this configuration, [eslint-config-red](https://github.com/GrosSacASac/JavaScript-Set-Up/blob/master/js/red-javascript-style-guide/index.js) was partially used as a base.<br />
+Additionally, inspiration was drawn from [eslint-config-airbnb](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb) for some of the rules in `no-restricted-syntax`.<br />
+I don’t take any attribution for the rules in the various ESLint plugins used here (except for the few that I personally created). Please consider starring the respective projects for the awesome work their authors made. Sheriff wouldn’t be possible without their efforts.<br />
 The full list of the plugins used is [here](https://www.eslint-config-sheriff.dev/docs/eslint-plugins).
+
+[docs]: https://www.eslint-config-sheriff.dev
+[docs-dir]: https://github.com/AndreaPontrandolfo/sheriff/tree/master/apps/docs-website
+[config-pkg]: https://www.npmjs.com/package/eslint-config-sheriff
+[config-dir]: https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/eslint-config-sheriff
+[config-badge]: https://img.shields.io/npm/v/eslint-config-sheriff.svg?color=1A786D
+[create-pkg]: https://www.npmjs.com/package/@sherifforg/create-config
+[create-dir]: https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/sheriff-create-config
+[create-badge]: https://img.shields.io/npm/v/@sherifforg/create-config.svg?color=1A786D
+[cli-pkg]: https://www.npmjs.com/package/@sherifforg/cli
+[cli-dir]: https://github.com/AndreaPontrandolfo/sheriff/tree/master/packages/sheriff-cli
+[cli-badge]: https://img.shields.io/npm/v/@sherifforg/cli.svg?color=1A786D
+[downloads-badge]: https://img.shields.io/npm/dm/eslint-config-sheriff.svg?label=npm%20downloads&color=1A786D
+[conduct-badge]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?color=1A786D

apps/docs-website/blog/2023-08-16-sheriff-reboot.mdx

@@ -27,41 +27,41 @@ Let's walkthrough the key changes of this release.
 
 ## Restructured Codebase in a monorepo
 
-The codebase has been restructured into a monorepo setup with [Turborepo](https://turbo.build/repo) + [pnpm workspaces](https://pnpm.io/workspaces), as it allows for the management of multiple related packages under a single repository, streamlining the development process and enabling better coordination between different parts of the project.
+The codebase has been restructured into a monorepo setup with [Turborepo](https://turbo.build/repo/docs) + [pnpm workspaces](https://pnpm.io/workspaces), as it allows for the management of multiple related packages under a single repository, streamlining the development process and enabling better coordination between different parts of the project.
 
 As a side-effect, the project now relies on [changesets](https://github.com/changesets/changesets) to manage semantic versioning, in place of [semantic-release](https://github.com/semantic-release/semantic-release).
 
 ## Complete Rebranding
 
 ### New Docs
 
-The documentation has been fully revamped, moving on from [Gitbook](https://www.gitbook.com/) to [Docusaurus](https://docusaurus.io/), a modern documentation framework.<br/>
-Whether a newcomer or a seasoned user, the documentation is more accessible and easier to navigate, with a sidebar that allows for quick access to the different sections.<br/>
+The documentation has been fully revamped, moving on from [GitBook](https://www.gitbook.com/) to [Docusaurus](https://docusaurus.io/), a modern documentation framework.<br />
+Whether a newcomer or a seasoned user, the documentation is more accessible and easier to navigate, with a sidebar that allows for quick access to the different sections.<br />
 Also, a special [Rules page](https://www.eslint-config-sheriff.dev/docs/rules) was carefully crafted to let users explore in detail all the rules that Sheriff enables.
 
 Visit the new docs at this [link](https://www.eslint-config-sheriff.dev).
 
 ### New Logo
 
-The beginning of a fresh era for Sheriff is marked by a new logo, that features the iconic ESLint logo and a shield.
+The beginning of a fresh era for Sheriff is marked by a new logo that features the iconic ESLint logo and a shield.
 
 ![Sheriff Logo](/img/sheriff-logo.svg)
 
 ### New Blog
 
-A [brand-new blog](https://www.eslint-config-sheriff.dev/blog) is now available, where I'll keep sharing updates on the projects as it grows along.
+A [brand-new blog](https://www.eslint-config-sheriff.dev/blog) is now available, where I'll keep sharing updates as it grows along.
 
 ## What's Next
 
 The focus remains on continuously improving the tool, making it more adaptable, and responding to the evolving needs of the development community.<br />
 Looking ahead, several exciting developments are in store:
 
-- **Astro Support**: In the continuous effort to integrate more eslint-plugins into Sheriff, the next in line is [eslint-plugin-astro](https://github.com/ota-meshi/eslint-plugin-astro).
+- **Astro Support**: In the continuous effort to integrate more ESLint plugins into Sheriff, the next in line is [eslint-plugin-astro](https://github.com/ota-meshi/eslint-plugin-astro).
 - **Searchbar**: full-text search, powered by [Algolia](https://www.algolia.com/) in the new docs.
 - **Ask AI**: along with the new searchbar will come an "Ask AI bot" feature. Details on this one are still being worked on.
 
 ## Conclusion
 
-With this much-needed facelift, Sheriff is ready to keep growing. With a new documentation hub powered by Docusaurus, logo, and blog in place, Sheriff is set to provide an even more exceptional ESLint sharable config experience.<br/>
-If you want to help feel free to propose new features, both for the config and the docs, or report any bug you might come across.<br/>
+With this much-needed facelift, Sheriff is ready to keep growing. With a new documentation hub powered by Docusaurus, logo, and blog in place, Sheriff is set to provide an even more exceptional ESLint sharable config experience.<br />
+If you want to help feel free to propose new features, both for the config and the docs, or report any bug you might come across.<br />
 Stay tuned for updates and insights on the new blog!

apps/docs-website/blog/2023-11-01-astro-support-landed.mdx

@@ -21,19 +21,25 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
 
 ## Sheriff release v16
 
-Sheriff continues his quest to conquer the JS ecosystem.
+Sheriff continues its quest to conquer the JS ecosystem.
 
 ## Sheriff extends support for Astro
 
-This release introduces support for [Astro.js](https://astro.build/), thanks to [ota-meshi](https://github.com/ota-meshi) libraries, [eslint-plugin-astro](https://github.com/ota-meshi/eslint-plugin-astro) and [astro-eslint-parser](https://github.com/ota-meshi/astro-eslint-parser).
+This release introduces support for [Astro](https://astro.build/), thanks to [ota-meshi](https://github.com/ota-meshi)’s libraries, [eslint-plugin-astro](https://github.com/ota-meshi/eslint-plugin-astro) and [astro-eslint-parser](https://github.com/ota-meshi/astro-eslint-parser).
 
 The integration is provided out-of-the-box, meaning nothing has to be configured on the user side. Sheriff will automatically detect Astro projects and run the appropriate rules. All you have to do is upgrade Sheriff to this version.
 
+:::important
+
+As of Sheriff v19, Astro support has been moved behind an option.
+
+:::
+
 This integration presented significant challenges, as the pertinent ESLint plugins are still in experimental status and also because this integration provides JSX-relevant ESLint rules inside `.astro` files, meaning that we are now parsing `.astro` files (in a Typescript-aware way) and provide Astro and React relevant rules inside them. This has not been trivial.
 
 ## Sheriff meets Algolia
 
-The Sheriff documentation website has now a full-text search powered by [Algolia Docsearch](https://docsearch.algolia.com/), generously provided for free by the open-source projects sponsorship by [Algolia](https://www.algolia.com/) . The documentation is now easier than ever to navigate.
+The Sheriff documentation website has now a full-text search powered by [Algolia Docsearch](https://docsearch.algolia.com/), generously provided for free by the open-source projects sponsorship by [Algolia](https://www.algolia.com/). The documentation is now easier than ever to navigate.
 
 The "Ask AI" feature, instead, didn't make it in this release. There aren't yet solid solutions in this space, for now.
 
@@ -44,7 +50,7 @@ Finally, as the last treat, my newest `eslint-plugin`, [fsecond](https://github.
 Fsecond adds 2 new rules:
 
 - `fsecond/prefer-destructured-optionals`: enforce placing optional parameters to the end of the function signature as destructured objects
-- `fsecond/valid-event-listener`: enforce using a `useEventListener` utility function instead of `addEventListener` methods, or, optionally, you can disable that behaviour and the rule will just warn against incorrect usage of addEventListener methods
+- `fsecond/valid-event-listener`: enforce using a `useEventListener` utility function instead of `addEventListener` methods, or, optionally, you can disable that behavior and the rule will just warn against incorrect usage of addEventListener methods
 
 ## What's Next
 
@@ -58,6 +64,6 @@ The commitment to improving Sheriff remains strong. Here's a glimpse of what's o
 
 ## Conclusion
 
-As always, if you feel like contributing, feel free to propose suggestions or pull-requests. And if you just want to show appreciation, leave a star on Github.
+As always, if you feel like contributing, feel free to propose suggestions or pull-requests. And if you just want to show appreciation, leave a star on GitHub.
 
 Sheriff is actively dedicated to becoming even more adaptable and feature-rich. Stay tuned for further updates and enhancements!