feat(docs): migrate docs to docusaurus (#4693)

* docs: migrate to docusaurus (#3511) The following stack was used: - Docusaurus 2 - tailwindcss - postcss Min required node version is: 16.14 --------- Co-authored-by: colin axnér <[email protected]> * merge: fixing conficts * merge: bringing back client docs * merge: removing versions again * merge: fix conflicts * fix: merge conflicts * fix: merge conflicts * fix: merge conflicts * docs: implement versioned documentation (#3577) * docs: workflow and linter improvements (#3805) * docs: added version 7.0.0 docs, need to check for bugs * docs: renamed the version to v7.0.0 * docs: added v6.1.0 * docs: added v5.3.0 * docs: added v4.4.0 * docs: updated the base url redirect, and version banners * docs: replaced 'Pre-requisites Readings' -> 'Pre-requisite readings' * docs: added missing ADRs to README.md * docs: added versioning info to README.md * docs: replaced '../../../../docs/architecture/adr-001-coin-source-tracing.md' -> '../../../architecture/adr-001-coin-source-tracing.md' * docs: updated the url of the 7.0.0 (latest) * docs: fixed all broken links * docs: updated 'make build-docs' command to use docusaurus * docs: Added a Links section to README.md * docs: updated code blocks in 02-integration.md to use docusaurus features as an example * docs: removed all TODOs from README.md * docs: updated the typical versioned docs tree in README.md * docs: made file naming section more precise * docs: updated README.md * docs: updated release-tracker.md * docs: removed search section from README.md * docs: updated release-management.md * docs: updated Makefile * docs: fixed more broken links * docs: updated workflows to only run when changes to main occur (not releases) * fix(ci): attempt to convert absolute urls to absolute filepaths in the ci * fix(ci): added '@site/' to ignorePatterns instead * imp(docs): removed wrong comment * fix(ci): fix markdown-link-check for docusaurus * docs: changed architecture links to absolute links * fix(ci): replace only affects architect and event links now * docs: fix broken more links * imp(ci): ignore http links in markdown-link-check replace statements * imp(ci): markdown-link-check should only run on modified md files * fix(ci): attempt to fix markdown-link-check * fix(ci): only check modified files for markdown-link-check * revert(ci): reverted link-check.yml to initial state * imp(ci): set link check timeout to 16 mins * imp(ci/link-check): link-check should ignore versioned_docs now * fix(ci/link-check): attempt to ignore files ending with '/' * docs: fixed broken link * docs: fixed broken link in RELEASES.md * fix(ci/link-check): config works now * refactor(ci/link-check): combined two regexp patterns into one in link-check config * fix(ci/link-check): config is good - attempt to fix the workflow * fix(ci/link-check): config is good - attempt to fix the workflow * fix(ci/link-check): added verbose mode * revert(ci/link-check): reverted workflow to initial state (not config) * nit: broke a link to test ci * revert(docs): fixed broken link * build(docs/deps): updated docusaurus to 2.4.1 * docs: replaced intro titles * docs: remove extra ')' * docs: wrapped some prerequisites in note * docs: replaces '::: tip' with ':::tip' * docs: replace '::: warning' with ':::warning' * docs: fix styling error * docs: readme updated * docs: removed all references to 'order:' frontmatter * docs: fixed list styling in transfer/state-transitions * docs: removed unneeded quotation * imp(docs): improved the markdownlint settings * imp(docs): improved the markdownlint settings * docs: ran markdownlint with the new config * docs: do not lint autogenerated CHANGELOG.md * docs: removed 'bash' from the codeblock in the PR template * docs: added '.github' to .markdownlintignore * imp(docs): added more comments to markdownlint config * docs: fixed incorrect category linking * docs: fixed indentation issue in fee middleware * imp(docs): added two more rules to markdownlint * docs: ran 'make docs-lint' * docs: made transfer the first app * docs: made transfer the first app in all versions * imp(makefile/docs): added link-check to makefile * docs: added back the spaces * docs: fixed a lint violation * docs: contents of DOCS_GUIDELINES.md have been merged with README.md * docs: ran markdownlint-cli * docs: fixed a lot of linting errors * docs: fixed a more linting errors * docs: fixed all linting errors * docs: corrected PR template's code box * imp(docs): add a new workflow for linting changed markdown files * docs: fixed linter violation * imp(docs): switch to using markdownlint-cli2 * revert(ci/markdown-lint): original state * imp(ci/markdown-lint): fix an error * imp(ci/markdown-lint): only runs on PRs which modify .md files * imp(ci/markdown-lint): only runs on PRs which modify .md files not in .github * docs: fixed broken link * imp(ci/link-check): this workflow only runs if a .md file has been modified * deps(docs): ran 'npm i --save @easyops-cn/docusaurus-search-local' * feat(docs): added local search bar * fix(docs): search bar highlight color is not buggy anymore * imp(docs): added term highlighting to search * fix: merge conflicts * docs: ran linter * refactor: removed markdownlint changes in this PR * refactor: removed markdownlint changes in this PR * refactor: removed linkcheck changes in this PR * revert: changes in PR template * revert: added swagger-docs thing back * revert: "revert: added swagger-docs thing back" This reverts commit f6cdcdb. * revert: "revert: changes in PR template" This reverts commit 5a23809. * revert: "refactor: removed linkcheck changes in this PR" This reverts commit b401b31. * revert: "refactor: removed markdownlint changes in this PR" This reverts commit eb31283. * revert: "refactor: removed markdownlint changes in this PR" This reverts commit d5b74e0. * add extra path to ignore * docs linting * Update docs/docs/01-ibc/09-roadmap.md Co-authored-by: Charly <[email protected]> --------- Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Charly <[email protected]> * feat: v7.3.x docs added * imp: improved Makefile for serving docs * imp: checked out some problematic files * fix: merge conflicts * imp(docs): added versioned docs for v6.2.x * ci: switched to docusaurus check and deploy workflows (#4688) * ci: switched to docusaurus check and deploy workflows * ci: added workflow_dispatch back to deploy-docs * imp(lint): ignores all changelogs now * imp: ran linter * imp(makefile): improved build-docs * fix(docs): broken links * imp: improved workflows around markdownlint * imp: improved workflows around markdownlint * imp(docs): added the new ibc assets * deps(docs): updated deps * style(docs): reorganized footer code * docs: fix cosmos-sdk broken links * imp(docs): removed link from the footer logo * imp(docs): improved footer * imp(docs): added a link to privacy policy * deps(docs): added 'npm run dev' script * imp(docs): apply review item * imp: ran 'make docs-lint' * imp: added 'make tag-docs-version' --------- Co-authored-by: colin axnér <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Charly <[email protected]>
cosmos · Sep 20, 2023 · d39a825 · d39a825
1 parent e647a2c
commit d39a825
Show file tree

Hide file tree

Showing 546 changed files with 40,990 additions and 19,416 deletions.
diff --git a/.github/ISSUE_TEMPLATE/release-tracker.md b/.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
 

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -15,7 +15,7 @@ closes: #XXXX
 
 ### Commit Message / Changelog Entry
 
-```bash
+```text
 type: commit message
 ```
 

diff --git a/.github/workflows/check-docs.yml b/.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
diff --git a/.github/workflows/deploy-docs.yml b/.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
diff --git a/.github/workflows/link-check-config.json b/.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"
-}
+}
diff --git a/.github/workflows/link-check.yml b/.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'
diff --git a/.github/workflows/markdown-lint.yml b/.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: ","
diff --git a/.markdownlint-cli2.jsonc b/.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/**"
+  ]
+}
diff --git a/.markdownlint.jsonc b/.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
+}
diff --git a/.markdownlintignore b/.markdownlintignore
diff --git a/CODE_OF_CONDUCT.md b/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.
 

diff --git a/CONTRIBUTING.md b/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/). ADRs are 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)
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,7 +15,7 @@ closes: #XXXX @@
     ### Commit Message / Changelog Entry
-    ```bash
+    ```text
     type: commit message
     ```
@@ Expand Down @@