diff --git a/content/content-management/archetypes.md b/content/content-management/archetypes.md index f1d1e5770..bcb6f6b93 100644 --- a/content/content-management/archetypes.md +++ b/content/content-management/archetypes.md @@ -70,7 +70,7 @@ Similar to the lookup order for [templates in the `layouts` directory][lookup], 5. `_internal` (i.e., `title` and `date`) {{% note "Using a Theme Archetype" %}} -If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/project-organization/configuration/). +If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/getting-started/configuration/). {{% /note %}} ## Choosing Your Front Matter Format @@ -185,7 +185,7 @@ The preceding archetype is kept up to date with every Hugo build by using Hugo's [archetypes directory]: /getting-started/directory-structure/ [`now()`]: http://golang.org/pkg/time/#Now -[configuration file]: /project-organization/configuration/ +[configuration file]: /getting-started/configuration/ [sections]: /sections/ [content types]: /content-management/types/ [front matter]: /content-management/front-matter/ diff --git a/content/content-management/formats.md b/content/content-management/formats.md index ed7798f64..57bd16125 100644 --- a/content/content-management/formats.md +++ b/content/content-management/formats.md @@ -1,6 +1,6 @@ --- title: Supported Content Formats -linktitle: Content Formats +linktitle: Formats description: Markdown is natively supported in Hugo and is parsed by the feature-rich and incredibly speed Blackfriday parse. Hugo also provides support for additional syntaxes (eg, Asciidoc) via external helpers. date: 2017-01-10 publishdate: 2017-01-10 @@ -11,7 +11,6 @@ weight: 20 draft: false aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/] toc: true -notesforauthors: --- ## Markdown diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md index fd6f71f9e..3e3093998 100644 --- a/content/content-management/front-matter.md +++ b/content/content-management/front-matter.md @@ -107,7 +107,7 @@ If neither `slug` nor `url` is present, and [permalinks are not configured other It's possible to set some options for Markdown rendering in the page's front matter as an override to the site-wide configuration. -See [site configuration][] for more information on setting up global Blackfriday options. +See [site configuration][config] for more information on setting up global Blackfriday options. ## Parameters @@ -124,8 +124,8 @@ See [site configuration][] for more information on setting up global Blackfriday * [JSON Spec][] [aliases]: /content-management/urls/#aliases/ +[config]: /getting-started/configuration/ "Hugo documentation for site configuration" [content type]: /content-management/types/ -[site configuration]: /project-organization/configuration/ "Hugo documentation for site configuration" [JSON Spec]: /documents/ecma-404-json-spec.pdf "Specification for JSON, JavaScript Object Notation" [TOML Spec]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" [YAML Spec]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --git a/content/content-management/organization.md b/content/content-management/organization.md index e621810cd..830f5fa60 100644 --- a/content/content-management/organization.md +++ b/content/content-management/organization.md @@ -1,6 +1,6 @@ --- title: Content Organization -linktitle: Content Organization +linktitle: Organization description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. date: 2017-02-01 publishdate: 2017-02-01 @@ -14,21 +14,139 @@ toc: true wip: true --- -## Introduction +## Organization of Content Source -Hugo uses files (see [Hugo's supported content formats][formats]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][urls]. +In Hugo, your content should be organized in a manner that reflects the rendered website. -## Organizing Content Source +While Hugo supports content nested at any level, the top levels (i.e. `content/*`) are special in Hugo and considered the content [sections][section]. Without any additional configuration, the following will just work: -In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/*``) is special in Hugo and is considered the content [section][]. +``` +. +└── content + └── about + | └── _index.md // <- http://yoursite.com/about/ + ├── post + | ├── firstpost.md // <- http://yoursite.com/post/firstpost/ + | ├── happy + | | └── ness.md // <- http://yoursite.com/post/happy/ness/ + | └── secondpost.md // <- http://yoursite.com/post/secondpost/ + └── quote + ├── first.md // <- http://yoursite.com/quote/first/ + └── second.md // <- http://yoursite.com/quote/second/ +``` -## Destinations +## Path Breakdown in Hugo + +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website at render. These examples assume you are using pretty URLs, which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your site's configuration file. + +### Section Index Page + +`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [section list template][sectionlists] as of v0.18. + +You can keep one `_index.md` in each of your content sections. The following shows typical placement of an `_index.md` that would contain content or front matter for a `posts` section list page on a Hugo website: + + +```bash +. url +. ⊢------^------⊣ +. path slug +. ⊢--^-⊣⊢---^---⊣ +. filepath +. ⊢------^------⊣ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + +```bash + + url ("/posts/") + ⊢-^-⊣ + baseurl section ("posts") +⊢--------^---------⊣⊢-^-⊣ + permalink +⊢----------^-------------⊣ +http://yoursite.com/posts/index.html +``` + +### Section Single Page + +Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: + + +```bash + path ("posts/my-first-hugo-post.md") +. ⊢-----------^------------⊣ +. section slug +. ⊢-^-⊣⊢--------^----------⊣ +content/posts/my-first-hugo-post.md +``` + +At the time Hugo renders your site, the content will be output to the following destination: + +```bash + + url ("/posts/my-first-hugo-post/") + ⊢------------^----------⊣ + baseurl section slug +⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ + permalink +⊢--------------------^---------------------⊣ +http://yoursite.com/posts/my-first-hugo-post/index.html +``` + +### Section with Nested Directories + +To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site: + + +```bash + section + ⊢--^--⊣ + url + ⊢-------------^------------⊣ + + baseURL path slug +⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣ + permalink +⊢----------------------^-----------------------⊣ +http://yoursite.com/events/chicago/lollapalooza/ +``` + +## + +#### `section` + +Default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. + +#### `slug` + +A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by + +* the name of the content file (e.g., `content-name.md`) +* front matter overrides + +#### `path` + +A content's `path` is determined by the section's path to the file. The file `path` + +* is based on the path to the content's location +* does not include the slug + +#### `url` + +The `url` is the relative URL for the piece of content. The `url` + +* is defined in front matter +* overrides all the above + +## Destinations for Content Source Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination. -Notice that the first level `about/` page URL was created using a directory named "about" with a single `_index.md` file inside. Find out more about `_index.md` specifically in [content for the homepage and other list pages](https://gohugo.io/overview/source-directory#content-for-home-page-and-other-list-pages). +Notice that the first level `about/` page URL was created using a directory named "about" with a single `_index.md` file inside.. -There are times when one would need more control over their content. In these cases, there are a variety of things that can be specified in the front matter to determine the destination of a specific piece of content. +There are times where you may need more control over your content. In these cases, there are a variety of things that can be specified in the front matter to determine the destination of a specific piece of content. The following items are defined in order; latter items in the list will override earlier settings. @@ -60,95 +178,6 @@ The actual path to the file on disk. Destination will create the destination wit A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a "/"). When a `url` is provided, it will be used exactly. Using `url` will ignore the `--uglyURLs` setting. - -## Path Breakdown in Hugo - -### Content - -```bash -. path slug -. ⊢-------^----⊣ ⊢------^-------⊣ -content/extras/indexes/category-example/index.html -``` - -```bash -. section slug -. ⊢--^--⊣ ⊢------^-------⊣ -content/extras/indexes/category-example/index.html -``` - -```bash -. section slug -. ⊢--^--⊣⊢--^--⊣ -content/extras/indexes/index.html -``` - -### Destination - -```bash - permalink -⊢--------------^-------------⊣ -http://spf13.com/projects/hugo -``` - -```bash - baseURL section slug -⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣ -http://spf13.com/projects/hugo -``` - -```bash - baseURL section slug -⊢-----^--------⊣ ⊢--^--⊣ ⊢--^--⊣ -http://spf13.com/extras/indexes/example -``` - -```bash - baseURL path slug -⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣ -http://spf13.com/extras/indexes/example -``` - -```bash - baseURL url -⊢-----^--------⊣ ⊢-----^-----⊣ -http://spf13.com/projects/hugo -``` - -```bash - baseURL url -⊢-----^--------⊣ ⊢--------^-----------⊣ -http://spf13.com/extras/indexes/example -``` - -#### `section` - -A section is the content type the piece of content is assigned to by default. `section` is determined by the following: - -* content location within the project's directory structure -* front matter overrides - -#### `slug` - -A content's `slug` is either `name.extension` or `name/`. `slug` is determined by the following: - -* the name of the content file (e.g., `content-name.md`) -* front matter overrides - -#### `path` - -A content's `path` is determined by the section's path to the file. `path` - -* is based on the path to the content's location -* excludes the slug - -#### `url` - -The `url` is the relative URL for the piece of content. The `url` - -* is defined in front matter -* overrides all the above - ## \_index.md and "Everything is a Page" As of version v0.18, Hugo now treats "[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)". This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomy list pages][taxonomytemplates], [taxonomy terms pages](/templates/terms/) and even to potential "special case" pages like the [homepage][]. @@ -265,5 +294,6 @@ Hugo themes are designed to use the 'content' directory as the root of the websi [homepage]: /templates/homepage/ [section]: /content-management/section/ [formats]: /content-management/formats/ +[sectionlists]: /templates/section-templates/ [singles]: /templates/single-page-templates/ [urls]: /content-management/urls/ diff --git a/content/content-management/shortcodes.md b/content/content-management/shortcodes.md index 366446ad8..2c02702b5 100644 --- a/content/content-management/shortcodes.md +++ b/content/content-management/shortcodes.md @@ -405,7 +405,6 @@ To learn more about creating your own shortcode templates, see the [shortcode te [pagevariables]: /variables/page-variables/ [partials]: /templates/partials-templates/ [Pygments]: http://pygments.org/ -[projectorganizationsection]: /project-organization/directory-structure/ [quickstart]: /getting-started/quick-start/ [shortcode template documentation]: /templates/shortcode-templates/ [Speaker Deck]: https://speakerdeck.com/ diff --git a/content/content-management/taxonomies.md b/content/content-management/taxonomies.md index ca06e2dd2..443ec6899 100644 --- a/content/content-management/taxonomies.md +++ b/content/content-management/taxonomies.md @@ -25,9 +25,14 @@ Taxonomies were previously known as *indexes* in Hugo before v0.11. In order to effectively work with taxonomies in Hugo, it's important to first understand the language used to described the concept. -* **Taxonomy:** A categorization that can be used to classify content -* **Term:** A key within that taxonomy -* **Value:** A piece of content assigned to that Term +Taxonomy +: a categorization that can be used to classify content + +Term +: A key within the taxonomy + +Value +: A piece of content assigned to a term ### Example Taxonomy: Movie Website @@ -94,7 +99,7 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a ## Configuring Taxonomies -Taxonomies must be defined in your [website configuration][] before they can be +Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. @@ -123,7 +128,7 @@ taxonomies: ### Overriding Hugo's Default Taxonomies -If you do not specify any taxonomies in your [site configuration][] file *and* your content already includes front matter with `tags:` or `categories`, Hugo will automatically create taxonomy pages. To override this behavior, set the key-value pairs for both of the default taxonomies to empty strings in your `config` file. +If you do not specify any taxonomies in your site configuration file *and* your content already includes front matter with `tags:` or `categories`, Hugo will automatically create taxonomy pages. To override this behavior, set the key-value pairs for both of the default taxonomies to empty strings in your `config` file. {{% code file="remove-default-taxonomies-config.toml" %}} ```toml @@ -145,7 +150,7 @@ taxonomies: By default, taxonomy names are hyphenated, lower-cased, normalized, and then fixed and title-ized within. -Therefore, if you want to have a taxonomy value with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, you need to set the value for `preserveTaxonomyNames` in your [site configuration][] to `true`. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs. +Therefore, if you want to have a taxonomy value with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, you need to set the value for `preserveTaxonomyNames` in your [site configuration][config] to `true`. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs. Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][]. @@ -249,9 +254,7 @@ Currently taxonomies only support the default ordering of content which is weigh [content type]: /content-type/ [documentation on archetypes]: /content-management/archetypes/ [front matter]: /content-management/front-matter/ -[project organization]: /project-organization/ -[site configuration]: /project-organization/configuration/ [taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates [taxonomy templates]: /templates/taxonomy-templates/ [taxonomy terms templates]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy" -[website configuration]: /project-organization/configuration/ \ No newline at end of file +[config]: /getting-started/configuration/ \ No newline at end of file diff --git a/content/content-management/urls.md b/content/content-management/urls.md index 00166fd28..0604b9c57 100644 --- a/content/content-management/urls.md +++ b/content/content-management/urls.md @@ -16,7 +16,9 @@ wip: true ## Permalinks -By default, a Hugo-built site is laid out into the target `publishdir` specified in your [site configuration][configuration]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder. namespace matching its layout within the `contentdir` hierarchy. The `permalinks` option in your [site configuration][] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. +By default, Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishdir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy. + +The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. {{% note "Default Publish and Content Folders" %}} These examples use the default values for `publishDir` and `contentDir`; i.e., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). @@ -57,7 +59,7 @@ The following is a list of values that can be used in a `permalink` definition i * `:yearday` = the 1- to 3-digit day of the year * `:section` = the content's section * `:title` = the content's title -* `:slug` = the content's slug (or title if no slug) +* `:slug` = the content's slug (or title if no slug is provided in the front matter) * `:filename` = the content's filename (without extension) ## Example @@ -167,9 +169,9 @@ content/posts/post-3.md ## Ugly URLs -If you would like to have what we call "ugly URLs" (e.g., http://example.com/extras/urls.html), set `uglyurls = true` or `uglyurls: true` to your site-wide `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][]. +If you would like to have what we call "ugly URLs" (e.g., http://example.com/extras/urls.html), set `uglyurls = true` or `uglyurls: true` to your site-wide `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage]. -If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be run with the default See [Content Organization][] for more details. +If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be run with the default. See [Content Organization][contentorg] for more details. ```bash . @@ -230,22 +232,23 @@ Or, if you are on Windows and do not have `grep` installed: hugo config | FINDSTR /I canon ``` -## Overriding URLS in Front Matter +## Overriding URLS with Front Matter -**Need explanation of *slug* and *url* here** +In addition to specifying permalink values in your site configuration for different sections of content, Hugo provides even more granular for individual pieces of content. + +Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, seee [Content Organization][contentorg]. ## Relative URLs By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. -Setting `relativeURLs` to `true` in your [site configuration][configuration] will cause Hugo to rewrite all relative URLs to be relative to the current content. +Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. For example, if the `/post/first/` page contained a link to `/about/`, Hugo would rewrite that URL to `../../about/`. -[configuration]: /getting-started/configuration/ -[Content Organization]: /content-management/organization/ -[flag from the command line]: /getting-started/usage/ +[config]: /getting-started/configuration/ +[contentorg]: /content-management/organization/ [front matter]: /content-management/front-matter/ [multilingual]: /content-management/multilingual/ [sections]: /content-management/sections/ -[site configuration]: /project-organization/configuration/ \ No newline at end of file +[usage]: /getting-started/usage/ \ No newline at end of file diff --git a/content/functions/jsonify.md b/content/functions/jsonify.md index 3468ae79e..1385b52b1 100644 --- a/content/functions/jsonify.md +++ b/content/functions/jsonify.md @@ -7,18 +7,21 @@ date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-02-01 categories: [functions] -tags: [] +tags: [strings,json] signature: workson: [] hugoversion: -relatedfuncs: [] +relatedfuncs: [plainify] deprecated: false aliases: [] --- -`jsonify` encodes a given object to JSON. +`jsonify` encodes a given object to JSON and converts it to HTML-safe content. ``` {{ dict "title" .Title "content" .Plain | jsonify }} ``` +See also the [`.PlainWords`, `.Plain`, and `.RawContent` page variables][pagevars]. + +[pagevars]: /variables/page-variables/ \ No newline at end of file diff --git a/content/functions/plainify.md b/content/functions/plainify.md index cb255fb33..83b669c31 100644 --- a/content/functions/plainify.md +++ b/content/functions/plainify.md @@ -11,7 +11,7 @@ tags: [strings] signature: workson: [] hugoversion: -relatedfuncs: [] +relatedfuncs: [jsonify] deprecated: false aliases: [] --- @@ -22,4 +22,9 @@ aliases: [] {{ "BatMan" | plainify }} → "BatMan" ``` +See also the [`.PlainWords`, `.Plain`, and `.RawContent` page variables][pagevars]. + + +[pagevars]: /variables/page-variables/ + diff --git a/content/functions/relpermalink.md b/content/functions/relpermalink.md new file mode 100644 index 000000000..d85b8f1e2 --- /dev/null +++ b/content/functions/relpermalink.md @@ -0,0 +1,21 @@ +--- +title: relpermalink +linktitle: RelPermalink +description: +godocref: +date: 2017-03-04 +publishdate: 2017-03-04 +lastmod: 2017-03-04 +categories: [functions] +tags: [urls, permalinks] +signature: +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +wip: true +needsexamples: true +--- + +**NEEDS CONTENT: explanation and examples** \ No newline at end of file diff --git a/content/getting-started/configuration.md b/content/getting-started/configuration.md index aa133e3d6..c37fc2bc8 100644 --- a/content/getting-started/configuration.md +++ b/content/getting-started/configuration.md @@ -5,7 +5,7 @@ description: Hugo is designed to make enough assumptions that often configuratio date: 2017-01-02 publishdate: 2017-01-02 lastmod: 2017-01-02 -categories: [project organization] +categories: [getting started] tags: [configuration,fundamentals,toml,yaml,json] weight: 60 draft: false @@ -14,7 +14,7 @@ toc: true notesforauthors: --- -The [directory structure][] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to statically generate a finished website. +The [directory structure][dirs] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to statically generate a finished website. Because of Hugo's preference for sane defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns (and even expects them by default). @@ -377,7 +377,7 @@ blackfriday: * [JSON Spec][json] [`.Site.Params`]: /variables/ -[directory structure]: /project-organization/directory-structure +[dirs]: /getting-started/directory-structure [json]: /documents/ecma-404-json-spec.pdf [templates]: /templates/ [toml]: https://github.com/toml-lang/toml diff --git a/content/templates/go-templates.md b/content/templates/go-templates.md index eb71a6cd6..d3650fba9 100644 --- a/content/templates/go-templates.md +++ b/content/templates/go-templates.md @@ -405,9 +405,9 @@ We want the *default* behavior to be for pages to include a TOC unless otherwise ## Using Site Configuration Parameters -In your [site's configuration file][hugoconfig] (e.g., `config.yaml`), you can define site-level parameters that are available to you as variables throughout your templates. +You can arbitrarily define as many site-level parameters as you want in n your [site's configuration file][hugoconfig]. These parameters are globally available in your templates. -For instance, you might declare: +For instance, you might declare the following: {{% code file="config.yaml" %}} ```yaml @@ -440,7 +440,7 @@ An alternative way of writing the "`if`" and then referencing the same value is ``` {{% /code %}} -Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`](/functions/first/) and [`.RelPermalink`](/functions/relpermalink/) functions as well as the [`.Site.Pages` variable](/variables/site-variables/). +Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] and [`.RelPermalink`][relpermalink] functions, as well as the [`.Site.Pages`][sitevars] variable. ```html