diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..3d57836
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 California Institute of Technology.
+
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build docs
+        run: uv run zensical build
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v6
+
+      - id: deploy
+        uses: actions/deploy-pages@v5
diff --git a/.gitignore b/.gitignore
index 2ed1e34..5c67bc9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,8 +51,8 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
-docs/_build/
+# MkDocs build output
+site/
 
 # PyBuilder
 target/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
deleted file mode 100644
index 4a49353..0000000
--- a/.readthedocs.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-
-# Required
-version: 2
-
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.12"
-
-sphinx:
-  configuration: docs/conf.py
-
-python:
-  install:
-    - requirements: docs/requirements.txt
diff --git a/AUTHORS.md b/AUTHORS.md
new file mode 100644
index 0000000..3dd2d04
--- /dev/null
+++ b/AUTHORS.md
@@ -0,0 +1,21 @@
+<!--
+SPDX-FileCopyrightText: 2015-2019 CERN.
+SPDX-License-Identifier: BSD-3-Clause
+
+In applying this license, CERN does not waive the privileges and immunities
+granted to it by virtue of its status as an Intergovernmental Organization
+or submit itself to any jurisdiction.
+-->
+
+# Authors
+
+- Adrian Pawel Baran
+- Alan Rubin
+- Alexander Ioannidis
+- Antoine Lambert
+- Bruno Marmol
+- Guillaume Viger
+- Jiri Kuncar
+- Lars Holm Nielsen
+- Pedro Gaudencio
+- Tibor Simko
diff --git a/AUTHORS.rst b/AUTHORS.rst
deleted file mode 100644
index d562b11..0000000
--- a/AUTHORS.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-..
-   SPDX-FileCopyrightText: 2015-2019 CERN.
-   SPDX-License-Identifier: BSD-3-Clause
-
-   In applying this license, CERN does not waive the privileges and immunities
-   granted to it by virtue of its status as an Intergovernmental Organization
-   or submit itself to any jurisdiction.
-
-
-Authors
-=======
-
-- Adrian Pawel Baran
-- Alan Rubin
-- Alexander Ioannidis
-- Antoine Lambert
-- Bruno Marmol
-- Guillaume Viger
-- Jiri Kuncar
-- Lars Holm Nielsen
-- Pedro Gaudencio
-- Tibor Simko
diff --git a/CHANGES.rst b/CHANGES.md
similarity index 70%
rename from CHANGES.rst
rename to CHANGES.md
index 9d65e48..8fadeee 100644
--- a/CHANGES.rst
+++ b/CHANGES.md
@@ -1,46 +1,45 @@
-..
-   SPDX-FileCopyrightText: 2015-2023 CERN.
-   SPDX-FileCopyrightText: 2022 Northwestern University.
-   SPDX-License-Identifier: BSD-3-Clause
+<!--
+SPDX-FileCopyrightText: 2015-2023 CERN.
+SPDX-FileCopyrightText: 2022 Northwestern University.
+SPDX-License-Identifier: BSD-3-Clause
 
-   In applying this license, CERN does not waive the privileges and immunities
-   granted to it by virtue of its status as an Intergovernmental Organization
-   or submit itself to any jurisdiction.
+In applying this license, CERN does not waive the privileges and immunities
+granted to it by virtue of its status as an Intergovernmental Organization
+or submit itself to any jurisdiction.
+-->
 
+# Changes
 
-Changes
-=======
-
-Version v1.6.1 (released 2026-05-28)
+## Version v1.6.1 (released 2026-05-28)
 
 - setup: replace isbnlib with isbnlib2
 
-Version v1.6.0 (released 2026-03-19)
+## Version v1.6.0 (released 2026-03-19)
 
 - refactor: remove DeprecationWarning
 - feat: add cstr and rrid identifiers
 - adding tests
 - feat: add openalex validator
 
-Version v1.5.1 (released 2025-12-15)
+## Version v1.5.1 (released 2025-12-15)
 
 - feat: add support for wikidata type QID scheme
 - gh-action: various version bumps
 
-Version v1.5.0 (released 2025-07-14)
+## Version v1.5.0 (released 2025-07-14)
 
 - chores: replaced importlib_metadata with importlib.metadata
 
-Version 1.4.5 (2025-06-05)
+## Version 1.4.5 (2025-06-05)
 
 - ark: fix regex to match new ARK identifiers without slash
 
