From: Bjørn Erik Pedersen Date: Sun, 15 Dec 2019 09:37:36 +0000 (+0100) Subject: Merge commit '2e711a28c71e8667258e5ab824f9b9a71c261b0a' X-Git-Tag: v0.62.0~23 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=67f3aa72cf9aaf3d6e447fa6bc12de704d46adf7;p=brevno-suite%2Fhugo Merge commit '2e711a28c71e8667258e5ab824f9b9a71c261b0a' --- 67f3aa72cf9aaf3d6e447fa6bc12de704d46adf7 diff --cc docs/README.md index 7ca9d734,00000000..a2c767b7 mode 100644,000000..100644 --- a/docs/README.md +++ b/docs/README.md @@@ -1,48 -1,0 +1,48 @@@ +[![Netlify Status](https://api.netlify.com/api/v1/badges/e0dbbfc7-34f1-4393-a679-c16e80162705/deploy-status)](https://app.netlify.com/sites/gohugoio/deploys) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://gohugo.io/contribute/documentation/) + +# Hugo Docs + +Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go. + +## Contributing + +We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. + +Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. + +*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* + - Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had these in mind when writing: ++Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had the following criteria in mind when writing: + +* Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …". - * For examples, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great, but don't list long and similar examples just so people can use them on their sites. - * Hugo has users from all over the world, so an easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good. ++* For example, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great. Don't list long and similar examples just so people can use them on their sites. ++* Hugo has users from all over the world, so easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good. + +## Branches + +* The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version. - * The `next` branch is where we store changes that is related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/ ++* The `next` branch is where we store changes that are related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/ + +## Build + +To view the documentation site locally, you need to clone this repository: + +```bash +git clone https://github.com/gohugoio/hugoDocs.git +``` + +Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo). + +Then to view the docs in your browser, run Hugo and open up the link: + +```bash +▶ hugo server + +Started building sites ... +. +. +Serving pages from memory +Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) +Press Ctrl+C to stop +``` diff --cc docs/content/en/_index.md index bfebd8b2,00000000..b4e60243 mode 100644,000000..100644 --- a/docs/content/en/_index.md +++ b/docs/content/en/_index.md @@@ -1,49 -1,0 +1,49 @@@ +--- +title: "The world’s fastest framework for building websites" +date: 2017-03-02T12:00:00-05:00 +features: + - heading: Blistering Speed + image_path: /images/icon-fast.svg + tagline: What's modern about waiting for your site to build? + copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. + + - heading: Robust Content Management + image_path: /images/icon-content-management.svg + tagline: Flexibility rules. Hugo is a content strategist's dream. + copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins. + + - heading: Shortcodes + image_path: /images/icon-shortcodes.svg + tagline: Hugo's shortcodes are Markdown's hidden superpower. + copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility. + + - heading: Built-in Templates + image_path: /images/icon-built-in-templates.svg + tagline: Hugo has common patterns to get your work done quickly. + copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done. + + - heading: Multilingual and i18n + image_path: /images/icon-multilingual2.svg + tagline: Polyglot baked in. + copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites. + + - heading: Custom Outputs + image_path: /images/icon-custom-outputs.svg + tagline: HTML not enough? + copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own. +sections: + - heading: "300+ Themes" + cta: Check out the Hugo themes. + link: https://themes.gohugo.io/ + color_classes: bg-accent-color white + image: /images/homepage-screenshot-hugo-themes.jpg + copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites." + - heading: "Capable Templating" + cta: Get Started. + 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 --cc docs/content/en/content-management/image-processing/index.md index 9ec0734c,00000000..53e72bee mode 100644,000000..100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@@ -1,294 -1,0 +1,295 @@@ +--- +title: "Image Processing" +description: "Image Page resources can be resized and cropped." +date: 2018-01-24T13:10:00-05:00 +linktitle: "Image Processing" +categories: ["content management"] +keywords: [resources,images] +weight: 4004 +draft: false +toc: true +menu: + docs: + parent: "content-management" + weight: 32 +--- + +## The Image Page Resource + +The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder. + +To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}): + +```go-html-template +{{ with .Resources.ByType "image" }} +{{ end }} + +``` + +## Image Processing Methods + + +The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. The `image` resource also, since Hugo 0.58, implements the method `Exif` and `Filter`. + +### Resize + +Resizes the image to the specified width and height. + +```go +// Resize to a width of 600px and preserve ratio +{{ $image := $resource.Resize "600x" }} + +// Resize to a height of 400px and preserve ratio +{{ $image := $resource.Resize "x400" }} + +// Resize to a width 600px and a height of 400px +{{ $image := $resource.Resize "600x400" }} +``` + +### Fit +Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. + +```go +{{ $image := $resource.Fit "600x400" }} +``` + +### Fill +Resize and crop the image to match the given dimensions. Both height and width are required. + +```go +{{ $image := $resource.Fill "600x400" }} +``` + +### Filter + +Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list. + +```go-html-template +{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The above can also be written in a more functional style using pipes: + +```go-html-template +{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The filters will be applied in the given order. + +Sometimes it can be useful to create the filter chain once and then reuse it: + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $img1 = $img1.Filter $filters }} +{{ $img2 = $img2.Filter $filters }} +``` + +### Exif + +Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image. + +Note that this is only suported for JPG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.: + +```go-html-template +{{ with $img.Exif }} +Date: {{ .Date }} +Lat/Long: {{ .Lat}}/{{ .Long }} +Tags: +{{ range $k, $v := .Tags }} +TAG: {{ $k }}: {{ $v }} +{{ end }} ++{{ end }} +``` + +#### Exif fields + - Data ++Date +: "photo taken" date/time + +Lat +: "photo taken where", GPS latitude + +Long +: "photo taken where", GPS longitude + +See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif. + + + + + +## Image Processing Options + +In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. + +### Background Color + +The background color to fill into the transparency layer. This is mostly useful when converting to a format that does not support transparency, e.g. `JPEG`. + +You can set the background color to use with a 3 or 6 digit hex code starting with `#`. + +```go +{{ $image.Resize "600x jpg #b31280" }} +``` + +For color codes, see https://www.google.com/search?q=color+picker + +**Note** that you also set a default background color to use, see [Image Processing Config](#image-processing-config). + +### JPEG Quality +Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. + +```go +{{ $image.Resize "600x q50" }} +``` + +### Rotate +Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +```go +{{ $image.Resize "600x r90" }} +``` + +### Anchor +Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. +Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. + +```go +{{ $image.Fill "300x200 BottomLeft" }} +``` + +### Resample Filter +Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. + +Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. + +See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + +```go +{{ $image.Resize "600x400 Gaussian" }} +``` + +### Target Format + +By default the images is encoded in the source format, but you can set the target format as an option. + +Valid values are `jpg`, `png`, `tif`, `bmp`, and `gif`. + +```go +{{ $image.Resize "600x jpg" }} +``` + +## Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + + +This is the shortcode used in the examples above: + + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + +```go-html-template +{{}} +``` + + +{{% note %}} +**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. +{{% /note %}} + +## Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Default JPEG quality setting. Default is 75. +quality = 75 + +# Anchor used when cropping pictures. +# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop +# Smart Cropping is content aware and tries to find the best crop for each image. +# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight +anchor = "smart" + +# Default background color. +# Hugo will preserve transparency for target formats that supports it, +# but will fall back to this color for JPEG. +# Expects a standard HEX color string with 3 or 6 digits. +# See https://www.google.com/search?q=color+picker +bgColor = "#ffffff" + +[imaging.exif] + # Regexp matching the fields you want to Exclude from the (massive) set of Exif info +# available. As we cache this info to disk, this is for performance and +# disk space reasons more than anything. +# If you want it all, put ".*" in this config setting. +# Note that if neither this or ExcludeFields is set, Hugo will return a small +# default set. +includeFields = "" + +# Regexp matching the Exif fields you want to exclude. This may be easier to use +# than IncludeFields above, depending on what you want. +excludeFields = "" + +# Hugo extracts the "photo taken" date/time into .Date by default. +# Set this to true to turn it off. +disableDate = false + +# Hugo extracts the "photo taken where" (GPS latitude and longitude) into +# .Long and .Lat. Set this to true to turn it off. +disableLatLong = false + + +``` + +## Smart Cropping of Images + +By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. + +An example using the sunset image from above: + + +{{< imgproc sunset Fill "200x200 smart" />}} + + +## Image Processing Performance Consideration + +Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} + + + diff --cc docs/content/en/content-management/syntax-highlighting.md index a4359e05,00000000..1220a06c mode 100644,000000..100644 --- a/docs/content/en/content-management/syntax-highlighting.md +++ b/docs/content/en/content-management/syntax-highlighting.md @@@ -1,150 -1,0 +1,142 @@@ +--- +title: Syntax Highlighting +description: Hugo comes with really fast syntax highlighting from Chroma. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [highlighting,chroma,code blocks,syntax] +categories: [content management] +menu: + docs: + parent: "content-management" + weight: 300 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/] +toc: true +--- + + +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. + +## 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: + +```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. + +### Example: Highlight Shortcode + +``` +{{}} +// ... code +{{}} +``` + +Gives this: + +{{< highlight 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": - 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 >}} + + + +## Highlight Template Func + +See [Highlight](/functions/highlight/). + +## Highlighting in Code Fences + +Highlighting in code fences is enabled by default.{{< new-in "0.60.0" >}} + - ```` - ```go-html-template{hl_lines=[3,"5-6"],linenos=true} - ``` - ```` - +```` +```go {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code ++``` +```` + + +Gives this: + +```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": - 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) + } +} +``` + +{{< 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. + +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. + +## 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 >}} + +[Prism]: https://prismjs.com +[prismdownload]: https://prismjs.com/download.html +[Highlight.js]: https://highlightjs.org/ +[Rainbow]: https://craig.is/making/rainbows +[Syntax Highlighter]: https://alexgorbatchev.com/SyntaxHighlighter/ +[Google Prettify]: https://github.com/google/code-prettify +[Yandex]: https://yandex.ru/ diff --cc docs/content/en/content-management/toc.md index 31326746,00000000..fbb2df06 mode 100644,000000..100644 --- a/docs/content/en/content-management/toc.md +++ b/docs/content/en/content-management/toc.md @@@ -1,95 -1,0 +1,99 @@@ +--- +title: Table of Contents +linktitle: +description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +keywords: [table of contents, toc] +menu: + docs: + parent: "content-management" + weight: 130 +weight: 130 #rem +draft: false +aliases: [/extras/toc/] +toc: true +--- + +{{% note "TOC Heading Levels are Fixed" %}} - Currently, the `{{.TableOfContents}}` [page variable](/variables/page/) does not allow you to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `` is going to start at `

` when pulling from `{{.Content}}`. ++ ++Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `` was going to start at `

` when pulling from `{{.Content}}`. ++ ++Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer. ++ +{{% /note %}} + +## Usage + +Create your markdown the way you normally would with the appropriate headings. Here is some example content: + +``` + + +## Introduction + +One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. + +## My Heading + +He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. + +### My Subheading + +A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops +``` + +Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`. + - The built-in `.TableOfContents` variables outputs a `