Migrate documentation to MkDocs

.github/ISSUE_TEMPLATE/config.yml

@@ -1,7 +1,7 @@
 blank_issues_enabled: true
 contact_links:
   - name: '🛟 Help on Slack'
-    url: https://slack.wiremock.org/
+    url: https://wiremock.org/docs/community/slack
     about: |
       You can ask questions on the community Slack in the '#help' or '#help-contributing' channels.
       Please do not raise GitHub issues for questions.

.github/workflows/ci.yml

@@ -36,6 +36,23 @@ jobs:
         run: bundle exec jekyll build --config '_config.yml' --baseurl "${{ steps.pages.outputs.base_path }}"
         env:
           JEKYLL_ENV: development
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.5.1
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Build the docs
+        run: mkdocs build
+
       - name: Build 2.x with Jekyll
         # Outputs to the './_site' directory by default
         run: |
@@ -52,6 +69,7 @@ jobs:
 #        with:
 #          directory: ./_site
 #          enforce_https: false
-      - name: Upload artifact
-        # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v1
+
+#      - name: Upload artifact
+#        # Automatically uploads an artifact from the './_site' directory by default
+#        uses: actions/upload-pages-artifact@v1

.github/workflows/deploy-mkdocs-preview.yaml

@@ -0,0 +1,111 @@
+name: Deploy Preview to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main", "mkdocs"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: "true"
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
+        with:
+          ruby-version: '2.7.6' # Not needed with a .ruby-version file
+          bundler: '2.4.10'
+          bundler-cache: false # runs 'bundle install' and caches installed gems automatically
+          cache-version: 3 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name:  Update RubyGems and Co
+        run: gem update --system
+      - name: Install Ruby Bundles
+        run: bundle install
+
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --config '_config.yml,_config-oleg-nenashev.yml' --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.5.1
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Build the docs site
+        run: mkdocs build
+
+      - name: Build 2.x with Jekyll
+        # Outputs to the './_site' directory by default
+        run: |
+          cd .submodules/wiremock.org-2.x
+          bundle exec jekyll build --config '../../_config.yml,../../_config-2.x.yml,../../_config-oleg-nenashev-2.x.yml' --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      #- name: Build 3.x with Jekyll
+        # We use the same as the root build, but with additional config
+      #  run: |
+      #    bundle exec jekyll build --config '_config.yml,_config-3.x.yml,_config-oleg-nenashev-3.x.yml' --baseurl "${{ steps.pages.outputs.base_path }}"
+      #  env:
+      #    JEKYLL_ENV: production
+      - name: Deploy version branches to the website
+        run: |
+          ruby .scripts/merge-sitemaps.rb
+          mkdir _site/2.x
+          cp -R .submodules/wiremock.org-2.x/tmp/site_2x/* _site/2.x/
+          mkdir -p _site/docs
+          cp -R _site-docs/* _site/docs/
+          mkdir -p _site/3.x/docs
+          cp -R _site-docs/* _site/3.x/docs/
+# TODO: Uncomment when cleaned up (if ever)
+#      - name: Validate HTML and links
+#        uses: anishathalye/proof-html@v2
+#        with:
+#          directory: ./_site
+#          enforce_https: false
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v1
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/deploy.yaml

@@ -1,4 +1,4 @@
-name: Deploy Jekyll site to Pages
+name: Deploy to GitHub Pages
 
 on:
   # Runs on pushes targeting the default branch

.gitignore

@@ -18,3 +18,8 @@ main.css
 /tmp
 
 **/.DS_Store
+
+# MkDocs
+/temp_dir/
+/_site-docs/
+.cache

.gitmodules

@@ -2,3 +2,7 @@
 	path = .submodules/wiremock.org-2.x
 	url = https://github.com/wiremock/wiremock.org.git
 	branch = 2.x
+[submodule "extra_sass/vendor/breakpoint"]
+	path = extra_sass/vendor/breakpoint
+	url = https://github.com/at-import/breakpoint.git
+	branch = main

.scripts/merge-sitemaps.rb

@@ -1,5 +1,5 @@
 # Merges sitemaps, to be called from the root directory
-header, footer, content_main, content_2x, content_3x = []
+header, footer, content_main, content_2x, content_docs = []
 
 File.open( "_site/sitemap.xml", 'r' ) do |f1|
     content_main = (IO.readlines f1)
@@ -13,14 +13,14 @@
     content_2x.slice!( -1 ) 
 end
 
-File.open( "./tmp/site_3x/sitemap.xml", 'r' ) do |f3|
-    content_3x = (IO.readlines f3)
-    content_3x.slice!( 0..11 )
-    content_3x.slice!( -1 ) 
+File.open( "./_site-docs/sitemap.xml", 'r' ) do |f3|
+    content_docs = (IO.readlines f3)
+    content_docs.slice!( 0..11 )
+    content_docs.slice!( -1 ) 
 end
 
 File.open( "_site/sitemap.xml", 'w' ) do |f4|
-    f4.write ( header + content_main + content_2x + content_3x + footer ).join()
+    f4.write ( header + content_main + content_docs + content_2x + footer ).join()
 end
 
 

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "search.exclude": {
+      "**/wiremock.org-2.x/**": true
+    }
+  }

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to the WireMock website
 
