From 42c8ec549bf694749aa51d0a25fe66e84c88496d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Mon, 23 Aug 2021 23:32:34 +0200 Subject: [PATCH] code highlighter: avoid unstyled blocks in docs #32 The new highlighter does not work to well if no syntax is specified for the code block / code fence / indention. See https://github.com/gohugoio/hugo/pull/8917 --- .../content/basics/installation/_index.en.md | 12 ++--- exampleSite/content/cont/archetypes.en.md | 17 ++++--- exampleSite/content/cont/icons.en.md | 4 +- exampleSite/content/cont/markdown.en.md | 44 ++++++++++--------- exampleSite/content/cont/pages/_index.en.md | 2 +- exampleSite/content/shortcodes/INCLUDE_ME.md | 2 +- exampleSite/content/shortcodes/button.en.md | 2 +- exampleSite/content/shortcodes/expand.en.md | 12 ++--- exampleSite/content/shortcodes/include.en.md | 4 +- exampleSite/content/shortcodes/mermaid.en.md | 12 ++--- exampleSite/content/shortcodes/notice.en.md | 26 +++++------ .../content/shortcodes/siteparam.en.md | 2 +- 12 files changed, 72 insertions(+), 67 deletions(-) diff --git a/exampleSite/content/basics/installation/_index.en.md b/exampleSite/content/basics/installation/_index.en.md index e3e615f662..768c2d7c77 100644 --- a/exampleSite/content/basics/installation/_index.en.md +++ b/exampleSite/content/basics/installation/_index.en.md @@ -9,7 +9,7 @@ The following steps are here to help you initialize your new website. If you don Hugo provides a `new` command to create a new website. -``` +```shell hugo new site ``` @@ -38,7 +38,7 @@ home = [ "HTML", "RSS", "JSON"] Chapters are pages that contain other child pages. It has a special layout style and usually just contains a _chapter name_, the _title_ and a _brief abstract_ of the section. -``` +```markdown ### Chapter 1 # Basics @@ -52,7 +52,7 @@ renders as **Hugo-theme-relearn** provides archetypes to create skeletons for your website. Begin by creating your first chapter page with the following command -``` +```shell hugo new --kind chapter basics/_index.md ``` @@ -64,7 +64,7 @@ By default all chapters and pages are created as a draft. If you want to render Then, create content pages inside the previously created chapter. Here are two ways to create content in the chapter: -``` +```shell hugo new basics/first-content.md hugo new basics/second-content/_index.md ``` @@ -75,7 +75,7 @@ Feel free to edit thoses files by adding some sample content and replacing the ` Launch by using the following command: -``` +```shell hugo serve ``` @@ -91,7 +91,7 @@ You should notice three things: When your site is ready to deploy, run the following command: -``` +```shell hugo ``` diff --git a/exampleSite/content/cont/archetypes.en.md b/exampleSite/content/cont/archetypes.en.md index d5fd997028..c78c7a0785 100644 --- a/exampleSite/content/cont/archetypes.en.md +++ b/exampleSite/content/cont/archetypes.en.md @@ -11,13 +11,13 @@ It is pre-configured skeleton pages with default front matter. Please refer to t To create a Chapter page, run the following commands -``` +```shell hugo new --kind chapter /_index.md ``` It will create a page with predefined Front-Matter: -```markdown +```toml +++ title = "{{ replace .Name "-" " " | title }}" date = {{ .Date }} @@ -35,18 +35,21 @@ Lorem Ipsum. ## Default -To create a default page, run either one of the following commands +To create a default page, run either one of the following commands either -``` -# Either +```shell hugo new //_index.md -# Or +``` + +or + +```shell hugo new /.md ``` It will create a page with predefined Front-Matter: -```markdown +```toml +++ title = "{{ replace .Name "-" " " | title }}" date = {{ .Date }} diff --git a/exampleSite/content/cont/icons.en.md b/exampleSite/content/cont/icons.en.md index 954a7da542..7d5d7b2389 100644 --- a/exampleSite/content/cont/icons.en.md +++ b/exampleSite/content/cont/icons.en.md @@ -13,7 +13,7 @@ Once on the Font Awesome page for a specific icon, for example the page for the The HTML to include the heart icon is: -``` +```html ``` @@ -21,7 +21,7 @@ The HTML to include the heart icon is: Paste the `` HTML into markup and Font Awesome will load the relevant icon. -``` +```html Built with by Relearn and Hugo ``` diff --git a/exampleSite/content/cont/markdown.en.md b/exampleSite/content/cont/markdown.en.md index a151fbf2a1..7caa0ab24e 100644 --- a/exampleSite/content/cont/markdown.en.md +++ b/exampleSite/content/cont/markdown.en.md @@ -403,9 +403,11 @@ HTML: Use "fences" ```` ``` ```` to block in multiple lines of code. -```markdown +````plaintext +``` Sample text here... ``` +```` HTML: @@ -423,28 +425,28 @@ See [Code Highlighting]({{% relref "syntaxhighlight.md" %}}) for additional docu For example, to apply syntax highlighting to JavaScript code: -```plaintext - ```js - grunt.initConfig({ - assemble: { - options: { - assets: 'docs/assets', - data: 'src/data/*.{json,yml}', - helpers: 'src/custom-helpers.js', - partials: ['src/partials/**/*.{hbs,md}'] - }, - pages: { - options: { - layout: 'default.hbs' - }, - files: { - './': ['src/templates/pages/index.hbs'] - } - } +````plaintext +```js +grunt.initConfig({ + assemble: { + options: { + assets: 'docs/assets', + data: 'src/data/*.{json,yml}', + helpers: 'src/custom-helpers.js', + partials: ['src/partials/**/*.{hbs,md}'] + }, + pages: { + options: { + layout: 'default.hbs' + }, + files: { + './': ['src/templates/pages/index.hbs'] } - }; - ``` + } + } +}; ``` +```` Renders to: diff --git a/exampleSite/content/cont/pages/_index.en.md b/exampleSite/content/cont/pages/_index.en.md index 276c72afbb..3bf11d7ac8 100644 --- a/exampleSite/content/cont/pages/_index.en.md +++ b/exampleSite/content/cont/pages/_index.en.md @@ -81,7 +81,7 @@ The following steps are here to help you initialize your new website. If you don Hugo provides a `new` command to create a new website. -``` +```shell hugo new site ``` diff --git a/exampleSite/content/shortcodes/INCLUDE_ME.md b/exampleSite/content/shortcodes/INCLUDE_ME.md index 45b18b4b5f..e91e305d0b 100644 --- a/exampleSite/content/shortcodes/INCLUDE_ME.md +++ b/exampleSite/content/shortcodes/INCLUDE_ME.md @@ -7,7 +7,7 @@ You can add: - other shortcodes besides `expand` - etc. -``` +```plaintext ...and even source code ``` diff --git a/exampleSite/content/shortcodes/button.en.md b/exampleSite/content/shortcodes/button.en.md index 3303dfa400..d0cea54b5a 100644 --- a/exampleSite/content/shortcodes/button.en.md +++ b/exampleSite/content/shortcodes/button.en.md @@ -5,7 +5,7 @@ description : "Nice buttons on your page." A button is a just a clickable button with optional icon. -``` +```go {{%/* button href="https://gohugo.io/" */%}}Get Hugo{{%/* /button */%}} {{%/* button href="https://gohugo.io/" icon="fas fa-download" */%}}Get Hugo with icon{{%/* /button */%}} {{%/* button href="https://gohugo.io/" icon="fas fa-download" icon-position="right" */%}}Get Hugo with icon right{{%/* /button */%}} diff --git a/exampleSite/content/shortcodes/expand.en.md b/exampleSite/content/shortcodes/expand.en.md index 74f3828aa5..6be3364824 100644 --- a/exampleSite/content/shortcodes/expand.en.md +++ b/exampleSite/content/shortcodes/expand.en.md @@ -7,7 +7,7 @@ The Expand shortcode displays an expandable/collapsible section of text on your ## Usage -```` +````go {{%/* expand "Does this relearn theme rock?" { "true" | "false" } */%}} Yes! {{%/* /expand */%}} @@ -25,7 +25,7 @@ Yes, you did it! {{% /expand %}} {{% expand "Show markup" "true" %}} -```` +````go {{%/* expand */%}} Yes, you did it! {{%/* /expand */%}} @@ -39,7 +39,7 @@ No need to press you! {{% /expand %}} {{% expand "Show markup" "true" %}} -```` +````go {{%/* expand "Expand me..." "true" */%}} No need to press you! {{%/* /expand */%}} @@ -60,7 +60,7 @@ You can add: - other shortcodes besides `expand` - etc. -``` +```plaintext ...and even source code ``` @@ -68,7 +68,7 @@ You can add: {{% /expand %}} {{% expand "Show markup" %}} -```` +````go {{%/* expand "Show me endless possibilities" */%}} Some expandable text. @@ -81,7 +81,7 @@ You can add: - other shortcodes besides `expand` - etc. -``` +```plaintext ...and even source code ``` diff --git a/exampleSite/content/shortcodes/include.en.md b/exampleSite/content/shortcodes/include.en.md index 68851eb4e5..4173970655 100644 --- a/exampleSite/content/shortcodes/include.en.md +++ b/exampleSite/content/shortcodes/include.en.md @@ -7,7 +7,7 @@ The include shortcode includes other files from your project inside of the curre ## Usage -```` +````go {{%/* include "" */%}} ```` @@ -18,7 +18,7 @@ The include shortcode includes other files from your project inside of the curre {{% include "shortcodes/INCLUDE_ME.md" %}} {{% expand "Show markup" %}} -```` +````go {{%/* include "shortcodes/INCLUDE_ME.md" */%}} ```` {{% /expand %}} diff --git a/exampleSite/content/shortcodes/mermaid.en.md b/exampleSite/content/shortcodes/mermaid.en.md index 09ac30ef9b..7a7079162e 100644 --- a/exampleSite/content/shortcodes/mermaid.en.md +++ b/exampleSite/content/shortcodes/mermaid.en.md @@ -10,7 +10,7 @@ description : "Generation of diagram and flowchart from text in a similar manner Just insert your mermaid code in the `mermaid` shortcode like this: -```` +````go {{}} classDiagram Person *-- Dog @@ -43,7 +43,7 @@ graph LR; {{< /mermaid >}} {{% expand "Show markup" "true" %}} -```` +````go {{}} graph LR; A[Hard edge] -->|Link text| B(Round edge) @@ -71,7 +71,7 @@ sequenceDiagram {{< /mermaid >}} {{% expand "Show markup" "true" %}} -```` +````go {{}} sequenceDiagram participant Alice @@ -109,7 +109,7 @@ gantt {{< /mermaid >}} {{% expand "Show markup" "true" %}} -```` +````go {{}} gantt dateFormat YYYY-MM-DD @@ -150,7 +150,7 @@ classDiagram {{< /mermaid >}} {{% expand "Show markup" "true" %}} -```` +````go {{}} classDiagram Class01 <|-- AveryLongClass : Cool @@ -184,7 +184,7 @@ stateDiagram-v2 {{< /mermaid >}} {{% expand "Show markup" "true" %}} -```` +````go {{}} stateDiagram-v2 open: Open Door diff --git a/exampleSite/content/shortcodes/notice.en.md b/exampleSite/content/shortcodes/notice.en.md index 1368983a9d..efa8ecd888 100644 --- a/exampleSite/content/shortcodes/notice.en.md +++ b/exampleSite/content/shortcodes/notice.en.md @@ -7,7 +7,7 @@ The notice shortcode shows four types of disclaimers to help you structure your ## Usage -```` +````go {{%/* notice [ note | info | tip | warning ] */%}} Some markup {{%/* /notice */%}} @@ -29,7 +29,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -37,7 +37,7 @@ You can add: {{% /notice %}} {{% expand "Show markup" %}} -```` +````go {{%/* notice note */%}} A **notice** disclaimer @@ -50,7 +50,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -73,7 +73,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -81,7 +81,7 @@ You can add: {{% /notice %}} {{% expand "Show markup" %}} -```` +````go {{%/* notice info */%}} An **information** disclaimer @@ -94,7 +94,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -117,7 +117,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -125,7 +125,7 @@ You can add: {{% /notice %}} {{% expand "Show markup" %}} -```` +````go {{%/* notice tip */%}} A **tip** disclaimer @@ -138,7 +138,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -161,7 +161,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` @@ -169,7 +169,7 @@ You can add: {{% /notice %}} {{% expand "Show markup" %}} -```` +````go {{%/* notice warning */%}} A **warning** disclaimer @@ -182,7 +182,7 @@ You can add: - other shortcodes besides `notice` - etc. -``` +```plaintext ...and even source code ``` diff --git a/exampleSite/content/shortcodes/siteparam.en.md b/exampleSite/content/shortcodes/siteparam.en.md index dd1169fc8b..89049e6ae8 100644 --- a/exampleSite/content/shortcodes/siteparam.en.md +++ b/exampleSite/content/shortcodes/siteparam.en.md @@ -14,7 +14,7 @@ For instance, in this current site, the `editURL` variable is used in `config.to Use the `siteparam` shortcode to display its value. -``` +```go `editURL` Value : {{%/* siteparam "editURL" */%}} ```