emscripten-forge · ianthomas23 · Sep 30, 2026 · Sep 30, 2026
diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml
@@ -38,15 +38,15 @@ jobs:
       # BUILD
       ################################################################
       - name: Build docs
-        run: pixi run docs-build -d docs_build
+        run: pixi run docs-build
 
       ################################################################
       # UPLOAD
       ################################################################
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: docs_build
+          path: docs/_build/html/
 
   deploy:
     # only run on main branch

diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,6 @@ output/
 
 # emscripten forge install
 emscripten_forge_emsdk_install/
+
+# docs output
+docs/_build
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/assets/custom.css b/docs/assets/custom.css
@@ -0,0 +1,29 @@
+img.banner {
+  display: block;
+  width: 90%;
+  margin: 0 auto 2em;
+}
+
+/* Smaller logo at the top of the primary sidebar */
+.navbar-brand .logo__image {
+  width: 50%;
+}
+
+/* Larger site name below the logo, shrinking to stay on one line in a narrow sidebar */
+.navbar-brand {
+  container-type: inline-size;
+}
+
+.navbar-brand .logo__title {
+  font-size: min(1.6rem, 11.5cqi);
+  white-space: nowrap;
+}
+
+/* Links and selected items in orange  */
+html[data-theme="light"] {
+  --pst-color-primary: #ff6e42;
+}
+
+html[data-theme="dark"] {
+  --pst-color-primary: #ff764d;
+}
diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml
diff --git a/docs/blog/index.md b/docs/blog/index.md
@@ -0,0 +1,7 @@
+# Blog
+
+```{postlist}
+:date: "%Y-%m-%d"
+:excerpts:
+:expand: Read more…
+```
diff --git a/docs/blog/posts/pixi.md b/docs/blog/posts/pixi.md
@@ -1,11 +1,7 @@
----
-date: 2024-05-10
-category:
-    - rust
-
-authors:
-    - derthorsten
----
+```{post} 2024-05-10
+:author: derthorsten
+:category: rust
+```
 
 # Local builds with `pixi`
 

diff --git a/docs/blog/posts/rattler_build.md b/docs/blog/posts/rattler_build.md
@@ -1,11 +1,7 @@
----
-date: 2024-05-10
-category:
-    - rust
-
-authors:
-    - derthorsten
----
+```{post} 2024-05-10
+:author: derthorsten
+:category: rust
+```
 
 # Goodby boa, welcome rattler-build
 

diff --git a/docs/blog/posts/repack_emscripten.md b/docs/blog/posts/repack_emscripten.md
@@ -1,12 +1,7 @@
----
-date: 2024-05-24
-category:
-    - rust
-
-authors:
-    - derthorsten
-    - wolfv
----
+```{post} 2024-05-24
+:author: derthorsten, wolfv
+:category: rust
+```
 
 # Emscripten is now a proper package
 

diff --git a/docs/blog/posts/rust.md b/docs/blog/posts/rust.md
@@ -1,12 +1,7 @@
----
-date: 2024-05-10
-category:
-    - rust
-    - python
-
-authors:
-    - derthorsten
----
+```{post} 2024-05-10
+:author: derthorsten
+:category: rust, python
+```
 
 # Rust/PyO3 Support 
 

