github.com/thanos-io/thanos@v0.32.5/docs/contributing/how-to-contribute-to-docs.md (about)

     1  # How to contribute to Docs/Website
     2  
     3  `./docs` directory is used as markdown source files using [blackfriday](https://github.com/russross/blackfriday) to render Thanos website resources.
     4  
     5  However the aim for those is to also have those `*.md` files renderable and usable (including links) via GitHub.
     6  
     7  To make that happen we use following rules and helpers that are listed here.
     8  
     9  ## Front Matter
    10  
    11  [Front Matter](https://gohugo.io/content-management/front-matter/) is essential on top of every markdown file if you want to link this file into any menu/submenu option. We use YAML formatting. This will render in GitHub as markdown just fine:
    12  
    13  ```md
    14  
    15  ---
    16  title: <title>
    17  type: ...
    18  weight: <weight>
    19  menu: <where to link files in>  # This also is referred in permalinks.
    20  ---
    21  ```
    22  
    23  ## Links
    24  
    25  Aim is to match linking behavior in website being THE SAME as Github. This means:
    26  
    27  * For files in Hugo <content> dir (so `./docs`). Put `slug: /<filename with extension>`
    28  * For any sub dir add to `website/hugo.yaml` new dir as key `permalinks:` with `<dir>: /<dir>/:filename.md`
    29  
    30  Then everywhere use native markdown absolute path to the project repository if you want to link to exact commit e.g:
    31  
    32  ```
    33  [title](/Makefile)
    34  ```
    35  
    36  Small [post processing script](../../scripts/website/websitepreprocess.sh) adjusts link for Hugo rendering.
    37  
    38  NOTE: Spaces matters so: `[xxx]( link` and `[xxx] (link` will not work.
    39  
    40  Why?
    41  
    42  * Links works on GitHub
    43  * Links works on website
    44  * Markdown plugins works as expected (e.g IDE integrations)
    45  * We use markdown-link-check to test links
    46  
    47  ## Sections/Menu
    48  
    49  New menus `.Site.Menus` are added as soon as some file has Front Matter with certain `menu`.
    50  
    51  Keep `menu` the same as sub-directory the file is in. This will help to manage all docs.
    52  
    53  Show new menu section in main page by changing `website/layouts/_default/baseof.html` file.
    54  
    55  ## Adopters Logos
    56  
    57  We'd love to showcase your company's logo on our main page and README! Requirements for the company:
    58  
    59  * it is using Thanos on production
    60  * it is a legal registered company
    61  * it is happy to announce that you use Thanos publicly
    62  
    63  If all those are met, add yourself in [`website/data/adopters.yml`](../../website/data/adopters.yml) like so:
    64  
    65  ```yml
    66  - name: My Awesome Company
    67    url: https://wwww.company.com
    68    logo: company.png
    69  ```
    70  
    71  Copy your company's logo in [`website/static/logos`](../../website/static/logos), make sure it follows these rules:
    72  
    73  * Rectangle shape
    74  * Greyscale is preferred but color is fine
    75  * Keep it under 50KB
    76  
    77  and create PR against Thanos `main` branch.
    78  
    79  ## White noise
    80  
    81  We want all docs to not have any white noise. To achieve it, we provide [cleanup-white-noise.sh](https://github.com/thanos-io/thanos/blob/main/scripts/cleanup-white-noise.sh) under `scripts` to check. You can call it before a pull request, also PR test would call it too.
    82  
    83  ## Testing
    84  
    85  ### PR testing
    86  
    87  On every PR we build the website and on success display the link to the preview under the checks at the bottom of the github PR.
    88  
    89  ### Local testing
    90  
    91  To test the changes to the docs locally just start serving the website by running the following command and you will be able to access the website on `localhost:1313` by default:
    92  
    93  ```bash
    94  make web-serve
    95  ```
    96  
    97  ## Deployment
    98  
    99  We use [Netlify](https://www.netlify.com/) for hosting. We are using Open Source license (PRO). Thanks Netlify for this!
   100  
   101  On every commit to `main` netlify runs CI that invokes `make web` (defined in [netlify.toml](../../netlify.toml))
   102  
   103  NOTE: Check for status badge in README for build status on the page.
   104  
   105  If main build for netlify succeed, the new content is published automatically.