docs: migrate documentation to mdBook with GitHub Pages deployment

Replace flat Markdown docs with mdBook, splitting content into structured
chapters (Getting Started, User Guide, Advanced Usage, Reference). Add
deploy-docs CI job that builds and deploys to GitHub Pages on push to main.
Update Makefile with docs, docs-serve, and docs-api targets.

Author: abdoufermat5

.github/workflows/ci.yml

@@ -2,14 +2,19 @@ name: CI
 
 on:
   push:
-    branches: [ develop ]
+    branches: [ main ]
   pull_request:
-    branches: [ develop ]
+    branches: [ main ]
 
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
 
+# Allow only one concurrent deployment to Pages
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
   test:
     name: Test
@@ -43,6 +48,36 @@ jobs:
     - name: Check formatting
       run: cargo fmt --all -- --check
 
+  deploy-docs:
+    name: Deploy Docs
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install mdBook
+      uses: peaceiris/actions-mdbook@v2
+      with:
+        mdbook-version: 'latest'
+
+    - name: Build documentation
+      run: mdbook build
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/book
 
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
 
 

.gitignore

@@ -43,6 +43,7 @@ config.local.json
 
 # Documentation build artifacts
 docs/_build/
+docs/book/
 site/
 
 # Temporary files
@@ -69,10 +70,6 @@ Thumbs.db
 coverage/
 *.profraw
 
-# Documentation build
-docs/_build/
-site/
-
 # Package files
 *.tar.gz
 *.zip

Makefile

@@ -1,7 +1,7 @@
 # Bayesian SSH Makefile
 # Provides common development and build tasks
 
-.PHONY: help build test release clean install uninstall format lint check deps update-deps
+.PHONY: help build test release clean install uninstall format lint check deps update-deps docs docs-serve docs-api
 
 # Configuration
 BINARY_NAME = bayesian-ssh
@@ -143,10 +143,19 @@ quick: build test ## Quick build and test
 	@echo "🎉 Quick build and test completed!"
 
 # Documentation
-docs: ## Build documentation
+docs: ## Build documentation with mdBook
 	@echo "📚 Building documentation..."
+	mdbook build
+	@echo "✅ Documentation built in docs/book/"
+
+docs-serve: ## Serve documentation locally with live reload
+	@echo "📚 Serving documentation..."
+	mdbook serve --open
+
+docs-api: ## Build Rust API documentation
+	@echo "📚 Building API documentation..."
 	$(CARGO) doc --no-deps --open
-	@echo "✅ Documentation built"
+	@echo "✅ API documentation built"
 
 # Show binary info
 info: release ## Show binary information

README.md

@@ -141,12 +141,19 @@ bayesian-ssh config --use-kerberos --default-user customuser
 
 ## Documentation
 
-For comprehensive guides and advanced topics, see the [docs/](docs/) folder:
+Full documentation is built with [mdBook](https://rust-lang.github.io/mdBook/). To build and view locally:
 
-- **[Technical Architecture](docs/technical-architecture.md)** - System design and architecture
-- **[Advanced Usage](docs/advanced-usage.md)** - Enterprise scenarios and complex use cases  
-- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-- **[Documentation Index](docs/README.md)** - Complete documentation overview
+```bash
+make docs          # Build to docs/book/
+make docs-serve    # Serve locally with live reload
+```
+
+Documentation covers:
+
+- **[Getting Started](docs/src/getting-started/installation.md)** - Installation, quick start, configuration
+- **[User Guide](docs/src/user-guide/connection-management.md)** - Connections, sessions, aliases, TUI, bastion hosts
+- **[Advanced Usage](docs/src/advanced-usage/enterprise.md)** - Enterprise, cloud, CI/CD, security & compliance
+- **[Reference](docs/src/reference/architecture.md)** - Architecture, troubleshooting, changelog
 
 ## Changelog
 See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.

book.toml

@@ -0,0 +1,16 @@
+[book]
+title = "Bayesian SSH Documentation"
+authors = ["Abdoufermat5"]
+description = "Documentation for Bayesian SSH - An intelligent SSH session manager"
+src = "docs/src"
+language = "en"
+
+[build]
+build-dir = "docs/book"
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/abdoufermat5/bayesian-ssh"
+edit-url-template = "https://github.com/abdoufermat5/bayesian-ssh/edit/main/{path}"
+site-url = "/bayesian-ssh/"