docs: align GitHub Pages source with MkDocs deployment

[t-uda]

Summary

The published docs are not currently being served from the MkDocs site generated into gh-pages. GitHub Pages is configured to use the repository root on main, so /docs/ is being rendered by Jekyll instead.

Current state (confirmed on March 26, 2026)

• GitHub Pages config: build_type: legacy, source.branch: main, source.path: /
• Published site URL: https://t-uda.github.io/ellphi/
• origin/gh-pages does contain the MkDocs Material site at repository root
• But https://t-uda.github.io/ellphi/docs/ is serving Jekyll-generated HTML from main/docs/index.md, not the MkDocs build

Evidence

• The deployed /docs/ HTML includes meta name="generator" content="Jekyll v3.10.0"
• The deployed /docs/ page leaves MkDocs-only Markdown extensions unprocessed, e.g. the attribute-list tail after the logo image
• The deployed /docs/ page uses the plain GitHub Pages stylesheet (/ellphi/assets/css/style.css) instead of MkDocs Material assets
• origin/gh-pages:index.html is a MkDocs page (mkdocs-1.6.1, mkdocs-material-9.7.1)

Why this matters

• The docs workflow can pass while the public docs still show the wrong renderer
• Styling/navigation/search are not the MkDocs site we intended to publish
• The current setup is confusing because docs.yml deploys to gh-pages, but GitHub Pages is not reading from gh-pages

Follow-up

• Decide the intended public docs URL structure (/ellphi/ vs /ellphi/docs/)
• Align GitHub Pages settings with the actual deployment method
• Prefer a single source of truth for docs publishing:
  • either serve the MkDocs build from gh-pages / GitHub Actions
  • or stop deploying MkDocs to gh-pages and make the docs build strategy match the main-branch Pages setup
• Verify that docs assets, theme, and intra-doc links render correctly after the switch

Related files

• mkdocs.yml
• .github/workflows/docs.yml
• docs/index.md