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, b1d3f24, 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.

[taylorsilva]

As is tradition, after wrangling my python env, I got the site to build locally. I love the current homepage setup, it looks good so far!

---

I prefer your initial attempt for displaying schemas. I agree about the noisy feel. At least for me, I think it comes from mix of bolding and inline code blocks. Played around with it a bit and I liked it most when everything was wrapped in code tags.

I think wrapping the keywords in code tags also helps suggest that it's a keyword that you use in your pipeline.

I also like how the link highlighting appears when the whole word is in the code tag:

Here's the diff I made locally:

diff --git a/docs/docs/pipelines/index.md b/docs/docs/pipelines/index.md
index 1f3daf2e..fa30757c 100644
--- a/docs/docs/pipelines/index.md
+++ b/docs/docs/pipelines/index.md
@@ -15,24 +15,24 @@ declarative [YAML files](../config-basics.md#intro-to-yaml) which conform to the

 ## `pipeline` schema

-??? warning "**jobs**: `[`**[job](../jobs.md#job-schema)**`]`"
+??? warning "**`jobs`**: [`[job]`](../jobs.md#job-schema)"

     A set of [jobs](../jobs.md) for the pipeline to continuously schedule. At least one job is required for
     a pipeline to be valid.

-??? info "**resources**: `[`**resource**`]`"
+??? info "`resources`: [`[resource]`]()"

     A set of resources for the pipeline to continuously check.

-??? info "**resource_types**: `[`**resource_type**`]`"
+??? info "`resource_types`: [`[resource_type]`]()"

     A set of resource types for resources within the pipeline to use.

-??? info "**var_sources**: `[`**var_source**`]`"
+??? info "`var_sources`: [`[var_source]`]()"

     A set of Var sources for the pipeline to use.

-??? info "**groups**: `[`**group**`]`"
+??? info "`groups`: `[group]`"

     A list of job groups to use for organizing jobs in the web UI.

@@ -103,7 +103,7 @@ declarative [YAML files](../config-basics.md#intro-to-yaml) which conform to the
             Depending on how it's used, *, {, and } have special meaning in YAML, and may need to be quoted
             (as was done in the all job above)

-??? info "**display**: **display_config**"
+??? info "`display`: `display_config`"

     !!! warning "Experimental Feature"

It would also be nice if the font size was the same between the paragraph text and the schema blocks.

Current:

Same size:

I'm guessing the font size is smaller because these are meant to be like "nested" bits of info.

Those are my thoughts so far. It's look good!