Page MenuHomePhabricator

Create POC using mkdocs
Closed, ResolvedPublic

Description

Make a POC of static site using mkdocs as the site generator.

Related Objects

Event Timeline

bd808 changed the task status from Open to In Progress.Oct 26 2021, 8:22 PM
bd808 moved this task from Backlog to Implementation on the Wikimedia-Developer-Portal board.
bd808 changed the task status from In Progress to Stalled.Nov 3 2021, 8:47 PM
bd808 moved this task from In Dev/Progress to Needs Review/Feedback on the User-bd808 board.

Proof of concept at https://github.com/bd808/developer-portal. Implements the basics of the content creation workflow outlined in T276708#7360487. Awaiting peer review of that part of the design before deciding what to do next.

The creation workflow looks good to me! Using YAML files to store documentation links makes it easy to reuse links across the Dev Portal, allowing us to create tailored views for various user types and interests.

bd808 changed the task status from Stalled to Open.Nov 16 2021, 11:52 PM

General POC has been approved in team discussion. Additional investigation is needed for integration with TWN.

Let's call the POC {{Done}}.

We have a plan for using mkdocs as the base technology for generating the static site. The https://squidfunk.github.io/mkdocs-material/ theme will provide client side search support and general site theme templates. The https://mkdocs-macros-plugin.readthedocs.io/en/latest/ plugin will provide tools for simplifying repetitive authoring tasks via jinja template macros and filters. Per T295832 we will develop a local mkdocs plugin for the l10n/i18n workflows which borrows ideas from https://github.com/mondeja/mkdocs-mdpo-plugin/ with changes designed to ease integration with translatewiki.net.