diff options
author | Matthew Taylor <matthew@m-taylor.co.uk> | 2020-06-01 16:59:45 +0300 |
---|---|---|
committer | Matthew Taylor <matalo33@users.noreply.github.com> | 2020-06-01 17:08:15 +0300 |
commit | 6dea56b8717c1226b72391c78d1955b25904e45f (patch) | |
tree | 5e3f2efc7720b3cd9c256c9de28f56a5fe9222df | |
parent | 9c080a39d8ed1abae53cac26931c10672f4b58e2 (diff) |
Add additional documentation for code highlighting
-rw-r--r-- | exampleSite/content/cont/markdown.en.md | 14 | ||||
-rw-r--r-- | exampleSite/content/cont/syntaxhighlight.en.md | 89 |
2 files changed, 98 insertions, 5 deletions
diff --git a/exampleSite/content/cont/markdown.en.md b/exampleSite/content/cont/markdown.en.md index 13c9e00..c97701e 100644 --- a/exampleSite/content/cont/markdown.en.md +++ b/exampleSite/content/cont/markdown.en.md @@ -164,7 +164,7 @@ and this HTML: <em>rendered as italicized text</em> ``` -### strikethrough +### Strikethrough In GFM (GitHub flavored Markdown) you can do strikethroughs. @@ -420,7 +420,7 @@ HTML: Use "fences" ```` ``` ```` to block in multiple lines of code. -```markup +```markdown Sample text here... ``` @@ -434,9 +434,13 @@ HTML: ### Syntax highlighting -GFM, or "GitHub Flavored Markdown" also supports syntax highlighting. To activate it, simply add the file extension of the language you want to use directly after the first code "fence", ` ```js `, and syntax highlighting will automatically be applied in the rendered HTML. For example, to apply syntax highlighting to JavaScript code: +GFM, or "GitHub Flavored Markdown" also supports syntax highlighting. To activate it, simply add the file extension of the language you want to use directly after the first code "fence", ` ```js `, and syntax highlighting will automatically be applied in the rendered HTML. -<!-- markdownlint-disable MD046 --> +See [Code Highlighting]({{< ref "syntaxhighlight.md" >}}) for additional documentation. + +For example, to apply syntax highlighting to JavaScript code: + +```plaintext ```js grunt.initConfig({ assemble: { @@ -457,7 +461,7 @@ GFM, or "GitHub Flavored Markdown" also supports syntax highlighting. To activat } }; ``` -<!-- markdownlint-disable MD046 --> +``` Renders to: diff --git a/exampleSite/content/cont/syntaxhighlight.en.md b/exampleSite/content/cont/syntaxhighlight.en.md new file mode 100644 index 0000000..ed1fe72 --- /dev/null +++ b/exampleSite/content/cont/syntaxhighlight.en.md @@ -0,0 +1,89 @@ +--- +date: 2020-06-01T13:31:12+01:00 +title: Code highlighting +weight: 16 +--- + +Learn theme uses [highlight.js](https://highlightjs.org/) to provide code syntax highlighting. + +## Markdown syntax + +Wrap the code block with three backticks and the name of the language. Highlight will try to auto detect the language if one is not provided. + +<!-- markdownlint-disable MD046 --> +```plaintext + ```json + [ + { + "title": "apples", + "count": [12000, 20000], + "description": {"text": "...", "sensitive": false} + }, + { + "title": "oranges", + "count": [17500, null], + "description": {"text": "...", "sensitive": false} + } + ] + ``` +``` +<!-- markdownlint-disable MD046 --> + +Renders to: + +```json +[ + { + "title": "apples", + "count": [12000, 20000], + "description": {"text": "...", "sensitive": false} + }, + { + "title": "oranges", + "count": [17500, null], + "description": {"text": "...", "sensitive": false} + } +] +``` + +## Supported languages + +Learn theme ships with its own version of highlight.js to support offline browsing. The included package supports 38 common languages, as described on the [highlight.js download page](https://highlightjs.org/download/). + +## Identifying failed language detection + +Highlight will write a warning to the browser console if a requested language was not found. For example, the following code block references an imaginary language `foo`. An error will be output to the console on this page. + +```plaintext + ```foo + bar + ``` +``` + +```nohighlight +Could not find the language 'foo', did you forget to load/include a language module?(anonymous) @ highlight.pack.js +``` + +## Supporting additional languages + +To support languages other than the 38 common languages included in the default highlight.js you will need to download your own version of highlight.js and add it to your site content. + +### Download custom highlight.js + +Visit [https://highlightjs.org/download/](https://highlightjs.org/download/) and select your desired language support. Note that more languages means greater package size. + +### Add custom highlight.js to static resources + +Inside the zip archive downloaded from highlight.js extract the file named `highlight.pack.js`. Move this file to the **new** location + +```nohighlight +static/js/highlight.pack.js +``` + +**Do not** replace the existing file at `themes/hugo-theme-learn/static/js/highlight.pack.js`. + +Including the file in the correct path will override the theme default highlight.pack.js and prevent issues caused in the future if the theme default file is updated. + +## Further usage information + +See [https://highlightjs.org/usage/](https://highlightjs.org/usage/) |