mirror of
https://github.com/gohugoio/hugo.git
synced 2026-09-02 03:32:38 +00:00
Finish local file templates page
This commit is contained in:
Ryan Watters
@@ -7,9 +7,7 @@ lastmod: ""
|
||||
categories: []
|
||||
tags: []
|
||||
weight: 00
|
||||
draft: true
|
||||
slug: ""
|
||||
aliases: []
|
||||
toc: false
|
||||
z_notesforauthors: "Go to gohugo.io/contribute/documentation for more info on using this archetype."
|
||||
---
|
||||
@@ -10,7 +10,7 @@ tags: [cli,command line]
|
||||
weight: 01
|
||||
draft: false
|
||||
aliases: [/cli/]
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
The following list contains auto-generated and up-to-date (thanks to [Cobra][]) documentation for all the CLI commands in Hugo.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 70
|
||||
draft: false
|
||||
aliases: [/content/archetypes/]
|
||||
toc: true
|
||||
notesforauthors:
|
||||
wip: true
|
||||
---
|
||||
|
||||
## What are Archetypes?
|
||||
@@ -24,7 +24,7 @@ Hugo's generator assumes your working directory is the content folder at the roo
|
||||
hugo new [content-section/file-name.md]
|
||||
```
|
||||
|
||||
We can use this pattern to create a new `.md` file in the `posts` section of the [example site][]:
|
||||
We can use this pattern to create a new `.md` file in the `posts` section:
|
||||
|
||||
{{% code file="archetype-example.sh" %}}
|
||||
```bash
|
||||
@@ -60,8 +60,8 @@ Similar to the lookup order for [templates in the `layouts` directory][], Hugo l
|
||||
|
||||
1. `archetypes/posts.md`
|
||||
2. `archetypes/default.md`
|
||||
3. `themes/theme-name/archetypes/posts.md`
|
||||
4. `themes/theme-name/archetypes/default.md`
|
||||
3. `themes/<THEME>/archetypes/posts.md`
|
||||
4. `themes/<THEME>/archetypes/default.md`
|
||||
5. `_internal` (i.e., `title` and `date`)
|
||||
|
||||
{{% note "Using a Theme Archetype" %}}
|
||||
@@ -76,11 +76,11 @@ You can specify a different default format in your site [configuration file][] f
|
||||
|
||||
## Default Archetypes
|
||||
|
||||
Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][].
|
||||
Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][sections].
|
||||
|
||||
### Creating the Default Archetype
|
||||
|
||||
The [example site][] includes `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
|
||||
The following examples are from a site using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
|
||||
|
||||
{{% code file="archetypes/default.md" %}}
|
||||
```toml
|
||||
@@ -124,15 +124,9 @@ We see that the `title` and `date` key-values have been added in addition to the
|
||||
You may notice that content files created with `hugo new` do not observe the order of the key-values specified in your archetype files and instead list your front matter alphabetically. This is a [known issue](https://github.com/spf13/hugo/issues/452).
|
||||
{{% /note %}}
|
||||
|
||||
### Example Site Default Archetype
|
||||
|
||||
The following is the default archetype used in the [example site][].
|
||||
|
||||
{{< exfile "static/example/archetypes/default.md" "yaml">}}
|
||||
|
||||
## Custom Archetypes
|
||||
|
||||
Suppose the example site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. We can create a custom archetype for our posts at `archetypes/posts.md` that includes the full set of front matter.
|
||||
Suppose your site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. You can create a custom archetype for your posts at `archetypes/posts.md` that includes the full set of front matter to be added to the two default archetypes fields.
|
||||
|
||||
### Creating a Custom Archetype
|
||||
|
||||
@@ -148,7 +142,7 @@ categories = ""
|
||||
|
||||
### Using a Custom Archetype
|
||||
|
||||
With an `archetypes/posts.md` in place, we can use the CLI to create a new posts with custom `posts` metadata in the `posts` content section:
|
||||
With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your custom `posts` metadata in the `posts` content section:
|
||||
|
||||
{{% code file="new-post-from-custom.sh" %}}
|
||||
```bash
|
||||
@@ -170,23 +164,27 @@ title = post from custom
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
### Example Site Custom Archetype
|
||||
### Hugo Docs Custom Archetype
|
||||
|
||||
`musicians` in the [example site] require more sophisticated front matter than what has been specified in `archetypes/default.md`. We can create a custom archetype for musicians at `archetypes/musicians.md` that includes the full set of front matter.
|
||||
As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
|
||||
|
||||
The following is the `musicians` archetype from the [example site][]:
|
||||
|
||||
{{< exfile "static/example/archetypes/musicians.md" "yaml" >}}
|
||||
{{% code file="archetypes/functions.md" %}}
|
||||
```yaml
|
||||
{{< readfile file="archetypes/functions.md" >}}
|
||||
```
|
||||
{{% /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/).
|
||||
{{% /note %}}
|
||||
|
||||
[archetypes directory]: /project-organization/directory-structure/
|
||||
[`now()`]: http://golang.org/pkg/time/#Now
|
||||
[configuration file]: /project-organization/configuration/
|
||||
[content sections]: /sections/
|
||||
[sections]: /sections/
|
||||
[content types]: /content-management/content-types/
|
||||
[example site]: /getting-started/using-the-hugo-docs/#example-site
|
||||
[front matter]: /content-management/front-matter/
|
||||
[RFC 3339 format]: https://www.ietf.org/rfc/rfc3339.txt
|
||||
[taxonomies]: /content-management/taxonomies/
|
||||
[templates in the `layouts` directory]: /templates/base-templates-and-blocks/
|
||||
[templates]: /templates/
|
||||
[templates]: /templates/
|
||||
@@ -11,7 +11,7 @@ weight: 140
|
||||
draft: false
|
||||
aliases: [/extras/comments/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
As Hugo is a static site generator, the content produced is static and doesn't allow for a high degree of interaction with the website's end users. The most common interaction people ask for in static websites is the ability to add comments.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 60
|
||||
draft: false
|
||||
aliases: [/content/types]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo provides full support for sites with multiple content types. A **content type** can have a unique set of metadata (i.e., [front matter][]) or customized [template][] and can be created by the `hugo new` command via content [archetypes][].
|
||||
|
||||
@@ -10,7 +10,7 @@ tags: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
|
||||
weight: 30
|
||||
draft: false
|
||||
aliases: [/content/front-matter/]
|
||||
needsreview: true
|
||||
wip: true
|
||||
toc: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
@@ -11,7 +11,7 @@ draft: false
|
||||
weight: 120
|
||||
aliases: [/extras/menus/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo's simple yet powerful menu system allows you to add content to menus with a high degree of control and a very low amount of effort on the part of content authors.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 150
|
||||
draft: false
|
||||
aliases: [/content/multilingual/,/content-management/multilingual/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). Define the available languages in a `Languages` section in your top-level `config.toml` (or equivalent).
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 10
|
||||
draft: false
|
||||
aliases: [/content-management/sections,/content/sections/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -19,37 +19,37 @@ Hugo believes that you organize your content with a purpose. The same structure
|
||||
|
||||
Following this pattern, Hugo uses the top level of your content organization as the content **section**.
|
||||
|
||||
The [example site][] used throughout the Hugo docs includes three sections: "authors," "events," and "posts". The following illustrates both the source organization and the default URL structure for the rendered files:
|
||||
The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts":
|
||||
|
||||
```bash
|
||||
.
|
||||
└── content
|
||||
├── authors
|
||||
| ├── _index.md // <- example.com/authors/
|
||||
| ├── john-doe.md // <- example.com/authors/john-doe/
|
||||
| └── jane-doe.md // <- example.com/authors/jane-doe/
|
||||
| ├── _index.md // <- yoursite.com/authors/
|
||||
| ├── john-doe.md // <- yoursite.com/authors/john-doe/
|
||||
| └── jane-doe.md // <- yoursite.com/authors/jane-doe/
|
||||
└── events
|
||||
| ├── _index.md // <- example.com/events/
|
||||
| ├── event-1.md // <- example.com/events/event-1/
|
||||
| ├── event-2.md // <- example.com/events/event-2/
|
||||
| └── event-3.md // <- example.com/events/event-3/
|
||||
| ├── _index.md // <- yoursite.com/events/
|
||||
| ├── event-1.md // <- yoursite.com/events/event-1/
|
||||
| ├── event-2.md // <- yoursite.com/events/event-2/
|
||||
| └── event-3.md // <- yoursite.com/events/event-3/
|
||||
└── posts
|
||||
| ├── _index.md // <- example.com/posts/
|
||||
| ├── event-1.md // <- example.com/posts/event-1/
|
||||
| ├── event-2.md // <- example.com/posts/event-2/
|
||||
| ├── event-3.md // <- example.com/posts/event-3/
|
||||
| ├── event-4.md // <- example.com/posts/event-4/
|
||||
| └── event-5.md // <- example.com/posts/event-5/
|
||||
| ├── _index.md // <- yoursite.com/posts/
|
||||
| ├── event-1.md // <- yoursite.com/posts/event-1/
|
||||
| ├── event-2.md // <- yoursite.com/posts/event-2/
|
||||
| ├── event-3.md // <- yoursite.com/posts/event-3/
|
||||
| ├── event-4.md // <- yoursite.com/posts/event-4/
|
||||
| └── event-5.md // <- yoursite.com/posts/event-5/
|
||||
```
|
||||
|
||||
## 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 [list and section templates][listsandsectiontemplatespage] for details on customizing the way these pages are rendered.
|
||||
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.
|
||||
|
||||
As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content.
|
||||
|
||||
{{% warning "`index.md` vs `_index.md`" %}}
|
||||
Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/).
|
||||
Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore [`_`]) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/). If you want to alter the new default behavior for `_index.md`, configure `disableKinds` accordingly in your [site's configuration](/getting-started/configuration/).
|
||||
{{% /warning %}}
|
||||
|
||||
## Content *Section* vs Content *Type*
|
||||
@@ -58,8 +58,7 @@ By default, everything created within a section will use the [content type][] th
|
||||
|
||||
[archetype]: /content-management/archetypes/
|
||||
[content type]: /content-management/content-types/
|
||||
[example site]: /getting-started/using-the-hugo-docs/
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[listsandsectiontemplatespage]: /templates/section-templates/
|
||||
[section templates]: /templates/section-templates/
|
||||
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 130
|
||||
draft: false
|
||||
aliases: [/extras/toc/,/content-management/toc/]
|
||||
toc: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo can automatically parse Markdown content and create a Table of Contents you can leverage in your templates to guide readers to sections of longer pages.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 110
|
||||
draft: false
|
||||
aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Permalinks
|
||||
|
||||
@@ -10,7 +10,7 @@ tags: []
|
||||
weight: 01
|
||||
draft: false
|
||||
slug:
|
||||
aliases: [/tutorials/how-to-contribute-to-hugo/]
|
||||
aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Contribute to Hugo Development
|
||||
title: Contribute to Development
|
||||
linktitle: Contribute to Hugo Development
|
||||
description: Hugo relies heavily on contributions from the open source community. You don't need to be a Golang guru to contribute to the project's development.
|
||||
date: 2017-02-01
|
||||
@@ -12,7 +12,7 @@ weight: 10
|
||||
draft: false
|
||||
aliases: [/contribute/development/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Contribute to the Hugo Docs
|
||||
linktitle: Contribute to the Hugo Docs
|
||||
linktitle: Improve the Docs
|
||||
description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to teach its users.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
@@ -11,7 +11,7 @@ weight: 20
|
||||
draft: false
|
||||
aliases: [/contribute/docs/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.19, but there is always room for improvement.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title:
|
||||
title: Add Your Hugo Theme to the Showcase
|
||||
linktitle: Add Your Theme
|
||||
description: If you've built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase.
|
||||
date: 2017-02-01
|
||||
@@ -11,7 +11,7 @@ authors: [digitalcraftsman]
|
||||
weight: 10
|
||||
draft: false
|
||||
aliases: [/contribute/theme/]
|
||||
needsreview: true
|
||||
wip: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
@@ -117,6 +117,6 @@ This is because its content will appear in two places—i.e., it will appear
|
||||
1. On your theme's details page at [themes.gohugo.io](http://themes.gohugo.io/); and
|
||||
1. At GitHub (as usual), on your theme's regular main page.
|
||||
|
||||
**Note:** If you add screenshots to the README please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
|
||||
|
||||
|
||||
{{% note "Screenshots"%}}
|
||||
If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
|
||||
{{% /note %}}
|
||||
@@ -16,7 +16,7 @@ relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration][]), as well as params for [individual pages][pagevars].
|
||||
|
||||
@@ -9,7 +9,7 @@ categories: [project organization]
|
||||
tags: [source, organization, directories,fundamentals]
|
||||
weight: 50
|
||||
draft: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
aliases: [/overview/source-directory/]
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 40
|
||||
draft: false
|
||||
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Testing Installation with `hugo help`
|
||||
|
||||
@@ -12,9 +12,9 @@ weight: 20
|
||||
draft: true
|
||||
aliases: [/getting-started/using-the-docs/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
notesforauthors:
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Example Site
|
||||
|
||||
@@ -12,7 +12,7 @@ weight: 20
|
||||
draft: false
|
||||
aliases: [/tutorials/automated-deployments/]
|
||||
toc: true
|
||||
needsreview: false
|
||||
wip: false
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ authors: [Riku-Pekka Silvola]
|
||||
weight: 50
|
||||
draft: false
|
||||
toc: true
|
||||
needsreview: false
|
||||
wip: false
|
||||
aliases: [/tutorials/hosting-on-gitlab/]
|
||||
---
|
||||
|
||||
|
||||
@@ -12,6 +12,6 @@ weight: 20
|
||||
draft: true
|
||||
aliases: []
|
||||
toc: true
|
||||
needsreview:
|
||||
wip:
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
@@ -12,7 +12,7 @@ weight: 20
|
||||
draft: false
|
||||
aliases: [/templates/blocks/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages one or more master template(s), filling in or overriding portions as necessary.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 70
|
||||
draft: false
|
||||
aliases: [/templates/views/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
In addition to the [single page content template][singletemplates], Hugo can render alternative views of your content. These are especially useful in [list templates][listtemplates].
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 120
|
||||
draft: false
|
||||
aliases: [/templates/404/]
|
||||
toc: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 80
|
||||
draft: false
|
||||
aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
<!-- begin data files -->
|
||||
|
||||
@@ -12,7 +12,7 @@ weight: 10
|
||||
draft: false
|
||||
aliases: [/templates/go-template-primer/,/layouts/go-templates/,/layout/go-templates/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo uses the excellent [Go html/template][gohtmltemplate] library, an extremely lightweight engine that provides just the right amount of logic to be able to create any style of static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 22
|
||||
draft: false
|
||||
aliases: [/templates/list/,/layout/indexes/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## What is a List Page Template?
|
||||
|
||||
@@ -12,8 +12,6 @@ weight: 110
|
||||
draft: false
|
||||
aliases: [/extras/localfiles/,/templates/files/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
needsexample: true
|
||||
---
|
||||
|
||||
## Traversing Local Files
|
||||
@@ -29,7 +27,7 @@ Whether the path is absolute or relative does not matter because---at least for
|
||||
1. The file system root
|
||||
2. The current working directory
|
||||
|
||||
## Example: List Directory Files
|
||||
### `readDir` Example: List Directory Files
|
||||
|
||||
So, let's create a new shortcode using `readDir`:
|
||||
|
||||
@@ -39,29 +37,75 @@ So, let's create a new shortcode using `readDir`:
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
For the files in any given directory, this shortcode usefully lists the files' basenames and sizes and also creates a link to each of them.
|
||||
This shortcode creates a link, files' basenames and sizes and creates a link to each of them.
|
||||
|
||||
This shortcode [has already been included in this very website][]. So, let's list some of its CSS files. (If you click on their names, you can reveal the contents.)
|
||||
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][shortcodes] used to render the above output:
|
||||
The following is the [shortcode declaration][sc] used to render the above output:
|
||||
|
||||
```html
|
||||
{{</* directoryindex path="/static/css" pathURL="/css" */>}}
|
||||
```
|
||||
|
||||
{{% note "Slashes are Important" %}}
|
||||
The initial slash `/` in `pathURL` is important. Otherwise, `pathURL` becomes relative to the current web page.
|
||||
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] returns...
|
||||
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.
|
||||
|
||||
**CONTENT NEEDED**.
|
||||
To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*:
|
||||
|
||||
[has already been included in this very website]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
|
||||
```
|
||||
{{ readFile "content/templates/local-file-templates" }}
|
||||
```
|
||||
|
||||
### `readFile` Example: Add a Project File to Your 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:
|
||||
|
||||
```
|
||||
{{</* readfile file="path/to/local/file.txt" markdown="true" */>}}
|
||||
```
|
||||
|
||||
Here is the templating for our new `readfile` shortcode:
|
||||
|
||||
{{% code file="layouts/shortcodes/readfile.html" download="readfile.html" %}}
|
||||
```
|
||||
{{< readfile file="layouts/shortcodes/readfile.html">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
This shortcode is [also part of the Hugo docs][readfilesource]. The Hugo docs also include this [`testing.txt`][testfile] file. We can call pass this file into our new `readfile` shortcode as follows:
|
||||
|
||||
```
|
||||
{{</* readfile file="testing.txt" */>}}
|
||||
```
|
||||
|
||||
The output "string" for calling this file is as follows:
|
||||
|
||||
```markdown
|
||||
{{< readfile file="testing.txt" >}}
|
||||
```
|
||||
|
||||
However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter:
|
||||
|
||||
```html
|
||||
{{</* readfile file="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:
|
||||
|
||||
{{< readfile file="testing.txt" markdown="true">}}
|
||||
|
||||
[called directly in the Hugo docs]: https://github.com/spf13/hugo/blob/master/docs/content/templates/local-file-templates.md
|
||||
[dirindex]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
|
||||
[osfileinfo]: https://golang.org/pkg/os/#FileInfo
|
||||
[reads]: /functions/readdir-and-readfile/
|
||||
[shortcodes]: /content-management/shortcodes/
|
||||
[reads]: /functions/readfile/
|
||||
[sc]: /content-management/shortcodes/
|
||||
[sct]: /templates/shortcode-templates/
|
||||
[readfilesource]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/readfile.html
|
||||
[testfile]: https://github.com/spf13/hugo/blob/master/docs/testfile
|
||||
@@ -11,7 +11,7 @@ tags: [lookup,fundamentals]
|
||||
weight: 15
|
||||
draft: false
|
||||
aliases: []
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 130
|
||||
draft: false
|
||||
aliases: [/templates/menus/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo makes no assumptions about how your rendered HTML will be
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 140
|
||||
draft: false
|
||||
aliases: [/extras/pagination,/doc/pagination/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo supports pagination for your homepage, section pages, and taxonomies. Hugo's pagination features were designed with ease of use and flexibility in mind. The real power of Hugo pagination shines when combine with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 90
|
||||
draft: false
|
||||
aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Partials vs Templates
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 27
|
||||
draft: false
|
||||
aliases: [/templates/ordering/,/templates/grouping/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 165
|
||||
draft: false
|
||||
aliases: [/extras/robots-txt/]
|
||||
toc: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Hugo can generate a customized [robots.txt][robots] in the same way as any other template.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 150
|
||||
draft: false
|
||||
aliases: [/templates/rss/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## RSS Template Lookup Order
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 40
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
Section page templates are lists and therefore have all the variables and methods available to [list pages][lists].
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 160
|
||||
draft: false
|
||||
aliases: [/layout/sitemap/,/templates/sitemap/]
|
||||
toc: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
A single Sitemap template is used to generate the `sitemap.xml` file.
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 50
|
||||
draft: false
|
||||
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
<!-- NOTE! Check on https://github.com/spf13/hugo/issues/2826 for shifting of terms' pages to .Data.Pages -->
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 30
|
||||
draft: false
|
||||
aliases: [/themes/creation/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% warning "Use Relative Links" %}}
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 20
|
||||
draft: false
|
||||
aliases: [/themes/customize/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -11,7 +11,7 @@ weight: 10
|
||||
draft: false
|
||||
aliases: [/themes/usage/,/themes/installing/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% note "No Default Theme" %}}
|
||||
|
||||
@@ -13,7 +13,7 @@ draft: false
|
||||
hugoversion: 14
|
||||
toc: true
|
||||
aliases: [/tutorials/migrate-from-jekyll/]
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% note "Support for Jekyll Imports" %}}
|
||||
|
||||
@@ -11,7 +11,7 @@ draft: false
|
||||
weight: 40
|
||||
aliases: []
|
||||
toc: false
|
||||
needsreview: true
|
||||
wip: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ draft: false
|
||||
weight: 50
|
||||
aliases: [/extras/gitinfo/,/variables/other-variables/]
|
||||
toc: true
|
||||
needsreview: false
|
||||
wip: false
|
||||
---
|
||||
|
||||
## Shortcode Variables
|
||||
|
||||
@@ -11,7 +11,7 @@ draft: false
|
||||
weight: 30
|
||||
aliases: []
|
||||
toc: true
|
||||
needsreview: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
### Taxonomy Terms Page Variables
|
||||
|
||||
Vendored
+1
-1
File diff suppressed because one or more lines are too long
@@ -0,0 +1,3 @@
|
||||
##### Hello World!
|
||||
|
||||
Testing one, **two**, *three*. Don't delete this sample file used in the [templates](/templates/) section of the Hugo docs.
|
||||
@@ -9,7 +9,7 @@
|
||||
{{- partial "content-header-links.html" . -}}
|
||||
{{- partial "tags.html" . -}}
|
||||
<!-- temporary WIP badge; should be removed before site launch -->
|
||||
{{- if .Params.needsreview -}}
|
||||
{{- if .Params.wip -}}
|
||||
<div id="beingreviewed">WIP</div>
|
||||
{{- end -}}
|
||||
{{ $title := .Title }}
|
||||
|
||||
@@ -121,7 +121,6 @@ button.download-button {
|
||||
font-weight: bold;
|
||||
color: $code-copy-button-text-color;
|
||||
font-size: 14px;
|
||||
display: block;
|
||||
width: 80px;
|
||||
line-height: 24px;
|
||||
height: 24px;
|
||||
@@ -138,6 +137,22 @@ button.download-button {
|
||||
position: absolute;
|
||||
}
|
||||
}
|
||||
//hide copy button on iPad and iPhone
|
||||
button.copy-button {
|
||||
@include MQ(retinaPortrait) {
|
||||
display: none;
|
||||
}
|
||||
@include MQ(retinaLandscape) {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
button.download-button {
|
||||
display: none;
|
||||
@include MQ(M) {
|
||||
display: block;
|
||||
}
|
||||
}
|
||||
|
||||
a[role="button"].see-code-source {
|
||||
position: absolute;
|
||||
@@ -156,26 +171,27 @@ a[href*="bitbucket"].see-code-source:after {
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
margin-left: .2em;
|
||||
}
|
||||
|
||||
a[href*="github"].see-code-source:after {
|
||||
content: '\f09b';
|
||||
font-family: 'FontAwesome';
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
margin-left: .2em;
|
||||
}
|
||||
|
||||
a[href*="gitlab"].see-code-source:after {
|
||||
content: '\f296';
|
||||
font-family: 'FontAwesome';
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
margin-left: .2em;
|
||||
}
|
||||
|
||||
|
||||
button.copy-button {
|
||||
display: none;
|
||||
@include MQ(M) {
|
||||
@@ -187,14 +203,7 @@ button.copy-button {
|
||||
}
|
||||
}
|
||||
|
||||
button.copy-button {
|
||||
@include MQ(retinaPortrait) {
|
||||
display: none;
|
||||
}
|
||||
@include MQ(retinaLandscape) {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
div.code-copy {
|
||||
position: relative;
|
||||
|
||||
Reference in New Issue
Block a user