[Do not merge] Mkdocs material prototype

[willingc]

Folks this uses mkdocs to create a skeleton site using the mkdocs material theme.

It's Python and supports Jinja, CSS, JS changes if desired. The landing page can be customized. It handles localization well and has excellent docs. FastAPI and a bunch of startups and projects are using.

To build if getting this branch:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

[BethanyG]

Ooh. Nice! Somehow, I missed MKdocs when listing out potential frameworks.

[tiidadavena]

That's amazing! Because it addresses the issues #3 and #4 - beacause MKDocs uses Material UI, that is already a11y safe.

[tiidadavena]

And it's quite easy to add the PyLadies theme colors: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/?h=color#custom-colors

[trallard]

That's amazing! Because it addresses the issues #3 and #4 - beacause MKDocs uses Material UI, that is already a11y safe.

I think MKDocs provides a good foundation for accessible sites as it inherits some of the a11y affordances from Material UI at a component level (I am cautious when saying a tool is accessible, as I have yet to come across such a tool, even more so since a11y is a continuous effort). That said, the last time I did some a11y checks on MKDocs, the theme had several WCAG violations and some blockers for full keyboard navigation/AT support (perhaps a couple of months ago).
Unfortunately, this will be the case for most frameworks; some will be more or less accessible, but it is one vertical/decision criterion we have to keep in mind when choosing our stack.
Then, as we work with designers and through the implementation phase, we also have opportunities to include some remediation within our control.

[tiidadavena]

That's amazing! Because it addresses the issues #3 and #4 - beacause MKDocs uses Material UI, that is already a11y safe.

I think MKDocs provides a good foundation for accessible sites as it inherits some of the a11y affordances from Material UI at a component level (I am cautious when saying a tool is accessible, as I have yet to come across such a tool, even more so since a11y is a continuous effort). That said, the last time I did some a11y checks on MKDocs, the theme had several WCAG violations and some blockers for full keyboard navigation/AT support (perhaps a couple of months ago). Unfortunately, this will be the case for most frameworks; some will be more or less accessible, but it is one vertical/decision criterion we have to keep in mind when choosing our stack. Then, as we work with designers and through the implementation phase, we also have opportunities to include some remediation within our control.

Totally agree with you. 👏🏻 MK Docs is a great start, but we need extra caution to review WCAG guidelines and adding/reviewing accessbility issues.

[willingc]

The specific theme used here, MkDocs Material, would likely be responsive to PRs for accessibility. mkdocs, the tool itself may have issues. Also worth noting is that MkDocs Material theme has overrides for pretty much everything that can be done with JS and CSS so we have the option to do that if needed.

[trallard]

The specific theme used here, MkDocs Material, would likely be responsive to PRs for accessibility.

I agree, though IIRC correctly, there were a number of those that would be pretty significant (re-effort), so while it is reasonable to try to make PRs to improve a11y, I also would like to be mindful of folks' time and contribution to the PyLadies website redesign effort. I do not think ensuring that MKDocs meets WCAG should be tied to the PyLadies website work, as there is potential to drag the latter over a long while.

MkDocs Material theme has overrides for pretty much everything that can be done with JS and CSS so we have the option to do that if needed.

This is what I had in mind regarding remediation work on our end; there is a lot we can still do to work on a11y of the PyLadies website regardless.