docx: Full re-write of the Concourse site using MkDocs

[kcbimonte]

BLUF

As a Concourse Contributor, I want to modernize the Concourse docs using MkDocs, so that I can lower the barrier of entry for contributing new information.

Task List

Current task list:

• Move all existing files to .old
• Create skeletons for all pages
• Create redirects for all pages
• Transfer all docs information over
• Transfer all blog information over
• Determine how to display schemas
• Determine how to create homepage
• Update CI to support mkdocs (could use mkdocs gh-deploy --force) for ease of use

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: kcbimonte / name: Kevin C. Bimonte (0bce221, 0f26112, 0f42b40, 1454cb9, 16ef467, 174b223, 1867a3f, 19ba8c6, 276b027, 2c464fa, 43926e1, 43987fa, 4e63c7f, 543816e, 594a04f, 667b407, 67898ad, 6973d93, 6a9b697, 6c97125, 6f2e25d, 7065f5f, 804eb4c, 919cc05, 951cf3c, 9802b31, 9e6459c, 9f21f20, b005cb4, b1d3f24, b1d8a94, b6706f8, b7040ce, ba1ead9, bf876b3, c1d4705, c241e79, c5fb02b, cff2c03, dd5f741, e74d09b, e943759, f1f727a, f77f1b1)

[taylorsilva]

This just came across my feed: https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/

Some interesting tidbits:

• Mkdocs is unmaintained (?). Last release is August 2024 and master branch has received very few commits. I did not notice this before.
• Material for MkDocs is now in maintenance mode and the team behind it started zensical as a successor to mkdocs

I don't think we should try switching to their thing now. I think making this jump, booklit to Mkdocs, is a good first step. Then we can possibly look at moving over to Zensical. They mention they're putting significant effort into the mkdocs -> zensical migration path.

[kcbimonte]

Yup, just saw that as well and was going to suggest a slight pause on this to see how this whole Zensical thing played out before going any further.

[kcbimonte]

Ok so holiday update. I think I've transferred over all docs content so sanity checks are appreciated.

I've moved onto to Blog content. Most Blog content is easy since it's already Markdown, but it's just getting all the images and breaks in place before calling it done.

Also, apparently the Blog was previously on Medium as I was looking for original authors for Blog Posts. There are some missing posts that I've started to add back (2 in 2017 so far).

• https://medium.com/concourse-ci