Use mkdocs-material instead of sphinx

.gitignore

@@ -1 +1,3 @@
-_build
+site
+.cache
+__pycache__

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "yaml.schemas": {
+      "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+    },
+    "yaml.customTags": [
+      "!ENV scalar",
+      "!ENV sequence",
+      "!relative scalar",
+      "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+      "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+      "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+    ]
+  }

Makefile

@@ -1,29 +1,15 @@
-# Minimal makefile for Sphinx documentation
-#
+MKDOCS = python -m mkdocs
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = StarDist
-SOURCEDIR     = .
-BUILDDIR      = _build
-DEPLOYDIR     = ../stardist.github.io
+serve:
+	$(MKDOCS) $@
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+build:
+	$(MKDOCS) $@ --clean # --verbose
 
-.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)
-
-deploy:
-	make clean html html
-	cd "$(DEPLOYDIR)" && git reset --hard && git clean -fd && git rm -r .
-	cp $(BUILDDIR)/html/.nojekyll "$(DEPLOYDIR)"
-	cp -r $(BUILDDIR)/html/* "$(DEPLOYDIR)"
-	cd "$(DEPLOYDIR)" && git add .
-	cd "$(DEPLOYDIR)" && git commit -m "Update" && git push origin master
+# deploy:
+# 	make clean html html
+# 	cd "$(DEPLOYDIR)" && git reset --hard && git clean -fd && git rm -r .
+# 	cp $(BUILDDIR)/html/.nojekyll "$(DEPLOYDIR)"
+# 	cp -r $(BUILDDIR)/html/* "$(DEPLOYDIR)"
+# 	cd "$(DEPLOYDIR)" && git add .
+# 	cd "$(DEPLOYDIR)" && git commit -m "Update" && git push origin master

docs/CNAME

@@ -0,0 +1 @@
+stardist.net

index.md → docs/index.md

@@ -1,14 +1,19 @@
+---
+hide:
+  - navigation
+  - toc
+---
 
-# FAQs for StarDist - Object Detection with Star-Convex Polygons
+# StarDist - Object Detection with Star-Convex Polygons
 
-![](https://github.com/stardist/stardist/raw/master/images/stardist_overview.png)
+![](assets/overview.png)
 
-This page provides answers to frequently asked questions (FAQ) when using StarDist.
+This web site provides answers to [frequently asked questions (FAQ)](faq.md) when using StarDist.
 
 Please visit the [main stardist project page](https://github.com/stardist/stardist/) for general documentation, installation instructions, and issue reports. 
 
 
-If you are using StarDist in your research please cite the paper(s) 
+If you are using StarDist in your research please cite the relevant paper(s):
 
 ```bibtex
 @inproceedings{schmidt2018,
@@ -29,11 +34,4 @@ If you are using StarDist in your research please cite the paper(s)
   year      = {2020},
   doi       = {10.1109/WACV45572.2020.9093435}
 }
-```
-
-``` toctree::
-    :maxdepth: 2
-    :hidden:
-    
-    docs/faq
-```
+```

local.py

@@ -0,0 +1,11 @@
+from docutils.nodes import make_id
+
+
+# slugify as used by sphinx for backwards compatibility (to not break existing links)
+# - https://github.com/sphinx-doc/sphinx/issues/2574
+# - https://github.com/sphinx-doc/sphinx/issues/8709#issuecomment-763605496
+# use same signature as pymdownx.slugs.slugify
+def slugify(text, sep):
+    if sep != "-":
+        raise NotImplementedError(sep)
+    return make_id(text)

mkdocs.yml

@@ -0,0 +1,87 @@
+site_name: StarDist
+site_url: https://stardist.net/
+
+site_author: StarDist docs authors
+copyright: Copyright © 2020 – 2024 StarDist docs authors.
+site_description: StarDist is a deep learning based nuclei/cell detection and segmentation method for 2D and 3D microscopy images that is suited for densely packed objects that can be well approximated by star-convex polygons/polyhedra.
+
+repo_url: https://github.com/stardist/stardist
+repo_name: stardist/stardist
+edit_uri: https://github.com/stardist/stardist-docs/blob/main/docs/
+
+nav:
+  - Overview: index.md
+  - FAQ: faq.md
+  # - 'Forum': 'https://forum.image.sc/tag/stardist'
+
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        'docs/faq.html': 'faq.md'
+  - git-revision-date-localized:
+      enable_creation_date: false
+
+theme:
+  name: material
+  custom_dir: overrides
+  logo: assets/logo.png
+  font: false
+  # favicon: assets/favicon.png
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - toc.follow
+    - toc.integrate
+    - search.highlight
+    - navigation.tabs
+    # - navigation.footer
+    # - navigation.top
+    - navigation.indexes
+    - navigation.sections
+    - navigation.tracking
+    - content.action.edit
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: "teal"
+      accent: "teal"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: "teal"
+      accent: "teal"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+extra:
+  analytics:
+    provider: plausible
+    domain: stardist.net
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/stardist
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/stardist/
+
+markdown_extensions:
+  - toc:
+      # toc_depth: 3
+      # permalink: "★"
+      # permalink: ⚓︎
+      permalink: "#"
+      # note: always must use "python -m mkdocs" instead of "mkdocs" from the command line
+      # cf. https://github.com/mkdocs/mkdocs/issues/1442
+      slugify: !!python/name:local.slugify
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences

overrides/partials/integrations/analytics/plausible.html

@@ -0,0 +1 @@
+<script defer data-domain="{{ config.extra.analytics.domain }}" src="https://plausible.io/js/plausible.outbound-links.js"></script>

requirements.txt

@@ -1,3 +1,6 @@
-sphinx>=1.8
-sphinx-rtd-theme
-recommonmark
+mkdocs==1.5.3
+mkdocs-redirects==1.2.1
+mkdocs-material==9.5.6
+mkdocs-git-revision-date-localized-plugin==1.2.2
+pymdown-extensions==10.7
+docutils==0.20.1