Skip to content
Snippets Groups Projects

Set up new website structure with MkDocs

    • Closed Issue created by Moul @moul

    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:
    • 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?)
    • Activate search engine

    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
    • 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
    52 of 53 checklist items completed · Edited
    To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information

    Child items ...

    • Activity

    Please register or sign in to reply