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 (0f42b40, 1454cb9, 16ef467, 1867a3f, 19ba8c6, 276b027, 2c464fa, 43926e1, 43987fa, 543816e, 594a04f, 667b407, 67898ad, 6973d93, 6c97125, 6f2e25d, 7065f5f, 804eb4c, 919cc05, 9802b31, b005cb4, b1d3f24, b1d8a94, b6706f8, ba1ead9, bf876b3, c241e79, c5fb02b, cff2c03, dd5f741, 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.

[taylorsilva]

Looking great!

If the cookies are not accepted, can we still show a download button that links to https://github.com/concourse/concourse/releases/latest
Maybe have it render beside the Quickstart button, "Download Latest Release" or something.

---

Nit-pick thing:
Can this hover effect be turned off? It appears over some links, like the quickstart button on the home page

I noticed it on the schema links as well, though that actually looks useful for quickly seeing the underlying reference:

[kcbimonte]

Yes! It can be fully customized, I just put it on for the full site to play with it.

Adding a Button that just takes you to the releases page should be simple enough. I'll play around with the layout of it.

[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