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 (37c8f84, 3e959aa, 5261f05, 71864b4, e46f3bd)

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

And just like that, all tasks are complete with all content transferred. @taylorsilva this should have all content presently in main (including #576).

External to this repo, tasks still remaining include shutting down the existing Blog site (maybe putting a redirect) and updating the link in the Resource Types Website repo.

Let me know if you want me to delete to .old folder containing all the previous content or not

[taylorsilva]

THANK YOU! I'm going to dive into this now. There is a lot of extra external work that needs to happen, but I'll probably merge this and figure it out. This is great timing too because I'm going to start cutting v8 of Concourse. Probably going to try and have v8 and the website refresh go out together. Will be a great way to kick-off this new year!

Massive kudos to you for making this happen. Can't express my appreciation enough 🙏

[taylorsilva]

I'm going to merge this. There is some stuff to change, but it's all small stuff that I can fix as I go through things. I'm going to flesh out the home page a bit too.

Thank you so much for doing this massive migration. This should make it much easier for others to contribute to the docs and for us to add to as well.