feat(docs): migrate docs to docusaurus

.github/ISSUE_TEMPLATE/release-tracker.md

@@ -1,14 +1,13 @@
 ---
 name: Release tracker
 about: Create an issue to track release progress
-
 ---
 
-<!-- < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < ☺ 
-v                            ✰  Thanks for opening an issue! ✰    
+<!-- < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < ☺
+v                            ✰  Thanks for opening an issue! ✰
 v    Before smashing the submit button please review the template.
-v    Word of caution: poorly thought-out proposals may be rejected 
-v                     without deliberation 
+v    Word of caution: poorly thought-out proposals may be rejected
+v                     without deliberation
 ☺ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  -->
 
 ## Milestones
@@ -32,7 +31,7 @@ versions of ibc-go to guarantee that no regression is introduced -->
 
 ### Other testing
 
-## Migration 
+## Migration
 
 <!-- Link to migration document -->
 
@@ -42,7 +41,7 @@ versions of ibc-go to guarantee that no regression is introduced -->
 
 - [ ] Bump [go package version](https://github.com/cosmos/ibc-go/blob/main/go.mod#L3).
 - [ ] Change all imports starting with `github.com/cosmos/ibc-go/v{x}` to `github.com/cosmos/ibc-go/v{x+1}`.
-- [ ] Branch off main to create release branch in the form  of `release/vx.y.z` and add branch protection rules.
+- [ ] Branch off main to create release branch in the form of `release/vx.y.z` and add branch protection rules.
 - [ ] Add branch protection rules to new release branch.
 - [ ] Add backport task to [`mergify.yml`](https://github.com/cosmos/ibc-go/blob/main/.github/mergify.yml)
 - [ ] Upgrade ibc-go version in [ibctest](https://github.com/strangelove-ventures/ibctest).
@@ -59,8 +58,13 @@ versions of ibc-go to guarantee that no regression is introduced -->
   - Remove any tags that might not be recommended anymore.
 - [ ] Update the list of [supported release lines in README.md](https://github.com/cosmos/ibc-go#releases), if necessary.
 - [ ] Update docs site:
-  - [ ] Add new release branch to [`docs/versions`](https://github.com/cosmos/ibc-go/blob/main/docs/versions) file.
-  - [ ] Add `label` and `key` to `versions` array in [`config.js`](https://github.com/cosmos/ibc-go/blob/main/docs/.vuepress/config.js#L62).
+  - [ ] If the release is occurring on the main branch, on the latest version, then run `npm run docusaurus docs:version vX.Y.Z` in the `docs/` directory. (where `X.Y.Z` is the new version number)
+  - [ ] If the release is occurring on an older release branch, then make a PR to the main branch called `docs: new release vX.Y.Z` doing the following:
+    - [ ] Update the content of the docs found in `docs/versioned_docs/version-vx.y.z` if needed. (where `x.y.z` is the previous version number)
+    - [ ] Update the version number of the older release branch by changing the version number of the older release branch in:
+      - [ ] In `docs/versions.json`.
+      - [ ] Rename `docs/versioned_sidebars/version-vx.y.z-sidebars.json`
+      - [ ] Rename `docs/versioned_docs/version-vx.y.z`
 - [ ] Bump ibc-go version in [cosmos/interchain-accounts-demo repository](https://github.com/cosmos/interchain-accounts-demo) and create a tag.
 - [ ] Update the [compatibility test matrices](https://github.com/cosmos/ibc-go/tree/main/.github/compatibility-test-matrices):
   - Add the new release.
@@ -71,7 +75,7 @@ versions of ibc-go to guarantee that no regression is introduced -->
 - [ ] After changes to docs site are deployed, check [ibc.cosmos.network](https://ibc.cosmos.network) is updated.
 - [ ] Open issue in [SDK tutorials repo](https://github.com/cosmos/sdk-tutorials) to update tutorials to the released version of ibc-go.
 
-____
+---
 
 #### For Admin Use
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,7 @@ closes: #XXXX
 
 ### Commit Message / Changelog Entry
 
-```bash
+```text
 type: commit message
 ```
 

.github/workflows/check-docs.yml

@@ -1,26 +1,27 @@
+# This check-docs workflow was created based on instructions from:
+# https://docusaurus.io/docs/deployment
 name: Check docs build
 # This workflow runs when a PR is labeled with `docs`
 # This will check if the docs build successfully by running `npm run build`
 on:
   pull_request:
+    branches:
+      - main
     paths:
       - './docs'
 
 jobs:
   check-docs-build:
-    if: ${{ github.event.label.name == 'docs' }}
-
     name: Check docs build
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          persist-credentials: false
-          fetch-depth: 0
+          node-version: 18
+          cache: npm
 
-      - name: Install dependencies and build docs 🧱
-        run: |
-          cd docs
-          npm install
-          npm run build
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build

.github/workflows/deploy-docs.yml

@@ -1,43 +1,37 @@
-name: Deploy docs
-# This job builds and deploys documenation to github pages.
-# It runs on every push to main with a change in the docs folder.
+# This deploy-docs workflow was created based on instructions from:
+# https://docusaurus.io/docs/deployment
+name: Deploy to GitHub Pages
+
 on:
   workflow_dispatch:
   push:
     branches:
       - main
-      - "release/**"
     paths:
       - "docs/**"
       - .github/workflows/deploy-docs.yml
 
-permissions:
-  contents: read
-
 jobs:
-  build-and-deploy:
-    permissions:
-      contents: write # for JamesIves/github-pages-deploy-action to push changes in repo
+  deploy:
+    name: Deploy to GitHub Pages
     runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/cosmos/website-deployment
     steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          ref: "main"
-          persist-credentials: false
-          fetch-depth: 0
-          path: "."
+          node-version: 18
+          cache: npm
 
-      - name: Build 🔧
-        run: |
-          git config --global --add safe.directory /__w/ibc-go/ibc-go
-          make build-docs LEDGER_ENABLED=false
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
 
-      - name: Deploy 🚀
-        uses: JamesIves/[email protected]
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
         with:
-          branch: gh-pages
-          folder: ~/output
-          single-commit: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./build

.github/workflows/link-check-config.json

@@ -4,7 +4,17 @@
       "pattern": "(localhost)"
     }
   ],
+  "replacementPatterns": [
+    {
+      "pattern": "(^\\/(architecture|event)[^#]*)(#.*|$)",
+      "replacement": "$1.md$3"
+    },
+    {
+      "pattern": "^(\\/|@site\\/)",
+      "replacement": "{{BASEURL}}/docs/"
+    }
+  ],
   "retryOn429": true,
   "retryCount": 3,
   "fallbackRetryDelay": "10s"
-}
+}

.github/workflows/link-check.yml

@@ -1,10 +1,14 @@
 name: Check Markdown links
-on: pull_request
+on:
+  pull_request:
+    paths:
+      - "**.md"
+      - "!.github/**"
 jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
-      with:
-        config-file: '.github/workflows/link-check-config.json'
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: '.github/workflows/link-check-config.json'

.github/workflows/markdown-lint.yml

@@ -0,0 +1,25 @@
+name: Markdown Lint
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "**.md"
+      - "!.github/**"
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: tj-actions/changed-files@v39
+      id: changed-files
+      with:
+        files: '**/*.md'
+        separator: ","
+    - uses: DavidAnson/markdownlint-cli2-action@v12
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        separator: ","

.markdownlint-cli2.jsonc

@@ -0,0 +1,12 @@
+// This file is used by markdownlint-cli2 to configure the linting process
+// in conjunction with .markdownlint.jsonc.
+{
+  "ignores": [
+    "docs/node_modules/**",
+    ".github",
+    "**/CHANGELOG.md",
+    "vendor/**",
+    "e2e/vendor/**",
+    "modules/capability/vendor/**"
+  ]
+}

.markdownlint.jsonc

@@ -1,10 +1,17 @@
 {
   "default": true,
+  "MD003": { "style": "atx" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md003---heading-style
+  "MD004": { "style": "dash" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md004---unordered-list-style
+  "MD007": { "indent": 4 }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007---unordered-list-indentation
+  "MD009": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md009---trailing-spaces
+  "MD010": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md010---hard-tabs
   "MD013": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
   "MD024": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content
   "MD025": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md025---multiple-top-level-headings-in-the-same-document
   "MD029": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix
   "MD033": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033---inline-html
   "MD036": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md036---emphasis-used-instead-of-a-heading
-  "MD041": false // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-in-a-file-should-be-a-top-level-heading
-}
+  "MD041": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-in-a-file-should-be-a-top-level-heading
+  "MD049": { "style": "asterisk" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md049---emphasis-style-should-be-consistent
+  "MD050": { "style": "asterisk" } // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md050---strong-style-should-be-consistent
+}

CODE_OF_CONDUCT.md

@@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo
 
 Examples of behavior that contributes to creating a positive environment include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 

CONTRIBUTING.md

@@ -25,7 +25,7 @@ New features or improvements should be written in an issue using the [new featur
 
 ### Architecture Decision Records (ADR)
 
-When proposing an architecture decision for the ibc-go, please create an [ADR](./docs/architecture/README.md) so further discussions can be made. We are following this process so all involved parties are in agreement before any party begins coding the proposed implementation. Please use the [ADR template](./docs/architecture/adr-template.md) to scaffold any new ADR. If you would like to see some examples of how these are written refer to ibc-go's [ADRs](./docs/architecture/). Solidified designs that will be implemented in ibc-go (and do not have a spec). They should document the architecture that will be built. Most design feedback should be gathered before the initial draft of the ADR. ADR's can/should be written for any design decisions we make which may be changed at some point in the future.
+When proposing an architecture decision for the ibc-go, please create an [ADR](./docs/architecture/README.md) so further discussions can be made. We are following this process so all involved parties are in agreement before any party begins coding the proposed implementation. Please use the [ADR template](./docs/architecture/adr.template.md) to scaffold any new ADR. If you would like to see some examples of how these are written refer to ibc-go's [ADRs](./docs/architecture/). Solidified designs that will be implemented in ibc-go (and do not have a spec). They should document the architecture that will be built. Most design feedback should be gathered before the initial draft of the ADR. ADR's can/should be written for any design decisions we make which may be changed at some point in the future.
 
 ### Participating in discussions
 
@@ -57,7 +57,7 @@ Please make sure to check out our [Pull request guidelines](./docs/dev/pull-requ
 - [Project structure](./docs/dev/project-structure.md)
 - [Develoment setup](./docs/dev/development-setup.md)
 - [Go style guide](./docs/dev/go-style-guide.md)
-- [Documentation guidelines](./docs/DOCS_GUIDELINES.md)
+- [Documentation guide](./docs/README.md)
 - [Writing tests](./testing/README.md)
 - [Pull request guidelines](./docs/dev/pull-requests.md)
 - [Release process](./docs/dev/release-management.md)

Makefile

@@ -138,38 +138,15 @@ go.sum: go.mod
 ###                              Documentation                              ###
 ###############################################################################
 
-update-swagger-docs: statik
-	$(BINDIR)/statik -src=docs/client/swagger-ui -dest=docs/client -f -m
-	@if [ -n "$(git status --porcelain)" ]; then \
-        echo "\033[91mSwagger docs are out of sync!!!\033[0m";\
-        exit 1;\
-    else \
-        echo "\033[92mSwagger docs are in sync\033[0m";\
-    fi
-.PHONY: update-swagger-docs
-
 godocs:
 	@echo "--> Wait a few seconds and visit http://localhost:6060/pkg/github.com/cosmos/cosmos-sdk/types"
 	godoc -http=:6060
 
-# This builds a docs site for each branch/tag in `./docs/versions`
-# and copies each site to a version prefixed path. The last entry inside
-# the `versions` file will be the default root index.html.
 build-docs:
-	@cd docs && \
-	while read -r branch path_prefix; do \
-		echo "building branch $${branch}" ; \
-		(git clean -fdx && git reset --hard && git checkout $${branch} && npm install && VUEPRESS_BASE="/$${path_prefix}/" npm run build) ; \
-		mkdir -p ~/output/$${path_prefix} ; \
-		cp -r .vuepress/dist/* ~/output/$${path_prefix}/ ; \
-		cp ~/output/$${path_prefix}/index.html ~/output ; \
-		cp ~/output/$${path_prefix}/404.html ~/output ; \
-	done < versions ;
-
-view-docs: 
-		@cd docs && \
-    npm install && npm run serve
+	@cd docs && npm ci && npm run build
 
+serve-docs:
+	@cd docs && npm run serve
 
 changelog:
 	docker run --rm -v "$$(pwd)"/.git:/app/ -v "$$(pwd)/cliff.toml":/app/cliff.toml orhunp/git-cliff:latest --unreleased --tag $(tag)
@@ -307,12 +284,15 @@ format:
 .PHONY: format
 
 docs-lint:
-	markdownlint . --fix
+	markdownlint-cli2 "**.md"
+
+docs-lint-fix:
+	markdownlint-cli2-fix "**.md"
 
-docs-lint-changed:
-	./scripts/linting/lint-changed-md-files.sh
+docs-link-check:
+	find . -name 'node_modules' -prune -o -name '*.md' -print0 | xargs -0 -n1 markdown-link-check --config ./.github/workflows/link-check-config.json
 
-.PHONY: lint lint-fix docs-lint docs-lint-changed
+.PHONY: lint lint-fix docs-lint docs-lint-fix docs-link-check
 
 ###############################################################################
 ###                                Protobuf                                 ###