From: Bjørn Erik Pedersen Date: Fri, 16 Mar 2018 08:44:54 +0000 (+0100) Subject: Squashed 'docs/' changes from 4e7e1815b..211a3c613 X-Git-Tag: v0.38~5^2~2 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=3886fc1fef6ac19d58b9ba1bb642d0c6c9a54031;p=brevno-suite%2Fhugo Squashed 'docs/' changes from 4e7e1815b..211a3c613 211a3c613 Prepare the forestry.io article for release 23995d6b4 Add forestry.io to showcase 3f177c94e Fix some typos (found by codespell) dc26e0a5a Clarify the default for site config files and multiple config files c87c9c62e Review and update the Site config documentation for consistency a29edc50c Fix the default value of rssLimit site config 83f3c46b0 Minor style fix 4f860d1a2 Typo capitalization fixes 7851345c8 Add docs about comments within templates d129b4a28 Make the recommendation to use partial over template consistent 6cd260a41 Update index.md a2787e1a4 Add Let’s Encrypt showcase 7e664f69e Update configuration.md 8002120f1 Update multilingual.md 702b46a62 Add documentation for the disableLanguages setting cb3d395de Fix content type reference d33226924 Update Page Kinds documentation 8203f649d Fix misformed markdown link 19e99c957 Add Section definition git-subtree-dir: docs git-subtree-split: 211a3c6136c69f49baeae6cd35e5a8853cddf710 --- diff --git a/content/content-management/menus.md b/content/content-management/menus.md index 26c1eafa..1353ce0e 100644 --- a/content/content-management/menus.md +++ b/content/content-management/menus.md @@ -151,7 +151,7 @@ menu: {{< /code >}} {{% note %}} -The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. +The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. {{% /note %}} ## Nesting diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md index f9c7a9ba..eba196c3 100644 --- a/content/content-management/multilingual.md +++ b/content/content-management/multilingual.md @@ -59,6 +59,28 @@ If you want all of the languages to be put below their respective language code, Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. +## Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "jp"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr jp" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + ## Configure Multilingual Multihost From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. diff --git a/content/content-management/page-bundles.md b/content/content-management/page-bundles.md index fbb9025c..f497a59b 100644 --- a/content/content-management/page-bundles.md +++ b/content/content-management/page-bundles.md @@ -129,9 +129,7 @@ This `_index.md` can also be directly under the `content/` directory. {{% note %}} Here `md` (markdown) is used just as an example. You can use any file -type as a content resource as long as it is a MIME type recognized by -Hugo (`json` files will, as one example, work fine). If you want to -get exotic, you can define your own media type. +type as a content resource as long as it is a content type recognized by Hugo. {{% /note %}} diff --git a/content/content-management/sections.md b/content/content-management/sections.md index 0e167d14..e53e0feb 100644 --- a/content/content-management/sections.md +++ b/content/content-management/sections.md @@ -17,36 +17,50 @@ aliases: [/content/sections/] toc: true --- +A **Section** is a collection of pages that gets defined based on the +organization structure under the `content/` directory. + +By default, all the **first-level** directories under `content/` form their own +sections (**root sections**). + +If a user needs to define a section `foo` at a deeper level, they need to create +a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles] +for more information). + + +{{% note %}} +A **section** cannot be defined or overridden by a front matter parameter -- it +is strictly derived from the content organization structure. +{{% /note %}} ## Nested Sections The sections can be nested as deeply as you need. ```bash -blog -├── funny-cats -│   └── kittens -│   └── _index.md -└── tech - └── _index.md +content +└── blog <-- Section, because first-level dir under content/ + ├── funny-cats + │   ├── mypost.md + │   └── kittens <-- Section, because contains _index.md + │   └── _index.md + └── tech <-- Section, because contains _index.md + └── _index.md ``` - -**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** - +**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** {{% note %}} -When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`). +When we talk about a **section** in correlation with template selection, it is +currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`). If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter. {{% /note %}} - ## Example: Breadcrumb Navigation With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: - {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
    {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} @@ -71,15 +85,14 @@ Also see [Page Variables](/variables/page/). ## Content Section Lists -Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. +Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. ## Content *Section* vs Content *Type* -By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. +By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. [archetype]: /content-management/archetypes/ [content type]: /content-management/types/ [directory structure]: /getting-started/directory-structure/ [section templates]: /templates/section-templates/ - - +[branch bundles]: /content-management/page-bundles/#branch-bundles diff --git a/content/functions/title.md b/content/functions/title.md index e3a7e9c0..63a34835 100644 --- a/content/functions/title.md +++ b/content/functions/title.md @@ -24,7 +24,7 @@ aliases: [] {{title "BatMan"}}` → "Batman" ``` -Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Intial Caps. +Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Initial Caps. ``` {{ range $name, $items := .Site.Taxonomies.categories }} diff --git a/content/getting-started/configuration.md b/content/getting-started/configuration.md index b051347d..ed896fb6 100644 --- a/content/getting-started/configuration.md +++ b/content/getting-started/configuration.md @@ -18,10 +18,28 @@ aliases: [/overview/source-directory/,/overview/configuration/] toc: true --- +Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the +site root) as the default site config file. + +The user can choose to override that default with one or more site config files +using the command line `--config` switch. + +Examples: + +``` +hugo --config debugconfig.toml +hugo --config a.toml,b.toml,c.toml +``` + +{{% note %}} +Multiple site config files can be specified as a comma-separated string to the `--config` switch. +{{% /note %}} ## All Configuration Settings -The following is the full list of Hugo-defined variables with its default value in parens. +The following is the full list of Hugo-defined variables with their default +value in parentheses. Users may choose to override those values in their site +config file(s). archetypeDir ("archetypes") : The directory where Hugo finds archetype files (content templates). @@ -29,6 +47,9 @@ archetypeDir ("archetypes") baseURL : Hostname (and path) to the root, e.g. http://bep.is/ +blackfriday +: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday) + buildDrafts (false) : Include drafts when building. @@ -41,9 +62,6 @@ buildFuture (false) canonifyURLs (false) : Enable to turn relative URLs into absolute. -config ("config.toml") -: Config file (default is path/config.yaml|json|toml). - contentDir ("content") : The directory from where Hugo reads content files. @@ -54,43 +72,43 @@ defaultContentLanguage ("en") : Content without language indicator will default to this language. defaultContentLanguageInSubdir (false) -: Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/. +: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. disableHugoGeneratorInject (false) : Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. disableKinds ([]) -: Allows you to disable all page types and will render nothing related to 'kind'. Allowed values are "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404". +: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. disableLiveReload (false) -: Turn off automatic live reloading of browser window. +: Disable automatic live reloading of browser window. disablePathToLower (false) -: Do not make the url/path to lowercase. +: Do not convert the url/path to lowercase. enableEmoji (false) -: Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com. +: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). enableGitInfo (false) -: If the Hugo site is versioned by Git, you will then get a `.GitInfo` object per page, and `Lastmod` will get updated by the last commit date for content. +: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. enableMissingTranslationPlaceholders (false) -: Show a placeholder instead of the default value or an empty string if a translation is missing +: Show a placeholder instead of the default value or an empty string if a translation is missing. enableRobotsTXT (false) -: When enabled, Hugo will generate a `robots.txt` file. +: Enable generation of `robots.txt` file. footnoteAnchorPrefix ("") -: A prefix for your footnote anchors. +: Prefix for footnote anchors. footnoteReturnLinkContents ("") -: A return link for your footnote. +: Text to display for footnote return links. googleAnalytics ("") -: google analytics tracking id +: Google Analytics tracking ID. hasCJKLanguage (false) -: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly in CJK languages. +: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. imaging : See [Image Processing Config](/content-management/image-processing/#image-processing-config). @@ -101,6 +119,9 @@ languages languageCode ("") : The site's language code. +disableLanguages +: See [Disable a Language](/content-management/multilingual/#disable-a-language) + layoutDir ("layouts") : The directory from where Hugo reads layouts (templates). @@ -114,7 +135,7 @@ menu : See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). metaDataFormat ("toml") -: "toml","yaml", or "json" +: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`. newContentEditor ("") : The editor to use when creating new content. @@ -123,19 +144,19 @@ noChmod (false) : Don't sync permission mode of files. noTimes (false) -: Don't sync modification time of files +: Don't sync modification time of files. paginate (10) -: Default number of pages per page in pagination. +: Default number of pages per page in [pagination](/templates/pagination/). paginatePath ("page") -: The path element used during pagination (http://example.com/page/2). +: The path element used during pagination (https://example.com/page/2). permalinks -: See [Content Management](/content-management/urls/#permalinks) +: See [Content Management](/content-management/urls/#permalinks). pluralizeListTitles (true) -: Pluralize titles in lists using inflect. +: Pluralize titles in lists. preserveTaxonomyNames (false) : Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu"). @@ -144,13 +165,13 @@ publishDir ("public") : The directory to where Hugo will write the final static site (the HTML files etc.). pygmentsCodeFencesGuessSyntax (false) -: Enables syntax guessing for code fences without specified language. +: Enable syntax guessing for code fences without specified language. pygmentsStyle ("monokai") -: Color-codes for highlighting derived from this style. See https://help.farbox.com/pygments.html +: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html). pygmentsUseClasses (false) -: Enable to use external CSS for code highlighting. +: Enable using external CSS for syntax highlighting. related : See [Related Content](/content-management/related/#configure-related-content). @@ -158,14 +179,14 @@ related relativeURLs (false) : Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. -rssLimit (15) +rssLimit (unlimited) : Maximum number of items in the RSS feed. -sectionPagesMenu ("")( +sectionPagesMenu ("") : See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). sitemap -: Default sitemap configuration. +: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml). staticDir ("static") : Relative directory from where Hugo reads static files. @@ -174,13 +195,13 @@ stepAnalysis (false) : Display memory and timing of different steps of the program. summaryLength (70) -: The length of text to show in a `.Summary`. +: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting). taxonomies -: See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies) +: See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies). theme ("") -: Theme to use (located by default in /themes/THEMENAME/) +: Theme to use (located by default in `/themes/THEMENAME/`). themesDir ("themes") : The directory where Hugo reads the themes from. @@ -189,7 +210,7 @@ title ("") : Site title. uglyURLs (false) -: When enabled creates URL on the form `/filename.html` instead of `/filename/` +: When enabled, creates URL on the form `/filename.html` instead of `/filename/`. verbose (false) : Enable verbose output. diff --git a/content/getting-started/directory-structure.md b/content/getting-started/directory-structure.md index f8b4cced..ebfe6646 100644 --- a/content/getting-started/directory-structure.md +++ b/content/getting-started/directory-structure.md @@ -42,7 +42,7 @@ The following is a high-level overview of each of the directories with links to [`archetypes`](/content-management/archetypes/) : You can create new content files in Hugo using the `hugo new` command. -By default, hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well. +By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well. [`config.toml`](/getting-started/configuration/) : Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website. @@ -58,7 +58,7 @@ used by Hugo when generating your website. You can write these files in YAML, JS : Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more. [`static`][] -: stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content. +: Stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content. {{% note %}} From **Hugo 0.31** you can have multiple static directories. diff --git a/content/news/0.30-relnotes-ready.md b/content/news/0.30-relnotes-ready.md index 06489cb3..7c2632ae 100644 --- a/content/news/0.30-relnotes-ready.md +++ b/content/news/0.30-relnotes-ready.md @@ -14,7 +14,7 @@ Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but muc The second performance-related feature is a follow-up to the Template Metrics added in Hugo `0.29`. Now, if you add the flag `--templateMetricsHints`, we will calculate a score for how your partials can be cached (with the `partialCached` template func). -This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most noteable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier. +This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most notable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier. This release represents **31 contributions by 10 contributors** to the main Hugo code base. [@bep](https://github.com/bep) leads the Hugo development with a significant amount of contribution, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@digitalcraftsman](https://github.com/digitalcraftsman), and [@bmon](https://github.com/bmon) for their ongoing contributions. diff --git a/content/news/0.34-relnotes/index.md b/content/news/0.34-relnotes/index.md index de596fc6..dd5418a7 100644 --- a/content/news/0.34-relnotes/index.md +++ b/content/news/0.34-relnotes/index.md @@ -32,7 +32,7 @@ Hugo now has: * 197+ [themes](http://themes.gohugo.io/) ## Notes -* `Resources.GetByPrefix` and `Resources.ByPrefix` are depracated. They still work, but will eventually be removed. Use `Resources.Match` (many) and `Resources.GetMatch` (one). +* `Resources.GetByPrefix` and `Resources.ByPrefix` are deprecated. They still work, but will eventually be removed. Use `Resources.Match` (many) and `Resources.GetMatch` (one). * When filtering bundles pages in sub-folders, you need to include the sub-folder when matching. This was a bug introduced in `0.33` and gets it in line with images and other resources. ## Enhancements diff --git a/content/showcase/forestry/bio.md b/content/showcase/forestry/bio.md new file mode 100644 index 00000000..767365cc --- /dev/null +++ b/content/showcase/forestry/bio.md @@ -0,0 +1,5 @@ + +Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. + +Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams. + diff --git a/content/showcase/forestry/featured.png b/content/showcase/forestry/featured.png new file mode 100644 index 00000000..1ee315e7 Binary files /dev/null and b/content/showcase/forestry/featured.png differ diff --git a/content/showcase/forestry/index.md b/content/showcase/forestry/index.md new file mode 100644 index 00000000..ee1ebe07 --- /dev/null +++ b/content/showcase/forestry/index.md @@ -0,0 +1,48 @@ +--- +title: Forestry.io +date: 2018-03-16 +description: "A Git-backed CMS (content management system) for websites and web products built using static site generators." +siteURL: https://forestry.io/ +siteSource: https://github.com/forestryio/forestry.io +--- + +It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us? + +### Why Hugo? + +In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast. + +We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look: + +```bash + | EN ++------------------+-----+ + Pages | 141 + Paginator pages | 4 + Non-page files | 0 + Static files | 537 + Processed images | 0 + Aliases | 60 + Sitemaps | 1 + Cleaned | 0 + +Total in 739 ms +``` + +In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing. + +Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website. + +### What tools did we use? + +* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a designer’s dream come true. +* Some say our main graphic is [mesmerizing](https://twitter.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview). +* [**Hugo**](https://gohugo.io/) -- of course. +* Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization. +* Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes. +* We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia]([https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](https://gohugo.io/templates/output-formats/). +* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. +* We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer. +* For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/). +* [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests. +* We also use browser cookies and JS to customize our user’s experience and give it a more dynamic feel. \ No newline at end of file diff --git a/content/showcase/letsencrypt/bio.md b/content/showcase/letsencrypt/bio.md new file mode 100644 index 00000000..24d7b96e --- /dev/null +++ b/content/showcase/letsencrypt/bio.md @@ -0,0 +1,3 @@ + + +Let's Encrypt is a free, automated, and open certificate authority (CA), run for the public's benefit. It is a service provided by the [Internet Security Research Group (ISRG)](https://letsencrypt.org/isrg/). diff --git a/content/showcase/letsencrypt/featured.png b/content/showcase/letsencrypt/featured.png new file mode 100644 index 00000000..9535d91b Binary files /dev/null and b/content/showcase/letsencrypt/featured.png differ diff --git a/content/showcase/letsencrypt/index.md b/content/showcase/letsencrypt/index.md new file mode 100644 index 00000000..8487a3c7 --- /dev/null +++ b/content/showcase/letsencrypt/index.md @@ -0,0 +1,21 @@ +--- +title: "Let’s Encrypt" +date: 2018-03-13 +description: "Showcase: Lessons learned from taking letsencrypt.org to Hugo." +siteURL: https://letsencrypt.org/ +siteSource: https://github.com/letsencrypt/website +byline: "[bep](https://github.com/bep), Hugo Lead" +--- + +The **Let’s Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1] + +{{< tweet 971755920639307777 >}} + +I helped them port the site from Jekyll to Hugo. There are usually very few surprises doing this. I know Hugo very well, but working on sites with a history usually comes up with something new. + +That site is bookmarked in many browsers, so preserving the URLs was a must. Hugo's URL handling is very flexible, but there was one challenge. The website has a mix of standard and what we in Hugo call _ugly URLs_ (`https://letsencrypt.org/2017/12/07/looking-forward-to-2018.html`). In Hugo this is handled automatically, and you can turn it on globally or per language. But before Hugo `0.33` you could not configure it for parts of your site. You could set it manually for the relevant pages in front matter -- which is how it was done in Jekyll -- but that would be hard to manage, especially when you start to introduce translations. So, in [Hugo 0.33](https://gohugo.io/news/0.33-relnotes/) I added support for _ugly URLs_ per section and also `url` set in front matter for list pages (`https://letsencrypt.org/blog/`). + +The lessons learned from this also lead to [disableLanguages](/content-management/multilingual/#disable-a-language) in Hugo `0.34` (a way to turn off languages during translation). And I also registered [this issue](https://github.com/gohugoio/hugo/issues/4463). Once fixed it will make it easier to handle partially translated sites. + + +[^1]: The work on getting the content translated is in progress. diff --git a/content/templates/introduction.md b/content/templates/introduction.md index 0f4e8e3d..95db7eab 100644 --- a/content/templates/introduction.md +++ b/content/templates/introduction.md @@ -109,22 +109,35 @@ There are more boolean operators than those listed in the Hugo docs in the [Gola ## Includes -When including another template, you will pass to it the data it will be -able to access. To pass along the current context, please remember to -include a trailing dot. The templates location will always be starting at -the `/layouts/` directory within Hugo. +When including another template, you will need to pass it the data that it would +need to access. -### Template and Partial Examples +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include *partial* templates using +the syntax `{{ partial "/." . }}`. + +Example: ``` -{{ template "partials/header.html" . }} +{{ partial "header.html" . }} ``` -Starting with Hugo v0.12, you may also use the `partial` call -for [partial templates][partials]: +### Template + +The `template` function was used to include *partial* templates in much older +Hugo versions. Now it is still useful for calling [*internal* +templates][internal_templates]: ``` -{{ partial "header.html" . }} +{{ template "_internal/opengraph.html" . }} ``` ## Logic @@ -261,7 +274,7 @@ Stuff Here {{ end }} ``` -### Example 4: Internet Explorer Conditional Comments +### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments} By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: @@ -361,6 +374,45 @@ Go considers the following characters whitespace: * carriage return * newline +## Comments + +In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. + +### Go templates comments + +Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. + +For example: + +``` +Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. +``` + +Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block. + +### HTML comments + +If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: + +``` +{{ printf "" .Site.Title | safeHTML }} +``` + +#### HTML comments containing Go templates + +HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. + +{{% note %}} +Do **not** try to comment out Go template code using HTML comments. +{{% /note %}} + +``` + +{{ $author }} +``` + +The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. + ## Hugo Parameters Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file. @@ -479,6 +531,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function] [index]: /functions/index/ [math functions]: /functions/math/ [partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs" +[internal_templates]: /templates/internal/ [relpermalink]: /variables/page/ [safehtml]: /functions/safehtml/ [sitevars]: /variables/site/ diff --git a/content/templates/pagination.md b/content/templates/pagination.md index 24d806ea..22acb307 100644 --- a/content/templates/pagination.md +++ b/content/templates/pagination.md @@ -96,11 +96,11 @@ If you want to build custom navigation, you can do so using the `.Paginator` obj `PageNumber` : The current page's number in the pager sequence -`URL`: -The relative URL to the current pager +`URL` +: The relative URL to the current pager -`Pages`: -The pages in the current pager +`Pages` +: The pages in the current pager `NumberOfElements` : The number of elements on this page @@ -152,4 +152,4 @@ The pages are built on the following form (`BLANK` means no value): [`after`]: /functions/after/ [configuration]: /getting-started/configuration/ [lists]: /templates/lists/ -[where]: /functions/where/ \ No newline at end of file +[where]: /functions/where/ diff --git a/content/templates/partials.md b/content/templates/partials.md index 0d2a9f47..4cb7fb3a 100644 --- a/content/templates/partials.md +++ b/content/templates/partials.md @@ -67,10 +67,6 @@ As shown in the above example directory structure, you can nest your directories {{ partial "footer/scripts.html" . }} ``` -{{% note %}} -Before v0.12, Hugo used the `template` call to include partial templates. When using Hugo v0.12 and newer, be sure to use the `{{ partial "/.html" . }}` syntax. The old approach will still work but has fewer benefits. -{{% /note %}} - ### Variable Scoping The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context]. @@ -166,4 +162,4 @@ The following `footer.html` partial template is used for [spf13.com](http://spf1 [lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order." [partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page." [singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages." -[themes]: /themes/ \ No newline at end of file +[themes]: /themes/ diff --git a/content/templates/section-templates.md b/content/templates/section-templates.md index 60e486ec..577529e3 100644 --- a/content/templates/section-templates.md +++ b/content/templates/section-templates.md @@ -26,25 +26,31 @@ To effectively leverage section page templates, you should first understand Hugo See [Template Lookup](/templates/lookup-order/). -## `.Site.GetPage` with Sections +## Page Kinds -Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. +Every `Page` in Hugo has a `.Kind` attribute. -The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. +| Kind | Description | Example | +|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------| +| `home` | The home page | `/index.html` | +| `page` | A page showing a _regular page_ | `my-post` page (`/posts/my-post/index.html`) | +| `section` | A page listing _regular pages_ from a given [_section_][sections] | `posts` section (`/posts/index.html`) | +| `taxonomy` | A page listing _regular pages_ from a given _taxonomy term_ | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) | +| `taxonomyTerm` | A page listing terms from a given _taxonomy_ | page for the `tags` taxonomy (`/tags/index.html`) | -{{% note %}} -`.GetPage` is not currently supported to grab single content files but *may* be supported in the future. -{{% /note %}} +## `.Site.GetPage` with Sections -You can call `.Site.GetPage` with two arguments: `kind` and `kind value`. +`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. + +The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. -These are the valid values for 'kind': +You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values +of `Kind` from above) and `kind value`. -1. `home` -2. `section` -3. `taxonomy` -4. `taxonomyTerm` +Examples: +- `{{ .Site.GetPage "section" "posts" }}` +- `{{ .Site.GetPage "page" "search" }}` ## Example: Creating a Default Section Template @@ -113,3 +119,4 @@ Which then returns the following: [lists]: /templates/lists/ [lookup]: /templates/lookup-order/ [where]: /functions/where/ +[sections]: /content-management/sections/ diff --git a/content/tools/search.md b/content/tools/search.md index 4d5779b9..149bdfe0 100644 --- a/content/tools/search.md +++ b/content/tools/search.md @@ -22,7 +22,7 @@ A static website with a dynamic search function? Yes. As alternatives to embedda * [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results. * [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project. -* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you seperate the Chinese keywords. +* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords. * [Github Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](http://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo! ## Commercial Search Services diff --git a/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_1024x512_fill_catmullrom_top_2.png b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_1024x512_fill_catmullrom_top_2.png new file mode 100644 index 00000000..9a88db50 Binary files /dev/null and b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_1024x512_fill_catmullrom_top_2.png differ diff --git a/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_192a300d3ccaa4371c674791fb50a62c.png b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_192a300d3ccaa4371c674791fb50a62c.png new file mode 100644 index 00000000..a25b83ef Binary files /dev/null and b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_192a300d3ccaa4371c674791fb50a62c.png differ diff --git a/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_640x0_resize_catmullrom_2.png b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_640x0_resize_catmullrom_2.png new file mode 100644 index 00000000..7c98b045 Binary files /dev/null and b/resources/_gen/images/showcase/forestry/featured_hu77de7d99834fa13b854b7fc62e2912a7_227009_640x0_resize_catmullrom_2.png differ diff --git a/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_1024x512_fill_catmullrom_top_2.png b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_1024x512_fill_catmullrom_top_2.png new file mode 100644 index 00000000..5df68ea1 Binary files /dev/null and b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_1024x512_fill_catmullrom_top_2.png differ diff --git a/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_640x0_resize_catmullrom_2.png b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_640x0_resize_catmullrom_2.png new file mode 100644 index 00000000..7589afd5 Binary files /dev/null and b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_640x0_resize_catmullrom_2.png differ diff --git a/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_825bc0f79626434a7ab711238e84984a.png b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_825bc0f79626434a7ab711238e84984a.png new file mode 100644 index 00000000..9e531de4 Binary files /dev/null and b/resources/_gen/images/showcase/letsencrypt/featured_hu51cfa254cfc1fb105704d2cdd6ae4737_147459_825bc0f79626434a7ab711238e84984a.png differ