From fe0b7f0ae8bdd48234ec53c5f2e91a793b82a776 Mon Sep 17 00:00:00 2001 From: nisbet-hubbard <87453615+nisbet-hubbard@users.noreply.github.com> Date: Fri, 20 Dec 2024 23:29:08 +0800 Subject: [PATCH] Document the fact that Rouge only recognises lower-case language identifiers (#35697) Co-authored-by: Felicity Chapman --- .../creating-and-highlighting-code-blocks.md | 3 +++ .../about-github-pages-and-jekyll.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md b/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md index 7cb074b04c0d..415fdd8de958 100644 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md +++ b/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md @@ -66,6 +66,9 @@ This will display the code block with syntax highlighting: ![Screenshot of three lines of Ruby code as displayed on {% data variables.product.prodname_dotcom %}. Elements of the code display in purple, blue, and red type for scannability.](/assets/images/help/writing/code-block-syntax-highlighting-rendered.png) +> [!TIP] +> When you create a fenced code block that you also want to have syntax highlighting on a GitHub Pages site, use lower-case language identifiers. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#syntax-highlighting). + We use [Linguist](https://github.com/github-linguist/linguist) to perform language detection and to select [third-party grammars](https://github.com/github-linguist/linguist/blob/main/vendor/README.md) for syntax highlighting. You can find out which keywords are valid in [the languages YAML file](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml). ## Creating diagrams diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md index 81f38ce1acd7..da923660e358 100644 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md +++ b/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md @@ -110,6 +110,9 @@ To make your site easier to read, code snippets are highlighted on {% data varia By default, code blocks on your site will be highlighted by Jekyll. Jekyll uses the [Rouge](https://github.com/rouge-ruby/rouge) highlighter (which is compatible with [Pygments](https://pygments.org/)). If you specify Pygments in your `_config.yml` file, Rouge will be used as the fallback instead. Jekyll cannot use any other syntax highlighter, and you'll get a page build warning if you specify another syntax highlighter in your `_config.yml` file. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites). +> [!NOTE] +> Rouge only recognizes lower-case language identifiers for fenced code blocks. For a list of supported languages, see [Languages](https://rouge-ruby.github.io/docs/file.Languages.html). + If you want to use another highlighter, such as [highlight.js](https://github.com/highlightjs/highlight.js), you must disable Jekyll's syntax highlighting by updating your project's `_config.yml` file. ```yaml