-Version 1.4.4 (2025-06-03)
+## Version 1.4.4 (2025-06-03)
 
 - swhid: improved SWHID validation
 - tests: additional tests
 
-Version 1.4.3 (2025-05-12)
+## Version 1.4.3 (2025-05-12)
 
 - is_url: allow URL parameters (i.e. semicolon)
 - gnd: improve validation and normalization
@@ -48,137 +47,137 @@ Version 1.4.3 (2025-05-12)
 - pmid: add trailing slash
 - new: email and sha1 identifiers
 
-Version 1.4.2 (2024-11-01)
+## Version 1.4.2 (2024-11-01)
 
 - setup: remove pytest-invenio to make imports cleaner
 - setup: install importlib_metadata for compatibility
 - bibcode/ads: normalize unicode
 
-Version 1.4.1 (2024-10-18)
+## Version 1.4.1 (2024-10-18)
 
 - install: add importlib_metadata
 
-Version 1.4.0 (2024-10-17)
+## Version 1.4.0 (2024-10-17)
 
 - Restructure module to be configurable and readable.
 - Adds a new entrypoint to register new custom schemes
 - Adds deprecations for direct imports of schemes
 
-Version 1.3.0 (2024-10-15) (yanked due to undesired flask dependency)
+## Version 1.3.0 (2024-10-15) (yanked due to undesired flask dependency)
 
 - Restructure module to be configurable and readable.
 - Adds a new entrypoint to register new custom schemes
 - Adds deprecations for direct imports of schemes
 
-Version 1.2.1 (2023-03-02)
+## Version 1.2.1 (2023-03-02)
 
 - Fixes ORCiD validation, by adding the new ISNI block range.
 
-Version 1.2.0 (2023-01-30)
+## Version 1.2.0 (2023-01-30)
 
 - schemes: add support for viaf and urn
 
-Version 1.1.12 (2022-02-28)
+## Version 1.1.12 (2022-02-28)
 
-- Replaces ``isbnid_fork`` with ``isbnlib``
+- Replaces `isbnid_fork` with `isbnlib`
 
-Version 1.1.11 (2022-01-28)
+## Version 1.1.11 (2022-01-28)
 
 - Normalize pmid + their URL identifiers
 
-Version 1.1.10 (2022-01-11)
+## Version 1.1.10 (2022-01-11)
 
 - Add purl.fdlp.gov as a valid PURL netloc
 - Normalize ror identifiers
 
-Version 1.1.9 (2021-08-30)
+## Version 1.1.9 (2021-08-30)
 
 - Update ARK's NAAN regex per https://datatracker.ietf.org/doc/html/draft-kunze-ark-28#section-2.3.
 
-Version 1.1.8 (2020-08-13)
+## Version 1.1.8 (2020-08-13)
 
 - Adds support for GEO and ArrayExpress identifiers.
 
-Version 1.1.7 (2020-06-22)
+## Version 1.1.7 (2020-06-22)
 
 - Updates Software Heritage identifiers
 - Adds Research Organization Registry identifiers
 - Fixes DeprctationWarnings by using raw strings for regular expressions
 
-Version 1.1.6 (2020-05-07)
+## Version 1.1.6 (2020-05-07)
 
 - Deprecates Python versions lower than 3.6.0. Now supporting 3.6.0 and 3.7.0.
 
-Version 1.1.5 (2020-02-26)
+## Version 1.1.5 (2020-02-26)
 
 - Adds support for Software Heritage identifiers.
 - Fixes handling of non-digit characters in DOI detection.
 
-Version 1.1.4 (2019-09-27)
+## Version 1.1.4 (2019-09-27)
 
 - Adds support for ASCL identifiers.
 - Fixes the ADS identifier regex to also detect lower-case author initials.
 
-Version 1.1.3 (2019-09-17)
+## Version 1.1.3 (2019-09-17)
 
 - Adds support for HTTPS ORCiD identifiers.
 
-Version 1.1.2 (2019-02-12)
+## Version 1.1.2 (2019-02-12)
 
 - Adds support for HAL identifiers.
 
-Version 1.1.1 (2018-11-18)
+## Version 1.1.1 (2018-11-18)
 
 - Changes URL resolution for bibcodes to use https://ui.adsabs.harvard instead
   of https://adsabs.harvard.edu/abs/.
