diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..8da4407
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,47 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install project + docs deps
+        run: |
+          pip install -e .[docs]
+
+      - name: Build docs
+        run: make docs
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/Makefile b/Makefile
index b22c59f..dec2a19 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,17 @@
 PYTHON ?= python3
 
-.PHONY: clean format format-check typecheck typecheck_pyright lint test test_fastfail audit
+.PHONY: docs docs-live docs-clean clean format format-check typecheck typecheck_pyright lint test test_fastfail audit
 
-clean:
+docs:
+	$(PYTHON) -m sphinx -b html -W --keep-going docs docs/_build/html
+
+docs-live:
+	sphinx-autobuild docs docs/_build/html
+
+docs-clean:
+	rm -rf docs/_build docs/reference/autoapi
+
+clean: docs-clean
 	find . -name "*.pyc" -print0 | xargs -0 rm -f
 	find . -name "*~" -print0 | xargs -0 rm -f
 	find . -name "__pycache__" -print0 | xargs -0 rm -rf
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..22728e3
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,43 @@
+import os
+import sys
+from datetime import date
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+project = "httk-web"
+author = "The httk-web AUTHORS"
+copyright = f"{date.today().year}, {author}"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+autosummary_generate = True
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": False,
+    "show-inheritance": True,
+}
+
+html_theme = "furo"
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "navigation_with_keys": True,
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
diff --git a/docs/how_it_works.rst b/docs/how_it_works.rst
new file mode 100644
index 0000000..a9cc2b4
--- /dev/null
+++ b/docs/how_it_works.rst
@@ -0,0 +1,101 @@
+How It Works
+============
+
+Current
+-------
+
+The default mode is the current, modern ``httk-web`` workflow.
+
+Directory layout
+^^^^^^^^^^^^^^^^
+
+A site source directory is expected to contain:
+
+- ``content/``: page sources (``.md``, ``.rst``, ``.html``)
+- ``templates/``: Jinja2 templates (for example ``default.html.j2`` and ``base_default.html.j2``)
+- ``static/``: static files copied as-is in publish mode
+- ``functions/``: optional Python modules exposing ``execute(...)``
+
+Runtime flow
+^^^^^^^^^^^^
+
+1. Route resolution maps a URL path to a content page or static file.
+2. Content rendering extracts metadata and body HTML.
+3. Function injection evaluates ``*-function`` metadata entries when query/post constraints are satisfied.
+4. Template rendering produces final HTML through Jinja2.
+5. ASGI serving returns responses, or static publishing writes ``.html`` output files.
+
+Public API
+^^^^^^^^^^
+
+The main API surface is:
+
+- ``httk.web.create_asgi_app(...)``
+- ``httk.web.serve(...)``
+- ``httk.web.publish(...)``
+
+Example usage
+^^^^^^^^^^^^^
+
+Serve dynamically:
+
+.. code-block:: python
+
+   from httk.web import serve
+   serve("src", port=8080)
+
+Publish statically:
+
+.. code-block:: python
+
+   from httk.web import publish
+   publish("src", "public", "http://127.0.0.1/")
+
+Examples
+^^^^^^^^
+
+Modern examples live under ``examples/modern``:
+
+- ``minimal``
+- ``rst_site``
+- ``blog``
+- ``search_app``
+
+Legacy
+------
+
+``httk-web`` also supports a compatibility mode for legacy site structures and templates.
+
+Enable compatibility mode
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``compatibility_mode=True`` in API calls:
+
+.. code-block:: python
+
+   from httk.web import serve
+   serve("src", compatibility_mode=True)
+
+Compatibility behaviors
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When compatibility mode is enabled, ``httk-web`` additionally supports:
+
+- ``.httkweb`` content and ``.httkweb.html`` template resolution
+- legacy formatter constructs used by old templates (for example repeat/call/if forms)
+- loading global metadata from ``config.*`` (or another name via ``config_name``)
+- running ``functions/init.py`` at engine startup
+- ``_functions/`` directory fallback when ``functions/`` is not present
+
+Examples
+^^^^^^^^
+
+Migrated legacy examples are available under ``examples/legacy``:
+
+- ``static_simple``
+- ``hello_world_app``
+- ``rst_templator``
+- ``blog``
+- ``search_app``
+
+For legacy examples that use optional old ``httk`` subsystems, availability depends on those dependencies.
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..da5c84a
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,17 @@
+httk-web
+========
+
+``httk-web`` provides web serving and static publishing functionality for ``httk`` v2.
+
+Quick links
+-----------
+
+- :doc:`how_it_works`
+- :doc:`reference`
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Documentation
+
+   how_it_works
+   reference
diff --git a/docs/reference.rst b/docs/reference.rst
new file mode 100644
index 0000000..aac4154
--- /dev/null
+++ b/docs/reference.rst
@@ -0,0 +1,18 @@
+Reference
+=========
+
+Public API
+----------
+
+.. automodule:: httk.web.api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Convenience Exports
+-------------------
+
+.. automodule:: httk.web
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/pyproject.toml b/pyproject.toml
index 7c13021..5d66118 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -44,6 +44,16 @@ dev = [
   "pyright",
   "mypy"
 ]
+docs = [
+  "sphinx",
+  "furo",
+  "myst-parser",
+  "myst-nb",
+  "sphinx-autodoc-typehints",
+  "sphinx-copybutton",
+  "sphinx-autoapi"
+]
+
 
 [tool.setuptools]
 package-dir = {"" = "src"}