Migrate documentation to MkDocs

oleg-nenashev commented 11 months ago

For #24 . This is a big WiP prototype

Closes:

Closes #24
Closes #28
Closes https://github.com/wiremock/wiremock.org/issues/169

Other key features

Search
Better Mobile navigation

Preview

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

TODOs

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

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

Details: Contributor Guide

tomakehurst commented 11 months ago

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 commented 9 months ago

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

oleg-nenashev commented 6 months ago

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

tomakehurst commented 6 months ago

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 commented 6 months ago

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 https://github.com/wiremock/wiremock.org/pull/228#issuecomment-2091052013, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAW4RIA2MGOHBEV5M5WTKKLZAJVO3AVCNFSM6AAAAAA7TRMNNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJRGA2TEMBRGM . You are receiving this because you were assigned.Message ID: @.***>

tomakehurst commented 6 months ago

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 commented 6 months ago

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 https://github.com/wiremock/wiremock.org/pull/228#issuecomment-2091120047, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAW4RIDCPBAACES6LJTL2VLZAJZMZAVCNFSM6AAAAAA7TRMNNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJRGEZDAMBUG4 . You are receiving this because you were assigned.Message ID: @.***>

wiremock / wiremock.org