Migrate documentation to MkDocs

[oleg-nenashev]

For #24 . This is a big WiP prototype

Closes:

• Closes Move Documentation website to another documentation engine #24
• Closes Add a /community/Slack page #28
• Closes Publish WireMock 3 specification on the website #169

Other key features

• Search
• Better Mobile navigation

Preview

https://oleg-nenashev.github.io/wiremock.org/

TODOs

• Initial MkDocs setup
• Split and relocate images
• Move code tabs to the native engine
• Setup CI
• Setup staging site
• Fix redirects within docs
• Fix images
• Ensure section links and breadcrumbs work fine
• Fix sitemap generation for docs
• Fix Docs Landing page rendering or move it back to the Jekyll site
• Fix Header and Footer
• Add OpenGraph rendering
• Fix OpenAPI specification rendering and source it from the repo
• Fix version number rendering/propagation to MkDocs
• Move events pages to the new engine
• Move external resources to the new engine
• Configure Google Analytics
• Configure MS Clarity (Custom script needed)
• Align the header with the old website
• Move Support pages to the documentation engine
• Fix the docs site header on mobile screens

Production deployment TODO

• Update deployment pipelines to follow staging
• Update Google Analytics and Clarity tags

Submitter checklist

• The PR request is well described and justified, including the body and the references
• The PR title represents the desired changelog entry
• If the change against WireMock 2 functionality (incompatible with WireMock 3),
  it is submitted against the 2.x branch
• The repository's code style is followed (see the contributing guide)

Details: Contributor Guide

[tomakehurst]

Great progress so far.

A couple of bits of feedback:

• It would be great if the in-page nav was in a panel on the right rather than integrated into the LH nav.
• Would also be great to have a anchor links on the page titles (like you added to the current docs)

[tomakehurst]

Closing this as it's been merged and superseded via branching

[oleg-nenashev]

It was not merged BTW, an alternative implementation was done instead.
It's your decision tho

[tomakehurst]

We'll get there at some point in the next couple of months I think. Just hasn't been the bandwidth to get it over the line yet.

[oleg-nenashev]

Ack, thanks for the clarification! I remain available to help if any small changes are needed. I will probably take some parts of the implementation for the Gradle community subsite that basically has a similar Jekyll+MkDocs structure. So I will keep improving templates and layouts

…

On Thu, May 2, 2024, 18:53 Tom Akehurst ***@***.***> wrote: We'll get there at some point in the next couple of months I think. Just hasn't been the bandwidth to get it over the line yet. — Reply to this email directly, view it on GitHub <#228 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAW4RIA2MGOHBEV5M5WTKKLZAJVO3AVCNFSM6AAAAAA7TRMNNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJRGA2TEMBRGM> . You are receiving this because you were assigned.Message ID: ***@***.***>

[tomakehurst]

We've actually dropped Jekyll completely from it now on our branch. That was one of the reasons for delaying the switch i.e. the vestiges of Jekyll were still a pain to live with.

[oleg-nenashev]

I totally support that move. Thumbs up! :) In my case, it might have to live for some time, but hopefully not for long

…

On Thu, May 2, 2024 at 7:26 PM Tom Akehurst ***@***.***> wrote: We've actually dropped Jekyll completely from it now on our branch. That was one of the reasons for delaying the switch i.e. the vestiges of Jekyll were still a pain to live with. — Reply to this email directly, view it on GitHub <#228 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAW4RIDCPBAACES6LJTL2VLZAJZMZAVCNFSM6AAAAAA7TRMNNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJRGEZDAMBUG4> . You are receiving this because you were assigned.Message ID: ***@***.***>