From 47e40604694058b085224b457d85761a58f014b2 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Fri, 31 Oct 2025 16:34:11 -0700
Subject: [PATCH] Enable MyST Markdown docs, port events.rst, refs #2565

---
 Justfile                       |  2 +-
 docs/conf.py                   | 12 +++++++++++-
 docs/{events.rst => events.md} | 10 +++++-----
 pyproject.toml                 |  2 ++
 4 files changed, 19 insertions(+), 7 deletions(-)
 rename docs/{events.rst => events.md} (74%)

diff --git a/Justfile b/Justfile
index 8e4d6066..a9cdd94a 100644
--- a/Justfile
+++ b/Justfile
@@ -29,7 +29,7 @@ export DATASETTE_SECRET := "not_a_secret"
 
 # Serve live docs on localhost:8000
 @docs: cog blacken-docs
-  cd docs && uv run make livehtml
+  uv sync --extra docs && cd docs && uv run make livehtml
 
 # Apply Black
 @black:
diff --git a/docs/conf.py b/docs/conf.py
index e13882b2..0879eeb9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -36,12 +36,19 @@ extensions = [
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc",
     "sphinx_copybutton",
+    "myst_parser",
+    "sphinx_markdown_builder",
 ]
 if not os.environ.get("DISABLE_SPHINX_INLINE_TABS"):
     extensions += ["sphinx_inline_tabs"]
 
 autodoc_member_order = "bysource"
 
+myst_enable_extensions = ["colon_fence"]
+
+markdown_http_base = "https://docs.datasette.io/en/stable"
+markdown_uri_doc_suffix = ".html"
+
 extlinks = {
     "issue": ("https://github.com/simonw/datasette/issues/%s", "#%s"),
 }
@@ -53,7 +60,10 @@ templates_path = ["_templates"]
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
 
 # The master toctree document.
 master_doc = "index"
diff --git a/docs/events.rst b/docs/events.md
similarity index 74%
rename from docs/events.rst
rename to docs/events.md
index b86c8025..399317e9 100644
--- a/docs/events.rst
+++ b/docs/events.md
@@ -1,14 +1,14 @@
-.. _events:
-
-Events
-======
+(events)=
+# Events
 
 Datasette includes a mechanism for tracking events that occur while the software is running. This is primarily intended to be used by plugins, which can both trigger events and listen for events.
 
 The core Datasette application triggers events when certain things happen. This page describes those events.
 
-Plugins can listen for events using the :ref:`plugin_hook_track_event` plugin hook, which will be called with instances of the following classes - or additional classes :ref:`registered by other plugins <plugin_hook_register_events>`.
+Plugins can listen for events using the {ref}`plugin_hook_track_event` plugin hook, which will be called with instances of the following classes - or additional classes {ref}`registered by other plugins <plugin_hook_register_events>`.
 
+```{eval-rst}
 .. automodule:: datasette.events
     :members:
     :exclude-members: Event
+```
diff --git a/pyproject.toml b/pyproject.toml
index 1536c09b..fb9f0453 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -64,6 +64,8 @@ docs = [
     "blacken-docs",
     "sphinx-copybutton",
     "sphinx-inline-tabs",
+    "myst-parser",
+    "sphinx-markdown-builder",
     "ruamel.yaml",
 ]
 test = [