heathkh · Oct 4, 2025 · Oct 4, 2025 · Oct 4, 2025 · Oct 4, 2025 · Oct 4, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,86 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      branch_name:
+        description: 'Branch to run workflow on'
+        required: true
+        default: 'feature/mkdocs'
+
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for mike versioning
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mike pillow cairosvg mkdocs-glightbox
+
+      - name: Configure Git for mike
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+
+      - name: Extract version from tag or use 'dev'
+        id: get_version
+        run: |
+          if [[ $GITHUB_REF == refs/tags/v* ]]; then
+            VERSION=${GITHUB_REF#refs/tags/v}
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "alias=latest" >> $GITHUB_OUTPUT
+            echo "is_release=true" >> $GITHUB_OUTPUT
+          else
+            echo "version=dev" >> $GITHUB_OUTPUT
+            echo "alias=dev" >> $GITHUB_OUTPUT
+            echo "is_release=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build documentation for pull request
+        if: github.event_name == 'pull_request'
+        run: mkdocs build
+        #run: mkdocs build --strict
+
+      - name: Deploy development docs
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          mike deploy --push --update-aliases dev development
+
+      - name: Deploy release docs with versioning
+        if: steps.get_version.outputs.is_release == 'true'
+        run: |
+          VERSION=${{ steps.get_version.outputs.version }}
+          mike deploy --push --update-aliases $VERSION latest
+          mike set-default --push latest
+
+      - name: Upload artifact for Pages (optional, for review)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: site/
diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,7 @@ debian/.debhelper
 *.mo
 *.po~
 *.mo~
+
+# MkDocs
+site/
+.cache/
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,6 @@
+{
+    "editor.rulers": [
+        { "column": 80, "color": "#ff0000" }
+    ],
+    "editor.wordWrap": "off"
+}
diff --git a/README.md b/README.md
@@ -10,227 +10,12 @@ Rayforge is a modern, cross-platform G-code sender and control software for GRBL
 
 ![Screenshot](docs/ss-main.png)
 
-## Key Features
 
-| Feature                      | Description                                                                                        |
-| :--------------------------- | :------------------------------------------------------------------------------------------------- |
-| **Modern UI**                | Polished and modern UI built with Gtk4 and Libadwaita. Supports system, light, and dark themes.    |
-| **Multi-Layer Operations**   | Assign different operations (e.g., engrave then cut) to layers in your design.                     |
-| **Versatile Operations**     | Supports Contour, Raster Engraving (with cross-hatch fill), Shrink Wrap, and Depth Engraving.      |
-| **Overscan & Kerf Comp.**    | Improve engraving quality with overscan and ensure dimensional accuracy with kerf compensation.    |
-| **2.5D Cutting**             | Perform multi-pass cuts with a configurable step-down between each pass for thick materials.       |
-| **3D G-code Preview**        | Visualize G-code toolpaths in 3D to verify the job before sending it to the machine.               |
-| **Multi-Machine Profiles**   | Configure and instantly switch between multiple machine profiles.                                  |
-| **GRBL Firmware Settings**   | Read and write firmware parameters (`$$`) directly from the UI.                                    |
-| **Comprehensive 2D Canvas**  | Full suite of tools: alignment, transformation, measurement, zoom, pan, and more.                  |
-| **Advanced Path Generation** | High-quality image tracing, travel time optimization, path smoothing, and spot size interpolation. |
-| **Holding Tabs**             | Add tabs to contour cuts to hold pieces in place. Supports manual and automatic placement.         |
-| **G-code Macros & Hooks**    | Run custom G-code snippets before/after jobs. Supports variable substitution.                      |
-| **Broad File Support**       | Import from SVG, DXF, PDF, JPEG, PNG, BMP, and even Ruida files (`.rd`).                           |
-| **Multi-Laser Operations**   | Choose different lasers for each operation in a job                                                |
-| **Camera Integration**       | Use a USB camera for workpiece alignment, positioning, and background tracing.                     |
-| **Cross-Platform**           | Native builds for Linux and Windows.                                                               |
-| **Extensible**               | Open development model makes it easy to [add support for new devices](docs/driver.md).             |
-| **Multi-Language**           | Available in English, Portuguese, Spanish, and German.                                             |
-| **G-code Dialects**          | Supports GRBL, Smoothieware, and other GRBL-compatible firmwares.                                  |
+## Documentation
 
-## Device Support
+- User documentation at [rayforge.org](https://rayforge.org).
+- Developer documentation in [docs](docs/README.md).
 
-| Device Type      | Connection Method       | Notes                                                          |
-| :--------------- | :---------------------- | :------------------------------------------------------------- |
-| **GRBL**         | Serial Port             | Supported since version 0.13. The most common connection type. |
-| **GRBL**         | Network (WiFi/Ethernet) | Connect to any GRBL device on your network.                    |
-| **Smoothieware** | Telnet                  | Supported since version 0.15.                                  |
-
-## Installation
-
-### Windows
-
-Download the latest installer from the **[Releases Page](https://github.com/barebaric/rayforge/releases/)**.
-
-### Linux
-
-We offer several installation methods for Linux.
-
-#### Ubuntu & Derivatives (via PPA)
-
-For users on Ubuntu and its derivatives (like Linux Mint, Pop!\_OS), the recommended
-method is our official PPA. This integrates directly with your system's package
-manager and provides automatic updates.
-
-> [!NOTE]
-> The PPA supports **Ubuntu 24.04 LTS and newer**.
-
-Open a terminal and run the following commands:
-
-```bash
-sudo add-apt-repository ppa:knipknap/rayforge
-sudo apt update
-sudo apt install rayforge
-```
-
-#### Cross-Distro (Snap)
-
-The Snap package includes all dependencies and runs in a sandbox. It is the recommended
-method for most other Linux distributions.
-
-[![Get it from the Snap Store](https://snapcraft.io/en/light/install.svg)](https://snapcraft.io/rayforge)
-
-> [!IMPORTANT]
-> The Snap is sandboxed and requires you to manually grant permissions for hardware
-> access. Run these commands after installation.
-
-For camera access:
-
-```bash
-sudo snap connect rayforge:camera
-```
-
-For USB serial port access:
-
-```bash
-# First, enable experimental hotplug support
-sudo snap set system experimental.hotplug=true
-
-# Connect your laser via USB, then run this command
-sudo snap connect rayforge:serial-port
-```
-
-#### From Source (pip)
-
-This method is for developers and advanced users. You must install system dependencies manually.
-
-On Debian/Ubuntu-based systems:
-
-```bash
-sudo apt update
-sudo apt install python3-pip python3-gi gir1.2-gtk-3.0 gir1.2-adw-1 gir1.2-gdkpixbuf-2.0 libgirepository-1.0-dev libgirepository-2.0-0 libvips42t64 libadwaita-1-0 libopencv-dev
-
-pip3 install rayforge
-```
-
-_(Package names may differ on other distributions.)_
-
-### Other Operating Systems (e.g., macOS)
-
-There are no official builds for other platforms, but Rayforge may run from source via
-the `pip` method. Contributions for packaging on other platforms are welcome.
-
-## Screenshots
-
-<details>
-<summary><b>Click to expand screenshots</b></summary>
-
-**Operation Settings**
-![Contour Settings](docs/contour-settings.png)
-
-**Machine & Device Configuration**
-![General Settings](docs/machine-settings.png)
-![Device Settings](docs/machine-device.png)
-![Advanced Settings](docs/machine-advanced.png)
-![Laser Settings](docs/machine-laser.png)
-
-**Integrated Camera Support**
-![Camera Settings](docs/machine-camera.png)
-![Camera Alignment](docs/camera-alignment.png)
-![Camera Image](docs/camera-image.png)
-![Camera Overlay on Worksurface](docs/camera-overlay.png)
-
-</details>
-
-## Contributing
-
-We welcome contributions of all kinds! Whether you're fixing a bug, adding
-a feature, or improving documentation, your help is appreciated.
-
-- **Report a Bug:** Open an [issue](https://github.com/barebaric/rayforge/issues)
-  with a clear description and steps to reproduce.
-- **Suggest a Feature:** Start a discussion or open a feature request issue.
-- **Submit a Pull Request:** Please discuss major changes in an issue first.
-- **Add a Driver:** See the [driver development guide](docs/driver.md) to add
-  support for your hardware.
-
-### Packaging Help Wanted
-
-We are actively seeking help to create and maintain a **[Flatpak](flatpak/)** package.
-If you have experience with Flatpak, your contribution would be highly valuable!
-
-## Development
-
-This project uses [**Pixi**](https://pixi.sh/) to manage dependencies and
-development environments for a reproducible setup.
-
-### Prerequisites
-
-First, install Pixi by following the instructions on the
-[official website](https://pixi.sh/latest/installation/).
-
-### 1. Setup Environment
-
-Clone the repository and install dependencies.
-
-```bash
-# Install Gtk/Adwaita system dependency (Debian/Ubuntu)
-sudo apt install gir1.2-adw-1
-
-# Let Pixi handle the rest
-pixi install
-```
-
-This command reads `pixi.toml` and installs all conda and pip dependencies into a local
-`.pixi` virtual environment.
-
-### 2. Run the Application
-
-```bash
-pixi run rayforge
-```
-
-### 3. Run Tests and Lint
-
-```bash
-pixi run test
-pixi run lint
-```
-
-### 4. Activate the Development Shell
-
-For an interactive workflow, you can activate a shell within the project's environment.
-
-```bash
-pixi shell
-```
-
-Inside this shell, you can run commands directly without the `pixi run` prefix
-(e.g., `rayforge`, `pytest`). Type `exit` to leave the shell.
-
-### 5. Manage Dependencies
-
-Always use Pixi to manage dependencies to ensure the `pixi.lock` file is updated.
-
-```bash
-# Add a conda package
-pixi add numpy
-
-# Add a PyPI package
-pixi add --pypi requests
-```
-
-### 6. Translation Workflow
-
-The following tasks are available for managing language translations:
-
-#### Update `.po` files from source code
-
-```bash
-pixi run update-translations
-```
-
-#### Compile `.po` files to binary `.mo` files
-
-```bash
-pixi run compile-translations
-```
 
 ## License
-Original file line number
+Diff line change
@@ Expand Up / @@ -20,3 +20,7 @@ debian/.debhelper @@
     *.mo
     *.po~
     *.mo~
+    # MkDocs
+    site/
+    .cache/