ministryofjustice / mkdocs-tech-docs-template

Build flexible technical documentation with a GOV.UK style using MkDocs

This project will not be developed further. See govuk-eleventy-plugin for an alternative.

MkDocs Tech Docs Template

Build flexible technical documentation with a GOV.UK style using Material for MkDocs.

Visit the documentation website for more details.

This template is under construction. It has not passed an accessibility audit yet, so we currently do not recommend using it.

mkdocs-tech-docs-template's Issues

Accessibility: Fix View Source and Edit Page icons

The attached icons do not meet accessibility standards due to their low colour contrast. A ratio of at least 3:! is needed according to the Web Content Accessibility Guidelines

Preferably, we should change the icons to text that simply says 'View Source' and 'Edit This Page'. We could also include this text with the icons but in that case we should still change the colour of them.

Accessibility: Dark mode headings

As a user of dark mode
I want the colour of headings to not be black when dark mode is on
So that I can see page and section headings while in dark mode.

User access removed, access is now via a team

Hi there

The user benmillar-cgi either had direct member access to the repository or had direct member access and access via a team.

Access is now only via a team.

If the user was already in a team, then their direct access to the repository has been removed.

If the user was not in a team, then the user will have been added to an automated generated team named repository-name-<read|write|maintain|admin>-team and their direct access to the repository has been removed.

The list of Org teams can be found at https://github.com/orgs/ministryofjustice/teams or https://github.com/orgs/moj-analytical-services/teams.

The user will have the same level of access to the repository via the team.

The first user added to a team is made a team maintainer, this enables that user to manage the users within the team.

Users with admin access are added to the admin team as a team maintainer.

If you have any questions, please contact us in #ask-operations-engineering on Slack.

This issue can be closed.

Update CONTRIBUTE with more instructions

Updating the CSS

CI/CD pipelines

Linting

Publish to Github Pages

Build and push to PyPi

Spacing around active items if using sections, but not tabs

There seems to be a slightly strange (to my eye) spacing, around the active items in the left hand navigation menu. This can be seen here next to the "Getting started" item, where the vertical blue bar is very close to the text:

Adding this CSS seems to sort it:

.md-nav__item--section > .md-nav > .md-nav__list > .md-nav__item--active {
    margin-left:  0;
    padding-left: 3px;
}

I've done this at https://github.com/uktrade/stream-zip/blob/e09ac51c3f21938d2d9b18478892d4f8caaac47e/docs/assets/dit-extra.css, where its effect can currently be seen at https://stream-zip.docs.data.trade.gov.uk/getting-started/ and in the below screenshot

After a bit of trial and error, I think it's due to using navigation.sections, but not navigation.tabs as features in mkdocs.yml, as is done in https://github.com/uktrade/stream-zip/blob/5cf1edec090f8abb912f05df610bef0aaecae534/mkdocs.yml

Publish alternate tab-less version of theme

Publish alternate tab-less version of theme to different location to check that changes are compatible and to show case to users:

Accessibility: Fix truncated text

As a user of a 13-inch laptop screen
I want to be able to read headings in full
So that I know what they say

At 400% zoom on a 13-inch screen, page headings become truncated (see attached). If possible, we should wrap the text instead or find an alternative way to avoid truncating.

Accessibility: Revise/remove image alt-text

Change the aria label for the gov logo (attached) so that instead of 'MkDocs Tech Docs Template' it just says 'logo'

Also remove the alt-text from homepage image of laptops (also attached) - it currently says ‘services’ but since it is cosmetic it shouldn’t have any alt-text.

Consider integrating `termynal`

tech-docs quite often have code snippets embedded. It can be useful to render this as an animated terminal.

termynal is a nice lightweight component that can provide this whilst failing gracefully for anyone with javascript disabled.

An example of it embedded within material-for-mkdocs is viewable throughout the typer-cli docs.

Rename to govuk-mkdocs-material

See #42
Save repo to data engineering account on pypi

Add client-side search support

https://www.mkdocs.org/dev-guide/themes/#search-and-themes

Create github action to build and push package to pypi when merging with main

Display which repos are using the mkdocs-tech-docs-template

Create github action to lint project when raising pull request

Might be better to wait until data-engineering customised version of megalinter is available

Selecting heading in TOC highlights the topic above

Selecting a heading in the TOC highlights the topic above. For example if I select "Preview" then "Configuration" is highlighted:

Ensure longer headers in table of contents spill more gracefully

#45 and #48 means that longer subheadings don't carry over nicely:

A temporary work-around is to use short titles. A better solution would be to make the titles spill over the next line? Or perhaps this is a good way of forcing people to use more succinct titles?

Accessibility: Add yellow highlight to selected text

To benefit users and to be consistent with other Gov.uk sites, and the current TDT, if possible we should highlight selected text in yellow. See attached.

Evaluate mkdocs for technical documentation

See

• #56

Update footer to display images on all pages

Footer images are only displayed on home pages not other pages. I have raised ticket: squidfunk/mkdocs-material#4893

add transport font as an option

Migrate to gov github org?

Should we migrate to a cross government Github repo e.g.:

• https://github.com/x-govuk
• https://github.com/ukgovdatascience

Clean up extra.css file

• Create variables for the GDS colours
• Ensure colour settings are defined using the GDS colours instead of being hard-coded
• Use rem instead of px (https://austingil.com/px-or-rem-in-css/#:~:text=Pixels%20are%20an%20absolute%20unit,the%20equivalent%20of%2024%20pixels)

Make blue border content-width when tabs are disabled?

The blue border is content-width when tabs are missing in GOV.UK websites e.g. https://www.blog.gov.uk/:

However the blue border is full-width when tabs are missing in mkdocs-tech-docs-template:

Should we update to match with GOV.UK?

Update css to handle merged TOC with navigation bar

If you merge the TOC with navigation bar the titles are bold and there is a left line:

Which needs to be modified

convert packaging to poetry?

Convert packaging to poetry similar to other MoJ Data Engineering projects e.g. mojap-metadata

Accessibility: homepage headings

As a user of the MkDocs TDT
I want to reformat the homepage to use headings
So that screen readers will properly recognise them.

In the attached screenshot, 'Build flexible technical documentation with a GOV.UK style', 'Restrictions' and 'Prototype' should all be headings rather than admonitions.

Accessibility: Make dark mode work with tabbing

Currently, tabbing and using enter or spacebar does not work with the dark mode setting as it uses radio buttons (using arrow button does work sometimes, however). If we could switch the setting from radio buttons to a toggle button, for example, that should fix it.