Awesome Reviewers expert instructions

domains / docs / github/docs

Version-safe Docs Templating

Ensure documentation that uses Liquid/templating renders correctly across all supported doc versions and doesn’t break code samples. Apply these rules when authoring or updating docs:

raw .md Documentation Markdown updated

Ensure documentation that uses Liquid/templating renders correctly across all supported doc versions and doesn’t break code samples.

Apply these rules when authoring or updating docs:

  • Use ifversion/product variables so text and tables match the target platform(s) (for example, FPT vs GHEC), instead of hardcoding one variant.
  • Keep Markdown structure valid so UI elements render as intended (for example, add required blank lines before headings).
  • Escape templating tokens inside code blocks so the docs build/linter doesn’t interpret them as Liquid. For GitHub Actions examples, wrap ${{ ... }} content in ....

Example (escaping ${{ ... }} in a workflow YAML code block):

```yaml
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

```

This reduces broken previews/builds, avoids inconsistent multi-version content, and prevents readers from seeing incorrect or truncated code samples.

Source discussions