diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-03-16 09:44:54 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-03-16 09:44:54 +0100 |
commit | 91fb8f1b59cce50de914d66dac1d406655c3c43b (patch) | |
tree | cc13ef74ea408384d69e24643fe4ad1c86ae0e27 | |
parent | ac12d51e7ea3a0ffb7d8053a10b6bf6acf1235ae (diff) | |
parent | 3886fc1fef6ac19d58b9ba1bb642d0c6c9a54031 (diff) |
Merge commit '3886fc1fef6ac19d58b9ba1bb642d0c6c9a54031'
26 files changed, 277 insertions, 90 deletions
diff --git a/docs/content/content-management/menus.md b/docs/content/content-management/menus.md index 26c1eafad..1353ce0e2 100644 --- a/docs/content/content-management/menus.md +++ b/docs/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/docs/content/content-management/multilingual.md b/docs/content/content-management/multilingual.md index f9c7a9ba3..eba196c39 100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/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/docs/content/content-management/page-bundles.md b/docs/content/content-management/page-bundles.md index fbb9025ca..f497a59b2 100644 --- a/docs/content/content-management/page-bundles.md +++ b/docs/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/docs/content/content-management/sections.md b/docs/content/content-management/sections.md index 0e167d143..e53e0feb7 100644 --- a/docs/content/content-management/sections.md +++ b/docs/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" >}} <ol class="nav navbar-nav"> {{ 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/docs/content/functions/title.md b/docs/content/functions/title.md index e3a7e9c0b..63a34835f 100644 --- a/docs/content/functions/title.md +++ b/docs/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/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 8fd72290f..292b3e68b 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/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,47 +72,47 @@ 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. frontmatter : See [Front matter Configuration](#configure-front-matter). 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). @@ -105,6 +123,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). @@ -118,7 +139,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. @@ -127,19 +148,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"). @@ -148,13 +169,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). @@ -162,14 +183,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. @@ -178,13 +199,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. @@ -193,7 +214,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/docs/content/getting-started/directory-structure.md b/docs/content/getting-started/directory-structure.md index f8b4cced6..ebfe6646a 100644 --- a/docs/content/getting-started/directory-structure.md +++ b/docs/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/docs/content/news/0.30-relnotes-ready.md b/docs/content/news/0.30-relnotes-ready.md index 06489cb31..7c2632ae6 100644 --- a/docs/content/news/0.30-relnotes-ready.md +++ b/docs/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/docs/content/news/0.34-relnotes/index.md b/docs/content/news/0.34-relnotes/index.md index de596fc62..dd5418a77 100644 --- a/docs/content/news/0.34-relnotes/index.md +++ b/docs/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/docs/content/showcase/forestry/bio.md b/docs/content/showcase/forestry/bio.md new file mode 100644 index 000000000..767365cc0 --- /dev/null +++ b/docs/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/docs/content/showcase/forestry/featured.png b/docs/content/showcase/forestry/featured.png Binary files differnew file mode 100644 index 000000000..1ee315e78 --- /dev/null +++ b/docs/content/showcase/forestry/featured.png diff --git a/docs/content/showcase/forestry/index.md b/docs/content/showcase/forestry/index.md new file mode 100644 index 000000000..ee1ebe07a --- /dev/null +++ b/docs/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://fo |