diff --git a/docs/blog/posts/updates.md b/docs/blog/posts/updates.md
@@ -1,13 +1,7 @@
----
-date: 2025-04-30
-category:
-    - server
-    - python
-    - compiler
-
-authors:
-    - derthorsten
----
+```{post} 2025-04-30
+:author: derthorsten
+:category: server, python, compiler
+```
 
 # Major updates
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,58 @@
+import shutil
+from pathlib import Path
+
+project = 'Emscripten-forge'
+author = 'Emscripten-forge maintainers'
+copyright = '2026'
+
+extensions = [
+    "myst_parser",
+    "ablog",
+]
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Blog: any .md file in blog/posts is a post, ordered by the date in its {post} directive
+blog_post_pattern = "blog/posts/*"
+blog_title = f"{project} blog"
+blog_authors = {
+    "derthorsten": ("Dr. Thorsten Beier", "https://github.com/DerThorsten"),
+    "wolfv": ("Wolf Vollprecht", "https://prefix.dev"),
+}
+post_date_format = "%Y-%m-%d"
+post_date_format_short = "%Y-%m-%d"
+
+_book_sidebar = ["navbar-logo.html", "icon-links.html", "search-button-field.html", "sbt-sidebar-nav.html"]
+_blog_widgets = ["ablog/categories.html", "ablog/authors.html", "ablog/archives.html"]
+
+html_css_files = ["custom.css"]
+html_static_path = ['assets']
+html_sidebars = {
+    "blog/posts/*": _book_sidebar[:3] + ["ablog/postcard.html"] + _book_sidebar[3:],
+    "blog/index": _book_sidebar + _blog_widgets,
+    "blog/archive": _book_sidebar + _blog_widgets,
+    "blog/archive/**": _book_sidebar + _blog_widgets,
+}
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "logo": {
+        "alt_text": "Emscripten-forge logo",
+        "image_dark": "assets/icon.svg",
+        "image_light": "assets/icon.svg",
+        "text": project,
+    },
+    "navbar_persistent": [],
+    "repository_url": "https://github.com/emscripten-forge/recipes",
+    "use_repository_button": True,
+}
+html_title = project
+
+
+def _copy_qtapp(app, exception):
+    """Copy docs/qtapp to the same place in the HTML output, unchanged."""
+    if exception is None and app.builder.format == "html":
+        shutil.copytree(Path(app.srcdir) / "qtapp", Path(app.outdir) / "qtapp", dirs_exist_ok=True)
+
+
+def setup(app):
+    app.connect("build-finished", _copy_qtapp)
diff --git a/docs/development/conda_build_config.md b/docs/development/conda_build_config.md
@@ -53,9 +53,9 @@ Furthermore, this build-config specifies which compiler to use for each platform
 While conda-forge build configuration can be found [here](https://github.com/conda-forge/conda-forge-pinning-feedstock/blob/main/recipe/conda_build_config.yaml),
 we **need** to maintain our own [conda-build-config](https://github.com/emscripten-forge/recipes/blob/main/conda_build_config.yaml). In particular, we need to set up the emscripten compiler.
 
-!!! note
-    The conda-build-config of emscripten-forge uses the [rattler-recipes format](https://github.com/prefix-dev/rattler-build?tab=readme-ov-file#the-recipe-format)
-
+```{note}
+The conda-build-config of emscripten-forge uses the [rattler-recipes format](https://github.com/prefix-dev/rattler-build?tab=readme-ov-file#the-recipe-format)
+```
 
 ```yaml
 cxx_compiler:

diff --git a/docs/development/local_builds.md b/docs/development/local_builds.md
@@ -14,8 +14,9 @@ pixi run setup
 pixi run build-emscripten-wasm32-pkg recipes/recipes_emscripten/regex
 ```
 
-!!! note
-    When using [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/) (WSL), some local builds might fail due to `libatomic` not being available. For cases like this, developers are required to use a full Linux machine such as a virtual machine or cloud server.
+```{note}
+When using [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/) (WSL), some local builds might fail due to `libatomic` not being available. For cases like this, developers are required to use a full Linux machine such as a virtual machine or cloud server.
+```
 
 ## Local builds with `rattler-build`
 We recommend using the `pixi` command to build packages locally. However, if you want to use `rattler-build` directly, you can do so with the following steps:

diff --git a/docs/index.md b/docs/index.md
@@ -1,46 +1,49 @@
-<img src="assets/banner.svg" alt="Emscripten-forge Banner" style="width: 90%;">
-
-#
+```{image} assets/banner.svg
+:alt: Emscripten-forge banner
+:class: banner dark-light
+```
 
 # Introduction
 
-
 Emscripten-forge is a GitHub [organization](https://github.com/emscripten-forge)/[repository](https://github.com/emscripten-forge/recipes) containing  [conda recipes](https://github.com/emscripten-forge/recipes) for the `emscripten-wasm32` platform.
 Conda-forge does not (yet) support the `emscripten-wasm32` platform. `emscripten-forge` fills this gap by providing a channel with conda packages for the `emscripten-wasm32` platform.
 The recipes repository not only stores the recipe files for multiple packages, but it also builds and uploads these packages to the `emscripten-forge` channel on [prefix.dev](https://prefix.dev/channels/emscripten-forge-4x)
 
-!!! info "Community project"
-    Emscripten-forge strives to be a community project, shaped by its active individual and organizational supporters. Anyone can participate in the decision-making process openly through GitHub. See [Get Involved](project/get_involved.md) to learn how to participate as an individual or organisation.
-
-##
-
-### Development
-
-  * [Adding packages](development/adding_packages)
-  * [Recipe format](development/recipe_format)
-  * [Local builds](development/local_builds)
-  * [Conda build config](development/conda_build_config)
-  * [Troubleshooting](development/troubleshooting)
-  * [Code of conduct](development/code_of_conduct)
-
-### Usage
-
-  * [Installing packages](usage/installing_packages)
-  * [JupyterLite](usage/jupyterlite)
-  * [Package server](usage/package_server)
-  * [Experimental Qt runner](usage/qtapp)
-
-### Project
-
-  * [Blog](blog)
-  * [Get involved](project/get_involved)
-  * [Related projects](project/related_projects)
-  * [Showcase](project/showcase)
-  * [FAQ](project/faq)
-  * [Credits](project/credits)
-
-##
+```{admonition} Community project
+Emscripten-forge strives to be a community project, shaped by its active individual and organizational supporters. Anyone can participate in the decision-making process openly through GitHub. See [Get Involved](project/get_involved.md) to learn how to participate as an individual or organisation.
+```
+
+```{toctree}
+:caption: Development
+:maxdepth: 1
+development/adding_packages
+development/recipe_format
+development/local_builds
+development/conda_build_config
+development/troubleshooting
+development/code_of_conduct
+```
+
+```{toctree}
+:caption: Usage
+:maxdepth: 1
+usage/installing_packages
+usage/jupyterlite
+usage/package_server
+usage/qtapp
+```
+
+```{toctree}
+:caption: Project
+:maxdepth: 1
+blog/index
+project/get_involved
+project/related_projects
+project/showcase
+project/faq
+project/credits
+```
 
 # Acknowledgements
 
-Special thanks to [QuantStack](https://quantstack.net/), [Bloomberg](https://www.bloomberg.com/), and [prefix.dev](https://prefix.dev/), whose support made it possible to start the project. See [Credits](project/credits.md) for the current supporters and contributors.
+Special thanks to [QuantStack](https://quantstack.net/), [Bloomberg](https://www.bloomberg.com/), and [prefix.dev](https://prefix.dev/), whose support made it possible to start the project. See [Credits](project/credits.md) for the current supporters and contributors.
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/project/credits.md b/docs/project/credits.md
@@ -1,5 +1,6 @@
 # Credits
 
+(supporters)=
 ## Supporters
 
 - **[QuantStack](https://quantstack.net/)**: sponsors continued development and maintenance.