-[![a](https://img.shields.io/badge/slack-Join%20us-brightgreen?style=flat&logo=slack)](https://slack.wiremock.org/)
+[![a](https://img.shields.io/badge/slack-Join%20us-brightgreen?style=flat&logo=slack)](https://wiremock.org/docs/community/slack)
 
 All contributions to the website are welcome!
 Whether you develop new documentation, want to share your use-case,
@@ -32,21 +32,55 @@ that is included as a submodule and build by the CD flow.
 To update the documentation, submit pull requests against the branch,
 and they will be included into the main release line.
 
-## Editing
+## Documentation
+
+The documentation is built using 
+[MkDocs](https://www.mkdocs.org/),
+[mkdocs-multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin/tree/main) and
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material)
+
+### Building
+
+The documentation website uses some sources from submodules,
+so make sure to pull them before building the site.
+
+Requirements:
+
+- Python and PiP, recent versions
+- Submodules are pulled in your local git clone
+
+```shell
+pip install -r requirements.txt
+mkdocs build
+```
+
+### Local development
+
+To serve the site locally:
+
+```shell
+mkdocs serve
+```
+
+> **WARNING:** Note that the multi-repo site maybe quite slow during the
+> first build and then during the rebuilds.
+> You can disable it for local development just by commenting out the plugin section in `mkdocs.yml`
+> The same goes to the SCSS compiler which cannot be disabled.
+> There are [jdoiro3/mkdocs-multirepo-plugin #129](https://github.com/jdoiro3/mkdocs-multirepo-plugin/issues/129)
+> and [orzih/mkdocs-extra-sass-plugin #6](https://github.com/orzih/mkdocs-extra-sass-plugin/issues/6)
+> submitted to improve the developer experience.
 
 ### Code Tabs
 
 To reduce vertical space and provide examples by multiple technology stacks,
 we added support for code tabs in the documentation.
-It is a custom Jekyll plugin providing the `{% codetabs %}` macro in Markdown.
 See the example here: https://wiremock.org/docs/stubbing/ .
 
 Example:
 
 ```markdown
-    {% codetabs %}
 
-    {% codetab JSON %}
+=== "JSON"
 
     ```json
     {
@@ -64,9 +98,8 @@ Example:
     }
     ```
 
-    {% endcodetab %}
 
-    {% codetab Java %}
+=== "Java"
 
     ```java
     @Test
@@ -77,16 +110,13 @@ Example:
     }
     ```
 
-    {% endcodetab %}
-
-    {% endcodetabs %}
 ```
 
-
 When editing the existing code, make sure to also copy-edit text around it to ensure consistency.
-Example of a patch: [PR #165 - Code tabs in stubbing overview](https://github.com/wiremock/wiremock.org/pull/165).
 
-## Preparing the developer environment
+## Main site
+
+### Preparing the developer environment
 
 The website is powered by Jekyll, and hence the Ruby developer environment is needed.
 It is recommended to use `Ruby 2.7.6` because of the known compatibility issues between recent Jekyll version and Ruby 3.
@@ -98,7 +128,7 @@ Prerequisites:
 - Ruby 2.7.6
 - Bundler 2.4.10
 
-## Building the website
+### Building the website
 
 ```bash
 # Install the dependencies including Jekyll
@@ -110,7 +140,7 @@ bundle exec jekyll build --config '_config.yml'
 
 Note that `_config_preview.yml' is used to disable analytics in the deployed versions
 
-## Running the website locally
+### Running the website locally
 
 You can run the website locally and get live preview of the changes
 on the website and in the documentation contents.

README.md

@@ -3,6 +3,10 @@
 Repository that stores the WireMock website and documentation.
 Powered by Jekyll and Markdown.
 The website uses the [Minimal Mistakes Theme](https://mmistakes.github.io/minimal-mistakes/) for Jekyll.
+The documentation is built using
+[MkDocs](https://www.mkdocs.org/),
+[mkdocs-multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin/tree/main) and
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material)
 
 ## Contributing
 

_config-oleg-nenashev-2.x.yml

@@ -0,0 +1,2 @@
+url: "https://oleg-nenashev.github.io/wiremock.org"
+baseurl: "wiremock.org/2.x/"

_config-oleg-nenashev-3.x.yml

@@ -0,0 +1,2 @@
+url: "https://oleg-nenashev.github.io/"
+baseurl: "wiremock.org/3.x"

_config-oleg-nenashev.yml

@@ -0,0 +1,21 @@
+url: "https://oleg-nenashev.github.io/"
+baseurl: "wiremock.org/"
+
+# Analytics
+analytics:
+  google:
+      # gtag
+      id: "G-F923LHBYYT"
+
+  # MS Clarity
+  clarity:
+      enabled: true
+  vwo:
+      enabled: true
+
+# TODO: Update plugin code to support more fancy navigation
+breadcrumbs:
+  root:
+    hide: true
+    image: true
+    imagePath: /wiremock.org/images/logos/doc-sections/home.svg

_config.yml

@@ -104,6 +104,7 @@ author:
 include:
     - .htaccess
     - _pages
+    - _redirects
 exclude:
     - vendor/
     - "*.sublime-project"
@@ -130,6 +131,8 @@ exclude:
     - tmp
     # Served via symbolic links
     - .submodules
+    # Delegated to MkDocs
+    - _docs
 keep_files:
     - .git
     - .svn
@@ -241,7 +244,7 @@ pageEditPrefix: https://github.com/wiremock/wiremock.org/edit/main/
 grpc_extension_version: 0.4.0
 
 community_slack:
-  join_url: https://slack.wiremock.org/
+  join_url: /docs/community/slack
 
 # Default link for wiremock signup button in header
 # This can be overridden in pages using frontmatter start_link variable