Skip to content

Set up new website structure with MkDocs

MkDocs

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:
  • 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?
  • 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:
    • had to find the gitlab_links plugins name in setup.py, report that it would be great to have it in the readme: contribute
    • Would be great to being able to link other projects such as DuniterPy
  • Blog tab containing releases notes:
    • Move releases_notes directory in docs/blog directory
    • Set up built-in mkdocs-material blog (not mkdocs-blogging-plugin)
    • 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

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
  • delete pages branch
  • push changes
  • Check the CI manages to publish on pages branch
  • Remove commented line in CI, so it only pushed from main branch
  • protect pages branch
  • Switch Infra config of https://silkaj.duniter.org to this website.
Edited by Moul
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information