-- Allows choosing HTTP/HTTPS for any generated URL by ``idutils.to_url``.
+- Allows choosing HTTP/HTTPS for any generated URL by `idutils.to_url`.
 
-Version 1.1.0 (2018-08-17)
+## Version 1.1.0 (2018-08-17)
 
 - Adds support for genomic identifiers: SRA, BioProject, BioSample, Ensembl,
   UniProt, RefSeq, GenBank/RefSeq.
 - Fixes bug in bibcode detection for non-capitalized journals.
 
-Version 1.0.1 (2018-05-02)
+## Version 1.0.1 (2018-05-02)
 
 - Fixes bug causing invalid DOIs to be accepted.
 
-Version 1.0.0 (2017-12-07)
+## Version 1.0.0 (2017-12-07)
 
 - Fixes handling of unicode characters in DOIs.
 - Adds support for APS style arXiv identifiers.
 
-Version 0.2.4 (2017-01-30)
+## Version 0.2.4 (2017-01-30)
 
 - Removes `Python 3.3` from a list of supported Python versions and
   adds `Python 3.6`
 - Moves from `isbnid (v0.3.4)` to `isbnid_fork (v0.4.4)` library.
 
-Version 0.2.3 (2016-09-21)
+## Version 0.2.3 (2016-09-21)
 
 - Adds an optional parameter in `idutils.to_url` to use HTTPS scheme
   for PID providers that support it.
 - Detects and parses Handles and DOIs without the "http(s)://", and
   ignores whitespace after scheme tags (eg. "doi:  10.123/456").
 
-Version 0.2.2 (2016-09-16)
+## Version 0.2.2 (2016-09-16)
 
 - Fixes issue where a valid ISBN with dashes and spaces could not be
   normalized.
 
-Version 0.2.1 (2016-06-17)
+## Version 0.2.1 (2016-06-17)
 
 - Changes ISBN normalization to use `isbnid` instead of `isbnlib`. Now,
   importing this library will not change the default socket timeout, resulting
   in unwanted side effects.
 
-Version 0.2.0 (2016-04-07)
+## Version 0.2.0 (2016-04-07)
 
 - Changes URL resolution for DOIs to use https://doi.org instead of
   http://dx.doi.org according to
   https://www.doi.org/doi_handbook/3_Resolution.html#3.8
 
-Version 0.1.1 (2015-07-22)
+## Version 0.1.1 (2015-07-22)
 
 - Fixes GND validation and normalization.
 - Replaces invalid package name in `run-tests.sh` and makes `run-tests.sh` file
@@ -188,6 +187,6 @@ Version 0.1.1 (2015-07-22)
   `docker-compose build` rebuilds the image,
   `docker-compose run --rm web /code/run-tests.sh` runs the test suite.
 
-Version 0.1.0 (2015-07-02)
+## Version 0.1.0 (2015-07-02)
 
 - First public release.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.md
similarity index 69%
rename from CONTRIBUTING.rst
rename to CONTRIBUTING.md
index 8392336..a5e5b17 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.md
@@ -1,12 +1,10 @@
-Contributing
-============
+# Contributing
 
 Bug reports, feature requests, and other contributions are welcome.
 If you find a demonstrable problem that is caused by the code of this
 library, please:
 
