@@ -48,3 +48,23 @@ jobs:
         with:
             job-name: "{1}"
             run-cmd: "hatch run javascript:check"
+    docs:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+            - uses: oven-sh/setup-bun@v2
+              with:
+                  bun-version: latest
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: 3.x
+            - name: Install Python Dependencies
+              run: pip install --upgrade pip hatch uv
+            - name: Check documentation links
+              run: hatch run docs:linkcheck
+            - name: Check docs build
+              run: hatch run docs:build
+            - name: Check docs examples
+              run: hatch fmt docs --check
@@ -1,3 +1,7 @@
+# --- DOCS ---
+
+docs/site
+
 # --- Build Artifacts ---
 src/reactpy/static/*.js*
 src/reactpy/static/morphdom/
 
@@ -453,7 +453,7 @@ All settable by env var (`reactpy/config.py`).
 
 ---
 
-## 11. Docs house style (this repo, `new-docs` branch)
+## 11. Docs house style
 
 - Pages live in `docs/src/`; `docs/mkdocs.yml` `nav:` lists them. Add `🚧` to the nav
   entry of any page not yet migrated — and **remove `🚧` when you finish a page**.
 
@@ -15,6 +15,8 @@ Using the following categories, list your changes in this order:
 Don't forget to remove deprecated code on each major release!
 -->
 
+<!--changelog-start-->
+
 ## [Unreleased]
 
 ### Added
 
@@ -160,34 +160,14 @@ plugins:
     # - spellcheck:
     #       known_words: dictionary.txt
     #       allow_unicode: no
-    - mkdocstrings:
-          default_handler: python
-          handlers:
-              python:
-                  paths: ["../"]
-                  inventories:
-                      ["https://installer.readthedocs.io/en/stable/objects.inv"]
-                  options:
-                      signature_crossrefs: true
-                      scoped_crossrefs: true
-                      relative_crossrefs: true
-                      modernize_annotations: true
-                      unwrap_annotated: true
-                      find_stubs_package: true
-                      show_root_members_full_path: true
-                      show_bases: false
-                      show_source: false
-                      show_root_toc_entry: false
-                      show_labels: false
-                      show_symbol_type_toc: true
-                      show_symbol_type_heading: true
-                      show_object_full_path: true
-                      heading_level: 3
 
 extra:
     generator: false
     version:
         provider: mike
+    # analytics:
+    #     provider: google
+    #     property: G-xxx
 
 extra_javascript:
     - assets/js/main.js
 
@@ -70,4 +70,4 @@
 <span class=normal>3</span></pre></div></td><td class=code><div><pre><span></span><code>hatch<span class=w> </span>fmt<span class=w> </span>--check<span class=w> </span>docs/
 pyright<span class=w> </span>--pythonpath<span class=w> </span>&lt;your-env&gt;/bin/python<span class=w> </span>docs/
 <span class=nb>cd</span><span class=w> </span>docs<span class=w> </span><span class=o>&amp;&amp;</span><span class=w> </span>mkdocs<span class=w> </span>build<span class=w> </span>--strict<span class=p>;</span><span class=w> </span><span class=nb>echo</span><span class=w> </span><span class=s2>"exit=</span><span class=nv>$?</span><span class=s2>"</span>
-</code></pre></div></td></tr></table></div> <p>Then run the examples themselves and open the built page in a browser. <code>mkdocs build --strict</code> catches broken internal links and unresolvable includes — both abort the build with a nonzero exit. Two things it does <strong>not</strong> catch: a page missing from <code>nav:</code> (an <code>INFO</code> line, exit 0), and a link whose <code>#anchor</code> does not exist in an otherwise valid target file (also exit 0), so check both by eye. And it cannot catch a snippet that renders nothing.</p> <p>You are the only gate. The single workflow on <code>new-docs</code> runs <code>mkdocs gh-deploy --force</code> on push, and <code>gh-deploy</code> does not pass <code>--strict</code> — a build with broken links exits 0 and publishes. A miss does not fail a pipeline; it goes live.</p> <div class="admonition warning"> <p class=admonition-title>Pitfall</p> <p>Do not trust a component that renders without error. Set <code>REACTPY_DEBUG=1</code> when probing: with debug off, a component that raised produces <code>{"tagName": "", "error": ""}</code> — a blank region and a 200 response. See <a href=../running-tests/ >Running Tests</a> for the harness traps that make a broken example look green.</p> </div> <h2 id=process>Process<a class=headerlink href=#process title="Permanent link">&para;</a></h2> <p>Branch from <code>new-docs</code>, one page per branch, and use the same Conventional Commit subjects as the history there — <code>docs(learn): author X for ReactPy v2</code>. A commit that removes a <code>🚧</code> badge from <code>nav:</code> should be the same commit that authored the page, never a separate "mark done" commit that could be cherry-picked alone.</p> <p>No <code>CHANGELOG.md</code> entry: documentation work is not user-facing in the sense the changelog means. See <a href=../changelog/ >Changelog</a>.</p> <div class="admonition abstract"> <p class=admonition-title>Note</p> <p><code>docs/src/dictionary.txt</code> exists for the spellcheck plugin, which is currently commented out in <code>mkdocs.yml</code>. New domain words belong there if the plugin is ever re-enabled; nothing fails while it stays off.</p> </div> <h2 id=recap>Recap<a class=headerlink href=#recap title="Permanent link">&para;</a></h2> <ul> <li>A page is done when it runs and every claim is verified — then remove its <code>🚧</code> badge.</li> <li>Port, do not rename: delete JSX, non-existent hooks, StrictMode, <code>memo</code>, <code>&amp;&amp;</code> rendering, and React's dependency-array semantics.</li> <li>Fixed structure: Overview, intro paragraph, <code>You will learn</code>, sections, Recap, Related.</li> <li>Relative <code>.md</code> links; admonitions instead of ReactJS's JSX tags.</li> <li>Snippets are includes from <code>docs/examples/</code>, cropped at <code># start</code>, formatted at 88 columns.</li> <li><code>--strict</code> checks links and nothing about behaviour. Run the example.</li> </ul> <h2 id=related>Related<a class=headerlink href=#related title="Permanent link">&para;</a></h2> <ul> <li><a href=../running-tests/ >Running Tests</a> — the exact commands and how to read their failures</li> <li><a href=../code/ >Contributing Code</a> — branch and pull request conventions</li> <li><a href=../changelog/ >Changelog</a> — what does and does not deserve an entry</li> <li><a href=../community/ >Community</a> — where to ask about a page before rewriting it</li> </ul> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 12, 2026 07:17:22 UTC">October 12, 2026</span> </span> <span class=md-source-file__fact> <span class=md-icon title=Contributors> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 5.5A3.5 3.5 0 0 1 15.5 9a3.5 3.5 0 0 1-3.5 3.5A3.5 3.5 0 0 1 8.5 9 3.5 3.5 0 0 1 12 5.5M5 8c.56 0 1.08.15 1.53.42-.15 1.43.27 2.85 1.13 3.96C7.16 13.34 6.16 14 5 14a3 3 0 0 1-3-3 3 3 0 0 1 3-3m14 0a3 3 0 0 1 3 3 3 3 0 0 1-3 3c-1.16 0-2.16-.66-2.66-1.62a5.54 5.54 0 0 0 1.13-3.96c.45-.27.97-.42 1.53-.42M5.5 18.25c0-2.07 2.91-3.75 6.5-3.75s6.5 1.68 6.5 3.75V20h-13zM0 20v-1.5c0-1.39 1.89-2.56 4.45-2.9-.59.68-.95 1.62-.95 2.65V20zm24 0h-3.5v-1.75c0-1.03-.36-1.97-.95-2.65 2.56.34 4.45 1.51 4.45 2.9z"/></svg> </span> <nav> <a href=mailto:16909269+archmonger@users.noreply.github.com>Archmonger</a>, <a href=mailto:not.committed.yet>Not Committed Yet</a> </nav> </span> </aside> <div class=md-source-date> <small> Authors: <span class="git-page-authors git-authors"><a href=mailto:16909269+archmonger@users.noreply.github.com>Archmonger</a>, <a href=mailto:not.committed.yet>Not Committed Yet</a></span> </small> </div> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> &copy;<div id=year> </div> <script> document.getElementById("year").innerHTML = new Date().getFullYear(); </script>Reactive Python and affiliates.<div class=legal-footer-right>This project has no affiliation to ReactJS or Meta Platforms, Inc.</div> </div> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.top", "content.code.copy", "search.highlight"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"provider": "mike"}}</script> <script src=../../assets/javascripts/bundle.d7400e89.min.js></script> <script src=../../assets/js/main.js></script> </body> </html>
+</code></pre></div></td></tr></table></div> <p>Then run the examples themselves and open the built page in a browser. <code>mkdocs build --strict</code> catches broken internal links and unresolvable includes — both abort the build with a nonzero exit. Two things it does <strong>not</strong> catch: a page missing from <code>nav:</code> (an <code>INFO</code> line, exit 0), and a link whose <code>#anchor</code> does not exist in an otherwise valid target file (also exit 0), so check both by eye. And it cannot catch a snippet that renders nothing.</p> <p>You are the only gate. The single workflow on <code>new-docs</code> runs <code>mkdocs gh-deploy --force</code> on push, and <code>gh-deploy</code> does not pass <code>--strict</code> — a build with broken links exits 0 and publishes. A miss does not fail a pipeline; it goes live.</p> <div class="admonition warning"> <p class=admonition-title>Pitfall</p> <p>Do not trust a component that renders without error. Set <code>REACTPY_DEBUG=1</code> when probing: with debug off, a component that raised produces <code>{"tagName": "", "error": ""}</code> — a blank region and a 200 response. See <a href=../running-tests/ >Running Tests</a> for the harness traps that make a broken example look green.</p> </div> <h2 id=process>Process<a class=headerlink href=#process title="Permanent link">&para;</a></h2> <p>Branch from <code>new-docs</code>, one page per branch, and use the same Conventional Commit subjects as the history there — <code>docs(learn): author X for ReactPy v2</code>. A commit that removes a <code>🚧</code> badge from <code>nav:</code> should be the same commit that authored the page, never a separate "mark done" commit that could be cherry-picked alone.</p> <p>No <code>CHANGELOG.md</code> entry: documentation work is not user-facing in the sense the changelog means. See <a href=../changelog/ >Changelog</a>.</p> <div class="admonition abstract"> <p class=admonition-title>Note</p> <p><code>docs/src/dictionary.txt</code> exists for the spellcheck plugin, which is currently commented out in <code>mkdocs.yml</code>. New domain words belong there if the plugin is ever re-enabled; nothing fails while it stays off.</p> </div> <h2 id=recap>Recap<a class=headerlink href=#recap title="Permanent link">&para;</a></h2> <ul> <li>A page is done when it runs and every claim is verified — then remove its <code>🚧</code> badge.</li> <li>Port, do not rename: delete JSX, non-existent hooks, StrictMode, <code>memo</code>, <code>&amp;&amp;</code> rendering, and React's dependency-array semantics.</li> <li>Fixed structure: Overview, intro paragraph, <code>You will learn</code>, sections, Recap, Related.</li> <li>Relative <code>.md</code> links; admonitions instead of ReactJS's JSX tags.</li> <li>Snippets are includes from <code>docs/examples/</code>, cropped at <code># start</code>, formatted at 88 columns.</li> <li><code>--strict</code> checks links and nothing about behaviour. Run the example.</li> </ul> <h2 id=related>Related<a class=headerlink href=#related title="Permanent link">&para;</a></h2> <ul> <li><a href=../running-tests/ >Running Tests</a> — the exact commands and how to read their failures</li> <li><a href=../code/ >Contributing Code</a> — branch and pull request conventions</li> <li><a href=../changelog/ >Changelog</a> — what does and does not deserve an entry</li> <li><a href=../community/ >Community</a> — where to ask about a page before rewriting it</li> </ul> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 18, 2026 18:26:02 UTC">October 18, 2026</span> </span> <span class=md-source-file__fact> <span class=md-icon title=Contributors> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 4a4 4 0 0 1 4 4 4 4 0 0 1-4 4 4 4 0 0 1-4-4 4 4 0 0 1 4-4m0 10c4.42 0 8 1.79 8 4v2H4v-2c0-2.21 3.58-4 8-4"/></svg> </span> <nav> <a href=mailto:16909269+archmonger@users.noreply.github.com>Archmonger</a> </nav> </span> </aside> <div class=md-source-date> <small> Authors: <span class="git-page-authors git-authors"><a href=mailto:16909269+archmonger@users.noreply.github.com>Archmonger</a></span> </small> </div> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> &copy;<div id=year> </div> <script> document.getElementById("year").innerHTML = new Date().getFullYear(); </script>Reactive Python and affiliates.<div class=legal-footer-right>This project has no affiliation to ReactJS or Meta Platforms, Inc.</div> </div> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.tabs.sticky", "navigation.top", "content.code.copy", "search.highlight"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"provider": "mike"}}</script> <script src=../../assets/javascripts/bundle.d7400e89.min.js></script> <script src=../../assets/js/main.js></script> </body> </html>