blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 23:38:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update content and CSS

Browse Source
This commit is contained in:
Ryan Watters
2017-03-08 01:33:11 -06:00
parent 681712a9ab
commit 7bedd4e294
15 changed files with 97 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/about/features.md
+1 -1
View File
@@ -75,7 +75,7 @@ See what's coming next in the [Hugo roadmap][].
[Powerful theming]: /themes/
[Pretty URLs]: /content-management/urls/
[Pygments]: http://pygments.org/
[RSS]: /templates/rss-templates/
[RSS]: /templates/rss/
[Shortcodes]: /content-management/shortcodes/
[sort content]: /templates/
[supported formats]: /content-management/formats/
content/concept.md
+1 -1
View File
@@ -271,7 +271,7 @@ Themes section organization has only changed slightly in that the 6 content page
* URLS. Now combined with permalinks and others as a heading/subsection of [/content-management/urls/](/content-management/urls/)
* Syntax Highlighting. The shortcode is featured and explained with usage examples at [/content-management/shortcodes/](/content-management/shortcodes/), as well as expaned upon in it's own page under [/tools/syntax-highlighting/](/tools/syntax-highlighting/). I did this under the assumption that *developers* are most interested in adding code blocks to their content.
* Table of Contents. This is now it's own page under [/content-management/toc](/content-management/toc/) and referenced in [/variables/page-variables](/variables/page-variables/).
* Traversing Local Files. This is now split into [/templates/local-file-templates/](/templates/local-file-templates/) and variables delimited at [/variables/other/](/variables/other/).
* Traversing Local Files. This is now split into [/templates/files/](/templates/files/) and variables delimited at [/variables/other/](/variables/other/).
### Community
content/content-management/archetypes.md
+1 -1
View File
@@ -180,7 +180,7 @@ As an example of archetypes in practice, the following is the `functions` archet
{{% /code %}}
{{% note %}}
The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/local-file-templates/).
The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
{{% /note %}}
[archetypes directory]: /getting-started/directory-structure/
content/content-management/organization.md
+15 -8
View File
@@ -37,7 +37,7 @@ While Hugo supports content nested at any level, the top levels (i.e. `content/<
## 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][config].
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][pretty], 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][config].
### Section Index Page
@@ -69,7 +69,7 @@ At build, this will output to the following destination with the associated valu
http://yoursite.com/posts/index.html
```
### Section Single Pages
### Single Pages in Sections
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`:
@@ -112,7 +112,12 @@ To continue the example, the following demonstrates destination paths for a file
⊢----------------------^-----------------------⊣
http://yoursite.com/events/chicago/lollapalooza/
```
## Path Properties Explained
{{% note %}}
{{% /note %}}
## Paths Explained
#### `section`
@@ -139,7 +144,7 @@ The `url` is the relative URL for the piece of content. The `url`
* is based on the content's location within the directory structure OR
* is defined in front matter and *overrides all the above*
## Modifying Destinations for Content Source in Front Matter
## Overriding Destinations via Front Matter
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.
@@ -178,13 +183,14 @@ yoursite.com/posts/new-post/
### `type`
A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][].
A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
{{% code file="content/posts/my-post.md" %}}
```yaml
---
title: My Post
type: blog
type: new
layout: mylayout
---
```
{{% /code %}}
@@ -195,7 +201,7 @@ type: blog
### `url`
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 `url` is provided in the front matter, it will be used exactly. Using `url` will ignore the `--uglyURLs` setting.
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 `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration.
## \_index.md and "Everything is a Page"
@@ -211,7 +217,7 @@ In order to take advantage of this behavior, you need to do a few things.
### How `_index.md` Works
Before continuing, it's important to know that this page must reference certain templates to describe how the \_index.md page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
Before continuing, it's important to know that this page must reference certain templates to describe how the `_index.md` page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
If this is confusing or you are unfamiliar with Hugo's template hierarchy, visit the various template pages listed below. You may need to find the 'active' template responsible for any particular page on your own site by going through the template hierarchy and matching it to your particular setup/theme you are using.
@@ -315,6 +321,7 @@ Hugo themes are designed to use the 'content' directory as the root of the websi
[homepage template]: /templates/homepage/
[homepage]: /templates/homepage/
[lists]: /templates/lists/
[pretty]: /content-management/urls/#pretty-urls
[section templates]: /templates/section-templates/
[sections]: /content-management/sections/
[singles]: /templates/single-page-templates/
content/functions/readdir.md
+1 -1
View File
@@ -26,5 +26,5 @@ If your current project working directory has a single file named `README.txt`:
For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
[local]: /templates/local-file-templates/
[local]: /templates/files/
content/functions/readfile.md
+1 -1
View File
@@ -26,4 +26,4 @@ So, if you have a file with the name `README.txt` in the root of your project wi
For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
[local]: /templates/local-file-templates/
[local]: /templates/files/
content/templates/local-file-templates.md → content/templates/files.md
+16 -16
View File
@@ -10,7 +10,7 @@ categories: [templates]
tags: [files,directories]
weight: 110
draft: false
aliases: [/extras/localfiles/,/templates/files/]
aliases: [/extras/localfiles/,/templates/local-files/]
toc: true
---
@@ -29,7 +29,7 @@ Whether the path is absolute or relative does not matter because---at least for
### `readDir` Example: List Directory Files
So, let's create a new shortcode using `readDir`:
This shortcode creates a link to each of the files in a directory---display as the file's basename---along with the file's size in bytes.
{{% code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" %}}
```html
@@ -37,35 +37,35 @@ So, let's create a new shortcode using `readDir`:
```
{{% /code %}}
This shortcode creates a link, files' basenames and sizes and creates a link to each of them.
This shortcode [is part of the code for the Hugo docs][dirindex]. list some of its CSS files. (If you click on their names, you can reveal the contents.)
{{< directoryindex path="/static/css" pathURL="/css" >}}
The following is the [shortcode declaration][sc] used to render the above output:
You can then call the shortcode as follows inside of your content's markup:
```html
{{</* directoryindex path="/static/css" pathURL="/css" */>}}
```
The above shortcode [is part of the code for the Hugo docs][dirindex]. Here it lists this site's CSS files:
{{< directoryindex path="/static/css" pathURL="/css" >}}
{{% note "Slashes are Important" %}}
The initial slash `/` in `pathURL` is important in the `directoryindex` shortcode. Otherwise, `pathURL` becomes relative to the current web page.
{{% /note %}}
## Using `readFile`
The [`readfile` function][reads] reads a file--passed as an argument to the function, including path---from disk and converts it into a string to be manipulated by other Hugo functions or added as-is.
The [`readfile` function][reads] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function.
To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*:
```
```html
{{ readFile "content/templates/local-file-templates" }}
```
### `readFile` Example: Add a Project File to Your Content
### `readFile` Example: Add a Project File to Content
As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an options second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows:
As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows:
```
{{</* readfile file="path/to/local/file.txt" markdown="true" */>}}
@@ -79,13 +79,13 @@ Here is the templating for our new `readfile` shortcode:
```
{{% /code %}}
This shortcode is [also part of the Hugo docs][readfilesource]. The Hugo docs also includes this [`testing.txt`][testfile] file in a `readfiles` directory. We can call pass this file into our new `readfile` shortcode as follows:
This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is[`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows:
```
{{</* readfile file="content/readfiles/testing.txt" */>}}
```
The output "string" for calling this file is as follows:
The output "string" for this shortcode declaration will be the following:
```markdown
{{< readfile file="content/readfiles/testing.txt" >}}
@@ -97,7 +97,7 @@ However, if we want Hugo to pass this string through Blackfriday, we should add
{{</* readfile file="content/readfiles/testing.txt" markdown="true" */>}}
```
And here is it is [called directly in the Hugo docs][] content file used to creat this page and rendered for display:
And here is the result as [called directly in the Hugo docs][] and rendered for display:
{{< readfile file="content/readfiles/testing.txt" markdown="true">}}
content/templates/internal.md
+2 -2
View File
@@ -35,7 +35,7 @@ googleAnalytics = "UA-123-45"
googleAnalytics: "UA-123-45"
```
### Adding the Google Analytics Template
### Using the Google Analytics Template
You can then include the Google Analytics internal template:
@@ -70,7 +70,7 @@ You also have the option to set the following in the front matter for a given pi
* `disqus_title`
* `disqus_url`
### Adding the Disqus Template
### Using the Disqus Template
To add Disqus, include the following line in templates where you want your comments to appear:
content/templates/lists.md
+10 -12
View File
@@ -33,7 +33,7 @@ The idea of a list page comes from the [hierarchical mental model of the web][me
### Default Templates
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html`---or `themes/<THEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sectiontemplates] and [taxonomy lists][taxonomies] have their own default list templates in `_default`:
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html`---or `themes/<THEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`:
#### Default Section Templates
@@ -56,27 +56,24 @@ user.
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
* /layouts/taxonomy/`SINGULAR`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
1. `/layouts/taxonomy/<SINGULAR>.rss.xml`
1. `/layouts/_default/rss.xml`
1. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.rss.xml`
1. `/themes/<THEME>/layouts/_default/rss.xml`
## List Page Variables
A list page is a `Page` and has all the [page variables][pagevars]
and [site variables][sitevars] available to use in the templates.
Taxonomy pages will additionally have:
**.Data.`Singular`** The taxonomy itself.<br>
and [site variables][sitevars] available for use in templates.
Taxonomy list pages will additionally have:
**.Data.`Singular`** The taxonomy itself.<br> [See Taxonomy Variables][taxvars]
{{% note %}}
If `where` or `first` receives invalid input or a field name that doesn’t exist, it will return an error and stop site generation. `where` and `first` also work on taxonomy list templates *and* taxonomy terms templates. (See [Taxonomy Templates](/templates/taxonomy-templates/).)
{{% /note %}}
[directorystructure]: /getting-started/directory-structure/
[homepage]: /templates/homepage/
[homepage]: /templates/homepage/
@@ -85,9 +82,10 @@ If `where` or `first` receives invalid input or a field name that doesn’t exis
[pagevars]: /variables/pagevars/
[partials]: /templates/partials/
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
[rss]: /templates/rss-templates/
[rss]: /templates/rss/
[sections]: /content-management/sections/
[sectiontemps]: /templates/section-templates
[sitevars]: /variables/site-variables/
[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates/
[taxvars]: /templates/taxonomy-variables/
[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates/
content/templates/lookup-order.md
+1 -1
View File
@@ -40,7 +40,7 @@ See examples of the lookup order for each of the Hugo template types:
[directory structure]: /getting-started/directory-structure/
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[home]: /templates/homepage/#homepage-template-lookup-order
[rsslookup]: /templates/rss-templates/#rss-template-lookup-order
[rsslookup]: /templates/rss/#rss-template-lookup-order
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
[singlelookup]: templates/single-page-templates/#single-page-template-lookup-order
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
content/templates/rss-templates.md → content/templates/rss.md
View File
content/variables/file-variables.md
+8 -10
View File
@@ -11,37 +11,35 @@ draft: false
weight: 40
aliases: []
toc: false
wip: true
notesforauthors:
---
Hugo provides the ability to traverse your website's files on your server, including the local `Hugo server`. You can access file-system-related data for a piece of content via the `.File` variable.
{{% note "Rendering Local Files" %}}
For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/local-file-templates/).
For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/files/).
{{% /note %}}
The `.File` object contains the following fields:
`.File.Path`
: The original relative path of the page (e.g., `content/posts/foo.en.md`)
: the original relative path of the page (e.g., `content/posts/foo.en.md`)
`.File.LogicalName`
: The name of the content file that represents a page (e.g., `foo.en.md`)
: the name of the content file that represents a page (e.g., `foo.en.md`)
`.File.TranslationBaseName`
: The filename without extension or optional language identifier (e.g., `foo`)
: the filename without extension or optional language identifier (e.g., `foo`)
`.File.BaseFileName`
: The filename without extension (e.g., `foo.en`)
: the filename without extension (e.g., `foo.en`)
`.File.Ext`
: The file extension of the content file (e.g., `md`). This can also be called using `.File.Extension`.
: the file extension of the content file (e.g., `md`); this can also be called using `.File.Extension` as well. Note that it is *only* the extension without `.`.
`.File.Lang`
: The language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`)
: the language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`)
`.File.Dir`
: Given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`)
: given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`)
[Multilingual]: /content-management/multilingual/
content/variables/taxonomy-variables.md
+29 -3
View File
@@ -11,12 +11,14 @@ draft: false
weight: 30
aliases: []
toc: true
wip: true
wip: false
---
## Taxonomy Terms Page Variables
[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables. For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]:
[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables.
For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]:
`.Data.Singular`
: The singular name of the taxonomy (e.g., `tags => `tag`)
@@ -51,6 +53,30 @@ The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, co
### Example Usage of `.Site.Taxonomies`
**NEEDS EXAMPLE**
The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates].
{{% code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" %}}
```html
<section>
<ul>
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
<li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
<ul>
{{ range $key, $value := $taxonomy }}
<li> {{ $key }} </li>
<ul>
{{ range $value.Pages }}
<li><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</li>
{{ end }}
</ul>
</section>
```
{{% /code %}}
[partials]: /templates/partials/
[taxonomytemplates]: /templates/taxonomy-templates/
pipeline/scss/components/_code.scss
+10 -11
View File
@@ -63,17 +63,6 @@ code[class^="language-"] {
}
}
// .filename + .code-copy-content {
// code[class^="language-"] {
// &:after {
// // display: none;
// position: absolute;
// top: -16px;
// right: 4px;
// z-index:99999999;
// }
// }
// }
.copy-button + .code-copy-content {
code[class^="language-"] {
&:after {
@@ -149,6 +138,16 @@ code.language-markdown:after {
}
}
//hides icons in the occasional code block in blockquotes and admonitions
blockquote,
.admonition {
code[class^="language-"] {
&:after {
content: '';
}
}
}
.filename {
font-family: $code-font-family;
color: lighten($base-font-color, 25%);
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long