@@ -11,6 +11,44 @@ Browse the OpenSPP Documentation at https://docs.openspp.org/.
 
 Active development on the OpenSPP Documentation takes place on the branch [`main`](https://github.com/openspp/documentation/).
 
+## Building Documentation
+
+### Quick Start
+
+```bash
+git clone https://github.com/OpenSPP/documentation.git
+cd documentation
+make html        # Build HTML docs
+make livehtml    # Live-reload server at http://localhost:8050
+```
+
+### Dependencies
+
+- **Python 3.8+** - For Sphinx and extensions
+- **Graphviz** - For graph diagrams: `sudo apt install graphviz`
+
+### Mermaid Diagrams (Optional)
+
+The documentation uses Mermaid for flowcharts and diagrams. By default, diagrams render via CDN JavaScript.
+
+For **offline/air-gapped builds**, install mermaid-cli to pre-render diagrams to SVG:
+
+```bash
+# Install Node.js and mermaid-cli
+sudo apt install nodejs npm
+sudo npm install -g @mermaid-js/mermaid-cli
+
+# Install Chrome dependencies (Ubuntu/Debian)
+sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 \
+  libasound2t64 libpango-1.0-0 libpangocairo-1.0-0 libgtk-3-0 libx11-xcb1
+
+# Build with offline mode
+MERMAID_OFFLINE=svg make html
+```
+
+The build uses `docs/_static/puppeteer-config.json` to configure Chrome with `--no-sandbox` for environments where the sandbox is restricted (e.g., Ubuntu 23.10+ with AppArmor).
+
 ## Contribute
 
 - [Contributing to OpenSPP Documentation](https://docs.openspp.org/contributing/index.html)
 
@@ -0,0 +1,5 @@
+{
+  "executablePath": "",
+  "args": ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
+  "headless": true
+}
@@ -158,14 +158,51 @@
     "sphinxcontrib.httpexample",
     'sphinxcontrib.googleanalytics',
     "sphinxcontrib.video",
-    "sphinxext.opengraph",
     "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
     "sphinx.ext.graphviz",
     "sphinx_tabs.tabs",
     "notfound.extension",
+    "sphinx_reredirects",  # URL redirects for documentation restructure
+    "cel_lexer",  # Custom CEL expression syntax highlighting
+    "sphinxcontrib.mermaid",  # Mermaid diagrams (flowcharts, sequence, state)
 ]
 
+# Mermaid configuration
+# For offline/air-gapped builds, set MERMAID_OFFLINE=svg and install mermaid-cli:
+#   npm install -g @mermaid-js/mermaid-cli
+# This will pre-render diagrams to SVG at build time (no JavaScript needed at runtime)
+_mermaid_offline = os.environ.get("MERMAID_OFFLINE", "") == "svg"
+mermaid_output_format = "svg" if _mermaid_offline else "raw"
+# Use puppeteer config for no-sandbox mode (required on Ubuntu 23.10+)
+mermaid_cmd = ["mmdc", "--puppeteerConfigFile", os.path.join(os.path.dirname(__file__), "_static/puppeteer-config.json")]
+mermaid_include_elk = False  # Disable ELK layout to reduce dependencies
+mermaid_init_js = "" if _mermaid_offline else "mermaid.initialize({startOnLoad:true});"
+
+# Monkeypatch sphinxcontrib.mermaid to skip JS loading in offline/SVG mode
+if _mermaid_offline:
+    import sphinxcontrib.mermaid
+    _original_install_js = sphinxcontrib.mermaid.install_js
+    def _patched_install_js(app, pagename, templatename, context, doctree):
+        # Skip JS installation entirely when rendering to SVG
+        if app.config.mermaid_output_format == "svg":
+            return
+        return _original_install_js(app, pagename, templatename, context, doctree)
+    sphinxcontrib.mermaid.install_js = _patched_install_js
+
+# Some optional extensions depend on Pillow. In environments where Pillow cannot
+# be imported (for example, Python versions without compatible wheels), build
+# the documentation without those extensions.
+_pillow_available = True
+try:
+    from PIL import Image  # noqa: F401
+except Exception as exc:  # pragma: no cover - build-environment dependent
+    _pillow_available = False
+    _logger.warning("Pillow is not available (%s). Disabling sphinxext.opengraph.", exc)
+
+if _pillow_available:
+    extensions.append("sphinxext.opengraph")
+
 sphinx_tabs_disable_tab_closing = True
 sphinx_tabs_disable_css_loading = True
 
@@ -218,7 +255,10 @@
     "**/README.rst",
 ]
 
-html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]
+html_js_files = [
+    "patch_scrollToActive.js",
+    "search_shortcut.js",
+]
 
 html_extra_path = [
     "robots.txt",
 
@@ -41,7 +41,7 @@ Our guiding principles are informed by the Digital Public Goods Standard and the
 
 - **User-centricity**: Our products are designed to be intuitive and pragmatic, recognizing that social protection operates in complex, resource-constrained and rapidly changing contexts.
 - **Modularity**: The platform is composed of independent modules which allow for flexibility, scalability, and the interchangeability of components.
-- **Privacy and security**: We rigorously uphold privacy and security standards - essential prerequisites for safeguarding Digital Public Goods.
+- **Privacy and security**: We embed privacy and security best practices into the platform—protecting beneficiary data by default.
 - **Interoperability**: The platform is designed to support system interoperability - critical for the creation of cohesive and efficient digital ecosystems.
 - **Inclusivity**: Our products can be customized to suit linguistic and cultural requirements, accessibility, digital literacy, and deployment in remote and less-developed contexts.