Skip to content

Switch from GitHub to MkDocs Material for documentation#1086

Merged
troglobit merged 20 commits into
mainfrom
doc
Jul 30, 2025
Merged

Switch from GitHub to MkDocs Material for documentation#1086
troglobit merged 20 commits into
mainfrom
doc

Conversation

@troglobit

@troglobit troglobit commented Jul 29, 2025

Copy link
Copy Markdown
Contributor

Description

Adopt MkDocs Material as documentation framework for the Infix User's Guide. As part of the investigation towards #633, multiple frameworks were evaluated and MkDocs was chosen based on:

Great care has been taken to ensure a reader using the GitHub front-end is not detrimentally affected, although some features like image formatting and positioning may look "a bit odd". The primary target for publishing now is MkDocs.

When this PR has been accepted and merged, work can continue on #633 to build a stand-alone version for inclusion in the Infix images for target.

Checklist

Tick relevant boxes, this PR is-a or has-a:

  • Bugfix
    • Regression tests
    • ChangeLog updates (for next release)
  • Feature
    • YANG model change => revision updated?
    • Regression tests added?
    • ChangeLog updates (for next release)
    • Documentation added?
  • Test changes
    • Checked in changed Readme.adoc (make test-spec)
    • Added new test to group Readme.adoc and yaml file
  • Code style update (formatting, renaming)
  • Refactoring (please detail in commit messages)
  • Build related changes
  • Documentation content changes
    • ChangeLog updated (for major changes)
  • Other (please describe): Documentation Framework

Footnotes

  1. Nothing wrong with ReST, it's a great markup language actually, but we've long since decided on Markdown as the primary language for documentation. ↩

@troglobit troglobit added this to the Infix v25.08 milestone Jul 29, 2025
@troglobit troglobit requested a review from jovatn July 29, 2025 15:04
@troglobit troglobit self-assigned this Jul 29, 2025
Copilot AI review requested due to automatic review settings July 29, 2025 15:04
@troglobit troglobit added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 29, 2025
Copilot AI reviewed Jul 29, 2025
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR migrates documentation from GitHub's native rendering to MkDocs Material as the primary documentation framework for the Infix User's Guide. The change aims to provide better publishing options including web versioning and PDF generation while maintaining GitHub Markdown compatibility.

Key changes:

  • Introduces MkDocs Material configuration with orange branding theme
  • Restructures documentation with new navigation hierarchy and cross-references
  • Splits large documents into focused sections (e.g., separating upgrade content from system.md)
  • Adds GitHub Actions workflow for automated documentation deployment

Reviewed Changes