-1. Search for `already reported problems
-   <https://github.com/inveniosoftware/idutils/issues>`_.
+1. Search for [already reported problems](https://github.com/inveniosoftware/idutils/issues).
 2. Check if the issue has been fixed or is still reproducible on the
    latest `master` branch.
 3. Create an issue with **a test case**.
@@ -14,6 +12,6 @@ library, please:
 If you create a feature branch, you can run the tests to ensure everything is
 operating correctly:
 
-.. code-block:: console
-
-    $ ./run-tests.sh
+```console
+$ ./run-tests.sh
+```
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c18ce83
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2015 CERN.
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+SPDX-License-Identifier: BSD-3-Clause
+
+In applying this license, CERN does not waive the privileges and immunities
+granted to it by virtue of its status as an Intergovernmental Organization
+or submit itself to any jurisdiction.
+-->
+
+# IDUtils
+
+[![CI](https://github.com/inveniosoftware/idutils/workflows/CI/badge.svg)](https://github.com/inveniosoftware/idutils/actions?query=workflow%3ACI)
+[![Coverage](https://img.shields.io/coveralls/inveniosoftware/idutils.svg)](https://coveralls.io/r/inveniosoftware/idutils)
+[![Release](https://img.shields.io/github/tag/inveniosoftware/idutils.svg)](https://github.com/inveniosoftware/idutils/releases)
+[![Downloads](https://img.shields.io/pypi/dm/idutils.svg)](https://pypi.python.org/pypi/idutils)
+[![License](https://img.shields.io/github/license/inveniosoftware/idutils.svg)](https://github.com/inveniosoftware/idutils/blob/master/LICENSE)
+
+Small library for validating and normalising persistent identifiers used in
+scholarly communication.
+
+- Free software: Revised BSD license
+- Documentation: https://inveniosoftware.github.io/idutils/.
+
+## Features
+
+- Validation and normalization of persistent identifiers.
+- Detection of persistent identifier scheme.
+- Generation of resolving links for persistent identifiers.
+- Supported schemes: ISBN10, ISBN13, ISSN, ISTC, DOI, Handle, EAN8, EAN13, ISNI
+  ORCID, ARK, PURL, LSID, URN, Bibcode, arXiv, PubMed ID, PubMed Central ID,
+  GND, SRA, BioProject, BioSample, Ensembl, UniProt, RefSeq, GenBank/RefSeq, SWH,
+  OpenAlex, CSTR, RRID, RAiD.
+
+## Installation
+
+The IDUtils package is on PyPI so all you need is:
+
+```console
+$ pip install idutils
+```
diff --git a/README.rst b/README.rst
deleted file mode 100644
index c063362..0000000
--- a/README.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-..
-   SPDX-FileCopyrightText: 2015 CERN.
-   SPDX-License-Identifier: BSD-3-Clause
-
-   In applying this license, CERN does not waive the privileges and immunities
-   granted to it by virtue of its status as an Intergovernmental Organization
-   or submit itself to any jurisdiction.
-
-
-=======
-IDUtils
-=======
-
-.. image:: https://github.com/inveniosoftware/idutils/workflows/CI/badge.svg
-        :target: https://github.com/inveniosoftware/idutils/actions?query=workflow%3ACI
-
-.. image:: https://img.shields.io/coveralls/inveniosoftware/idutils.svg
-        :target: https://coveralls.io/r/inveniosoftware/idutils
-
-.. image:: https://img.shields.io/github/tag/inveniosoftware/idutils.svg
-        :target: https://github.com/inveniosoftware/idutils/releases
-
-.. image:: https://img.shields.io/pypi/dm/idutils.svg
-        :target: https://pypi.python.org/pypi/idutils
-
-.. image:: https://img.shields.io/github/license/inveniosoftware/idutils.svg
-        :target: https://github.com/inveniosoftware/idutils/blob/master/LICENSE
-
-
-Small library for validating and normalising persistent identifiers used in
-scholarly communication.
-
-* Free software: Revised BSD license
-* Documentation: https://idutils.readthedocs.io.
-
-Features
-========
-
-- Validation and normalization of persistent identifiers.
-- Detection of persistent identifier scheme.
-- Generation of resolving links for persistent identifiers.
-- Supported schemes: ISBN10, ISBN13, ISSN, ISTC, DOI, Handle, EAN8, EAN13, ISNI
-  ORCID, ARK, PURL, LSID, URN, Bibcode, arXiv, PubMed ID, PubMed Central ID,
-  GND, SRA, BioProject, BioSample, Ensembl, UniProt, RefSeq, GenBank/RefSeq, SWH,
-  OpenAlex, CSTR, RRID, RAiD.
-
-Installation
-============
-
-The IDUtils package is on PyPI so all you need is:
-
-.. code-block:: console
-
-    $ pip install idutils
diff --git a/docs/Makefile b/docs/Makefile
deleted file mode 100644
index 43f3caf..0000000
--- a/docs/Makefile
+++ /dev/null
@@ -1,192 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  applehelp  to make an Apple Help Book"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-	@echo "  coverage   to run coverage check of the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cookiecutterproject_name.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cookiecutterproject_name.qhc"
-
-applehelp:
-	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
-	@echo
-	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
-	@echo "N.B. You won't be able to view it unless you put it in" \
-	      "~/Library/Documentation/Help or install it in your application" \
-	      "bundle."
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/cookiecutterproject_name"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cookiecutterproject_name"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-coverage:
-	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
-	@echo "Testing of coverage in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/coverage/python.txt."
-
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..700af6d
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,25 @@
+<!--
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+-->
+
+# API Reference
+
+::: idutils.detectors
+    options:
+      filters:
+        - "!.*"
+        - "^detect_identifier_schemes$"
+
+::: idutils.validators
+    options:
+      filters:
+        - "!.*"
+        - "^is_"
+
+::: idutils.normalizers
+    options:
+      filters:
+        - "!.*"
+        - "^normalize_"
+        - "^to_url$"
+
diff --git a/docs/changelog.md b/docs/changelog.md
new file mode 100644
index 0000000..a1f9eb2
--- /dev/null
+++ b/docs/changelog.md
@@ -0,0 +1,5 @@
+<!--
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+-->
+
+--8<-- "CHANGES.md"
diff --git a/docs/conf.py b/docs/conf.py
deleted file mode 100644
index 68b681b..0000000
--- a/docs/conf.py
+++ /dev/null
@@ -1,317 +0,0 @@
-# SPDX-FileCopyrightText: 2015, 2016 CERN.
-# SPDX-FileCopyrightText: 2022 Graz University of Technology.
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# In applying this license, CERN does not waive the privileges and immunities
-# granted to it by virtue of its status as an Intergovernmental Organization
-# or submit itself to any jurisdiction.
-
-"""Sphinx configuration."""
-
-import sphinx.environment
-from docutils.utils import get_source_line
-
-from idutils import __version__
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
-
-# Do not warn on external images.
-suppress_warnings = ["image.nonlocal_uri"]
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.coverage",
-    "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The encoding of source files.
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
-project = "IDUtils"
-copyright = "2016, CERN"
-author = "Invenio Software Collaboration"
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-
-# The full version, including alpha/beta/rc tags.
-release = __version__
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = "en"
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = []
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
-# -- Options for HTML output ----------------------------------------------
-html_theme = "alabaster"
-
-html_theme_options = {
-    "description": "Small library for validating and normalising persistent "
-    "identifiers used in scholarly communication.",
-    "github_user": "inveniosoftware",
-    "github_repo": "idutils",
-    "github_button": False,
-    "github_banner": True,
-    "show_powered_by": False,
-    "extra_nav_links": {
-        "idutils@GitHub": "http://github.com/inveniosoftware/idutils",
-        "idutils@PyPI": "http://pypi.python.org/pypi/idutils/",
-    },
-}
-
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",
-        "searchbox.html",
-        "donate.html",
-    ]
-}
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-# html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-# html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-# html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_domain_indices = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-# html_search_scorer = 'scorer.js'
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "idutils_namedoc"
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
-    # Latex figure (float) alignment
-    #'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "idutils.tex", "idutils Documentation", "Invenio Software", "manual"),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "idutils", "idutils Documentation", [author], 1)]
-
-# If true, show URL addresses after external links.
-# man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "idutils",
-        "IDUtils Documentation",
-        author,
-        "idutils",
-        "Small library for validating and normalising persistent identifiers used in scholarly communication.",
-        "Miscellaneous",
-    ),
-]
-
-# Documents to append as an appendix to all manuals.
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-# texinfo_no_detailmenu = False
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"<name>": ("https://docs.python.org/", None)}
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..0488e09
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,5 @@
+<!--
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+-->
+
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/custom-schemes.md b/docs/custom-schemes.md
new file mode 100644
index 0000000..f454ef0
--- /dev/null
+++ b/docs/custom-schemes.md
@@ -0,0 +1,10 @@
+<!--
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+-->
+
+# How to add your own schemes
+
+::: idutils.ext
+    options:
+      filters:
+        - "!^_"
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..b1260b5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,5 @@
+<!--
+SPDX-FileCopyrightText: 2026 California Institute of Technology.
+-->
+
+--8<-- "README.md"
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index eee7916..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-..
-   SPDX-FileCopyrightText: 2015-2018 CERN.
-   SPDX-FileCopyrightText: 2018 Alan Rubin.
-   SPDX-License-Identifier: BSD-3-Clause
-
-   In applying this license, CERN does not waive the privileges and immunities
-   granted to it by virtue of its status as an Intergovernmental Organization
-   or submit itself to any jurisdiction.
-
-.. currentmodule:: idutils
-
-Small library for validating and normalising persistent identifiers used in
-scholarly communication.
-
-* Free software: Revised BSD license
-* Documentation: https://idutils.readthedocs.io.
-
-Features
-========
-
-- Addition of custom schemes supporting all features of predefined schemes
-- Validation and normalization of persistent identifiers.
-- Detection of persistent identifier scheme.
-- Generation of resolving links for persistent identifiers.
-- Supported schemes: ISBN10, ISBN13, ISSN, ISTC, DOI, Handle, EAN8, EAN13, ISNI
-  ORCID, ARK, PURL, LSID, URN, Bibcode, arXiv, PubMed ID, PubMed Central ID,
-  GND, SRA, BioProject, BioSample, Ensembl, UniProt, RefSeq, Genome Assembly,
-  GEO, ArrayExpress.
-
-Installation
-============
-
-The IDUtils package is on PyPI so all you need is:
-
-.. code-block:: console
-
-    $ pip install idutils
-
-
-API
-===
-
-.. automodule:: idutils
-   :members: is_isbn10, is_isbn13, is_isbn, is_issn, is_istc, is_doi, is_handle, is_ean8, is_ean13, is_ean, is_isni, is_orcid, is_purl, is_url, is_lsid, is_urn, is_ads, is_arxiv_post_2007, is_arxiv_pre_2007, is_arxiv, is_pmid, is_pmcid, is_gnd, is_sra, is_bioproject, is_biosample, is_ensembl, is_uniprot, is_refseq, is_genome, is_geo, is_arrayexpress_array, is_arrayexpress_experiment, detect_identifier_schemes, normalize_doi, normalize_handle, normalize_ads, normalize_orcid, normalize_gnd, normalize_pmid, normalize_arxiv, normalize_pid, to_url
-
-.. include:: ../CHANGES.rst
-
-.. include:: ../CONTRIBUTING.rst
-
-
-How to add your own schemes
-===========================
-
-.. automodule:: idutils.ext
-   :members:
-
-
-License
-=======
-
-.. include:: ../LICENSE
-
-.. include:: ../AUTHORS.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index c037791..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1 +0,0 @@
--e .[docs,tests]
diff --git a/idutils/detectors.py b/idutils/detectors.py
index fd6ec69..d063661 100644
--- a/idutils/detectors.py
+++ b/idutils/detectors.py
@@ -26,7 +26,8 @@
 def detect_identifier_schemes(val):
     """Detect persistent identifier scheme for a given value.
 
-    .. note:: Some schemes like PMID are very generic.
+    !!! note
+        Some schemes like PMID are very generic.
     """
     schemes = []
     scheme_validators = IDUTILS_PID_SCHEMES + custom_schemes_registry().pick_scheme_key(
diff --git a/idutils/ext.py b/idutils/ext.py
index 4d234ce..d9141b2 100644
--- a/idutils/ext.py
+++ b/idutils/ext.py
@@ -8,38 +8,39 @@
 """Extension class to collect and register new schemes via entrypoints.
 
 In order to define your own custom schemes you can use the following entrypoint to
-register them
+register them:
 
-.. code-block:: python
+```python
+[options.entry_points]
+idutils.custom_schemes =
+    my_new_scheme = my_module.get_scheme_config_func
+```
 
-    [options.entry_points]
-    idutils.custom_schemes =
-        my_new_scheme = my_module.get_scheme_config_func
-
-The entry point ``'my_new_scheme = my_module.get_scheme_config_func'`` defines an entry
-point named ``my_new_scheme`` pointing to the function ``my_module.get_scheme_config_func``
+The entry point `'my_new_scheme = my_module.get_scheme_config_func'` defines an entry
+point named `my_new_scheme` pointing to the function `my_module.get_scheme_config_func`
 which returns the config for your new registered scheme.
 
 That function must return a dictionary with the following format:
 
-.. code-block:: python
-
-    def get_scheme_config_func():
-        return {
-            # See examples in `idutils.validators` file.
-            "validator": lambda value: True else False,
-            # Used in `idutils.normalizers.normalize_pid` function.
-            "normalizer": lambda value: normalized_value,
-            # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
-            "filter": ["list_of_schemes_to_filter_out"],
-            # Used in `idutils.normalizers.to_url` function.
-            "url_generator": lambda scheme, normalized_pid: "normalized_url",
-        }
+```python
+def get_scheme_config_func():
+    return {
+        # See examples in `idutils.validators` file.
+        "validator": lambda value: True else False,
+        # Used in `idutils.normalizers.normalize_pid` function.
+        "normalizer": lambda value: normalized_value,
+        # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
+        "filter": ["list_of_schemes_to_filter_out"],
+        # Used in `idutils.normalizers.to_url` function.
+        "url_generator": lambda scheme, normalized_pid: "normalized_url",
+    }
+```
 
 Each key is optional and if not provided a default value is defined in
 `idutils.ext._set_default_custom_scheme_config()` function.
 
-Note: You can only add new schemes but not override existing ones.
+!!! note
+    You can only add new schemes but not override existing ones.
 """
 
 import importlib.metadata as m
diff --git a/idutils/normalizers.py b/idutils/normalizers.py
index c85e81c..0461208 100644
--- a/idutils/normalizers.py
+++ b/idutils/normalizers.py
@@ -234,13 +234,16 @@ def normalize_pid(val, scheme):
 def to_url(val, scheme, url_scheme="http"):
     """Convert a resolvable identifier into a URL for a landing page.
 
-    :param val: The identifier's value.
-    :param scheme: The identifier's scheme.
-    :param url_scheme: Scheme to use for URL generation, 'http' or 'https'.
-    :returns: URL for the identifier.
+    Args:
+        val: The identifier's value.
+        scheme: The identifier's scheme.
+        url_scheme: Scheme to use for URL generation, 'http' or 'https'.
 
-    .. versionadded:: 0.3.0
-       ``url_scheme`` used for URL generation.
+    Returns:
+        URL for the identifier.
+
+    !!! info "New in version 0.3.0"
+        `url_scheme` used for URL generation.
     """
     pid = normalize_pid(val, scheme)
     landing_urls = IDUTILS_LANDING_URLS
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..e320848
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: 2026 California Institute of Technology.
+
+site_name: IDUtils
+site_description: Small library for validating and normalising persistent identifiers used in scholarly communication.
+site_url: https://inveniosoftware.github.io/idutils
+repo_url: https://github.com/inveniosoftware/idutils
+repo_name: inveniosoftware/idutils
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - search.highlight
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: true
+            show_root_heading: true
+            heading_level: 2
+
+nav:
+  - Home: index.md
+  - API Reference: api.md
+  - Custom Schemes: custom-schemes.md
+  - Changelog: changelog.md
+  - Contributing: contributing.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      base_path: ["."]
+      check_paths: true
+  - toc:
+      permalink: true
diff --git a/pyproject.toml b/pyproject.toml
index 26010bb..390379c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@
 [project]
 name = "idutils"
 description = "Small library for persistent identifiers used in scholarly communication."
-readme = "README.rst"
+readme = "README.md"
 requires-python = ">=3.9"
 license = "BSD-3-Clause"
 authors = [
@@ -28,13 +28,15 @@ dynamic = ["version"]
 Repository = "https://github.com/inveniosoftware/idutils"
 
 [project.optional-dependencies]
-docs = []
+docs = [
+    "zensical",
+    "mkdocstrings[python]",
+]
 tests = [
   "pytest-black-ng>=0.4.0",
   "pytest-cache>=1.0",
   "pytest-invenio>=1.4.0",
   "pytest-runner>=2.6.2",
-  "sphinx>=4.5",
 ]
 
 [build-system]
@@ -56,6 +58,6 @@ profile = "black"
 add_ignore = ""
 
 [tool.pytest.ini_options]
-addopts = '--black --isort --pydocstyle --doctest-glob="*.rst" --doctest-modules --cov=idutils --cov-report=term-missing'
+addopts = '--black --isort --pydocstyle --doctest-modules --cov=idutils --cov-report=term-missing'
 testpaths = "tests idutils"
 live_server_scope = "module"
diff --git a/run-tests.sh b/run-tests.sh
index 2b0e3a2..4c80b0b 100755
--- a/run-tests.sh
+++ b/run-tests.sh
@@ -9,5 +9,4 @@ set -o errexit
 # Quit on unbound symbols
 set -o nounset
 
-python -m sphinx.cmd.build -qnNW docs docs/_build/html
 python -m pytest