From 972a81a5a932753b8bdbfe8ad8ca90eb5888909f Mon Sep 17 00:00:00 2001 From: Julius Volz Date: Sat, 24 May 2025 12:41:28 +0200 Subject: [PATCH] Improve README.md and markdown-guide.md Signed-off-by: Julius Volz --- README.md | 9 ++++----- markdown-guide.md | 6 +++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 73160ce5..f5275259 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,11 @@ You'll need to have the following installed on your system: ### Environment variables -For downloading documentation from other repositories as well as for fetching information about available downloads, the build scripts need a GitHub access token with read access to the repositories. You can create a personal access token in your GitHub account settings (https://github.com/settings/tokens/new). +To bypass anonymous user rate limits while downloading documentation from the other repositories, as well as fetching information about available downloads from the GitHub API, the pre-build scripts require a GitHub access token with read access to the repositories (no write access is required). You can create a personal access token in your GitHub account settings (https://github.com/settings/tokens/new). Create a `.env` file in the root of the repository and add the following environment variable: ```env -# The URL of the Prometheus server repository GITHUB_TOKEN= ``` @@ -63,9 +62,9 @@ You can also run each of these build steps separately: * `npm run clean` - Cleans any build output and generated files from previous runs. * `npm run fetch-repo-docs` - Fetches the latest documentation from the Prometheus and Alertmanager repositories. * `npm run fetch-downloads-info` - Fetches information about available downloads (for the Download page). -* `npm run build` - Builds the website. Note: This also runs the `postbuild` script, which generates [Pagefind](https://pagefind.app/) search indexes. +* `npm run build` - Builds the website. When using `npm`, this automatically also runs the `postbuild` script, which generates [Pagefind](https://pagefind.app/) search indexes. If you are using `pnpm`, you will either need to run `npm run postbuild` manually, or set the [`enablePrePostScripts` option](https://pnpm.io/cli/run#pnpm-workspaceyaml-settings) in your `pnpm-workspace.yaml` file. -### Serving the static output +### Serving the static build output To serve the static build output, run: @@ -87,7 +86,7 @@ This will start a web server on port 3000. You can access the website at [http:/ The website will automatically reload when you make changes to the source files. -NOTE: Spotlight search is not available in development mode, as it requires building a [Pagefind](https://pagefind.app/) index on the static output and then loading the generated `/pagefind/pagefind.js` file. This only happens when building the app for production via `npm run build` (part of `npm run build-all`). +**NOTE:** Site search is not available in development mode, as it requires building a [Pagefind](https://pagefind.app/) index on the static build output and then loading the generated `/pagefind/pagefind.js` file. This only happens when building the app for production via `npm run build` (part of `npm run build-all`). ## Configuration diff --git a/markdown-guide.md b/markdown-guide.md index b45b5f0f..c6515bb5 100644 --- a/markdown-guide.md +++ b/markdown-guide.md @@ -8,14 +8,14 @@ Generally, we use [GitHub Flavored Markdown](https://github.github.com/gfm/) for * 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 `` elements with a text pattern of `` (e.g. `` or ``) 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. +* On configuration pages like https://prometheus.io/docs/prometheus/latest/configuration/configuration/, any inline `` element with a text pattern of `` (e.g. `` or ``) will be identified as a type definition, and references to those placeholders in code boxes will be linked to them. +* Links to images and other pages are normalized in various ways to point to the right locations, show external link icons, etc. ## Heading levels For both blog posts and documentation pages, please use headings in the following ways: -* DO NOT use any top-level headings (`# Heading`, `

`) in the Markdown content itself. The final rendered page will include an automatic H1 heading based on the `title` frontmatter field. +* **DO NOT use any top-level headings (`# Heading`, `

`) 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`, `

`) for the main sections of a page and use lower-level headings for subsections as appropriate. ## Frontmatter fields