prometheus/docs
1
0
Fork 0
mirror of https://github.com/prometheus/docs.git synced 2026-02-05 15:45:27 +01:00
Code Issues Releases Activity

Document more of our Markdown features in the Markdown guide

Browse Source 
Signed-off-by: Julius Volz <julius.volz@gmail.com>
This commit is contained in:
Julius Volz
2025-05-23 14:46:49 +02:00
parent 5ee012164f
commit 5174e6cb29
1 changed files with 10 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
markdown-guide.md
View File

@@ -4,14 +4,16 @@ This document gives an overview of the Markdown features and formatting options
## Markdown features
Generally, we use [GitHub Flavored Markdown](https://github.github.com/gfm/) for formatting.
Generally, we use [GitHub Flavored Markdown](https://github.github.com/gfm/) for formatting and add some custom filters on top:
TODO: document admonitions
TODO: document how to link between pages
* Paragraphs that start with `TIP:`, `NOTE:`, `CAUTION:`, or `TODO:` are automatically converted to alert boxes with an appropriate icon and color.
* Code blocks are automatically highlighted using [Shiki](https://shiki.matsu.io/).
* On configuration pages like https://prometheus.io/docs/prometheus/latest/configuration/configuration/, any inline `<code>` elements with a text pattern of `<placeholder>` (e.g. `<string>` or `<scrape_config>`) will be identified as type definitions and references to those placeholders in code boxes will be linked to them.
* Links to images and other pages are normalized in various ways.
## Heading levels
For both blog posts and documentation pages, adhere to the following heading rules:
For both blog posts and documentation pages, please use headings in the following ways:
* DO NOT use any top-level headings (`# Heading`, `<h1>`) in the Markdown content itself. The final rendered page will include an automatic H1 heading based on the `title` frontmatter field.
* Use second-level headings (`## Heading`, `<h2>`) for the main sections of a page and use lower-level headings for subsections as appropriate.
@@ -23,10 +25,10 @@ The following frontmatter fields are available:
### For local and remote documentation pages
* `title`: The title of the page. This is displayed as the main heading on the page and as the HTML page title.
* `sort_rank`: The sort order of the page relative to sibling pages in the same directory. Pages with a lower sort rank will appear first in the navigation menu. Should start at 1 and be incremented by 1 for each page.
* `nav_title` (OPTIONAL): The title to show in the navigation menu. If not set, the `title` field is used.
* `hide_in_nav` (OPTIONAL): If set to `true`, the page will not be included in the navigation menu but still be accessible via its URL. TODO RENAME
* `nav_icon` (OPTIONAL): The [Tabler](https://tabler.io/icons) icon to be displayed in the navigation menu for this section. This is only used for the top-level section index.md Markdown files. Any new icons need to be added to the `iconMap` in [`src/app/docs/layout.tsx`](src/app/docs/layout.tsx).
* `sort_rank`: The sort order of the page relative to its sibling pages in the same directory. Pages with a lower sort rank will appear first in the navigation menu. Should start at 1 and be incremented by 1 for each page.
* `nav_title` (OPTIONAL): The title to show in the navigation menu. If not set, the `title` field is used. This can be useful for showing a shorter title in the navigation menu, if necessary.
* `hide_in_nav` (OPTIONAL): If set to `true`, the page will not be included in the navigation menu but still be accessible via its URL.
* `nav_icon` (OPTIONAL): The [Tabler](https://tabler.io/icons) icon to be displayed in the navigation menu for this section. This is only used for the top-level section `index.md` Markdown files. Any new icons need to be added to the `iconMap` in [`src/app/docs/layout.tsx`](src/app/docs/layout.tsx).
### For blog posts