feat(docs): add editor recipes and update guides

This commit introduces a new "recipes" section to the documentation, providing guides for integrating Mago with popular code editors and CI/CD pipelines.

Updated Installation Guide: The installation documentation has been rewritten for clarity and now includes instructions for all supported methods (Shell, Homebrew, Composer, Cargo, Manual).

Simplified README: The main README.md has been updated to be more concise, directing users to the official documentation for detailed installation instructions.

Signed-off-by: azjezz <[email protected]>

Author: azjezz

README.md

@@ -1,5 +1,7 @@
+## README.md
+
 <p align="center">
-    <img src="assets/banner.svg" alt="Mago Banner" width="600" />
+  <img src="docs/public/assets/banner.svg" alt="Mago Banner" width="600" />
 </p>
 
 <div align="center">
@@ -31,59 +33,27 @@
 - [Inspiration & Acknowledgements](#inspiration--acknowledgements)
 - [License](#license)
 
-## How to Install
-
-### Shell (Linux, macOS)
-
-```sh
-# with curl
-curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash
-
-# with wget
-wget -qO- https://carthage.software/mago.sh | bash
-```
-
-### Package Managers
-
-#### Homebrew (macOS)
-
-```sh
-brew install mago
-
-mago self-update
-```
-
-#### Composer (PHP Project)
-
-```sh
-composer require --dev carthage-software/mago
-```
-
-#### Cargo (Rust Toolchain)
-
-```sh
-cargo install mago
-```
+## Installation
 
-### Manual Download
+For detailed instructions on how to install Mago, please refer to our official **[Installation Guide](https://mago.carthage.software/guide/installation)**.
 
-You can download pre-compiled binaries for your system from the [GitHub Releases](https://github.com/carthage-software/mago/releases) page.
+We support various installation methods, including shell scripts, Homebrew, Composer, and Cargo.
 
 ## Getting Started
 
 Once installed, you can start using Mago immediately.
 
 1. Lint your project:
 
-```sh
-mago lint src/
-```
+   ```sh
+   mago lint src/
+   ```
 
 2. Format your code:
 
-```sh
-mago format src/
-```
+   ```sh
+   mago format src/
+   ```
 
 For detailed usage, configuration options, and available rules, please visit the [Mago Documentation](https://mago.carthage.software/).
 
@@ -111,7 +81,7 @@ Mago stands on the shoulders of giants. Our design and functionality are heavily
 ### Inspirations:
 
 - [Clippy](https://github.com/rust-lang/rust-clippy): For its comprehensive linting approach.
-- [OXC](https://github.com/oxc-project/oxc/): A major inspiration for building a high-performancetoolchain in Rust.
+- [OXC](https://github.com/oxc-project/oxc/): A major inspiration for building a high-performance toolchain in Rust.
 - [Hakana](https://github.com/slackhq/hakana/): For its deep static analysis capabilities.
 
 ### Acknowledgements:

docs/.vitepress/config.mts

@@ -1,5 +1,8 @@
 import { defineConfig } from "vitepress";
 
+// A placeholder for your site's domain
+const site = "https://mago.carthage.software";
+
 export default defineConfig({
   srcDir: ".",
 
@@ -18,6 +21,30 @@ export default defineConfig({
       { rel: "icon", href: "/assets/favicon-16x16.png", sizes: "16x16" },
     ],
     ["link", { rel: "icon", href: "/assets/favicon.ico" }],
+    // Open Graph
+    ["meta", { property: "og:type", content: "website" }],
+    ["meta", { property: "og:title", content: "Mago" }],
+    [
+      "meta",
+      {
+        property: "og:description",
+        content:
+          "The Oxidized PHP Toolchain: Blazing fast linter, formatter, and static analyzer for PHP, written in Rust.",
+      },
+    ],
+    ["meta", { property: "og:image", content: `${site}/assets/banner.svg` }],
+    ["meta", { property: "og:url", content: site }],
+    ["meta", { name: "twitter:card", content: "summary_large_image" }],
+    ["meta", { name: "twitter:title", content: "Mago" }],
+    [
+      "meta",
+      {
+        name: "twitter:description",
+        content:
+          "The Oxidized PHP Toolchain: Blazing fast linter, formatter, and static analyzer for PHP, written in Rust.",
+      },
+    ],
+    ["meta", { name: "twitter:image", content: `${site}/assets/banner.svg` }],
   ],
   lastUpdated: true,
   cleanUrls: true,
@@ -149,6 +176,16 @@ export default defineConfig({
           },
         ],
       },
+      {
+        text: "🧩 Recipes",
+        collapsed: false,
+        items: [
+          { text: "GitHub Actions", link: "/recipes/github-actions" },
+          { text: "Zed", link: "/recipes/zed" },
+          { text: "Helix", link: "/recipes/helix" },
+          { text: "Visual Studio Code", link: "/recipes/vscode" },
+        ],
+      },
       { text: "🤝 Contributing", link: "/contributing" },
       { text: "⚡️ Benchmarks", link: "/benchmarks" },
       { text: "⭐ Projects Using Mago", link: "/projects-using-mago" },

docs/.vitepress/theme/custom.css

@@ -22,7 +22,6 @@
     --vp-c-brand-2: #47a467;
     --vp-c-brand-3: #32784a;
 
-    /* --- Typography Variables --- */
     --heading-text-color: #32784a;
     --heading-underline-color: #0b5a76;
 }
@@ -41,18 +40,12 @@
 .VPDoc h1 {
     font-size: 2.25em;
     padding-bottom: 0.5rem;
-    text-decoration: underline;
-    text-decoration-thickness: 4px;
-    text-decoration-color: var(--heading-underline-color);
     margin-bottom: 2rem;
 }
 
 .VPDoc h2 {
     font-size: 1.5em;
     padding-bottom: 0.4rem;
-    text-decoration: underline;
-    text-decoration-thickness: 3px;
-    text-decoration-color: var(--heading-underline-color);
     margin-top: 3rem;
     margin-bottom: 1.5rem;
 }
@@ -90,20 +83,20 @@
 
 @keyframes float {
     0% {
-        transform: translateY(0px) rotate(0deg);
+        transform: translateY(0px);
     }
     50% {
-        transform: translateY(-8px) rotate(0.5deg);
+        transform: translateY(-8px);
     }
     100% {
-        transform: translateY(0px) rotate(0deg);
+        transform: translateY(0px);
     }
 }
 
 #mago-logo {
     position: relative;
-    top: 0;
-    left: 0;
+    top: 50px;
+    left: 50px;
     animation: float 6s ease-in-out infinite;
     transition: transform 0.3s ease-out;
 }

docs/.vitepress/theme/index.js

@@ -8,11 +8,10 @@ export default {
     onMounted(() => {
       const target = document.querySelector("img#mago-logo");
       if (!target) {
-        console.warn("3D hover effect: target element not found");
         return;
       }
 
-      const intensity = 20;
+      const intensity = 10;
 
       target.addEventListener("mouseenter", () => {
         target.classList.add("is-interactive");
@@ -25,14 +24,15 @@ export default {
 
         target.style.transform = `
           perspective(1000px)
+          translateY(0px)
           rotateY(${x * intensity}deg)
           rotateX(${-y * intensity}deg)
           scale3d(1, 1, 1)
         `;
       });
 
       target.addEventListener("mouseleave", () => {
-        target.style.transform = "perspective(1000px) rotateY(0) rotateX(0) scale3d(1, 1, 1)";
+        target.style.transform = "";
         target.classList.remove("is-interactive");
       });
     });

docs/guide/installation.md

@@ -4,29 +4,71 @@ title: Installation
 
 # Installation
 
-Installing **Mago** is designed to be a quick and simple process.
+Installing **Mago** is a quick process with several options to suit your environment and preferences.
 
-## Automatic Installation (macOS & Linux)
+## Shell Installer (macOS & Linux)
 
-The easiest way to install Mago is by using our installer script. Open your terminal and run the following command:
+This is the recommended method for most macOS and Linux users. Our script automatically downloads the correct binary for your system and adds it to your path.
 
-```bash
-curl -sSL https://install.carthage.software/mago | bash
+#### Using `curl`
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf [https://carthage.software/mago.sh](https://carthage.software/mago.sh) | bash
+```
+
+#### Using `wget`
+
+```sh
+wget -qO- [https://carthage.software/mago.sh](https://carthage.software/mago.sh) | bash
+```
+
+---
+
+## Package Managers
+
+### Homebrew (macOS)
+
+If you're using Homebrew on macOS, you can install Mago with a single command:
+
+```sh
+brew install mago
+```
+
+You can later update Mago by running `mago self-update`.
+
+### Composer (PHP Project)
+
+To add Mago as a development dependency to your PHP project via Composer:
+
+```sh
+composer require --dev carthage-software/mago
+```
+
+### Cargo (Rust)
+
+If you have the Rust toolchain installed, you can install Mago directly from Crates.io:
+
+```sh
+cargo install mago
 ```
 
-This script will download the latest pre-compiled binary for your system, make it executable, and move it to a standard location (`/usr/local/bin`) so you can run `mago` from anywhere.
+---
 
-## Manual Installation (Windows & Other Systems)
+## Manual Download
 
-If you're on Windows or prefer to install manually, you can download the latest release from our GitHub page.
+You can always download a pre-compiled binary directly from our GitHub Releases page. This is the recommended method for **Windows** and other systems not covered above.
 
-1.  Go to the **[Mago Releases Page](https://github.com/carthage-software/mago/releases)**.
-2.  Download the appropriate binary for your operating system (e.g., `mago-x86_64-pc-windows-msvc.zip` for Windows).
+1.  Navigate to the **[Mago Releases Page](https://github.com/carthage-software/mago/releases)**.
+2.  Download the appropriate archive for your operating system (e.g., `mago-x86_64-pc-windows-msvc.zip` for Windows).
 3.  Unzip the archive.
-4.  Place the `mago.exe` (or `mago`) binary in a directory that is included in your system's `PATH`.
+4.  Place the `mago.exe` (or `mago`) executable in a directory that is part of your system's `PATH` environment variable.
+
+---
+
+## Verify Installation
 
-Once installed, you can verify it's working by running:
+Once installed, you can verify that Mago is working correctly by checking its version:
 
-```bash
+```sh
 mago --version
 ```

docs/index.md

@@ -1,5 +1,4 @@
 ---
-# https://vitepress.dev/reference/default-theme-home-page
 layout: home
 
 hero:

assets/banner.svg docs/public/assets/banner.svgassets/banner.svg renamed to docs/public/assets/banner.svg

@@ -0,0 +1,48 @@
+---
+title: GitHub Actions Recipe
+---
+
+# 🧩 GitHub Actions Recipe
+
+Automate your code quality checks by running **Mago** directly in your GitHub workflow. This setup will check for formatting and linting errors on every push and pull request, providing direct feedback within GitHub.
+
+## Quick Setup
+
+Create a new file at `.github/workflows/mago.yml` and add the following content:
+
+```yaml
+name: Mago Code Quality
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  mago:
+    name: Run Mago Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP with Composer cache
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4" # Or your project's version
+          coverage: none
+          tools: composer
+        env:
+          COMPOSER_ALLOW_SUPERUSER: 1
+
+      - name: Install Composer Dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Setup Mago
+        uses: nhedger/setup-mago@v1
+
+      - name: Run Mago
+        run: |
+          mago format --dry-run
+          mago lint --reporting-format=github
+          mago analyze --reporting-format=github
+```