diff options
Diffstat (limited to 'content')
31 files changed, 452 insertions, 577 deletions
diff --git a/content/en/_index.md b/content/en/_index.md index bfebd8b2f..b4e602438 100644 --- a/content/en/_index.md +++ b/content/en/_index.md @@ -43,7 +43,7 @@ sections: link: templates/ color_classes: bg-primary-color-light black image: /images/home-page-templating-example.png - copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex. If you prefer Jade/Pug-like syntax, you can also use Amber, Ace, or any combination of the three." + copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex." --- Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. diff --git a/content/en/about/features.md b/content/en/about/features.md index cadcc6b0f..a1e741ac0 100644 --- a/content/en/about/features.md +++ b/content/en/about/features.md @@ -52,7 +52,7 @@ toc: true * Integrated [Google Analytics][] support * Automatic [RSS][] creation * Support for [Go][], [Amber], and [Ace][] HTML templates -* [Syntax highlighting][] powered by [Chroma][] (partly compatible with Pygments) +* [Syntax highlighting][] powered by [Chroma][] [Ace]: /templates/alternatives/ diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index a0ed992f2..ea0568616 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -1,6 +1,6 @@ --- -title: Supported Content Formats -linktitle: Supported Content Formats +title: Content Formats +linktitle: Content Formats description: Both HTML and Markdown are supported content formats. date: 2017-01-10 publishdate: 2017-01-10 @@ -13,191 +13,37 @@ menu: weight: 20 weight: 20 #rem draft: false -aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/,/tutorials/mathjax/] +aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] toc: true --- -**Markdown is the main content format** and comes in two flavours: The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in front matter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in front matter), both very fast markdown engines written in Go. +You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.: -For Emacs users, [go-org](https://github.com/niklasfasching/go-org) provides built-in native support for Org-mode (name your files `*.org` or set `markup = "org"` in front matter) +* Markdown converted to HTML +* [Shortcodes](/content-management/shortcodes/) processed +* Layout applied -But in many situations, plain HTML is what you want. Just name your files with `.html` or `.htm` extension inside your content folder. Note that if you want your HTML files to have a layout, they need front matter. It can be empty, but it has to be there: +## List of content formats -```html ---- -title: "This is a content file in HTML" ---- - -<div> - <h1>Hello, Hugo!</h1> -</div> -``` - -{{% note "Deeply Nested Lists" %}} -Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations. -{{% /note %}} - -## Configure BlackFriday Markdown Rendering - -You can configure multiple aspects of Blackfriday as shown in the following list. See the docs on [Configuration][config] for the full list of explicit directions you can give to Hugo when rendering your site. - -{{< readfile file="/content/en/readfiles/bfconfig.md" markdown="true" >}} - -## Extend Markdown - -Hugo provides some convenient methods for extending markdown. - -### Task Lists - -Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration. - -#### Example Task List Input - -{{< code file="content/my-to-do-list.md" >}} -- [ ] a task list item -- [ ] list syntax required -- [ ] incomplete -- [x] completed -{{< /code >}} - -#### Example Task List Output - -The preceding markdown produces the following HTML in your rendered website: - -``` -<ul class="task-list"> - <li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li> - <li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li> - <li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li> - <li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li> -</ul> -``` - -#### Example Task List Display - -The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to [the Hugo Docs stylesheet][hugocss]. - -- [ ] a task list item -- [ ] list syntax required -- [ ] incomplete -- [x] completed - -### Emojis - -To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][]. - -For a full list of emojis, see the [Emoji cheat sheet][emojis]. - -### Shortcodes - -If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly. - -See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own. - -### Code Blocks - -Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` shortcode][hlsc], and syntax highlights those code blocks natively using *Chroma*. Users also have an option to use *Pygments* instead. See the [Syntax Highlighting][hl] section for details. - -## Mmark - -Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmark] or the full syntax on [Miek Gieben's website][]. - -### Use Mmark - -As Hugo ships with Mmark, using the syntax is as easy as changing the extension of your content files from `.md` to `.mmark`. - -In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content's front matter: - -``` ---- -title: My Post -date: 2017-04-01 -markup: mmark ---- -``` - -{{% warning %}} -Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/gohugoio/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/gohugoio/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/gohugoio/hugo/issues/2270)) are not fully supported. Contributions are welcome. -{{% /warning %}} - -## MathJax with Hugo - -[MathJax](https://www.mathjax.org/) is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here. - -This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo. - -### Enable MathJax - -The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](https://docs.mathjax.org/en/latest/web/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a `<script>` tag for the officially recommended secure CDN ([cdn.js.com](https://cdnjs.com)): - -{{< code file="add-mathjax-to-page.html" >}} -<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> -</script> -{{< /code >}} - -One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. - -### Options and Features - -MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](https://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options). - -### Issues with Markdown - -{{% note %}} -The following issues with Markdown assume you are using `.md` for content and BlackFriday for parsing. Using [Mmark](#mmark) as your content format will obviate the need for the following workarounds. - -When using Mmark with MathJax, use `displayMath: [['$$','$$'], ['\\[','\\]']]`. See the [Mmark `README.md`](https://github.com/miekg/mmark/wiki/Syntax#math-blocks) for more information. In addition to MathJax, Mmark has been shown to work well with [KaTeX](https://github.com/Khan/KaTeX). See this [related blog post from a Hugo user](http://nosubstance.me/post/a-great-toolset-for-static-blogging/). -{{% /note %}} - -After enabling MathJax, any math entered between proper markers (see the [MathJax documentation][mathjaxdocs]) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior. - -### Solution - -There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts. - -Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author). - -{{< code file="mathjax-markdown-solution.html" >}} -<script type="text/x-mathjax-config"> -MathJax.Hub.Config({ - tex2jax: { - inlineMath: [['$','$'], ['\\(','\\)']], - displayMath: [['$$','$$'], ['\[','\]']], - processEscapes: true, - processEnvironments: true, - skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'], - TeX: { equationNumbers: { autoNumber: "AMS" }, - extensions: ["AMSmath.js", "AMSsymbols.js"] } - } -}); -</script> -{{< /code >}} - -As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. - -{{< code file="mathjax-style.css" >}} -code.has-jax { - font: inherit; - font-size: 100%; - background: inherit; - border: inherit; - color: #515151; -} -{{< /code >}} - -In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. - -### Usage +The current list of content formats in Hugo: -With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page! +| Name | Markup identifiers | Comment | +| ------------- | ------------- |-------------| +| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} | +| Blackfriday | blackfriday |Blackfriday will eventually be deprecated.| +|MMark|mmark|Mmark is deprecated and will be removed in a future release.| +|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).| +|Asciidoc|asciidoc, adoc, ad|Needs Asciidoc or [Asciidoctor][ascii] installed.| +|RST|rst|Needs [RST](http://docutils.sourceforge.net/rst.html) installed.| +|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.| +|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.| -## Additional Formats Through External Helpers +The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/). -Hugo has a new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [pandoc]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].) -For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/)). +## External Helpers -To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files. +Some of the formats in the table above needs external helpers installed on your PC. For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/)). Hugo passes reasonable default arguments to these external helpers by default: diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 9ec0734cc..53e72bee1 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -98,11 +98,12 @@ Tags: {{ range $k, $v := .Tags }} TAG: {{ $k }}: {{ $v }} {{ end }} +{{ end }} ``` #### Exif fields -Data +Date : "photo taken" date/time Lat diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 6b277365f..1220a06c8 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -3,7 +3,7 @@ title: Syntax Highlighting description: Hugo comes with really fast syntax highlighting from Chroma. date: 2017-02-01 publishdate: 2017-02-01 -keywords: [highlighting,pygments,chroma,code blocks,syntax] +keywords: [highlighting,chroma,code blocks,syntax] categories: [content management] menu: docs: @@ -16,17 +16,39 @@ aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] toc: true --- -From Hugo 0.28, the default syntax highlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments. -If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config. +Hugo uses [Chroma](https://github.com/alecthomas/chroma) as its code highlighter; it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments we used before. -The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)). +## Configure Syntax Highlighter + +See [Configure Highlight](/getting-started/configuration-markup#highlight). + + +## Generate Syntax Highlighter CSS + +If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet. + +You can generate one with Hugo: -* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers. -* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma. +```bash +hugo gen chromastyles --style=monokai > syntax.css +``` + +Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles. + + +## Highlight Shortcode + +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. + +Options: + +* `linenos`: Valid values are `true`, `false`, `table`, `inline`. `table` will give copy-and-paste friendly code blocks) turns on line numbers. +* Setting `linenos` to `false` will turn off linenumbers if it's configured to be on in site config.{{< new-in "0.60.0" >}} +* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. * `linenostart=199` starts the line number count from 199. -With that, this: +### Example: Highlight Shortcode ``` {{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}} @@ -52,143 +74,64 @@ func GetTitleFunc(style string) func(s string) string { case "go": return strings.Title case "chicago": - tc := transform.NewTitleConverter(transform.ChicagoStyle) - return tc.Title + return transform.NewTitleConverter(transform.ChicagoStyle) default: - tc := transform.NewTitleConverter(transform.APStyle) - return tc.Title + return transform.NewTitleConverter(transform.APStyle) } } {{< / highlight >}} -## Configure Syntax Highlighter -To make the transition from Pygments to Chroma seamless, they share a common set of configuration options: - -pygmentsOptions -: A comma separated list of options. See below for a full list. - -pygmentsCodeFences -: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example). - -pygmentsStyle -: The style of code highlighting. Note that this option is not - relevant when `pygmentsUseClasses` is set. - - Syntax highlighting galleries: - **Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html), - [long snippets](https://xyproto.github.io/splash/docs/longer/all.html)), - [Pygments](https://help.farbox.com/pygments.html) - -pygmentsUseClasses -: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css). - -pygmentsCodeFencesGuessSyntax -: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag. - -pygmentsUseClassic -: Set to true to use Pygments instead of the much faster Chroma. - -### Options - -`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func. - -noclasses -: Use inline style. - -linenos -: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control. - -linenostart -: Start the line numbers from this value (default is 1). - - -hl_lines -: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20". - - -The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details. - - -## Generate Syntax Highlighter CSS - -If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet. - -You can generate one with Hugo: - -```bash -hugo gen chromastyles --style=monokai > syntax.css -``` - -Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/splash/docs/ for a gallery of available styles. - - -## Highlight Shortcode - -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 `highlight` Shortcode - -{{< code file="example-highlight-shortcode-input.md" >}} -{{</* highlight html */>}} -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</section> -{{</* /highlight */>}} -{{< /code >}} - - ## Highlight Template Func See [Highlight](/functions/highlight/). -## Highlight in Code Fences +## Highlighting in 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/); +Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}} ```` -```go-html-template -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</section> +```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code ``` ```` -## List of Chroma Highlighting Languages -The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences): - -{{< chroma-lexers >}} - -## Highlight with Pygments Classic - -If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path. +Gives this: -{{% 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 %}} +```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// GetTitleFunc returns a func that can be used to transform a string to +// title case. +// +// The supported styles are +// +// - "Go" (strings.Title) +// - "AP" (see https://www.apstylebook.com/) +// - "Chicago" (see https://www.chicagomanualofstyle.org/home.html) +// +// If an unknown or empty style is provided, AP style is what you get. +func GetTitleFunc(style string) func(s string) string { + switch strings.ToLower(style) { + case "go": + return strings.Title + case "chicago": + return transform.NewTitleConverter(transform.ChicagoStyle) + default: + return transform.NewTitleConverter(transform.APStyle) + } +} +``` -If you have never worked with Pygments before, here is a brief primer: +{{< new-in "0.60.0" >}}Note that only Goldmark supports passing attributes such as `hl_lines`, and it's important that it does not contain any spaces. See [goldmark-highlighting](https://github.com/yuin/goldmark-highlighting) for more information. -+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient. -+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it. +The options are the same as in the [highlighting shortcode](/content-management/syntax-highlighting/#highlight-shortcode),including `linenos=false`, but note the slightly different Markdown attribute syntax. -On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`. +## List of Chroma Highlighting Languages +The full list of Chroma lexers and their aliases (which is the identifier used in the `highlight` template func or when doing highlighting in code fences): |