./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: <titke>
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:
./docs
). Put slug: /<filename with extension>
website/hugo.yaml
new dir as key permalinks:
with <dir>: /<dir>/:filename.md
Then everywhere use native markdown absolute path to the project repository if you want to link to exact commit e.g:
[title](/Makefile)
Small post processing script adjusts link for Hugo rendering.
NOTE: Spaces matters so: [xxx]( link
and [xxx] (link
will not work.
Why?
New menus .Site.Menus
are added as soon as some file has Front Matter with certain menu
.
Keep 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 website/layouts/_default/baseof.html
file.
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 master
branch.
We want all docs do not have any white noise. To achieve it, we provide cleanup-white-noise.sh under scripts
to check. You can call it before pull a 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:
make web-serve
We use Netlify for hosting. We are using Open Source license (PRO). Thanks Netlify for this!
On every commit to master
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 master build for netlify succeed, the new content is published automatically.