Set up new website structure with MkDocs

MkDocs

• https://www.mkdocs.org/
• https://github.com/mkdocs/mkdocs
• https://github.com/mkdocs/catalog
• https://repology.org/badge/vertical-allrepos/python:mkdocs.svg
• https://repology.org/badge/vertical-allrepos/mkdocs.svg
• Used by substrate-interface, Textual, Pipx, and Ruff
• Allows to build markdown docs from the repository
• Very simple static framework website written in Python

Tasks

MkDocs initial set-up

• Read the User Guide
• pyproject.toml: Introduce mkdocs dependencies in doc group
• Set-up initial project mkdocs.yml
• Move md files to default docs directory
• Set symlinks for changelog, contributing(, readme)
• Choose theme: material
  • Set favicon
  • Night/day switch
• Set-up navigation with current content

Deployment

poetry install --only docs
poetry run mkdocs build -d public

• Support website/documentation per releases and development one with Mike:
  • Drop-down support to switch between ie v0.12 and main
  • Mike git commits changes to pages branch. Add .gitlab-ci.yml on this branch to publish the website and its’s multiple versions (no need schedule)
  • On pages branch: basic .gitlab-ci.yml to copy the content into a public directory and publish to GitLab Pages via a pages job
  • GitLab Pages implementation, will come later in the Community edition
  • https://pypi.org/project/lightweight-versioned-gitlab-pages/
  • https://stackoverflow.com/questions/55596789/deploying-gitlab-pages-for-different-branches/58915486#58915486
  • Version path /0.12 issue with GitLab/Nginx deployment for hard-coded links
    • We should always use a relative link as stated in: GH issue, MkDocs doc
    • not [](/path.md) (absolute breaks version). [](path.md) if in the same directory otherwise [](./path.md)
• only on main branch and tag? Set RELEASE variable to 0.12 or to 0.20-dev.
• how to handle the coverage and website deployments?
  • mkdocs-coverage
  • website job needs: tests:3.12:cov job artifact
  • https://stackoverflow.com/a/64008569
  • handle coverage display on main branch, don’t display Coverage tab when on release branch? Always display.
• Protect pages branch
• Update coverage badge link to website coverage path
• Adapt GitLab Pages deployment: Ansible role, now from Silkaj repository
  • NixOS configuration works with three paths clients/python/silkaj

Document contribution

• How to install mkdocs, serve the docs, build locally
• Link mkdocs, material, mike, coverage, gitlab … docs

Set up structure and use existing content

• Fix mkdocs serve warnings
  • Update links in release notes, contributing(, readme)
  • README.md CONTRIBUTING.md: update links to the URL of this website
• Create index/main page inspired from Textual one
• Clean and proofread current documentation
  • move container usage (and poetry installation) to install section? Advanced installation, somehow contributing stuff. Nope?
• enable syntax highlight, fix code block where we don’t want it
• enable code block copy where needed
• Id anchors in changelog
  • Move CHANGELOG.md to docs/changelog.md, with the { id=0.11.0 } it might get ugly looking at it on GitLab. Same for CONTRIBUTING.md, Drop them from GitLab "syntax", not sure for the logos
  • create CHANGELOG.md and CONTRIBUTING.md referring to those pages on the website
• structure docs folder: usage, contributing
• Introduce mdformat-mkdocs to format with four spaces bullet points
• Keep mike prefix_path to public, serving to http://localhost:8000/pages (needs doc precision) or select version.json, latest, and 0.12 items in the artifact
• Integrate generated coverage with mkdocs-coverage
• Changelog with mkdocs-gitlab-plugin:
  • mkdocs-gitlab-plugin improvements (#494)
• Blog tab containing releases notes:
  • Move releases_notes directory in docs/blog directory
  • Set up built-in mkdocs-material blog (not mkdocs-blogging-plugin)
    • Yaml frontmatter kept: mdformat-frontmatter
  • Add excerpts
  • Add authors
    • Local author profile picture not available from archive, category slug, set up url formats
    • Issue to display local avatar: relative not working between mkdocs-material and mike
      • Found a "dirty" hack which works with mike, but not when serving with mkdocs, to be investigated further later
  • Set up categories/tags for the releases and RC testing to separated them
• Add badge to readme and GitLab repo badges
• disable fonts coming from Google gstatic
• Retrieve valuable content from current and Vue websites (no real value left: intro text maybe?)

Archive current websites

• Archive two other websites repositories
• https://git.duniter.org/websites/silkaj_website
• https://git.duniter.org/websites/doc_silkaj

Set them as archives. Visible in the archived tab. Redirect, saying that the website is now in Silkaj repository

Thank Manutopik for the Vue website solution which wasn’t retained. I prefer MkDocs: it’s written in Python, it’s simple, (no JS), I have full control over it

Finalization

• Clean local history
• push changes
• protect pages branch
• Check the CI manages to publish on pages branch
  • a commit is added to pages branch once a .py or docs/**.md file changes. When there is no changes, the changelog has its date updated.
  • schedule pipeline won’t have the requirements to trigger website job, since no .py nor .md file was changed. Let’s see how it goes. There is no website job, and pages branch does not get a new "empty" commit. Let’s not create lot’s of useless commits on pages branch.
• Remove commented line in CI, so it only pushed from main branch
• Review changes
• Push clean pages branch
• Switch Infra config of https://silkaj.duniter.org to this website: admins/duniter-infra!101