blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-09-01 19:22:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Finalize syntax highlighting

Browse Source
This commit is contained in:
Ryan Watters
2017-02-21 23:49:32 -06:00
parent 2eb2431cd0
commit ed22a83f89
14 changed files with 203 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/content-management/shortcodes.md
+21 -13
View File
@@ -2,6 +2,7 @@
title: Shortcodes
linktitle:
description:
godocref:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
@@ -9,7 +10,6 @@ weight: 25
categories: [content management]
tags: [markdown,content,shortcodes]
draft: false
slug:
aliases: [/extras/shortcodes/]
toc: true
---
@@ -18,7 +18,7 @@ Hugo loves Markdown because of its simple content format, but there are times wh
Hugo created **shortcodes** to circumvent these limitations.
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files---if you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
In addition to cleaner markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
@@ -26,43 +26,47 @@ In addition to cleaner markdown, shortcodes can be updated any time to reflect n
In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters*/%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional or both (although you can't mixed parameter types in a single call). The format for named parameters models that of HTML with the format `name="value"`.
The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing shortcodes match (name only) with the closing declaration prepended with a slash.
Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
Example of a paired shortcode:
Here are two examples of paired shortcodes:
```golang
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
```
```golang
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
```
The examples above use two different delimiters, the difference being the `%` and the `<` character:
The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
### Shortcodes with Markdown
The `%` characters indicates that the shortcode's inner content (`.Inner`) needs further processing by the page's rendering processor (i.e. Markdown), which would be needed to convert `**World**` to `<strong>World</strong>` in the following example:
The `%` character indicates that the shortcode's inner content---called in the [shortcode template](/templates/shortcode-templates/) with the [`.Inner` variable](/variables-and-parmams/other/)---needs further processing by the page's rendering processor (i.e. Markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
```golang
{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
```
### Shortcodes without Markdown
### Shortcodes Without Markdown
The `<` character indicates that the shortcode's inner content doesn't need any further rendering, this will typically be pure HTML:
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
```golang
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
## Using the Built-in Shortcodes
## Using Hugo's Built-in Shortcodes
Hugo ships with a set of predefined shortcodes the represent very common usage that would otherwise muddy your content with unnecessary markup.
Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
### `figure`
`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figurelement].
`figure` can use the following named parameters:
The `figure` shortcode can use the following named parameters:
* `src`
* `link`
@@ -96,7 +100,7 @@ Hugo ships with a set of predefined shortcodes the represent very common usage t
### `gist`
Bloggers often want to include GitHub gists when writing posts. Let's supposed we want to use the following [gist][examplegist]:
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the following [gist][examplegist]:
```html
https://gist.github.com/spf13/7896402
@@ -114,6 +118,10 @@ If the gist contains several files and you want to quote just one of them, you c
{{</* gist spf13 7896402 "img.html" */>}}
```
To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page:
{{< gist spf13 7896402 >}}
### `highlight`
This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/developer-tools/syntax-highlighting/). `highlight` takes exactly one required parameter of _language_ and requires a closing shortcode.
content/developer-tools/syntax-highlighting.md
+58 -34
View File
@@ -41,11 +41,12 @@ Hugo gives you two options that you can set with the variable `pygmentsuseclasse
### Usage
Highlighting is carried out via the in-built shortcode `highlight`. `highlight` takes exactly one required parameter of language, and requires a closing shortcode. Note that `highlight` is _not_ used for client-side javascript highlighting.
Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is _not_ used for client-side javascript highlighting.
### Example
### Example `highlight` Shortcode Input
```
{{% input "example-highlight-shortcode-input.md" %}}
```html
{{</* highlight html */>}}
<section id="main">
<div>
@@ -57,9 +58,11 @@ Highlighting is carried out via the in-built shortcode `highlight`. `highlight`
</section>
{{</* /highlight */>}}
```
{{% /input %}}
### Example Output
### Example `highlight` Shortcode Output
{{% output "example-highlight-shortcode-output.html" %}}
```
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
@@ -70,10 +73,11 @@ Highlighting is carried out via the in-built shortcode `highlight`. `highlight`
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
```
{{% /output %}}
### Options
Options to control highlighting can be added as a quoted, comma separated key-value list as the second argument in the shortcode. The example below will highlight as language `go` with inline line numbers, with line number 2 and 3 highlighted.
Options for controlling highlighting can be added in the second argument as a quoted, comma-separated key-value list. The example below will syntax highlight in `go` with inline line numbers and line numbers 2 and 3 highlighted.
```
{{</* highlight go "linenos=inline,hl_lines=2 3" */>}}
@@ -84,13 +88,21 @@ var d string
{{</* / highlight */>}}
```
Supported keywords: `style`, `encoding`, `noclasses`, `hl_lines`, `linenos`. Note that `style` and `noclasses` will override the similar setting in the global config.
The `highlight` shortcode includes the following supported keywords:
The keywords are the same you would using with Pygments from the command line, see the [Pygments doc](http://pygments.org/docs/) for more info.
* `style`
* `encoding`
* `noclasses`
* `hl_lines`
* `linenos`
### Code fences
Note that `style` and `noclasses` will override the similar setting in the [global config](/getting-started/configuration/).
It is also possible to add syntax highlighting with GitHub flavoured code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's configuration file.
The keywords in the `highlight` shortcode mirror those of Pygments from the command line. See the [Pygments documentation](http://pygments.org/docs/) for more information.
### Code Fences
It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
````
``` html
@@ -105,15 +117,15 @@ It is also possible to add syntax highlighting with GitHub flavoured code fences
```
````
### Disclaimers
{{% note "Disclaimers on Pygments" %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* The languages available for highlighting depend on your Pygments installation.
{{% /note %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* Languages available depends on your Pygments installation.
## Client-side Syntax Highlighting
## Client-side
Alternatively, code highlighting can be done in client-side JavaScript.
Alternatively, code highlighting can be applied to your code blocks in client-side JavaScript.
Client-side syntax highlighting is very simple to add. You'll need to pick
a library and a corresponding theme. Some popular libraries are:
@@ -142,7 +154,10 @@ In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your
### Prism example
Prism is another popular highlighter library, used on some major sites. Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages, like so:
Prism is another popular highlighter library and is used on some major sites.
The [download section of the prism.js website] is simple to use and affords you a high degree of customization to pick only the languages you'll be using on your site.
Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages:
```html
...
@@ -150,7 +165,7 @@ Prism is another popular highlighter library, used on some major sites. Similar
...
```
... and add `prism.js` near the bottom of your `<body>` tag, again in whatever Hugo partial template is appropriate for your site or theme.
Add `prism.js` near the bottom of your `<body>` tag in whatever Hugo partial template is appropriate for your site or theme.
```html
...
@@ -159,45 +174,54 @@ Prism is another popular highlighter library, used on some major sites. Similar
</body>
```
In this example, the local paths indicate that your own copy of these files are being added to the site, typically under `./static/`.
In this example, the local paths indicate that your downloaded copy of these files are being added to the site, typically under `./static/css/` and `./static/js/`, respectively.
### Using Client-side highlighting
### Using Client-side Highlighting
To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` tags, with the language expressed in a class attribute on the `<code>` tag, such as `class="language-abc"`, where the `abc` is the code the highlighter script uses to represent that language.
To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` elements with language-specific class attributes. For example, a code block for HTML would have `class="language-html"`.
The script would be looking for classes like `language-go`, `language-html`, or `language-css`. If you look at the page's source, it would be marked up like so:
The client-side highlighting script therefore looks for programming language classes according to this convention: `language-go`, `language-html`, `language-css`, `language-bash`, etc. If you look at the page's source, you might see something like the following:
```html
<pre>
<code class="language-css">
body {
font-family: "Noto Sans", sans-serif;
}
</code>
<code class="language-css">
body {
font-family: "Noto Sans", sans-serif;
}
</code>
</pre>
```
The markup in your content pages (e.g. `my-css-tutorial.md`) needs to look like the following, with the name of the language to be highlighted entered directly after the first "fence. A fenced code block can be noted by opening and close triple tilde (`~`) or triple back ticks (```):
If you are using markdown, your content pages needs to use the following syntax, with the name of the language to be highlighted entered directly after the first "fence." A fenced code block can be noted by opening and closing triple tilde <kbd>~</kbd> or triple back ticks <kbd>`</kbd>:
```css
{{< nohighlight >}}
~~~css
body {
font-family: "Noto Sans", sans-serif;
}
~~~
```
{{< /nohighlight >}}
Or with back ticks:
Here is the same example but with triple back ticks to denote the fenced code block:
~~~css
{{< nohighlight >}}
```css
body {
font-family: "Noto Sans", sans-serif;
}
```
~~~
{{< /nohighlight >}}
When passed through the highlighter script, it would yield something like this output when viewed on your rendered page:
Passing the above examples through the highlighter script would yield the following markup:
{{< nohighlight >}}
&lt;pre&gt;&lt;code class="language-css hljs"&gt;;&lt;span class="hljs-selector-tag"&gt;body&lt;/span&gt; {
&lt;span class="hljs-attribute"&gt;font-family&lt;/span&gt;: &ltspan class="hljs-string"&gt;"Noto Sans"&lt;/span&gt;, sans-serif;
}
</code></pre>
{{< /nohighlight >}}
In the case of the coding color scheme used by the Hugo docs, the resulting output would then look like the following to the website's end users:
```css
body {
content/showcase/_index.md
+9 -5
View File
@@ -5,13 +5,17 @@ description: A collection of sites built using Hugo.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: []
tags: [introduction,overview]
categories: [site showcase]
tags: [featured,showcase]
weight: 01
draft: false
hidesectioncontents: false
type: showcase
layout: showcaselist.html
aliases: [/site-showcase/]
notesforauthors:
---
toc: false
---
The following sites have been built with <i class="icon-love"></i> and Hugo. [Interested in adding your site to the showcase?][addshowcase]
[addshowcase]: /contribute-to-hugo/add-your-site-to-the-showcase/
content/showcase/promotive.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
date: 2017-02-21T12:26:26+01:00
description: "Corporate website a event management agency"
description: "Corporate website of an event management agency"
license: ""
licenseLink: ""
sitelink: https://promotive.es
@@ -10,6 +10,6 @@ tags:
- spanish
- event management
- bootstrap
thumbnail: /img/promotive.png
image: promotive.png
title: Promotive
---
content/templates/partial-templates.md
+1 -1
View File
@@ -153,7 +153,7 @@ If you need to pass additional parameters to create unique variants, you can pas
Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key.
## Using the Built-in Partials
## Using Hugo's Built-in Partials
### Google Analytics
content/themes/theme-showcase.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: Theme Showcase
linktitle: Theme Showcase
description: Hugo has an ever-growing selection of community-developed themes for you to use in your Hugo site completely free. The Theme Showcase is a separate, Hugo-driven website.
redirecturl: "http://themes.gohugo.io/"
sitelink: "http://themes.gohugo.io/"
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
static/images/showcase/novelist.png → static/images/showcase/novelist-xyz.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB

themes/hugodocs/layouts/partials/contents-list.html
+2 -1
View File
@@ -4,7 +4,8 @@
<h2 id="contents" class="contents-list-heading section-heading">Contents:</h2>
{{end}}
{{range .Data.Pages}}
<a href="{{.Permalink}}">
<!-- if statement checks for sitelink, which includes the themes site and *every* showcase site -->
<a {{with .Params.sitelink }}href="{{.}}"target="_blank"{{else}}href="{{.Permalink}}"{{end}}>
<article class="contents-list {{$kind}}">
<header>
<h3 class="list-icon {{.Section}}">{{- partial "list-icon.html" . -}}{{with .LinkTitle}}{{. | markdownify}}{{else}}{{.Title | markdownify}}{{end}}</h3>
themes/hugodocs/layouts/partials/head/metadata-refreshredirect.html
+2 -2
View File
@@ -1,5 +1,5 @@
{{if and (eq .Kind "page") (.Params.redirecturl)}}
{{if and (eq .Kind "page") ( .Params.sitelink )}}
<link rel="canonical" href="{{.Permalink}}"/>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta http-equiv="refresh" content="0; url={{.Params.redirecturl}}"/>
<meta http-equiv="refresh" content="0; url={{if .Params.redirecturl}}{{.Params.redirecturl}}{{else}}{{.Params.sitelink}}{{end}}"/>
{{end}}
themes/hugodocs/layouts/partials/site-header.html
+1 -1
View File
@@ -6,6 +6,6 @@
<img src="{{$base}}images/hugo-logo/hugo-logo-wide.png" alt=""><span class="hugo-v">v{{$version}}</span>
</a>
<!-- From https://buttons.github.io/. -->
<a class="github-button" href="https://github.com/spf13/hugo" data-icon="octicon-star" data-style="mega" data-count-href="/spf13/hugo/stargazers" data-count-api="/repos/spf13/hugo#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star spf13/hugo on GitHub">Star</a>
<!-- <a class="github-button" href="https://github.com/spf13/hugo" data-icon="octicon-star" data-style="mega" data-count-href="/spf13/hugo/stargazers" data-count-api="/repos/spf13/hugo#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star spf13/hugo on GitHub">Star</a> -->
</div>
</header>
themes/hugodocs/layouts/section/showcase.html
+34
View File
@@ -5,5 +5,39 @@
<h1 class="page-title {{if eq .Kind "page"}}{{.Section}}{{end}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">{{with .LinkTitle}}{{.}}{{else}}{{ .Title | markdownify }}{{end}}</h1>
{{.Content}}
</header>
<ul id="showcase">
{{$base := .Site.BaseURL}}
{{- range .Data.Pages.ByPublishDate.Reverse -}}
{{$title := .Title}}
<li class="showcase-site">
<div class="image-wrapper">
<a href="{{.Params.sitelink}}" target="_blank">
<img src="{{$base}}images/showcase/{{.Params.image}}" alt="Screenshot thumbnail for the website {{.Title}}, {{.Description}}">
</a>
</div>
<div class="showcase-meta">
<div class="showcase-links">
{{with .Params.sitelink}}
<span class="showcase-title"><a href="{{.}}" target="_blank">{{$title}}</a></span>
{{else}}
<h3>{{$title}}</h3>
{{end}}
{{with .Params.sourcelink}}
<span class="showcase-source"><a href="{{.}}" target="_blank"><i class="icon-code"></i>Source</a></span>
{{end}}
</div>
{{- with .Params.tags -}}
<ul class="tags showcase-tags">
<li class="tags-icon-li"><i class="icon-tags"></i></li>
{{- range . -}}
<li><a href="{{$base}}tags/{{. | urlize}}">{{.}}</a></li>
{{- end -}}
</ul>
{{- end -}}
</div>
</li>
{{- end -}}
</ul>
</main>
{{end}}
themes/hugodocs/pipeline/scss/layout/_showcase.scss
+70
View File
@@ -0,0 +1,70 @@
main.showcase-list {
width: 90%;
max-width: $XL;
margin-left: auto;
margin-right: auto;
}
#showcase {
display: flex;
list-style: none;
padding-left: 0px;
margin-left: 0px;
width: 100%;
flex-wrap: wrap;
justify-content: space-between;
li.showcase-site {
list-style: none;
padding-left: 0px;
margin-left: 0px;
display: flex;
flex-direction: column;
width: 100%;
@include card(1);
margin-bottom: 1.5em;
@include MQ(M) {
width: 48%;
}
@include MQ(XL) {
width: 32%;
}
.image-wrapper {
width: 100%;
max-width: 100%;
img {
width: 100%;
max-width: 100%;
border-bottom: 1px solid lighten($hugo-gray-light, 10%);
}
}
ul.tags {
display: flex;
flex-wrap: wrap;
width: 100%;
li {
margin-bottom: .25em;
align-self: flex-start;
width: auto;
a {
font-size: 12px;
}
&.tags-icon-li {
box-shadow: none;
}
}
}
.showcase-meta {
padding: 10px;
.showcase-links {
display: flex;
justify-content: space-between;
align-items: center;
font-size: .8em;
.showcase-source {
font-size: .8em;
text-transform: uppercase;
}
}
}
}
}
themes/hugodocs/pipeline/scss/style.scss
+1
View File
@@ -38,6 +38,7 @@
@import 'layout/site-header';
@import 'layout/site-navigation';
@import 'layout/site-content';
@import 'layout/showcase';
@import 'layout/site-footer';
//styles for individual pages