Copilot reviewed 35 out of 39 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
mkdocs.yml Main MkDocs configuration defining site structure, theme, and plugins
doc/upgrade.md New dedicated document for system upgrade procedures (moved from system.md)
doc/index.md New introduction page replacing introduction.md with enhanced structure
doc/scripting-*.md Split scripting content into focused documents for different approaches
doc/templates/ PDF generation templates with custom styling
doc/extra.css Custom CSS for orange branding theme
Multiple doc/*.md Updated cross-references, formatting, and content organization
.github/workflows/docs.yml New CI workflow for automated documentation deployment

Comment thread mkdocs.yml Outdated
Comment thread mkdocs.yml Outdated
Comment thread mkdocs.yml Outdated
@troglobit troglobit force-pushed the doc branch 2 times, most recently from 31a4255 to 2ab18ef Compare July 29, 2025 15:10
jovatn
jovatn approved these changes Jul 30, 2025
View reviewed changes

@jovatn jovatn left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great! LGTM!

@troglobit

troglobit commented Jul 30, 2025

Copy link
Copy Markdown
Contributor Author

Great! LGTM!

Thanks! I'll add the pipx instructions we talked about to the developer's guide, and look for a potential spot to pimp a link to the documentation, before I merge 😃👍

@troglobit troglobit force-pushed the doc branch 4 times, most recently from cbe24ef to 65ad226 Compare July 30, 2025 12:57
troglobit added 15 commits July 30, 2025 14:57
@troglobit
doc: initial support for MkDocs Material framework
9d91244 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: minor syntax changes/cleanup, rephrase + use admonitions
a491f2a 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: split system.md -> system.md + upgrade.md
c692c93 
This makes it a lot easier to find relevant information on how to
perform a system upgrade.  Further consolidation may come later.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: fix broken links, GitHub vs MkDocs autolinking
a66e000 
Note, this change breaks some links on GitHub due to the difference in
how MkDocs and GitHub implement "autolinking" and anchors.  Since the
idea is to make MkDocs our primary documentation framework, breaking
links on GitHub in favor of MkDocs is the best compromise.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: reformat eth-counters.md to a proper markdown table
c574f23 
This will be easier to typset also in the PDF generated version.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: minor cleanup, fix markdown syntax and admonitions
67838fa 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: refactor section 'Upgrading Packages'
238ea91 
Major overhaul and simplification of both language and structure to
improve accessibility and UX in new documentation framework.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: add versioning using "mike"
fdf1aae 
The Python tool 'mike'[1] helps manage multiple versions of MkDocs-powered
documentation.  Only required when building the kernelkit.org site docs!

For each new tag, that steps year or month, a new version of is created of
the documentation, in a separate sub-directory on the gh-pages branch.

Strategy - Version Grouping with Early Publishing:

- Extract YEAR.MONTH from tag
  E.g., v25.06.0-beta1, v25.06.0-rc1, v25.06.0, v25.06.1 → become version 25.06
- From first pre-release onwards:
  - v25.06.0-beta1 → creates docs version 25.06
  - v25.06.0-rc1 → updates docs version 25.06
  - v25.06.0 (GA) → updates docs version 25.06
  - v25.06.1 (patch) → updates docs version 25.06
- New major/minor series:
  - v25.07.0-beta1 → creates new docs version 25.07

Benefits:
 - Users get docs as soon as beta/rc is available
 - Patches update existing docs (logical since patches rarely change docs significantly)
 - Clean version grouping by YEAR.MONTH
 - Mike handles create vs update automatically

[1]: https://github.com/jimporter/mike

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: markdown syntax, whitespace cleanup, and admonitions
d1e7145 
Consistency between different sections in the documentation is critical.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: split scripting.md into multiple files
fcbd75a 
Way too long.  By splitting it in multiple files we can also user
simpler (shorter) headings, which makes navigation easier.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: minor, adjust image syntax and headings
b0adf85 
 - Consistent formatting of image formatting
 - Make container examples easier to see

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: initial support for pdf export at doc. generation
83f2c27 
 - custom cover page for pdf
 - Center and resize logo
 - Place slogan just below logo
 - Ensure all text on cover page is in matching grey

Please note, the mkdocs-to-pdf plugin works, but it has a bug in the
enumeration of sections.  We may need to fork it to make it work the
way users expect.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: retitle -> Device Discovery
f98b00f 
And make the ASCII image more generic to ease any branding work we may
need to do for certain customers later on.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: retitle ssh+sysrepocfg -> Legacy Scripting
90ec35c 
We want to discourage people to use sysrepocfg and instead move to use
NETCONF, or even better, RESTCONF.  When something's missing we should
add it to these two official, and standardized, interfaces.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: clarify sections and use "home styled" admonitions
5a339e4 
Files in doc/cli/*.md are used in and displayed as help text in the CLI
admin-exec level.  So we cannot use standard admonitions (yet) since the
terminal markdown converter (lowdown) doesn't support the syntax.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
troglobit added 5 commits July 30, 2025 14:58
@troglobit
doc: much improved disposition of navigation
dc8fc40 
Lot of work still remains, but this new disposition should serve as a
more representative template.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: collapse about + introduction into a single index.md
5b100fb 
In the spirit of my uni English teacher; "simplify, Simplify, SIMPLIFY!"
This commit collapses the About and Introduction into a single document,
doc/index.md.

Also, relocate the System Boot section to doc/boot.md, which we alrady
have and covers the initial bootloader part of it.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: theme & svg logo tweak, grey to slightly darker lines and font
ed5baf5 
This commits tweaks the material orange theme to use the exact color hue
of Jackys footies.  To match this and give a slightly better contrast we
also change Jacksy border and logo text color to a slightly darker tone.

The original logo.svg is retained for reference, the new logo is logo2,
which all the .png variants have now been updated to.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
doc: update developer's guide, how to build documentation
edc1346 
Tested successfully on one unsuspecting team member :-)

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit
Update link to (new) documentation and fix admonition
cf4a29d 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
@troglobit troglobit merged commit ce89499 into main Jul 30, 2025
4 of 6 checks passed
@troglobit troglobit deleted the doc branch July 30, 2025 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@jovatn jovatn jovatn approved these changes

Assignees

@troglobit troglobit

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

Infix v25.08

Development

Successfully merging this pull request may close these issues.

3 participants

@troglobit @jovatn