Ah yes, I see the issue. When using MyST, we need to explicitly tell …

…Sphinx to use the README.md as the index page. Let's modify the `docs/conf.py`:

```python:docs/conf.py
# ... existing config ...

# Add README.md as the index page
root_doc = 'index'  # or 'contents' in older versions
```

And create/modify `docs/index.rst` to include the README:

```rst:docs/index.rst
.. include:: ../README.md
   :parser: myst_parser.sphinx_

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   examples
   modules
```

This should:
1. Use the README.md as the main content of the index page
2. Keep the table of contents below it
3. Properly render any mermaid diagrams in the README

The current page at https://endolith.github.io/elsim/index.html shows just the default Sphinx index template because it's not finding/including the README content.

docs/conf.py

@@ -91,3 +91,6 @@ def setup(app):
 
 # Add this to enable regular markdown mermaid syntax
 myst_fence_as_directive = ["mermaid"]
+
+# Add README.md as the index page
+root_doc = 'index'  # or 'contents' in older versions

docs/index.rst

@@ -1,13 +1,12 @@
-.. elsim documentation master file, created by
-   sphinx-quickstart on Wed Feb 15 16:14:19 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-.. mdinclude:: ../README.md
+   examples
+   modules