php · NickSdot · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
@@ -22,6 +22,8 @@ jobs:
         run: pip install -r docs/requirements.txt
       - name: Check formatting
         run: make -C docs check-formatting
+      - name: Build
+        run: make -C docs html
       - name: Publish
         if: github.event_name == 'push'
         uses: sphinx-notes/pages@v3

diff --git a/docs-old/output-api.md b/docs-old/output-api.md
diff --git a/docs/Makefile b/docs/Makefile
@@ -4,33 +4,29 @@
 # If people set these on the make command line, use 'em
 
 SPHINXBUILD ?= sphinx-build
+MDFORMAT ?= mdformat
 
 SOURCEDIR = source
 BUILDDIR = build
-RSTFMT = rstfmt
-RSTFMTFLAGS = -w 100
 
 rwildcard = $(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
-FILES = $(call rwildcard,$(SOURCEDIR),*.rst)
+MARKDOWN_FILES = $(call rwildcard,$(SOURCEDIR),*.md) $(call rwildcard,$(SOURCEDIR),*.rst)
 
 all : html
 
-.PHONY : check-formatting clean html preflight
+.PHONY : check-formatting clean format html
 .SUFFIXES : # Disable legacy behavior
 
 check-formatting :
-	$(RSTFMT) $(RSTFMTFLAGS) --check $(SOURCEDIR)
+	$(MDFORMAT) --check $(MARKDOWN_FILES)
 
 clean :
-	rm -rf -- $(wildcard $(SOURCEDIR)/.~ $(BUILDDIR))
+	rm -rf -- $(BUILDDIR)
 
-html : preflight
+format :
+	$(MDFORMAT) $(MARKDOWN_FILES)
+
+html :
 	$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR)
 	@printf 'Browse the \e]8;;%s\e\\%s\e]8;;\e\\.\n' \
 		"file://$(abspath $(BUILDDIR))/$@/index.$@" "php-src html docs locally"
-
-preflight : $(SOURCEDIR)/.~
-
-$(SOURCEDIR)/.~ : $(FILES)
-	$(RSTFMT) $(RSTFMTFLAGS) $?
-	touch $@
diff --git a/docs/README.md b/docs/README.md
@@ -27,12 +27,11 @@ your browser.
 
 ## Formatting
 
-The files in this documentation are formatted using the
-[``rstfmt``](https://github.com/dzhu/rstfmt) tool.
+The files in this documentation are formatted using
+[mdformat](https://mdformat.readthedocs.io/) with its
+[MyST plugin](https://github.com/executablebooks/mdformat-myst).
 
 ```bash
-rstfmt -w 100 source
+make format
+make check-formatting
 ```
-
-This tool is not perfect. It breaks on custom directives, so we might switch to
-either a fork or something else in the future.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,6 @@
 Sphinx
+mdformat==1.0.0
+mdformat-myst==0.3.0
+myst-parser>=5.1
 sphinx-design
 sphinxawesome-theme
-rstfmt
diff --git a/docs/source/_templates/redirect.html b/docs/source/_templates/redirect.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url={{ redirect_url }}">
+    <link rel="canonical" href="{{ redirect_url }}">
+    <title>Redirecting&hellip;</title>
+    <script>
+      window.location.replace({{ redirect_url | tojson }} + window.location.hash);
+    </script>
+  </head>
+  <body>
+    <p>This page has moved to <a href="{{ redirect_url }}">its new location</a>.</p>
+  </body>
+</html>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -15,9 +15,18 @@
 project = 'php-src docs'
 author = 'The PHP Group'
 extensions = [
+    'myst_parser',
     'sphinx_design',
     'sphinx.ext.autosectionlabel',
 ]
+exclude_patterns = ['**/*TODO.md']
+myst_enable_extensions = [
+    'alert',
+    'gfm_autolink',
+    'strikethrough',
+    'tasklist',
+]
+myst_heading_anchors = 6
 templates_path = ['_templates']
 html_theme = 'sphinxawesome_theme'
 html_static_path = ['_static']
@@ -58,3 +67,17 @@
 )
 html_theme_options = asdict(theme_options)
 pygments_style = 'sphinx'
+
+
+redirects = {
+    'core/data-structures/reference-counting': '../memory-management/reference-counting.html',
+}
+
+
+def generate_redirects(_app):
+    for source, target in redirects.items():
+        yield source, {'redirect_url': target}, 'redirect.html'
+
+
+def setup(app):
+    app.connect('html-collect-pages', generate_redirects)
diff --git a/docs/source/core/TODO.md b/docs/source/core/TODO.md
@@ -0,0 +1,8 @@
+Core TODO
+
+Pages to add:
+
+- Parser and AST: grammar generation, AST representation, compilation boundaries,
+  and important extension points.
+- Virtual Machine: opcode execution, operands, call frames, and VM variants.
+- Object Handlers: handler contracts, object storage, and common ownership traps.
diff --git a/docs/source/core/data-structures/TODO.md b/docs/source/core/data-structures/TODO.md
@@ -0,0 +1,4 @@
+Data Structures TODO
+
+- Add a HashTable page covering ownership, iteration, mutation, and common APIs.
+- Expand the zval macro table and document the remaining internal zval types.
diff --git a/docs/source/core/data-structures/index.md b/docs/source/core/data-structures/index.md
@@ -0,0 +1,12 @@
+# Data Structures
+
+```{toctree}
+---
+hidden: true
+---
+zval
+zend_string
+zend_constant
+```
+
+This section provides an overview of the core data structures used in php-src.
diff --git a/docs/source/core/data-structures/index.rst b/docs/source/core/data-structures/index.rst