Skip to content

Files

This branch is 496 commits ahead of, 2908 commits behind cosmos/cosmos-sdk:main.

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Oct 10, 2023
Mar 5, 2024
Oct 9, 2023
Sep 13, 2023
Nov 7, 2022
Oct 13, 2022
Sep 21, 2023
Nov 3, 2022
Nov 14, 2022
Oct 10, 2022
Mar 2, 2023
Sep 21, 2023
Jun 5, 2023
Jun 5, 2023
Sep 21, 2023
Nov 16, 2023
Apr 10, 2023
Oct 13, 2022
Oct 10, 2022

Updating the docs

If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in CONTRIBUTING.md and the Documentation Writing Guidelines.

Stack

The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the /docs directory. It is built using the following stack:

  • Docusaurus 2

  • Vuepress (pre v0.47)

  • Algolia DocSearch

        algolia: {
          appId: "QLS2QSP47E",
          apiKey: "067b84458bfa80c295e1d4f12c461911",
          indexName: "cosmos_network",
          contextualSearch: false,
        },
  • GitHub Pages

Docs Build Workflow

The docs are built and deployed automatically on GitHub Pages by a GitHub Action workflow. The workflow is triggered on every push to the main and release/v** branches, every time documentations or specs are modified.

How It Works

There is a GitHub Action listening for changes in the /docs directory for the main branch and each supported version branch (e.g. release/v0.46.x). Any updates to files in the /docs directory will automatically trigger a website deployment. Under the hood, the private website repository has a make build-docs target consumed by a Github Action within that repository.

How to Build the Docs Locally

Go to the docs directory and run the following commands:

cd docs
npm install

For starting only the current documentation, run:

npm start

It runs pre.sh scripts to get all the docs that are not already in the docs/docs folder. It also runs post.sh scripts to clean up the docs and remove unnecessary files when quitting.

Note, the command above only build the docs for the current versions. With the drawback that none of the redirections works. So, you'll need to go to /main to see the docs.

To build all the docs (including versioned documentation), run:

make build-docs

What to for new major SDK versions

When a new major version of the SDK is released, the following steps should be taken:

  • On the release/vX.Y.Z branch, remove the deploy action (.github/workflows/deploy-docs.yml), for avoiding deploying the docs from the release branches.

  • On the release/vX.Y.Z branch, update docusaurus.config.js and set the lastVersion to current, remove all other versions from the config.

  • Each time a new version is released (on docusaurus), drop support from the oldest versions.

    • If the old version is still running vuepress (v0.45, v0.46), remove its line from vuepress_versions

    • If any, remove the outdated redirections from docusaurus.config.js and add the base version redirection (/vX.XX) to /main.

        {
          from: ["/", "/master", "/v0.43", "/v0.44", "/v0.XX"], // here add the deprecated version
          to: "/main",
        },
  • Add the new version sidebar to the list of versionned sidebar and add the version to versions.json.

  • Update the latest version (presets[1].docs.lastVersion) in docusaurus.config.js.

  • Add the new version with in presets[1].docs.versions in docusaurus.config.js.

Learn more about versioning in Docusaurus.