cachebag · cachebag · Feb 3, 2026 · Feb 3, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,57 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdBook
+        run: |
+          mkdir -p ~/bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C ~/bin
+          echo "$HOME/bin" >> $GITHUB_PATH
+
+      - name: Build book
+        run: |
+          cd docs
+          mdbook build
+
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -3,6 +3,7 @@
 [![Crates.io](https://img.shields.io/crates/v/nmrs)](https://crates.io/crates/nmrs)
 [![Discord](https://img.shields.io/badge/chat-on%20discord-7289da?logo=discord&logoColor=white)](https://discord.gg/Sk3VfrHrN4)
 [![Documentation](https://docs.rs/nmrs/badge.svg)](https://docs.rs/nmrs)
+[![User Guide](https://img.shields.io/badge/docs-mdBook-blue)](https://cachebag.github.io/nmrs/)
 [![CI](https://github.com/cachebag/nmrs/actions/workflows/ci.yml/badge.svg)](https://github.com/cachebag/nmrs/actions/workflows/ci.yml)
 [![License](https://img.shields.io/crates/l/nmrs)](LICENSE)
 
@@ -15,11 +16,17 @@ The project is divided into the following crates:
 
 [Jump to the GUI section of this repo](#installation)
 
+## Documentation
+
+- **[User Guide](https://cachebag.github.io/nmrs/)** - Comprehensive guide with tutorials and examples
+- **[API Documentation](https://docs.rs/nmrs)** - Complete API reference on docs.rs
+- **[Discord](https://discord.gg/Sk3VfrHrN4)** - Join our community for help and discussion
+
 ## Getting Started
 
 _Please consider joining the [**Discord**](https://discord.gg/Sk3VfrHrN4). It's a welcoming community to both developers who want to contribute and/or learn about and discuss nmrs as well as users that would like to be engaged with the development process._
 
-The best way to get started with `nmrs` is the [API documentation](https://docs.rs/nmrs), which includes examples for common operations like scanning networks, connecting to Wi-Fi, and managing connection profiles.
+The best way to get started with `nmrs` is the [User Guide](https://cachebag.github.io/nmrs/), which includes comprehensive tutorials and examples. For detailed API information, see the [API documentation](https://docs.rs/nmrs).
 
 ## Sample usage
 We'll create a simple example that scans for available networks and connects to one. Note that these examples require NetworkManager to be running on your Linux system with D-Bus access, obviously.

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+# mdBook output
+book/
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,45 @@
+# nmrs Documentation
+
+This directory contains the mdBook-based user guide for nmrs.
+
+## Building Locally
+
+Install mdBook:
+
+```bash
+cargo install mdbook
+```
+
+Build the book:
+
+```bash
+cd docs
+mdbook build
+```
+
+Serve with live reload:
+
+```bash
+mdbook serve --open
+```
+
+The documentation will be available at http://localhost:3000
+
+## Structure
+
+- `src/` - Markdown source files
+- `book.toml` - mdBook configuration
+- `theme/` - Custom CSS and styling
+- `book/` - Generated output (gitignored)
+
+## Contributing
+
+When adding new pages:
+
+1. Create the markdown file in the appropriate `src/` subdirectory
+2. Add it to `src/SUMMARY.md` to include it in the table of contents
+3. Build and preview locally to ensure it looks correct
+
+## Deployment
+
+The documentation is automatically built and deployed to GitHub Pages via the `.github/workflows/docs.yml` workflow on every push to `master`.
diff --git a/docs/add-page.sh b/docs/add-page.sh
@@ -0,0 +1,49 @@
+#!/bin/bash
+# Helper script to add new pages to the documentation
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <section> <page-name>"
+    echo "Example: $0 guide wifi-configuration"
+    echo ""
+    echo "Available sections:"
+    echo "  - getting-started"
+    echo "  - guide"
+    echo "  - advanced"
+    echo "  - examples"
+    echo "  - gui"
+    echo "  - api"
+    echo "  - development"
+    echo "  - appendix"
+    exit 1
+fi
+
+SECTION=$1
+PAGE=$2
+TITLE=$(echo "${PAGE//-/ }" | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')
+
+# Create the file
+cat > "src/${SECTION}/${PAGE}.md" << EOF
+# ${TITLE}
+
+[Content to be added]
+
+## Overview
+
+...
+
+## Examples
+
+...
+
+## See Also
+
+- [Related page](../guide/other.md)
+EOF
+
+echo "✓ Created src/${SECTION}/${PAGE}.md"
+echo ""
+echo "Next steps:"
+echo "1. Add content to src/${SECTION}/${PAGE}.md"
+echo "2. Add to src/SUMMARY.md in the appropriate section:"
+echo "   - [${TITLE}](./${SECTION}/${PAGE}.md)"
+echo "3. Build and preview: mdbook serve"
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,53 @@
+[book]
+title = "nmrs Documentation"
+description = "Comprehensive guide to using nmrs - A Rust API for NetworkManager"
+authors = ["Akrm Al-Hakimi"]
+language = "en"
+src = "src"
+
+[rust]
+edition = "2021"
+
+[build]
+build-dir = "book"
+create-missing = true
+use-default-preprocessors = true
+
+[preprocessor.links]
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/cachebag/nmrs"
+edit-url-template = "https://github.com/cachebag/nmrs/edit/master/docs/{path}"
+site-url = "/nmrs/"
+cname = ""
+additional-css = ["theme/custom.css"]
+additional-js = []
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+editable = true
+copyable = true
+copy-js = true
+line-numbers = true
+runnable = true
+
+[output.html.search]
+enable = true
+limit-results = 30
+teaser-word-count = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3
+
+[output.html.print]
+enable = true
+
+[output.html.redirect]
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,74 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting Started
+
+- [Installation](./getting-started/installation.md)
+- [Quick Start](./getting-started/quick-start.md)
+- [Requirements](./getting-started/requirements.md)
+
+# User Guide
+
+- [WiFi Management](./guide/wifi.md)
+  - [Scanning Networks](./guide/wifi-scanning.md)
+  - [Connecting to Networks](./guide/wifi-connecting.md)
+  - [WPA-PSK Networks](./guide/wifi-wpa-psk.md)
+  - [WPA-EAP (Enterprise)](./guide/wifi-enterprise.md)
+  - [Hidden Networks](./guide/wifi-hidden.md)
+- [VPN Connections](./guide/vpn.md)
+  - [WireGuard Setup](./guide/vpn-wireguard.md)
+  - [VPN Management](./guide/vpn-management.md)
+- [Ethernet Management](./guide/ethernet.md)
+- [Bluetooth](./guide/bluetooth.md)
+- [Device Management](./guide/devices.md)
+- [Connection Profiles](./guide/profiles.md)
+- [Real-Time Monitoring](./guide/monitoring.md)
+- [Error Handling](./guide/error-handling.md)
+
+# Advanced Topics
+
+- [Async Runtime Support](./advanced/async-runtimes.md)
+- [Custom Timeouts](./advanced/timeouts.md)
+- [Connection Options](./advanced/connection-options.md)
+- [D-Bus Architecture](./advanced/dbus.md)
+- [Logging and Debugging](./advanced/logging.md)
+
+# Examples
+
+- [Basic WiFi Scanner](./examples/wifi-scanner.md)
+- [WiFi Auto-Connect](./examples/wifi-auto-connect.md)
+- [Enterprise WiFi](./examples/enterprise-wifi.md)
+- [WireGuard VPN Client](./examples/wireguard-client.md)
+- [Network Monitor Dashboard](./examples/network-monitor.md)
+- [Connection Manager](./examples/connection-manager.md)
+
+# nmrs-gui
+
+- [GUI Overview](./gui/overview.md)
+- [Installation](./gui/installation.md)
+- [Configuration](./gui/configuration.md)
+- [Themes](./gui/themes.md)
+- [Waybar Integration](./gui/waybar.md)
+
+# API Reference
+
+- [Core Types](./api/types.md)
+- [NetworkManager](./api/network-manager.md)
+- [Models Module](./api/models.md)
+- [Builders Module](./api/builders.md)
+- [Error Types](./api/errors.md)
+
+# Development
+
+- [Contributing](./development/contributing.md)
+- [Architecture](./development/architecture.md)
+- [Testing](./development/testing.md)
+- [Release Process](./development/releases.md)
+
+# Appendix
+
+- [Troubleshooting](./appendix/troubleshooting.md)
+- [FAQ](./appendix/faq.md)
+- [Changelog](./appendix/changelog.md)
+- [License](./appendix/license.md)
diff --git a/docs/src/advanced/async-runtimes.md b/docs/src/advanced/async-runtimes.md
@@ -0,0 +1,3 @@
+# Async Runtimes
+
+Documentation coming soon.
diff --git a/docs/src/advanced/connection-options.md b/docs/src/advanced/connection-options.md
@@ -0,0 +1,3 @@
+# Connection Options
+
+Documentation coming soon.
diff --git a/docs/src/advanced/dbus.md b/docs/src/advanced/dbus.md
@@ -0,0 +1,3 @@
+# Dbus
+
+Documentation coming soon.
diff --git a/docs/src/advanced/logging.md b/docs/src/advanced/logging.md
@@ -0,0 +1,3 @@
+# Logging
+
+Documentation coming soon.
diff --git a/docs/src/advanced/timeouts.md b/docs/src/advanced/timeouts.md
@@ -0,0 +1,3 @@
+# Timeouts
+
+Documentation coming soon.
diff --git a/docs/src/api/builders.md b/docs/src/api/builders.md
@@ -0,0 +1,5 @@
+# Builders
+
+Documentation coming soon.
+
+See the [API documentation](https://docs.rs/nmrs) for complete details.
diff --git a/docs/src/api/errors.md b/docs/src/api/errors.md
@@ -0,0 +1,5 @@
+# Errors
+
+Documentation coming soon.
+
+See the [API documentation](https://docs.rs/nmrs) for complete details.
diff --git a/docs/src/api/models.md b/docs/src/api/models.md
@@ -0,0 +1,5 @@
+# Models
+
+Documentation coming soon.
+
+See the [API documentation](https://docs.rs/nmrs) for complete details.
diff --git a/docs/src/api/network-manager.md b/docs/src/api/network-manager.md
@@ -0,0 +1,5 @@
+# Network Manager
+
+Documentation coming soon.
+
+See the [API documentation](https://docs.rs/nmrs) for complete details.
diff --git a/docs/src/api/types.md b/docs/src/api/types.md
@@ -0,0 +1,5 @@
+# Types
+
+Documentation coming soon.
+
+See the [API documentation](https://docs.rs/nmrs) for complete details.
diff --git a/docs/src/appendix/changelog.md b/docs/src/appendix/changelog.md
@@ -0,0 +1,3 @@
+# Changelog
+
+Documentation coming soon.
diff --git a/docs/src/appendix/faq.md b/docs/src/appendix/faq.md
@@ -0,0 +1,3 @@
+# Faq
+
+Documentation coming soon.
diff --git a/docs/src/appendix/license.md b/docs/src/appendix/license.md
@@ -0,0 +1,3 @@
+# License
+
+Documentation coming soon.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Connection Options

		Documentation coming soon.