github.com/cosmos/cosmos-sdk@v0.50.10/docs/README.md (about)

     1  # Updating the docs
     2  
     3  If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation) and the [Documentation Writing Guidelines](./DOC_WRITING_GUIDELINES.md).
     4  
     5  ## Stack
     6  
     7  The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the `/docs` directory.
     8  It is built using the following stack:
     9  
    10  * [Docusaurus 2](https://docusaurus.io)
    11  * Vuepress (pre v0.47)
    12  * [Algolia DocSearch](https://docsearch.algolia.com/)
    13  
    14    ```js
    15        algolia: {
    16          appId: "QLS2QSP47E",
    17          apiKey: "067b84458bfa80c295e1d4f12c461911",
    18          indexName: "cosmos_network",
    19          contextualSearch: false,
    20        },
    21    ```
    22  
    23  * GitHub Pages
    24  
    25  ## Docs Build Workflow
    26  
    27  The docs are built and deployed automatically on GitHub Pages by a [GitHub Action workflow](../.github/workflows/deploy-docs.yml).
    28  The workflow is triggered on every push to the `main` and `release/v**` branches, every time documentations or specs are modified.
    29  
    30  ### How It Works
    31  
    32  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.
    33  
    34  ## How to Build the Docs Locally
    35  
    36  Go to the `docs` directory and run the following commands:
    37  
    38  ```shell
    39  cd docs
    40  npm install
    41  ```
    42  
    43  For starting only the current documentation, run:
    44  
    45  ```shell
    46  npm start
    47  ```
    48  
    49  It runs `pre.sh` scripts to get all the docs that are not already in the `docs/docs` folder.
    50  It also runs `post.sh` scripts to clean up the docs and remove unnecessary files when quitting.
    51  
    52  Note, the command above only build the docs for the current versions.
    53  With the drawback that none of the redirections works. So, you'll need to go to /main to see the docs.
    54  
    55  To build all the docs (including versioned documentation), run:
    56  
    57  ```shell
    58  make build-docs
    59  ```
    60  
    61  ## What to for new major SDK versions
    62  
    63  When a new major version of the SDK is released, the following steps should be taken:
    64  
    65  * 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.
    66  * On the `release/vX.Y.Z` branch, update `docusaurus.config.js` and set the `lastVersion` to `current`, remove all other versions from the config.
    67  * Each time a new version is released (on docusaurus), drop support from the oldest versions.
    68      * If the old version is still running vuepress (v0.45, v0.46), remove its line from `vuepress_versions`
    69      * If any, remove the outdated redirections from `docusaurus.config.js` and add the base version redirection (`/vX.XX`) to `/main`.
    70  
    71        ```js
    72          {
    73            from: ["/", "/master", "/v0.43", "/v0.44", "/v0.XX"], // here add the deprecated version
    74            to: "/main",
    75          },
    76        ```
    77  
    78  * Add the new version sidebar to the list of versionned sidebar and add the version to `versions.json`.
    79  * Update the latest version (`presets[1].docs.lastVersion`) in `docusaurus.config.js`.
    80  * Add the new version with in `presets[1].docs.versions` in `docusaurus.config.js`.
    81  
    82  Learn more about [versioning](https://docusaurus.io/docs/versioning) in Docusaurus.