Optimize docs pipeline

.github/CONTRIBUTING.md

@@ -2,6 +2,14 @@
 
 Thank you for your interest in contributing to Fugue! This document provides guidelines for contributing to the project.
 
+## Community
+
+- **Discord**: Join our [Discord server](https://discord.gg/QAcF7Nwr)
+- **Issues & Bugs**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `Bug Report` template.
+- **Feature Requests**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `Feature Request` template.
+- **RFCs**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `RFC` template.
+- **Zotero**: Joing our [Zotero group](https://www.zotero.org/groups/6138134/fugue)
+
 ## Quick Start
 
 ```bash

.github/workflows/docs.yml

@@ -30,27 +30,52 @@ jobs:
             ~/.cargo/registry/index/
             ~/.cargo/registry/cache/
             ~/.cargo/git/db/
-          key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }}
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-mdbook-
+            ${{ runner.os }}-cargo-
 
       - name: Install mdBook and plugins
         run: |
+          # Check if tools are installed with correct major.minor version
+          install_if_needed() {
+            local tool=$1
+            local major_minor=$2
+            local cargo_version=$3
+
+            if command -v $tool &> /dev/null; then
+              local current_version=$($tool --version | grep -oE 'v[0-9]+\.[0-9]+' | head -1)
+              if [[ "$current_version" =~ v$major_minor ]]; then
+                echo "$tool $current_version already installed and compatible, skipping"
+                return
+              else
+                echo "$tool $current_version found but incompatible, updating to $cargo_version"
+              fi
+            else
+              echo "Installing $tool $cargo_version"
+            fi
+
+            cargo install $tool --vers "$cargo_version" --locked --force
+          }
+
           # Install mdBook with optimizations
-          cargo install mdbook \
-            --no-default-features \
-            --features search \
-            --vers "^0.4" \
-            --locked \
-            --force
+          install_if_needed mdbook "0\.4" "^0.4"
 
           # Install plugins
-          cargo install mdbook-admonish --vers "^1.18" --locked --force
-          cargo install mdbook-mermaid --vers "^0.14" --locked --force
-          cargo install mdbook-toc --vers "^0.14" --locked --force
-          cargo install mdbook-katex --vers "^0.9" --locked --force
+          install_if_needed mdbook-admonish "1\." "^1.18"
+          install_if_needed mdbook-mermaid "0\.14" "^0.14"
+          install_if_needed mdbook-toc "0\.14" "^0.14"
+          install_if_needed mdbook-katex "0\.9" "^0.9"
           # Note: linkcheck skipped due to issues with LaTeX math syntax
 
+      - name: Cache mdBook build
+        uses: actions/cache@v4
+        with:
+          path: docs/book
+          key: ${{ runner.os }}-mdbook-${{ hashFiles('docs/**/*.md', 'docs/book.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-mdbook-
+
       - name: Build documentation (validates structure)
         run: |
           cd docs
@@ -71,6 +96,13 @@ jobs:
           # Test the library's rustdoc examples
           cargo test --doc
 
+      - name: Upload built documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-docs
+          path: docs/book
+          retention-days: 1
+
   # Job to build and deploy (only on main branch)
   build-deploy:
     runs-on: ubuntu-latest
@@ -85,44 +117,11 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
 
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Cache Cargo registry and target
-        uses: actions/cache@v4
+      - name: Download built documentation
+        uses: actions/download-artifact@v4
         with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-          key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-mdbook-
-
-      - name: Install mdBook and plugins
-        run: |
-          # Install mdBook with optimizations
-          cargo install mdbook \
-            --no-default-features \
-            --features search \
-            --vers "^0.4" \
-            --locked \
-            --force
-
-          # Install plugins with version constraints
-          cargo install mdbook-admonish --vers "^1.18" --locked --force
-          cargo install mdbook-mermaid --vers "^0.14" --locked --force
-          cargo install mdbook-toc --vers "^0.14" --locked --force
-          cargo install mdbook-katex --vers "^0.9" --locked --force
-
-      - name: Build documentation
-        run: |
-          cd docs
-          mdbook build
+          name: built-docs
+          path: docs/book
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

README.md

@@ -15,6 +15,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml/badge.svg)](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml)
 [![codecov](https://codecov.io/gh/alexnodeland/fugue/branch/develop/graph/badge.svg?token=BDJ5OB6GOB)](https://codecov.io/gh/alexnodeland/fugue)
+[![Downloads](https://img.shields.io/crates/d/fugue-ppl?logo=rust)](https://crates.io/crates/fugue-ppl)
+[![Zotero](https://img.shields.io/badge/Zotero-Fugue-red?style=flat-square&logo=zotero&logoColor=CC2936)](https://www.zotero.org/groups/6138134/fugue/library)
 [![Discord](https://img.shields.io/discord/1412802057437712426?logo=discord&label=discord)](https://discord.gg/QAcF7Nwr)
 
 **Supported Rust:** 1.70+ • **Platforms:** Linux / macOS / Windows • **Crate:** [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl)
@@ -78,6 +80,7 @@ let mu_values: Vec<f64> = samples.iter()
 - **[User Guide](https://fugue.run/)** - Comprehensive tutorials and examples
 - **[API Reference](https://docs.rs/fugue-ppl/latest/fugue/)** - Complete API documentation
 - **Examples** - See `examples/` directory
+- **[References](https://www.zotero.org/groups/6138134/fugue/library)** - Zotero library for Fugue
 
 ## 🤝 Community
 
@@ -122,3 +125,5 @@ If you use Fugue in your research, please cite:
   year = {2025}
 }
 ```
+
+Or refer to the "Internal" collection in [Zotero](https://www.zotero.org/groups/6138134/fugue/library) to generate a bibliography.

docs/src/home.md

@@ -15,16 +15,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml/badge.svg)](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml)
 [![codecov](https://codecov.io/gh/alexnodeland/fugue/branch/develop/graph/badge.svg?token=BDJ5OB6GOB)](https://codecov.io/gh/alexnodeland/fugue)
+[![Downloads](https://img.shields.io/crates/d/fugue-ppl?logo=rust)](https://crates.io/crates/fugue-ppl)
+[![Zotero](https://img.shields.io/badge/Zotero-Fugue-red?style=flat-square&logo=zotero&logoColor=CC2936)](https://www.zotero.org/groups/6138134/fugue/library)
+[![Discord](https://img.shields.io/discord/1412802057437712426?logo=discord&label=discord)](https://discord.gg/QAcF7Nwr)
 
 **Supported Rust:** 1.70+ • **Platforms:** Linux / macOS / Windows • **Crate:** [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl)
 
 </div>
 
 ---
 
-```admonish info title="👋 Welcome to the Fugue User Guide"
+```admonish info title="👋 Welcome"
 
-Fugue is a production-ready, monadic probabilistic programming library for Rust. Check out these resources to get started:
+Check out these resources to get started:
 
 - [Getting Started](./getting-started/README.md) - Installation and first steps
 - [How-To Guides](./how-to/README.md) - Practical guides for common tasks
@@ -54,4 +57,5 @@ fugue-ppl = "0.1.0"
 
 - [GitHub Repository](https://github.com/alexnodeland/fugue)
 - [API Reference](https://docs.rs/fugue-ppl)
+- [Zotero](https://www.zotero.org/groups/6138134/fugue/library)
 ```