github.com/muhammadn/cortex@v1.9.1-0.20220510110439-46bb7000d03d/docs/proposals/version-documentation.md (about)

     1  ---
     2  title: "Documentation Versioning"
     3  linkTitle: "Documentation Versioning"
     4  weight: 1
     5  slug: documentation-versioning
     6  ---
     7  
     8  - Author: [Jay Batra](https://github.com/jaybatra26)
     9  - Date: March 2020
    10  - Status: proposal
    11  
    12  ## Problem
    13  
    14  In Cortex, currently, we are missing versioning of documentation. The idea is to have version documentation just like Prometheus.[`Prometheus`](https://prometheus.io/docs/introduction/overview/). Documentation is the main source of information for current contributors and first-timers. A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community.
    15  
    16  In this proposal, we want to solve this. In particular, we want to:
    17  
    18  1. Version specific pages of the documentation
    19  2. Include links to change version (the version must be in the URL)
    20  3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release.
    21  
    22  
    23  ## Proposed solution
    24  
    25  Currently, the documentation is residing under the docs/ folder of cortexproject/cortex. It is built by Hugo using the theme [`docsy`](https://www.docsy.dev). It will have a proper [`drop-down menu`](https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu) which will enable proper versioning. It has a section [`params.version`](https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu) in config.toml which will allow us to map URLs with proper versions. We will have to change all the occurrences of older doc links with new links. We will keep `master` version with 3 latest `release` versions. Each release is a minor version expressed as `1.x`. The document would default to latest minor version.
    26  
    27  From the current doc, the following paths (and all their subpages) should be versioned for now:
    28  
    29  1. https://cortexmetrics.io/docs/apis/
    30  2. https://cortexmetrics.io/docs/configuration/ (moving v1.x Guarantees outside of the tree, because these shouldn't be versioned)
    31  
    32  The above should be versioned under a single URL path (`/docs/running-cortex/` in the following example, but final prefix is still to be decided).
    33  
    34  ### Example:
    35  
    36  For `master` version we would be able to use the above links via the following path
    37  
    38  ```
    39  /docs/running-cortex/master/configuration/
    40  /docs/running-cortex/master/api/
    41  ```
    42  
    43  And for a minor version like `1.x`:
    44  
    45  ```
    46  /docs/running-cortex/1.0/configuration/
    47  /docs/running-cortex/1.0/apis/
    48  ```
    49  
    50  we'll have versioned documentation only under the /docs/running-cortex/ prefix and, as a starting point, all versioned pages should go there.
    51