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 (9802b31, f1f727a)

[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]

Determined how to do CI I believe. This will also clear out a bunch of junk from the gh-pages branch that shouldn't be there but is navigable:

• New build script: https://github.com/Aviator-Labs/docs-ci/blob/docs-rewrite/ci/build
• Example of routable less files: https://concourse-ci.org/less/base.less

[taylorsilva]

Looking at "Phased transition strategy" from https://zensical.org/compatibility/
I think we would need their project to reach "Phase 1b" before we could move ahead with using zensical because I think you mentioned we use some plugins.

[kcbimonte]

Definitely. The Blog Plugin is a big one for consolidation and unified search.

Tracking along with the API Docs convo under the Concourse repo (concourse/concourse#1122), there may be a plugin for OpenAPI docs for Zensical instead of just basic mkdocs-strings.

[kcbimonte]

Currently struggling on the best way to display the various schemas.

This was the first attempt which just feels too noisy.

Then moved onto something familiar to CF, but not exactly like, of using the property fields as headers. Also doesn't seem great and feel like you lose things

Moved onto putting it into a code block and trying to use annotations, but feels like it's hiding information.

If we wanted to replicate the existing feel, it'd have to be custom which kinda defeats the point of maintainability.

Super open to ideas at this point.