mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-19 12:54:57 -04:00
Make further improvements to content organization page
This commit is contained in:
Ryan Watters
parent
4b2d20fc7b
commit
90d7bfedd0
@ -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/
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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/<directories>*`) 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/<directories>*``) 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/
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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/
|
||||
[config]: /getting-started/configuration/
|
||||
@ -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/
|
||||
[usage]: /getting-started/usage/
|
||||
@ -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/
|
||||
@ -11,7 +11,7 @@ tags: [strings]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
relatedfuncs: [jsonify]
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
@ -22,4 +22,9 @@ aliases: []
|
||||
{{ "<b>BatMan</b>" | plainify }} → "BatMan"
|
||||
```
|
||||
|
||||
See also the [`.PlainWords`, `.Plain`, and `.RawContent` page variables][pagevars].
|
||||
|
||||
|
||||
[pagevars]: /variables/page-variables/
|
||||
|
||||
|
||||
|
||||
21
content/functions/relpermalink.md
Normal file
21
content/functions/relpermalink.md
Normal file
@ -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**
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
<nav class="recent">
|
||||
@ -476,6 +476,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
|
||||
[`where` function]: /functions/where/
|
||||
[documented feature of Go text/template]: http://golang.org/pkg/text/template/#hdr-Variables
|
||||
[first]: /functions/first/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[Go html/template]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
|
||||
[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
|
||||
@ -483,5 +484,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
[hugofunctions]: /functions/ "Link to section for Hugo's templating functions"
|
||||
[math functions]: /functions/math/
|
||||
[partials]: /templates/partials-templates/ "Link to the partial templates page inside of the templating section of the Hugo docs"
|
||||
[relpermalink]: /functions/relpermalink/
|
||||
[sitevars]: /variables/site-variables/
|
||||
[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
|
||||
[You can read more about `index` in the Godocs]: http://golang.org/pkg/text/template/ "Godocs page for index function"
|
||||
@ -63,7 +63,7 @@ Always review the `README.md` file that is shipped with a theme. Often, these fi
|
||||
## Theme Placement
|
||||
|
||||
Please make certain you have installed the themes you want to use in the
|
||||
`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][configuration], but this is not recommended.
|
||||
`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended.
|
||||
|
||||
## Using Themes
|
||||
|
||||
@ -87,7 +87,7 @@ hugo server -t themename
|
||||
|
||||
### `config` File
|
||||
|
||||
If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][configuration]:
|
||||
If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]:
|
||||
|
||||
```yaml
|
||||
theme: themename
|
||||
@ -99,5 +99,5 @@ The `themename` in the above examples must match the name of the specific theme
|
||||
|
||||
[customizethemes]: /themes/customizing-a-theme/
|
||||
[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage."
|
||||
[configuration]: /project-organization/configuration/ "Learn how to customize your Hugo website configuration file in yaml, toml, or json."
|
||||
[config]: /getting-started/configuration/ "Learn how to customize your Hugo website configuration file in yaml, toml, or json."
|
||||
[themesrepo]: https://github.com/spf13/hugoThemes
|
||||
@ -88,6 +88,12 @@ See [`.Scratch`](/functions/scratch/) for page-scoped writable variables.
|
||||
`.Permalink`
|
||||
: the Permanent link for this page; see [Permalinks](/content-management/urls/)
|
||||
|
||||
`.Plain`
|
||||
: the Page content stripped of HTML tags and presented as a string.
|
||||
|
||||
`.PlainWords`
|
||||
: the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice.
|
||||
|
||||
`.Prev`
|
||||
: Pointer to the previous content (based on `publishdate` in front matter).
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user