./docs directory is used as markdown source files using blackfriday to render Thanos website resources.
However the aim for those is to also have those
*.md files renderable and usable (including links) via GitHub.
To make that happen we use following rules and helpers that are listed here.
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:
--- title: <title> type: ... weight: <weight> menu: <where to link files in> # This also is referred in permalinks. ---
Aim is to match linking behavior in website being THE SAME as Github. This means:
slug: /<filename with extension>
website/hugo.yamlnew dir as key
Then everywhere use native markdown absolute path to the project repository if you want to link to exact commit e.g:
Small post processing script adjusts link for Hugo rendering.
NOTE: Spaces matters so:
[xxx]( link and
[xxx] (link will not work.
.Site.Menus are added as soon as some file has Front Matter with certain
menu the same as sub-directory the file is in. This will help to manage all docs.
Show new menu section in main page by changing
We’d love to showcase your company’s logo on our main page and README! Requirements for the company:
If all those are met, add yourself in
website/data/adopters.yml like so:
- name: My Awesome Company url: https://wwww.company.com logo: company.png
Copy your company’s logo in
website/static/logos, make sure it follows these rules:
and create PR against Thanos
We want all docs to not have any white noise. To achieve it, we provide cleanup-white-noise.sh under
scripts to check. You can call it before a pull request, also PR test would call it too.
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.
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:
We use Netlify for hosting. We are using Open Source license (PRO). Thanks Netlify for this!
On every commit to
main netlify runs CI that invokes
make web (defined in netlify.toml)
NOTE: Check for status badge in README for build status on the page.
If main build for netlify succeed, the new content is published automatically.