From 1fa6d82e35c5a2aaf776d3e912b7d58f15d960a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Thu, 4 Apr 2024 23:30:53 +0200 Subject: [PATCH] docs: announce new feature #822 --- .../content/basics/migration/_index.en.md | 4 +- exampleSite/content/cont/markdown.en.md | 125 +++++++++++------- 2 files changed, 82 insertions(+), 47 deletions(-) diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index a95df7415d..504c373f06 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/exampleSite/content/basics/migration/_index.en.md @@ -28,7 +28,9 @@ This document shows you what's new in the latest release and flags it with one o By that you can now call the dependency mechanism in your own overriden partials by giving it a distinct `location` parameter. In addition your injected files can now be spread to multiple locations which wasn't previously possible. -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can scroll forward and backward thru all headings of a page by using `ALT + 🡑` and `ALT + 🡓`. This also works for the `PRINT` output format +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Additional styling was added for the native HTML elements `` and ``. To use them you must allow the [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe) in your `hugo.toml`. + +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can scroll forward and backward thru all headings of a page by using ALT 🡑 and ALT 🡓. This also works for the `PRINT` output format. - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The breadcrumbs used in the topbar, search results and the taxonomy term lists are now using the pages frontmatter `linktitle` instead of `title` if set. diff --git a/exampleSite/content/cont/markdown.en.md b/exampleSite/content/cont/markdown.en.md index 404f63e77f..6a8c7eb1c5 100644 --- a/exampleSite/content/cont/markdown.en.md +++ b/exampleSite/content/cont/markdown.en.md @@ -1,6 +1,6 @@ +++ tags = ["Content"] -title = "Markdown syntax" +title = "Markdown Syntax" weight = 4 +++ @@ -23,14 +23,20 @@ John Gruber, the author of Markdown, puts it like this: > John Gruber {{% notice tip %}} -{{% icon bookmark %}} Bookmark this page and the [official Commonmark reference](https://commonmark.org/help/) for easy future reference! +{{% icon bookmark %}} Bookmark this page for easy future reference! {{% /notice %}} -## Support and Extensions +## Standard and Extensions -If not otherwise noted, the showed examples adhere to the Commonmark standard. In addition the theme supports the following extensions: +If not otherwise noted, the showed examples adhere to the [Commonmark](https://commonmark.org/help/) standard. In addition the theme supports the following extensions: -- {{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} GitHub Flavored Markdown allows further constructs on top of standard Markdown. +- {{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Extension on top of standard Markdown adhering to [GitHub Flavored Markdown](https://github.github.com/gfm/). + +- {{% badge color="#888cc4" icon="fa-fw fab fa-markdown" %}}PHP{{% /badge %}} Extension on top of standard Markdown adhering to [PHP Markdown](https://michelf.ca/projects/php-markdown/extra/). + +- {{% badge color="darkorange" icon="lightbulb" %}}Pants{{% /badge %}} Extension by John Gruber and his company Daring Fireball adhering to [SmartyPants](https://daringfireball.net/projects/smartypants/). + +- {{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} If the [usage of HTML](https://gohugo.io/getting-started/configuration-markup/#rendererunsafe) is allowed in your `hugo.toml` the theme supports styling for further elements not accessible using Markdown alone. ## Paragraphs @@ -133,7 +139,7 @@ I am rendered with _italicized text_ ### Strikethrough -{{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} You can do strikethroughs by enclosing text with two tildes `~~`. +{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can do strikethroughs by enclosing text with two tildes `~~`. ````md ~~Strike through this text~~ @@ -143,9 +149,24 @@ I am rendered with _italicized text_ ~~Strike through this text~~ {{% /notice %}} -## Text substitution +### Marked Text -This Markdown dialect supports an extension to combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code. +{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can mark text in the predefined accent color of your stylesheet. + +````html +Parts of this text are marked! +```` + +{{% notice style="secondary" icon="eye" title="Result" %}} +Parts of this text are marked! +{{% /notice %}} + + +## Special Typesetting + +### Text Substitution + +{{% badge color="darkorange" icon="lightbulb" %}}Pants{{% /badge %}} You can combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code. ````md Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**. @@ -167,6 +188,30 @@ Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and Three consecutive dots `...` are replaced by an ellipsis **...** entity. {{% /notice %}} +### Keyboard Shortcuts + +{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can use the `` element to style keyboard shortcuts. + +````html +Press STRG ALT DEL to end your shift early. +```` + +{{% notice style="secondary" icon="eye" title="Result" %}} +Press STRG ALT DEL to end your shift early. +{{% /notice %}} + +### Sub and Super Script + +{{% badge color="orangered" icon="fa-fw fas fa-code" %}}HTML{{% /badge %}} You can also use the `` and `` elements. For more complex stuff or if your configuration does not allow HTML, you can use the [`math` shortcode](shortcodes/math). + +````html +How many liters H2O fit into 1dm3? +```` + +{{% notice style="secondary" icon="eye" title="Result" %}} +How many liters H2O fit into 1dm3? +{{% /notice %}} + ## Lists ### Unordered @@ -231,7 +276,7 @@ Markdown will automatically number each of your items consecutively. This means, ### Tasks -{{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} You can add task lists resulting in checked or unchecked non-clickable items +{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can add task lists resulting in checked or unchecked non-clickable items ````md - [x] Basic Test @@ -251,7 +296,7 @@ Markdown will automatically number each of your items consecutively. This means, ### Definitions -This Markdown dialect supports an extension to add definition lists. Definition lists are made of terms and definitions of these terms, much like in a dictionary. +{{% badge color="#888cc4" icon="fa-fw fab fa-markdown" %}}PHP{{% /badge %}} Definition lists are made of terms and definitions of these terms, much like in a dictionary. A definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term. You can also associate more than one term to a definition. @@ -325,59 +370,47 @@ Be impressed by my advanced code: If you want to gain more control of your code block you can enclose your code by at least three backticks ```` ``` ```` a so called fence. -{{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} You can also add a language specifier directly after the opening fence, ` ```js `, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML. +{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can also add a language specifier directly after the opening fence, ` ```js `, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML. See [Code Highlighting](shortcodes/highlight) for additional documentation. ````plaintext ```js -grunt.initConfig({ - assemble: { - options: { - assets: 'docs/assets', - data: 'src/data/*.{json,yml}', - helpers: 'src/custom-helpers.js', - partials: ['src/partials/**/*.{hbs,md}'] +{ + name: "Claus", + surname: "Santa", + profession: "courier", + age: 666, + address: { + city: "North Pole", + postalCode: 1, + country: "Arctic" }, - pages: { - options: { - layout: 'default.hbs' - }, - files: { - './': ['src/templates/pages/index.hbs'] - } - } - } + friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ] }; ``` ```` {{% notice style="secondary" icon="eye" title="Result" %}} ```js -grunt.initConfig({ - assemble: { - options: { - assets: 'docs/assets', - data: 'src/data/*.{json,yml}', - helpers: 'src/custom-helpers.js', - partials: ['src/partials/**/*.{hbs,md}'] +{ + name: "Claus", + surname: "Santa", + profession: "courier", + age: 666, + address: { + city: "North Pole", + postalCode: 1, + country: "Arctic" }, - pages: { - options: { - layout: 'default.hbs' - }, - files: { - './': ['src/templates/pages/index.hbs'] - } - } - } + friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ] }; ``` {{% /notice %}} ## Tables -{{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} You can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned. +{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} You can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned. ````md | Option | Description | @@ -441,7 +474,7 @@ Blockquotes can also be nested. ### Autolink -{{% badge color="lightslategray" icon="fa-fw fab fa-github" %}}GFN{{% /badge %}} Absolute URLs will automatically be converted into a link. +{{% badge color="darkgray" icon="fa-fw fab fa-github" %}}GFM{{% /badge %}} Absolute URLs will automatically be converted into a link. ````md This is a link to https://example.com. @@ -494,7 +527,7 @@ Links can be simplyfied for recurring reuse by using a reference ID to later def ### Footnotes -Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes. +{{% badge color="#888cc4" icon="fa-fw fab fa-markdown" %}}PHP{{% /badge %}} Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes. Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.