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 all built-in shortcodes with output and display examples

Browse Source
This commit is contained in:
Ryan Watters
2017-02-24 19:37:10 -06:00
parent 564bce714a
commit ef3edffe45
53 changed files with 131770 additions and 1087 deletions
Download Patch File Download Diff File Expand all files Collapse all files
config.toml
+1 -1
View File
@@ -57,7 +57,7 @@ watch = true
[params]
organizationname = ""
sitedescription = ""
release = "0.18.1"
release = "0.19"
# Add GA Tracking Code Here. This leverages a built-in (ie, "internal") partial from HUGO: https://gohugo.io/extras/analytics#configuring-google-analytics
googleanalyticstrackingcode = ""
## Critical Render Path. If true, site style will be embedded in a <style> tag in each html <head> as part of Gulp Build. False puts a typical <link> to the stylesheet in <head>>
content-changes.md
-189
View File
@@ -1,189 +0,0 @@
# Annotated Content Reorganization
- [Changes to Existing Content Sections](#changes-to-existing-sections)
- [Extras](#extras)
- [Tutorials](#tutorials)
- [Getting Started](#getting-started)
- [Content Organization: \(Site Navigation\](#content-organization-site-navigation)
- [Content Organization: \(Source\)](#content-organization-source)
## Changes to Existing Sections
The following is an *abbreviated* listing and only includes the *larger* changes to content organization. Everything is ordered according to [existing site structure and site navigation](http://gohugo.io/overview/introduction/). These changes do not include copy edits for consistent usage, which easily numbers in the thousands, if not more.
### Download Hugo
This is no longer a site navigation link and is instead a button along with "File and Issue" and "Discuss Hugo".
### Site Showcase
### Press & Articles
### About Hugo
### Getting Started
* The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options&mdash;e.g. Arjen's Wercker tutorial&mdash;are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.
### Content
### Themes
### Templates
### Taxonomies
### [Extras](http://gohugo.io/extras)
* This section no longer exists in the new documentation site
* *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. READ: "We don't have any idea of where to put this"
* Previous pages in extras are now in the following locations:
* **Aliases** Incorporated into `/content-management/url-management/`
* **Analytics** Incorporated into /templates/partial-templates/#built-in
### Community
### [Tutorials](http://gohugo.io/tutorials)
* Moved all installation guides to /getting-started/install-hugo/
* Installing Hugo shouldn't be considered a separate tutorial
* "Tutorials" is not an intuitive place for end-users to look for this kind of documentation
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
* Aliases added to new pages and in-page links updated throughout
* Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes.
### Troubleshooting
### Tools
### Hugo Cmd Reference
This hasn't been touched. I'll make the necessary style changes once/if the site is integrated into the Hugo GH repo since these pages are pulled automatically using Viper.
### Issues & Help
This is no longer a site navigation link and is instead a button along with "Download" and "Discuss Hugo".
## Content Organization: Site Navigation
The following shows weights and ordering for the newly restructured site architecture.
### "About Hugo" Ordering (- weight)
_index - 01
what is hugo - 10
hugo features - 20
the benefits of static - 30
why i built hugo - 40
roadmap - 50
apache license - 60
### "Getting Started" Ordering (- weight)
* _index.md - 01
* quick start - 10
* using the hugo docs - 20
* install from source - 30
* install on linux - 40
* install on mac - 50
* install on pc - 60
* basic usage - 70
* directory structure - 80
* configuration - 90
### "Content Management" Ordering (- weight)
* _index.md - 01
* Content Organization - 10
* Supported Content Formats - 20
* Front Matter - 30
* Shortcodes - 40
* Sections - 50
* Content Types - 60
* Archetypes - 70
* Taxonomies - 80
* Content Summaries - 90
* Cross References - 100
* URL Management - 110
* Menus - 120
* Table of Contents - 130
* Comments - 140
* Multilingual Mode - 150
### "Templates" Ordering (- weight)
* _index - 01
* go template primer - 10
* base templates and blocks - 20
* lists in Hugo - 25
* homepage template - 30
* section templates - 40
* taxonomy templates - 50
* single page templates - 60
* content view templates - 70
* data templates - 80
* partial templates - 90
* shortcode templates - 100
* local file templates - 110
* custom 404 page - 120
* menu templates - 130
* pagination - 140
* rss templates - 150
* sitemap template - 160
* additional templating languages - 170
* template debugging - 180
## "Functions" Ordering
**Ordered by title (note that `.Title` is all lowercase, whereas `.Linktitle` is used for proper casing)**
### "Variables and Params" Ordering (- weight)
* _index.md - 01
* site variables - 10
* page variables - 20
* taxonomy variables - 30
* file variables - 40
* shortcode git and huge variables - 50
### "Hosting and Deployment" Ordering (- weight)
* _index.md - 01
* deployment with rsync - 10
* deployment with wercker - 20
* hosting on bitbucket - 30
* hosting on github - 40
* hosting on gitlab - 50
### "Themes" Ordering (- weight)
* _index.md - 01
* installing and using themes - 10
* customizing a theme - 20
* creating a them - 30
* theme showcase - 30
### "Site Showcase" Ordering
**Ordered by `.PublishDate`**
### "Themes" Ordering (- weight)
* _index.md - 01
* Installing and Using Themes - 10
* Customizing a Theme - 20
* Creating a Theme - 30
* Theme Showcase - 40
### "Troubleshooting" Ordering
**Ordered by title**
## Content Organization: Source
**[See tree.md at the root of this repository](tree.md).**
[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
content/about-hugo/hugo-features.md
+1 -1
View File
@@ -72,7 +72,7 @@ See what's coming next in the [Hugo roadmap][].
[LiveReload]: /getting-started/using-hugo/
[Mac OSX]: /getting-started/install-of-pc/
[organization for your projects]: /getting-started/directory-structure/
[pagevars]: /variables-and-params/page-variables/
[pagevars]: /variables/page-variables/
[Permalink]: /content-management/url-management/#permalinks
[Powerful theming]: /themes/
[Pretty URLs]: /content-management/url-management/
content/concept.md
+354
View File
@@ -0,0 +1,354 @@
---
title: Docs Concept
linktitle: Docs Concept
description: Notes on Hugo docs overhaul.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-24
weight: 01
categories: []
tags: []
draft: false
aliases: []
toc: true
---
## Strategy, Tactics, and Requirements
{{% warning "Disclaimer" %}}
WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the content strategy document.
{{% /warning %}}
### Introduction
The claims made in this strategic document are largely *empirical* and pulled from two major sources:
* My experience starting 18 months ago as a new user.
* Conversations with fellow Hugo users and noted trends within the [Discussion Forum][forum].
Ideally,
### Assumptions
* The current documentation
* is confusing for new users
* is a common complaint in the Hugo forums ([example discussion 1][ex1], [example discussion 2][ex2])
* lacks structure and is therefore
* unscalable, as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown
* inconsistent in its terminology, style, and (sometimes) layout
* limited in effective use of Alogolia's document search (i.e., because of redundant content grouping, headings, etc)
* difficult to optimize external search engines (SEO)
* does not leverage Hugo's more powerful feature (e.g., there is only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development. An prime example is the sparsity of basic and advanced code samples through the templating functions, some of which are still wholly undocumented.
### Goals
New Hugo documentation should...
* reduce confusion surrounding Hugo concepts; e.g., `list`, `section`, `page`, and `content type` with the intention of
* making it easier for new users to get up and running
* creating better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io](http://themes.gohugo.io))
* reducing the frequency of beginner-level questions in the [Hugo Discussion Forum][forum]
* not require, or assume, any degree of Golang proficiency from end users;
* that said, Hugo can&mdash;and *should*&mdash;act as a bridge for users interested in learning Golang. A implementationn example of this strategy point is the inclusion of `godocref:` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
* be easiest to expand and edit for *contributors** but even easier to understand by *end users*.
If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*;
* Content modeling is king
* Go DRY (e.g., by leveraging shortcodes whenever possible)
* Set required metadata (e.g., via section-specific *archetypes*)
* Develop contribution guidelines for both development *and* documentation
* be equally accessible via mobile, tablet, desktop, and offline.
* avoid "miscellaneous" sections (e.g.,"Extras"). [This is the last place end users look to get up and running with Hugo](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3). All content in miscellaneous sections should be edited and incorporated into more logical content groupings (e.g., with the goal of removing *extras* entirely).
* easily scaffold for potential i18n/multilingual versions.
### Audiences
* Primary: Web developers interested in static site generators
* Secondary: Web publishers (bloggers, authors) and hobbyists
* Tertiary: Web developers, both novice and professional, interested in learning Golang
### Persona
{{% note %}}
This is far from an inadequate persona exercise, but I think it helped my mental model as I worked through the existing docs.
{{% /note %}}
#### End User: SSG Developer
The SSG developer has
* basic proficiency in Git and DVCS
* no to little proficiency in Golang
* working proficiency in front-end development---HTML, CSS, JS---but not necessarily front-end build tools
* basic familiarity with at least one double-curly templating language (e.g., liquid, Twig, Swig, or Django)
* proficiency in the English language for the current version of the documentation
* proficiency in other languages (for future multilingual versions)
#### End User: Themes (i.e. blogger/author/hobbyist)
The themes end user has
* limited proficiency in the command line/prompt
* proficiency in one of the [supported content formats](https://hugodocsconcept.netlify.com/content-management/supported-content-formats/)(specifically markdown)
* access to static hosting;
* limited proficiency in deploying a static website
### Requirements
The following are high-level requirements for the documentation site.
#### Technical
- [X] Built with Hugo
- [X] Performant (e.g., 80+ [Google Page Speed Score](https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fhugodocsconcept.netlify.com%2Fabout-hugo))
- [X] Front-end build tools for concatenation, minification, of static assets
- [X] Browser compatibility: modern (i.e. Chrome, Edge, Firefox, Safari) and IE11
- [ ] CDN
- [ ] AMP?
#### SEO
- [X] [Open Graph Protocol](http://ogp.me/)
- [X] [schema.org](http://schema.org)
- [ ] [JSON+LD](https://developers.google.com/schemas/formats/json-ld), [validated](https://search.google.com/structured-data/testing-tool)
- [X] Consistent heading structure
- [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`)
- [X] SSL
- [ ] AMP?
#### Editorial and Content
- [ ] Basic style guide
- The style guide should facilitate a more consistent UX for the site but not be so complex as to deter documentation contributors
- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/))
- [X] Standardized content types (see [WIP archetypes in source](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
- [X] New content model, including taxonomies ([see tags page][tagspage])
- [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
- [X] New site architecture and content groupings
- [ ] Single sample website (include in docs source, [`/static/example`](https://github.com/rdwatters/hugo-docs-concept/tree/master/static/example)) for consistent code samples or in-page tutorials
#### [Content Strategy Statement](http://contentmarketinginstitute.com/2016/01/content-on-strategy-templates/)
> The Hugo documentation increases the Hugo user base and strengthens the Hugo community by providing intuitive, beginner-friendly, regularly updated usage guides. Hugo documentation makes visitors feel excited and confident that Hugo is the ideal choice for static website development.
#### [Editorial Mission](http://contentmarketinginstitute.com/2015/10/statement-content-marketing/)
> The Hugo documentation is a joint effort between the Hugo maintainers and the open-source community. Hugo documentation is designed to promote Hugo, the world's fastest, friendliest, and most extensible static site generator. Hugo documentation is the primary vehicle by which the Hugo team reaches its target audiences. When visitors comes to the Hugo documentation, we want them to install Hugo, develop a new static website with our tool, and share their progress and insights with the Hugo community at large.
## UX/UI
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
- [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
- [X] Smooth scrolling
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](http://localhost:1313/contribute-to-hugo/contribute-to-the-hugo-docs/#admonition-short-codes))
- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums
## Author Experience (AX)
- [X] Easy scaffolding of content types (CLI)
- [X] Type-based content storage model and scope (archetypes)
## Analytics/Metrics
- [X] Google Analytics
- [ ] Content groupings (GA) to measure usage, behavior flow, and define content gaps
- [ ] Automated reports (GA)
> **Note:** These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
## Visual Design
- [X] Clean typography with open-source font
- [X] Optimal line length (50-80 characters)
- [X] Consistent vertical rhythm
- [X] Responsive
- [X] Flexbox
- [X] Typography (via ems)
- [X] Custom iconography
- [X] Design assets versioned with source ([see design resources directory][designresources])
- [X] [WCAG color contrast requirements](http://webaim.org/blog/wcag-2-0-and-link-colors/)
- [X] [Sass Guidelines for Source Organization](https://sass-guidelin.es/)
- [X] Abstracted color palette
- [X] Abstracted typefaces (multiple open-source fonts available)
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
[forum]: https://discuss.gohugo.io
[ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
[ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
[forum]:
[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md
[tagspage]: https://hugodocsconcept.netlify.com/tags/
## Content Changes
The following is an *abbreviated* listing of *substantive* changes to content organization. Everything is ordered according to [existing site structure and site navigation](http://gohugo.io/overview/introduction/). These changes do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, if not more.
### Download Hugo
This is no longer a site navigation link and is instead a button along with "File and Issue" and "Discuss Hugo".
### Site Showcase
### Press & Articles
### About Hugo
### Getting Started
* The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options&mdash;e.g. Arjen's Wercker tutorial&mdash;are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.
### [Content](http://gohugo.io/content)
* This section has been renamed "Content Management" to facilitate elimination of the ["extras"](http://gohugo.io) section. **Note**: this section does *not* include any templating. The convention is `content-management/shortcodes.md` (for explanation and usage) and then `content-management/shortcode-templates.md`
### Themes
### Templates
### Taxonomies
### [Extras](http://gohugo.io/extras)
* This section no longer exists in the new documentation site
* *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. It's an area that's been tacked onto site navigation to accommodate a *seemingly* disparate set of new features. In other words, READ: "We don't have any idea of where to put this"
* *Extras* pages:
* **Aliases** Incorporated into [`/content-management/url-management/`]
* **Analytics** Incorporated into [/templates/partial-templates/#built-in]
### Community
### [Tutorials](http://gohugo.io/tutorials)
* All installation guides have been consilidated under [/getting-started/install-hugo/]
* Installing Hugo shouldn't be considered a separate tutorial
* "Tutorials" is not an intuitive place for end-users to look for this kind of documentation
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
* Aliases added to new pages and in-page links updated throughout
* Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes.
### Troubleshooting
### Tools
### Hugo Cmd Reference
This hasn't been touched. I'll make the necessary style changes once/if the site is integrated into the Hugo GH repo since these pages are pulled automatically using Viper.
### Issues & Help
This is no longer a site navigation link and is instead a button along with "Download" and "Discuss Hugo".
## Content Ordering: Site Navigation
The following shows weights and ordering for the newly restructured site architecture.
### "about-hugo" Ordering (`.OrderByWeight`)
_index - 01
What Is Hugo - 10
Hugo Features - 20
The Benefits Of Static - 30
Why I Built Hugo - 40
Roadmap - 50
Apache License - 60
### "getting-started" Ordering (`.OrderByWeight`)
* _index.md - 01
* Quick Start - 10
* Using the Hugo Docs - 20
* Install from Source - 30
* Install on Linux - 40
* Install on Mac - 50
* Install on Pc - 60
* Basic Usage - 70
* Directory Structure - 80
* Configuration - 90
### "content-management" Ordering (`.OrderByWeight`)
* _index.md - 01
* Content Organization - 10
* Supported Content Formats - 20
* Front Matter - 30
* Shortcodes - 40
* Sections - 50
* Content Types - 60
* Archetypes - 70
* Taxonomies - 80
* Content Summaries - 90
* Cross References - 100
* URL Management - 110
* Menus - 120
* Table of Contents - 130
* Comments - 140
* Multilingual Mode - 150
### "templates" Ordering (`.OrderByWeight`)
* _index - 01
* Go Template Primer - 10
* Base Templates And Blocks - 20
* Lists in Hugo - 25
* Homepage Template - 30
* Section Templates - 40
* Taxonomy Templates - 50
* Single Page Templates - 60
* Content View Templates - 70
* Data Templates - 80
* Partial Templates - 90
* Shortcode Templates - 100
* Local File Templates - 110
* Custom 404 Page - 120
* Menu Templates - 130
* Pagination - 140
* RSS Templates - 150
* Sitemap Template - 160
* Additional Templating Languages - 170
* Template Debugging - 180
### "functions" Ordering (`.OrderByTitle`)
### "variables-and-Params" Ordering (`.OrderByWeight`)
* _index.md - 01
* Site Variables - 10
* Page Variables - 20
* Taxonomy Variables - 30
* File Variables - 40
* Other Variables - 50
### "hosting-and-deployment" Ordering (`.OrderByWeight`)
* _index.md - 01
* Deployment with Rsync - 10
* Deployment with Wercker - 20
* Hosting on Bitbucket - 30
* Hosting on Github - 40
* Hosting on Gitlab - 50
### "themes" Ordering (`.OrderByWeight`)
* _index.md - 01
* Installing and Using Themes - 10
* Customizing a Theme - 20
* Creating a Theme - 30
* Theme Showcase - 40
### "site-showcase" Ordering (`.OrderByPublishDate`)
### "Troubleshooting" Ordering
**Ordered by title**
[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
## Current Content (Source)
```markdown
{{< readfile file="content/tree.txt" >}}
```
content/content-management/archetypes.md
+3 -3
View File
@@ -38,7 +38,7 @@ To override the content type Hugo infers from `[content-section]`, add the `--ki
Running this command in a new site that does not have default or custom archetypes will create the following file:
{{% output "content/posts/my-first-post.md" %}}
{{% output file="content/posts/my-first-post.md" %}}
```toml
+++
date = "2017-02-01T19:20:04-07:00"
@@ -107,7 +107,7 @@ $ hugo new posts/my-new-post.md
Hugo then creates a new markdown file with the following front matter:
{{% output "content/posts/my-new-post.md" %}}
{{% output file="content/posts/my-new-post.md" %}}
```toml
+++
categories = ["web development"]
@@ -158,7 +158,7 @@ $ hugo new posts/post-from-custom.md
This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`.
{{% output "content/posts/post-from-custom.md" %}}
{{% output file="content/posts/post-from-custom.md" %}}
```toml
+++
categories = ""
content/content-management/content-organization.md
+5 -35
View File
@@ -14,43 +14,13 @@ toc: true
needsreview: true
---
## Introduction
Hugo uses files (see [supported content 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][].
## Organizing Source Content
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 is special in Hugo and is used as the [section](/content-management/sections/).
```bash
.
└── content
└── about
| └── _index.md // <- http://1.com/about/
├── post
| ├── firstpost.md // <- http://1.com/post/firstpost/
| ├── happy
| | └── ness.md // <- http://1.com/post/happy/ness/
| └── secondpost.md // <- http://1.com/post/secondpost/
└── quote
├── first.md // <- http://1.com/quote/first/
└── second.md // <- http://1.com/quote/second/
```
Here's the same organization run with `hugo --uglyURLs`:
```bash
.
└── content
└── about
| └── _index.md // <- http://1.com/about/
├── post
| ├── firstpost.md // <- http://1.com/post/firstpost.html
| ├── happy
| | └── ness.md // <- http://1.com/post/happy/ness.html
| └── secondpost.md // <- http://1.com/post/secondpost.html
└── quote
├── first.md // <- http://1.com/quote/first.html
└── second.md // <- http://1.com/quote/second.html
```
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-management/sections/).
## Destinations
@@ -91,7 +61,7 @@ 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
## Path Breakdown in Hugo
### Content
@@ -161,7 +131,7 @@ http://spf13.com/extras/indexes/example
* based on `content-name.md`
* front matter overrides
**path** = section + path to file, excluding slug
**path** = section path to file, excluding slug
* based on path to content location
content/content-management/content-summaries.md
+1 -1
View File
@@ -71,5 +71,5 @@ You can show content summaries with the following code. You could use the follow
Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
[org]: /content-management/supported-content-formats/
[pagevariables]: /variables-and-params/page-variables/
[pagevariables]: /variables/page-variables/
[section template]: /templates/section-templates/
content/content-management/menus.md
+29 -61
View File
@@ -14,76 +14,40 @@ toc: true
needsreview: true
---
Hugo has a simple yet powerful menu system that permits content to be placed in menus with a good degree of control without a lot of work.
Hugo has a simple yet powerful menu system that 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.
{{% note "Lazy Blogger"%}}
If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-blogger).
{{% /note %}}
Some of the features of Hugo Menus:
Hugo's robust menu features allow you to do the following:
* Place content in one or many menus
* Handle nested menus with unlimited depth
* Create menu entries without being attached to any content
* Distinguish active element (and active branch)
## What is a Menu?
## What is a Menu in Hugo?
A menu is a named array of menu entries accessible on the site under `.Site.Menus` by name. For example, if I have a menu called `main`, I would access it via `.Site.Menus.main`.
A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
If you make use of the [multilingual feature](content-management/multilingual-mode/) you can define language-independent menus.
{{% note "Menus on Multilingual Sites" %}}
If you make use of the [multilingual feature](/content-management/multilingual-mode/), you can define language-independent menus.
{{% /note %}}
A menu entry has the following properties:
A menu entry has the following properties (i.e., variables) available to it:
`URL`
: string
`Name`
: string
`Menu`
: string
`Identifier`
: string
`Pre`
: template.HTML
`Post`
: template.HTML
`Weight`
: int
`Parent`
: string
`Children`
: Menu
And the following functions:
`HasChildren`
: boolean
Additionally, there are some relevant functions available on the page:
`IsMenuCurrent`
: (menu string, menuEntry *MenuEntry ) boolean
`HasMenuCurrent`
: (menu string, menuEntry *MenuEntry) bool
{{< readfile file="readfile-content/menuvars.md" markdown="true" >}}
## Adding content to menus
Hugo supports a couple of different methods of adding a piece of content to the front matter.
Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
### Simple
If all you need to do is add an entry to a menu, the simple form works well.
#### A Single Menu:
#### A Single Menu
```yaml
---
@@ -91,7 +55,7 @@ menu: "main"
---
```
#### Multiple Menus:
#### Multiple Menus
```yaml
---
@@ -116,8 +80,9 @@ menu:
You can also add entries to menus that aren’t attached to a piece of content. This takes place in the sitewide [config file](/overview/configuration/).
Here’s an example `config.toml`:
Here’s an example snippet pulled from a `config.toml`:
{{% code file="menu-in-config.toml" %}}
```toml
[[menu.main]]
name = "about hugo"
@@ -131,9 +96,11 @@ Here’s an example `config.toml`:
weight = -100
url = "/getting-started/"
```
{{% /code %}}
And the equivalent example `config.yaml`:
Here's the equivalent snippet pulled from a `config.yaml`:
{{% code file="menu-in-config.yml" %}}
```yaml
---
menu:
@@ -149,29 +116,30 @@ menu:
URL: "/getting-started/"
---
```
{{% /code %}}
**NOTE:** The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the `URL` is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
{{% note %}}
The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the `URL` is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
{{% /note %}}
## Nesting
All nesting of content is done via the `parent` field.
The parent of an entry should be the identifier of another entry.
Identifier should be unique (within a menu).
The parent of an entry should be the identifier of another entry. Identifier should be unique (within a menu).
The following order is used to determine an Identifier:
* Name >
* LinkTitle >
* Title
`.Name > .LinkTitle` > .Title`
This means that `title` will be used unless `linktitle` is present, etc. In practice, Name and Identifier are never displayed and only used to structure relationships.
This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
In this example, the top level of the menu is defined in the config file
and all content entries are attached to one of these entries via the
`parent` field.
In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field.
## Rendering Menus
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus.
[config]: /getting-started/configuration/
[multilingual]: /content-management/multilingual-mode/
[sitevars]: /variables/
content/content-management/shortcodes.md
+90 -9
View File
@@ -87,7 +87,7 @@ The `figure` shortcode can use the following named parameters:
#### Example `figure` Output
{{% output "figure-output-example.html" %}}
{{% output file="figure-output-example.html" %}}
```html
<figure>
<img src="/media/spf13.jpg" />
@@ -100,25 +100,41 @@ The `figure` shortcode can use the following named parameters:
### `gist`
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the following [gist][examplegist]:
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
```html
https://gist.github.com/spf13/7896402
```
###
We can embed the gist in our content via username and gist ID pulled from the URL:
```golang
{{</* gist spf13 7896402 */>}}
```
#### Example `gist` Input
If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
{{% code file="gist-input.md" %}}
```golang
{{</* gist spf13 7896402 "img.html" */>}}
```
{{% /code %}}
To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page:
#### Example `gist` Output
{{% output file="gist-output.html" %}}
```html
{{< gist spf13 7896402 >}}
```
{{% /output %}}
#### Example `gist` Display
To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< gist spf13 7896402 >}}
@@ -145,7 +161,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
#### Example `highlight` Output
{{% output "syntax-highlighted.html" %}}
{{% output file="syntax-highlighted.html" %}}
```html
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
@@ -158,25 +174,50 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
```
{{% /output %}}
{{% note "Syntax Highlighting" %}}
For more information on your options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting](/developer-tools/syntax-highlighting/.
{{% /note %}}
### `instagram`
If you'd like to embed a photo from [Instagram][], all you need is photo ID from the URL:
If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
```html
https://www.instagram.com/p/BMokmydjG-M/
```
Pass it to the shortcode:
#### Example `instagram` Input
{{% code file="instagram-input.md" %}}
```golang
{{</* instagram BMokmydjG-M */>}}
```
{{% /code %}}
You also have the option to hide the caption:
{{% code file="instagram-input-hide-caption.md" %}}
```golang
{{</* instagram BMokmydjG-M hidecaption */>}}
```
{{% /code %}}
#### Example `instagram` Output
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
{{% output file="instagraph-hide-caption-output.html" %}}
```html
{{< instagram BMokmydjG-M hidecaption >}}
```
{{% /output %}}
#### Example `instagram` Display
Using the preceding `instagram` with hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< instagram BMokmydjG-M hidecaption >}}
### `ref` and `relref`
@@ -208,12 +249,14 @@ Assuming that standard Hugo pretty URLs are turned on.
### `speakerdeck`
To embed slides from [Speaker Deck][], click on "&lt;&#8239;/&gt;&nbsp;Embed" (under Share right next to the template on Speaker Deck) and copy the URL, e.g.:
To embed slides from [Speaker Deck][], click on "&lt;&#8239;/&gt;&nbsp;Embed" (under Share right next to the template on Speaker Deck) and copy the URL:
```html
<script async class="speakerdeck-embed" data-id="4e8126e72d853c0060001f97" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
```
#### `speakerdeck` Example Input
Extract the value from the field `data-id` and pass it to the shortcode:
{{% code file="speakerdeck-example-input.md" %}}
@@ -222,15 +265,53 @@ Extract the value from the field `data-id` and pass it to the shortcode:
```
{{% /code %}}
#### `speakerdeck` Example Output
{{% output file="speakerdeck-example-input.md" %}}
```html
{{< speakerdeck 4e8126e72d853c0060001f97 >}}
```
{{% /output %}}
#### `speakerdeck` Example Display
For the preceding `speakerdeck` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< speakerdeck 4e8126e72d853c0060001f97 >}}
### `tweet`
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet. For example, let's say you want to include the following tweet from `https://twitter.com/spf13/status/666616452582129664`. Pass the tweet's ID from the URL as parameter to the shortcode as shown below:
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
```
https://twitter.com/spf13/status/666616452582129664
```
#### Example `tweet` Input
Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
{{% code file="example-tweet-input.md" %}}
```golang
{{</* tweet 666616452582129664 */>}}
```
{{% /code %}}
#### Example `tweet` Output
Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
{{% output file="example-tweet-output.html" %}}
```golang
{{< tweet 666616452582129664 >}}
```
{{% /output %}}
#### Example `tweet` Display
Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
{{< tweet 666616452582129664 >}}
### `vimeo`
@@ -271,7 +352,7 @@ To learn more about creating your own shortcode templates, see the [shortcode te
[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
[`figure` shortcode]: #figure
[Instagram]: https://www.instagram.com/
[pagevariables]: /variables-and-params/page-variables/
[pagevariables]: /variables/page-variables/
[partials]: /templates/partials-templates/
[Pygments]: http://pygments.org/
[projectorganizationsection]: /project-organization/directory-structure/
content/content-management/table-of-contents.md
+1 -1
View File
@@ -25,7 +25,7 @@ your content.
Simply create content like you normally would with the appropriate headers.
Hugo will take this Markdown and create a table of contents stored in the [content variable](/variables-and-params/page-variables/) `.TableOfContents`.
Hugo will take this Markdown and create a table of contents stored in the [content variable](/variables/page-variables/) `.TableOfContents`.
## Template Example
content/content-management/url-management.md
+40 -3
View File
@@ -16,8 +16,11 @@ needsreview: true
## Permalinks
By default, content is laid out into the target `publishdir` (public)
namespace matching its layout within the `contentdir` hierarchy. The `permalinks` [site configuration][] option allows you to adjust this 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, 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.
{{% 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/).
{{% /note %}}
For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year and month, you could set up the following configurations in YAML and TOML, respectively.
@@ -166,7 +169,40 @@ content/posts/post-3.md
If you would like to have what we call "ugly URLs" (e.g.,&nbsp;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 want a specific piece of content to have an exact URL, you can specify this in the front matter under the `url` key. 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][] for more details.
```bash
.
└── content
└── about
| └── _index.md // <- http://1.com/about/
├── post
| ├── firstpost.md // <- http://1.com/post/firstpost/
| ├── happy
| | └── ness.md // <- http://1.com/post/happy/ness/
| └── secondpost.md // <- http://1.com/post/secondpost/
└── quote
├── first.md // <- http://1.com/quote/first/
└── second.md // <- http://1.com/quote/second/
```
Here's the same organization run with `hugo --uglyURLs`:
```bash
.
└── content
└── about
| └── _index.md // <- http://1.com/about/
├── post
| ├── firstpost.md // <- http://1.com/post/firstpost.html
| ├── happy
| | └── ness.md // <- http://1.com/post/happy/ness.html
| └── secondpost.md // <- http://1.com/post/secondpost.html
└── quote
├── first.md // <- http://1.com/quote/first.html
└── second.md // <- http://1.com/quote/second.html
```
## Canonicalization
@@ -204,5 +240,6 @@ For example, if the `/post/first/` page contained a link with a relative URL of
[Content Organization]: /content-management/content-organization/
[flag from the command line]: /getting-started/basic-usage/
[front matter]: /content-management/front-matter/
[sections]: /content-management/sections/
[site configuration]: /project-organization/configuration/
content/contribute-to-hugo/contribute-to-the-hugo-docs.md
+2 -2
View File
@@ -86,7 +86,7 @@ Here is a piece of information I would like to draw your **attention** to.
#### `note` Admonition Shortcode Output (Code)
{{% output "note-with-heading.html" %}}
{{% output file="note-with-heading.html" %}}
```html
{{% note "Example Note Admonition" %}}
Here is a piece of information I would like to draw your **attention** to.
@@ -116,7 +116,7 @@ This is a warning, which should be reserved for *important* information like bre
#### `warning` Admonition Shortcode Output
{{% output "warning-admonition-output.html" %}}
{{% output file="warning-admonition-output.html" %}}
```html
{{% warning "Example Warning" %}}
This is a warning, which should be reserved for *important* information like breaking changes.
content/developer-tools/migrate-to-hugo.md
+1 -1
View File
@@ -6,7 +6,7 @@ date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [migrations,jekyll,wordpress,drupal,ghost,contentful]
weight: 40
weight: 10
draft: false
aliases: [/developer-tools/migrations/,/developer-tools/migrated/]
toc: true
content/developer-tools/starter-kits.md
+23
View File
@@ -0,0 +1,23 @@
---
title: Starter Kits
linktitle: Starter Kits
description: A list of community-developed projects designed to help you get up and running with Hugo.
date: 2017-02-22
publishdate: 2017-02-22
lastmod: 2017-02-22
tags: [starters,assets,pipeline]
weight: 30
draft: false
aliases: [/developer-tools/migrations/,/developer-tools/migrated/]
toc: false
---
Know of a Hugo-related project that isn't mentioned here? [Please add it to the list.][addkit]
| Kit | Actively Maintained? |
| --------------------------------- | -------------------- |
| [Victor Hugo](https://github.com/netlify/victor-hugo) | Yes |
[addkit]: https://github.com/spf13/hugo/blob/master/docs/content/developer-tools/starter-kits.md
content/developer-tools/syntax-highlighting.md
+2 -3
View File
@@ -7,9 +7,8 @@ publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [highlighting,pygments,code blocks]
categories: [developer tools]
weight:
weight: 20
draft: false
slug:
aliases: [/extras/highlighting/,/extras/highlight/]
toc: true
needsreview:
@@ -62,7 +61,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho
### Example `highlight` Shortcode Output
{{% output "example-highlight-shortcode-output.html" %}}
{{% output file="example-highlight-shortcode-output.html" %}}
```
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
content/functions/default.md
+1 -1
View File
@@ -75,7 +75,7 @@ And then using dot notation
Which would return
{{% output "dot-notation-default-return-value.html" %}}
{{% output file="dot-notation-default-return-value.html" %}}
```html
<title>Sane Defaults</title>
```
content/functions/delimit.md
+3 -3
View File
@@ -49,7 +49,7 @@ tags: [ "tag1", "tag2", "tag3" ]
```
{{% /code %}}
{{% output "delimit-page-tags-output.html" %}}
{{% output file="delimit-page-tags-output.html" %}}
```html
<p>Tags: tag1, tag2, tag3</p>
```
@@ -63,13 +63,13 @@ Tags: {{ delimit .Params.tags ", " ", and " }}
```
{{% /code %}}
{{% output "delimit-page-tags-final-and-output.html" %}}
{{% output file="delimit-page-tags-final-and-output.html" %}}
```html
<p>Tags: tag1, tag2, and tag3</p>
```
{{% /output %}}
[lists]: /templates/lists-in-hugo/
[lists]: /templates/lists/
[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates
[terms]: /templates/taxonomy-templates/#terms-list-templates
content/getting-started/configuration.md
+1 -1
View File
@@ -374,7 +374,7 @@ blackfriday:
* [YAML Spec][]
* [JSON Spec][]
[`.Site.Params`]: /variables-and-params/
[`.Site.Params`]: /variables/
[directory structure]: /project-organization/directory-structure
[JSON Spec]: /documents/ecma-404-json-spec.pdf
[templates]: /templates/
content/getting-started/directory-structure.md
+1 -2
View File
@@ -19,7 +19,6 @@ notesforauthors:
Hugo takes a single directory and uses it as the input for creating a complete
website.
The top level of a source directory will typically have the following elements:
```bash
@@ -105,7 +104,7 @@ This directory structure tells us a lot about this website:
## Content for Home Page and Other List Pages
Since Hugo 0.18, "everything" is a `Page` that can have content and metadata, like `.Params`, attached to it -- and share the same set of [page variables](/variables-and-params/page-variables/).
Since Hugo 0.18, "everything" is a `Page` that can have content and metadata, like `.Params`, attached to it -- and share the same set of [page variables](/variables/page-variables/).
To add content and front matter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name `_index` on the relevant place on the file system.
content/getting-started/quick-start.md
+15 -12
View File
@@ -14,17 +14,19 @@ aliases: [/overview/quickstart/]
toc: true
---
In this Quick Start, we will build an online bookshelf that lists books and their reviews. This quick start assumes you are using Hugo v0.15 or greater.
{{% note %}}
This Quick Start was originally written by [Shekhar Gulati](https://twitter.com/shekhargulati) in his [52 Technologies in 2016](https://github.com/shekhargulati/52-technologies-in-2016) blog series but has been heavily modified to represent additional features and other changes to Hugo.
{{% /note %}}
In this Quick Start, we will build an online bookshelf that lists books and their reviews.
## Assumptions
This quick start assumes you are using Hugo v0.15 or greater.
## Step 1. Install Hugo
Go to [Hugo Releases][releases] and download the appropriate version for your operating system and architecture or follow the [Quick Install][quickinstall] in the Hugo docs.
If installing from Hugo release, you'll need to save the main executable as `hugo` (or `hugo.exe` on Windows) somewhere in your `PATH`. You will need this command in the following steps..
[Install Hugo][install]. If installing from [Hugo releases][releases], you'll need to save the main executable as `hugo` (or `hugo.exe` on Windows) somewhere in your `PATH`. You will need the `hugo` command in the following steps.
{{% note "Windows Users and Git Bash" %}}
If you're on Windows, this Quick Start will assume you're using [Git Bash](https://git-for-windows.github.io/) (aka Git for Windows).
@@ -44,7 +46,7 @@ built with love by spf13 and friends in Go.
Complete documentation is available at http://gohugo.io/.
```
You can check your `hugo version` as well:
You can check the version of Hugo you're currently using with the `hugo version` command:
```bash
hugo version
@@ -77,13 +79,13 @@ Change into the newly created `bookshelf` directory. Listing the new directory's
6 directories, 1 file
```
You'll see the `bookshelf` directory has 6 subdirectories and 1 file. Let's look at each of them quickly. (For more detailed information, see [Directory Structure][hugodirectories].)
You'll see the `bookshelf` directory has 6 subdirectories and 1 file. Let's look at each of them quickly. (See [Directory Structure][hugodirectories].)
* `archetypes`: [Archetypes][archetypes] allow you to preconfigure [front matter][frontmatter] for content files for easier scaffolding of content from the command line using `hugo new`.
* `config.toml`: Hugo uses `.toml` as its default configuration format but also accepts `.yml` and `.json`. The configuration settings mentioned in the `config.toml` are applied to the full website an include important global variables such as the `baseURL` and `title` of your website. (See [Configuration][configuration])
* `config.toml`: Hugo uses `.toml` as its default configuration format but also accepts `.yml` and `.json`. The configuration settings mentioned in the `config.toml` are applied to the full website an include important global variables such as the `baseURL` and `title` of your website. (See [Configuration][configuration].)
* `content`: This single directory houses all of the content for your website. Each subdirectory in content is considered a [section][]. If your website has sections for posts, events, and tutorials, you would create `content/posts`, `content/events`, and `content/tutorials`.
* `data`: This directory is used to store files of serialized data (YAML, TOML, or JSON) that can be used in [data templates][datatemplates] and your [website's menu][sitemenu].
* `layouts`: This is the hub for all of our [templating][templating], including [list and section templates][listsectiontemplates] and [shortcodes][shortcodetemplates].
* `layouts`: This is the hub for all your [templating][templating], including [list and section templates][listsectiontemplates] and [shortcodes][shortcodetemplates].
* `static`: This houses all your static content; i.e., images, JavaScript, and CSS. Everything in `/static` is copied over *as is* to your finished website.
* `themes`: This is where you will download themes for Hugo. You can see a showcase of all themes at <http://themes.gohugo.io>.
@@ -580,7 +582,7 @@ git commit -m "<some change message>"
git push
```
----
--------
## Video: Hugo Website in 2 Minutes
@@ -594,13 +596,14 @@ git push
[datatemplates]: /templates/data-templates/
[frontmatter]: /content-management/front-matter/
[hugodirectories]: /getting-started/directory-structure/
[installhugo]: /getting-started/install-hugo/
[listsectiontemplates]: /templates/section-templates/
[install]: /getting-started/install-hugo/
[lists]: /templating/lists/
[partialtemplates]: /templates/partial-templates/
[quickinstall]: /getting-started/install-hugo/#quick-install
[releases]: https://github.com/spf13/hugo/releases
[robusttheme]: https://github.com/dim0627/hugo_theme_robust
[section]: /content-management/sections/
[sectiontemplates]: /templates/section-templates/
[shortcodetemplates]: /templates/shortcode-templates/
[sitemenu]: /content-management/menus/
[templating]: /templates/
content/mailing-list.md
+3 -1
View File
@@ -51,4 +51,6 @@ https://github.com/spf13/hugo/issues
### Twitter
Hugo doesn't have its own Twitter handle, but feel free to tweet [@spf13](http://twitter.com/spf13).
The Official Hugo Twitter Account: [@GoHugoIO](https://twitter.com/GoHugoIO)
Steve Francia: [@spf13](https://twitter.com/spf13).
Bjørn Erik Pedersen: [@bepsays](https://twitter.com/bepsays)
content/templates/custom-404-page.md
+1 -1
View File
@@ -54,4 +54,4 @@ Your 404.html file can be set to load automatically when a visitor enters a mist
* _Amazon AWS S3_ - when setting a bucket up for static web serving, you can specify the error file.
* _Caddy Server_ - using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors)
[pagevars]: /variables-and-params/page-variables/
[pagevars]: /variables/page-variables/
content/templates/data-templates.md
+1 -1
View File
@@ -22,7 +22,7 @@ Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json
**It even works with [LiveReload](/extras/livereload/).**
Data Files can also be used in [themes](/themes/overview/), but note: If the same `key` is used in both the main data folder and in the theme's data folder, the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/mytheme/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag, e.g. `hugo -v`.
Data Files can also be used in [themes](/themes/overview/), but note: If the same `key` is used in both the main data folder and in the theme's data folder, the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/<MYTHEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag, e.g. `hugo -v`.
## The Data Folder
content/templates/go-template-primer.md
+4 -4
View File
@@ -329,7 +329,7 @@ For instance, the following Go template will include the newlines and horizontal
```
{{% /code %}}
{{% output "with-whitespace-output.html" %}}
{{% output file="with-whitespace-output.html" %}}
```html
<div>
Hello, World!
@@ -347,7 +347,7 @@ Leveraging the `-` in the following example will remove the extra white space su
```
{{% /code %}}
{{% output "without-whitespace-input.html" %}}
{{% output file="without-whitespace-input.html" %}}
```html
<div>Hello, World!</div>
```
@@ -438,7 +438,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-and-params/site-variables/).
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/).
```html
<nav class="recent">
@@ -480,5 +480,5 @@ 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"
[variablesparams]: /variables-and-params/ "Link to the list page for the Variables and Params section of the site."
[variablesparams]: /variables/ "Link to the list page for the Variables and Params section of the site."
[You can read more about `index` in the Godocs]: http://golang.org/pkg/text/template/ "Godocs page for index function"
content/templates/lists-in-hugo.md
-47
View File
@@ -1,47 +0,0 @@
---
title: Lists in Hugo
linktitle: Lists in Hugo
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
tags: [lists,sections,rss,taxonomies,terms]
weight: 25
draft: false
aliases: [/templates/list/]
toc: true
needsreview: true
---
## What is a "List" Template
A list page template is a template used to render multiple pieces of content in a single HTML page (with the exception of the homepage, which has a [dedicated template][homepage]).
Hugo uses the term *list* in its truest sense: a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is being listed (e.g., [taxonomies][], [sections][], and [RSS][]). The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
![Image demonstrating a hierarchical website sitemap.](/images/site-hierarchy.svg)
## List Defaults
### Default Templates
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][]) are both *lists* with regards to their templates, both of these templates have the same terminating default of `_default/list.html`---or `themes/mytheme/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sections] and [taxonomy lists][taxonomies] have their own default list templates in `_default`:
#### Default Section Templates
1. `layouts/section/sectionname.html`
### Understanding `.Data.Pages`
{{% note "The Confusion over `.Data`" %}}
**Mention something here about the difference between .Data.Pages and .Site.Data maybe?**
{{% /note %}}
[homepage]: /templates/homepage-template/
[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[RSS]: /templates/rss-templates/
[sections]: /templates/section-templates
[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates/
[taxonomy terms lists]: /templates/#taxonomy-terms-templates/
content/templates/lists.md
+575
View File
@@ -0,0 +1,575 @@
---
title: Introduction to Lists in Hugo
linktitle: Lists in Hugo
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
tags: [lists,sections,rss,taxonomies,terms]
weight: 22
draft: false
aliases: [/templates/lists-in-hugo/]
toc: true
needsreview: true
---
## What is a List Page Template?
A list page template is a template used to render multiple pieces of content in a single HTML page (with the exception of the homepage, which has a [dedicated template][homepage]).
Hugo uses the term *list* in its truest sense: a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is being listed (e.g., [taxonomies][], [sections][], and [RSS][]). The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
---
aliases:
- /doc/using-index-md/
lastmod: 2017-02-22
date: 2017-02-22
linktitle: Using _index.md
menu:
main:
parent: content
prev: /content/example
next: /themes/overview
notoc: true
title: Using _index.md
weight: 70
---
# \_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](/content/sections/), [Taxonomies](/taxonomies/overview/), [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Home page](/templates/homepage/).
In order to take advantage of this behaviour you need to do a few things.
1. Create an \_index.md file that contains the front matter and content you would like to apply.
2. Place the \_index.md file in the correct place in the directory structure.
3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the \_index.md file to be rendered on the respective page.
## How \_index.md pages work
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.
- [Home page template](/templates/homepage/)
- [Content List templates](/templates/list/)
- [Single Content templates](/templates/content/)
- [Taxonomy Terms templates](/templates/terms/)
Now that you've got a handle on templates lets recap some Hugo basics to understand how to use an \_index.md file with a List page.
1. Sections and Taxonomies are 'List' pages, NOT single pages.
2. List pages are rendered using the template heirarchy found in the [Content - List Template](http://localhost:1313/templates/list/) docs.
3. The Home page, though technically a List page, can have [it's own template](/templates/homepage/) at layouts/index.html rather than \_default/list.html. Many themes exploit this behaviour so you are likely to encounter this specific use case.
4. Taxonomy terms pages are 'lists of metadata' not lists of content, so [have their own templates](/templates/terms/).
Let's put all this information together:
> **\_index.md files used in List pages, Terms pages or the Home page are NOT rendered as single pages or with Single Content templates.**
> **All pages, including List pages, can have front matter and front matter can have markdown content - meaning \_index.md files are the way to _provide_ front matter and content to the respective List/Terms/Home page.**
Here are a couple of examples to make it clearer...
| \_index.md location | Page affected | Rendered by |
| ------------------- | ------------ | ----------- |
| /content/post/\_index.md | site.com/post/ | /layouts/section/post.html |
| /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html |
## Why \_index.md files are used
With a Single page such as a post it's possible to add the front matter and content directly into the .md page itself. With List/Terms/Home pages this is not possible so \_index.md files can be used to provide that front matter/content to them.
## How to display content from \_index.md files
From the information above it should follow that content within an \_index.md file won't be rendered in its own Single Page, instead it'll be made available to the respective list, terms, Home page.
To **_actually render that content_** you need to ensure that the relevant template responsible for rendering the List/Terms/Home page contains (at least) `{{ .Content }}`.
This is the way to actually display the content within the \_index.md file on the List/Terms/Home page.
A very simple example is shown in the following default section list page:
{{% code file="layouts/_default/section.html" download="section.html" %}}
```html
{{ define "main" }}
<main>
{{ .Content }}
<ul class="contents">
{{ range .Paginator.Pages }}
<li>{{.Title}}
<div>
{{ partial "summary.html" . }}
</div>
</li>
{{ end }}
</ul>
{{ partial "pagination.html" . }}
</main>
{{ end }}
```
{{% /code %}}
You can see `{{ .Content }}` just after the `<main>` element. For this particular example, the content of the \_index.md file will show before the main list of summaries.
## Where to Organize `\_index.md` Files
To add content and front matter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name \_index on the relevant place on the file system.
```bash
└── content
├── _index.md
├── categories
│ ├── _index.md
│ └── photo
│ └── _index.md
├── post
│ ├── _index.md
│ └── firstpost.md
└── tags
├── _index.md
└── hugo
└── _index.md
```
In the above example \_index.md pages have been added to each section/taxonomy.
An `_index.md` file has also been added in the top level 'content' directory.
### Where to place \_index.md for the Home page
Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the home page.
## List Defaults
### Default Templates
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][]) are both *lists* with regards to their templates, both of these templates have the same terminating default of `_default/list.html`---or `themes/<MYTHEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sections] and [taxonomy lists][taxonomies] have their own default list templates in `_default`:
#### Default Section Templates
1. `layouts/section/<SECTIONNAME>.html`
2. `layouts/section/list.html`
3. `layouts/_default/section.html`
4. `layouts/_default/list.html`
### Understanding `.Data.Pages`
### Taxonomy Lists
A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/topics/golang/) from:
* /layouts/taxonomy/`SINGULAR`.html (e.g.&nbsp;`/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
* /themes/`THEME`/layouts/\_default/taxonomy.html
* /themes/`THEME`/layouts/\_default/list.html
Note that a taxonomy list page can also have a content file with front matter, see [Source Organization](/overview/source-directory/).
### Taxonomy RSS
A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml (e.g.&nbsp;http://spf13.com/topics/golang/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
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
## Variables
A list page is a `Page` and have all the [page variables](/templates/variables/)
and [site variables](/templates/variables/) available to use in the templates.
Taxonomy pages will additionally have:
**.Data.`Singular`** The taxonomy itself.<br>
## Example List Template Pages
### Example Section Template: `post.html`
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates][partials]. All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{% code file="layouts/section/post.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul id="list">
{{ range .Data.Pages }}
{{ .Render "li"}}
{{ end }}
</ul>
</div>
</section>
{{ partial "footer.html" . }}
```
{{% /code %}}
### Example Taxonomy Template
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates](/templates/partials/). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site defined.
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ end }}
{{% /code %}}
## Ordering Content
In the case of Hugo, each list will render the content based on metadata provided in the [front
matter](/content/front-matter/). See [ordering content](/content/ordering/) for more information.
Here are a variety of different ways you can order the content items in
your list templates:
### Order by Weight -> Date (default)
{{ range .Data.Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Weight -> Date
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Date
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by PublishDate
{{ range .Data.Pages.ByPublishDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by ExpiryDate
{{ range .Data.Pages.ByExpiryDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Lastmod
{{ range .Data.Pages.ByLastmod }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Length
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Title
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by LinkTitle
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Parameter
Order based on the specified front matter parameter. Pages without that
parameter will use the site's `.Site.Params` default. If the parameter is not
found at all in some entries, those entries will appear together at the end
of the ordering.
The below example sorts a list of posts by their rating.
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
If the front matter field of interest is nested beneath another field, you can
also get it:
```
{{ range (.Date.Pages.ByParam "author.last_name") }}
<!-- ... -->
{{ end }}
```
### Reverse Order
Can be applied to any of the above. Using Date for an example.
```
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
```
## Grouping Content
Hugo provides some grouping functions for list pages. You can use them to
group pages by Section, Type, Date etc.
Here are a variety of different ways you can group the content items in
your list templates:
### Grouping by Page field
```
{{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page date
```
{{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page publish date
```
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page param
```html
{{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page param in date format
```html
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Reversing Key Order
The ordering of the groups is performed by keys in alphanumeric order (A–Z,
1–100) and in reverse chronological order (newest first) for dates.
While these are logical defaults, they are not always the desired order. There
are two different syntaxes to change the order; they both work the same way, so
it’s really just a matter of preference.
#### Reverse method
```golang
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
```
```golang
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### Providing the (alternate) direction
```golang
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
```golang
{{ range .Data.Pages.GroupBy "Section" "desc" }}
```
### Ordering Pages within Group
Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
In this example, I’ve ordered the groups in chronological order and the content
within each group in alphabetical order by title.
```html
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
## Filtering & Limiting Content
Sometimes you only want to list a subset of the available content. A common
request is to only display “Posts” on the homepage. Using the `where` function,
you can do just that.
### `first`
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
1. `array` or `slice of maps or structs`
2. `number of elements`
{{% code file="layout/_default/section.html" %}}
```golang
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
```
{{% /code %}}
### `where`
`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
1. `array` or a `slice of maps or structs`
2. `key` or `field name'
3. `match value`
{{% code file="layouts/_default/.html" %}}
```html
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{% code file="first-and-where-together.html" %}}
```golang
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
{{% 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-template/
[homepage]: /templates/homepage-template/
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
[partials]: /templates/partial-templates/
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
[RSS]: /templates/rss-templates/
[sections]: /content-management/sections/
[sections]: /templates/section-templates
[singlepages]: /templates/single-page-templates/
[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates/
[taxonomy terms lists]: /templates/#taxonomy-terms-templates/
content/templates/local-file-templates.md
+12 -3
View File
@@ -19,9 +19,9 @@ needsreview: true
With Hugo's [`readDir` function][], you can traverse your website's files on your server.
## Using _readDir_
## Using `readDir`
The `readDir` function returns an array of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo). It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e. as found on your server's file system).
The [`readDir`](/functions/readdir) function returns an array of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo). It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e. as found on your server's file system).
Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both:
@@ -32,7 +32,11 @@ Whether the path is absolute or relative does not matter because---at least for
So, let's create a new shortcode using `readDir`:
{{% code file="layouts/shortcodes/directoryindex.html" %}}<pre><code>{{< readfile "layouts/shortcodes/directoryindex.html" >}}</code></pre>{{% /code %}}
{{% code file="layouts/shortcodes/directoryindex.html" %}}
```html
{{< readfile file="layouts/shortcodes/directoryindex.html" >}}
```
{{% /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.
@@ -50,6 +54,11 @@ The following is the [shortcode declaration][shortcodes] used to render the abov
The initial slash `/` in `pathURL` is important. Otherwise, `pathURL` becomes relative to the current web page.
{{% /note %}}
## Using `readFile`
The [`readDir`](/functions/readdir) function returns...
**CONTENT NEEDED**.
[has already been included in this very website]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
[`readDir` function]: /functions/readdir/
[shortcodes]: /content-management/shortcodes/
content/templates/ordering-and-grouping-lists.md
+21
View File
@@ -0,0 +1,21 @@
---
title: Ordering and Grouping Lists
linktitle: Ordering and Grouping
description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site, but
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [templates]
tags: []
weight: 27
draft: false
aliases: [/templates/ordering/,/templates/grouping/]
toc: true
needsreview: true
---
![Image demonstrating a hierarchical website sitemap.](/images/site-hierarchy.svg)
## Understanding `.Data.*Pages`
From this image, we can assume that the "homepage" for Section A---presumably, `/section-a/index.html`---is going to list the content pages 1,2,3. In this way, pages 1,2,3 are *data* made available to the template that renders to the .
content/templates/rss-templates.md
+10 -9
View File
@@ -18,13 +18,13 @@ needsreview: true
Like all other templates, you can use a single RSS template to generate all of your RSS feeds, or you can create a specific template for each individual feed.
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* `/layouts/section/<section>.rss.xml`
* `/layouts/\_default/rss.xml`
* `/themes/<theme>/layouts/section/<section>.rss.xml`
* `/themes/<theme>/layouts/\_default/rss.xml`
{{% note "Hugo Ships with an RSS Template" %}}
*Unlike other Hugo templates*, Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320). In most cases this will be sufficient, and an RSS template will not need to be provided by the user. But you can provide an rss template if you like, as you can see in the next section.
Unlike other Hugo templates, Hugo ships with its own [RSS 2.0 template][embedded]. In most cases this will be sufficient, and an RSS template will not need to be provided by the user. But you can provide an rss template if you like, as you can see in the next section.
{{% /note %}}
RSS pages are of the type `Page` and have all the [page variables](/layout/variables/) available to use in the templates.
@@ -50,15 +50,15 @@ Hugo will use the following prioritized list. If a file isn’t present, then th
* /layouts/rss.xml
* /layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
* [Embedded rss.xml][embedded]
### Section RSS
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/<mytheme>/layouts/section/<section>.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
* [Embedded rss.xml][embedded]
### Taxonomy RSS
@@ -66,7 +66,7 @@ Hugo will use the following prioritized list. If a file isn’t present, then th
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* [Embedded rss.xml](#the-embedded-rss-xml:eceb479b7b3b2077408a2878a29e1320)
* [Embedded rss.xml][embedded]
## Configuring RSS
@@ -139,5 +139,6 @@ The `.RSSLink` will render the appropriate RSS feed URL for the section, whether
<a href="{{ .URL }}" type="application/rss+xml" target="_blank">{{ .SomeText }}</a>
```
[embedded]:
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
[section]: /content-management/sections/
content/templates/section-templates.md
+5 -416
View File
@@ -16,7 +16,7 @@ needsreview: true
## Introduction to the Template Lookup Order
{{< lookupexplanation >}}
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
## Lookup Order for Section Page Templates
@@ -24,422 +24,19 @@ Hugo uses a set of rules to figure out which template to use when rendering a sp
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites only the \_default file at the end of the list will be needed.
### Section Lists
### Section Template Page Lookup Order
A Section will be rendered at /`SECTION`/ (e.g.&nbsp;http://spf13.com/project/)
A Section will be rendered at /<SECTION>/ (e.g.&nbsp;http://spf13.com/project/)
* /layouts/section/`SECTION`.html
* /layouts/section/<SECTION>.html
* /layouts/\_default/section.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/section/`SECTION`.html
* /themes/<THEME>/layouts/section/`SECTION`.html
* /themes/`THEME`/layouts/\_default/section.html
* /themes/`THEME`/layouts/\_default/list.html
Note that a sections list page can also have a content file with frontmatter, see [Source Organization](/overview/source-directory/}}).
### Taxonomy Lists
A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/topics/golang/) from:
* /layouts/taxonomy/`SINGULAR`.html (e.g.&nbsp;`/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
* /themes/`THEME`/layouts/\_default/taxonomy.html
* /themes/`THEME`/layouts/\_default/list.html
Note that a taxonomy list page can also have a content file with frontmatter, see [Source Organization](/overview/source-directory/).
### Taxonomy RSS
A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml (e.g.&nbsp;http://spf13.com/topics/golang/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
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
## Variables
A list page is a `Page` and have all the [page variables](/templates/variables/)
and [site variables](/templates/variables/) available to use in the templates.
Taxonomy pages will additionally have:
**.Data.`Singular`** The taxonomy itself.<br>
## Example List Template Pages
### Example Section Template: `post.html`
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates][partials]. All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{% code file="layouts/section/post.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul id="list">
{{ range .Data.Pages }}
{{ .Render "li"}}
{{ end }}
</ul>
</div>
</section>
{{ partial "footer.html" . }}
```
{{% /code %}}
### Example taxonomy template (tag.html)
This content template is used for [spf13.com](http://spf13.com/).
It makes use of [partial templates](/templates/partials/). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ partial "footer.html" . }}
## Ordering Content
In the case of Hugo, each list will render the content based on metadata provided in the [front
matter](/content/front-matter/). See [ordering content](/content/ordering/) for more information.
Here are a variety of different ways you can order the content items in
your list templates:
### Order by Weight -> Date (default)
{{ range .Data.Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Weight -> Date
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Date
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by PublishDate
{{ range .Data.Pages.ByPublishDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by ExpiryDate
{{ range .Data.Pages.ByExpiryDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Lastmod
{{ range .Data.Pages.ByLastmod }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Length
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Title
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by LinkTitle
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Parameter
Order based on the specified frontmatter parameter. Pages without that
parameter will use the site's `.Site.Params` default. If the parameter is not
found at all in some entries, those entries will appear together at the end
of the ordering.
The below example sorts a list of posts by their rating.
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
If the frontmatter field of interest is nested beneath another field, you can
also get it:
```
{{ range (.Date.Pages.ByParam "author.last_name") }}
<!-- ... -->
{{ end }}
```
### Reverse Order
Can be applied to any of the above. Using Date for an example.
```
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
```
## Grouping Content
Hugo provides some grouping functions for list pages. You can use them to
group pages by Section, Type, Date etc.
Here are a variety of different ways you can group the content items in
your list templates:
### Grouping by Page field
```
{{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page date
```
{{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page publish date
```
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page param
```html
{{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Grouping by Page param in date format
```html
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
### Reversing Key Order
The ordering of the groups is performed by keys in alphanumeric order (A–Z,
1–100) and in reverse chronological order (newest first) for dates.
While these are logical defaults, they are not always the desired order. There
are two different syntaxes to change the order; they both work the same way, so
it’s really just a matter of preference.
#### Reverse method
```golang
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
```
```golang
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### Providing the (alternate) direction
```golang
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
```golang
{{ range .Data.Pages.GroupBy "Section" "desc" }}
```
### Ordering Pages within Group
Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
In this example, I’ve ordered the groups in chronological order and the content
within each group in alphabetical order by title.
```html
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ range .Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
</ul>
{{ end }}
```
## Filtering & Limiting Content
Sometimes you only want to list a subset of the available content. A common
request is to only display “Posts” on the homepage. Using the `where` function,
you can do just that.
### `first`
`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
1. `array` or `slice of maps or structs`
2. `number of elements`
{{% code file="layout/_default/section.html" %}}
```golang
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
```
{{% /code %}}
### `where`
`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
1. `array` or a `slice of maps or structs`
2. `key` or `field name'
3. `match value`
{{% code file="layouts/_default/.html" %}}
```html
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
{{% code file="first-and-where-together.html" %}}
```golang
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
```
{{% /code %}}
{{% 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 %}}
## `.Site.GetPage`
Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with [`where`](/functions/where/) in your templates to create kind-specific lists of content, but there are times where you may want to fetch the index page of a single section by the section's path.
@@ -464,11 +61,3 @@ The `.Site.GetPage` example assumes the following project directory structure:
{{% /code %}}
`.Site.GetPage` will return `nil` if no `_index.md` page is found. If `content/blog/_index.md` does not exist, the template will output a blank section where `{{.Title}}` should have been in the preceding example.
[sections]: /content-management/sections/
[directorystructure]: /getting-started/directory-structure/
[homepage]: /templates/homepage-template/
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
[partials]: /templates/partial-templates/
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
[singlepages]: /templates/single-page-templates/
content/templates/shortcode-templates.md
+6 -6
View File
@@ -119,7 +119,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
{{% output "youtube-embed.html" %}}
{{% output file="youtube-embed.html" %}}
```html
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
@@ -168,7 +168,7 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
Would be rendered as:
{{% output "figure.html" %}}
{{% output file="figure.html" %}}
```html
<figure >
<img src="/media/spf13.jpg" />
@@ -204,7 +204,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
Would be rendered as:
{{% output "vimeo-iframes.html" %}}
{{% output file="vimeo-iframes.html" %}}
```html
<div class="vimeo-container">
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
@@ -237,7 +237,7 @@ The template for the `highlight` shortcode uses the following code, which is alr
The rendered output of the HTML example code block will be as follows:
{{% output "syntax-highlighted.html" %}}
{{% output file="syntax-highlighted.html" %}}
```html
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672">&lt;html&gt;</span>
<span style="color: #f92672">&lt;body&gt;</span> This HTML <span style="color: #f92672">&lt;/body&gt;</span>
@@ -259,8 +259,8 @@ More shortcode examples can be found in the [shortcodes directory for spf13.com]
[source organization]: /getting-started/directory-structure/ "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
[docsshortcodes]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
[figure]: /content-management/shortcodes/#figure
[pagevars]: /variables-and-params/page-variables/ "See which variables you can leverage in your templating for page vs list templates."
[shortcodesvars]: /variables-and-params/shortcode-variables/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
[pagevars]: /variables/page-variables/ "See which variables you can leverage in your templating for page vs list templates."
[shortcodesvars]: /variables/shortcode-variables/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
[spf13shortcodes]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
[templates]: /templates/ "The templates section of the Hugo docs."
[vimeoexample]: #single-flexible-example-vimeo
content/templates/single-page-templates.md
+19 -19
View File
@@ -17,7 +17,7 @@ The primary view of content in Hugo is the single view. Hugo will render every M
## Introduction to the Template Lookup Order
{{< lookupexplanation >}}
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
## Lookup Order for Single Page Templates
@@ -97,11 +97,11 @@ When it comes time for Hugo to render the content to the page, it will go throug
4. <span class="yes">`/layouts/posts/single.html`</span>
<br><span class="break">BREAK</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/mytheme/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/mytheme/layouts/posts/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/mytheme/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/mytheme/layouts/posts/single.html`</span>
10. <span class="na">`/themes/mytheme/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<MYTHEME>/layouts/posts/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<MYTHEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][section].)
@@ -129,11 +129,11 @@ Here is the way Hugo's traverses the single-page lookup order for `my-second-pos
3. <span class="na">`/layouts/review/single.html`</span>
4. <span class="na">`/layouts/posts/single.html`</span>
5. <span class="na">`/layouts/_default/single.html`</span>
6. <span class="na">`/themes/mytheme/layouts/review/reviewarticle.html`</span>
7. <span class="na">`/themes/mytheme/layouts/posts/reviewarticle.html`</span>
8. <span class="na">`/themes/mytheme/layouts/review/single.html`</span>
9. <span class="na">`/themes/mytheme/layouts/posts/single.html`</span>
10. <span class="na">`/themes/mytheme/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<MYTHEME>/layouts/review/reviewarticle.html`</span>
7. <span class="na">`/themes/<MYTHEME>/layouts/posts/reviewarticle.html`</span>
8. <span class="na">`/themes/<MYTHEME>/layouts/review/single.html`</span>
9. <span class="na">`/themes/<MYTHEME>/layouts/posts/single.html`</span>
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
@@ -161,11 +161,11 @@ Here is the way Hugo's traverses the single-page lookup order for `my-first-even
4. <span class="no">`/layouts/events/single.html`</span>
5. <span class="yes">`/layouts/_default/single.html`</span>
<br><span class="break">BREAK</span>
6. <span class="na">`/themes/mytheme/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/mytheme/layouts/events/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/mytheme/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/mytheme/layouts/events/single.html`</span>
10. <span class="na">`/themes/mytheme/layouts/_default/single.html`</span>
6. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
7. <span class="na">`/themes/<MYTHEME>/layouts/events/UNSPECIFIED.html`</span>
8. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/single.html`</span>
9. <span class="na">`/themes/<MYTHEME>/layouts/events/single.html`</span>
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
{{% note %}}
`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing-a-theme/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream.
@@ -179,7 +179,7 @@ Content pages are of the type `page` and will therefore have all the [page varia
This content template is used for [spf13.com][spf13]. It makes use of [partial templates][partials]:
{{% code file="layouts/post/single.html" %}}
{{% code file="layouts/post/single.html" download="single.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
@@ -228,7 +228,7 @@ This content template is used for [spf13.com][spf13]. It makes use of [partial t
This content template is also used for [spf13.com][spf13] and makes use of [partial templates][partials]:
{{% code file="project/single.html" %}}
{{% code file="project/single.html" download="single.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
@@ -285,5 +285,5 @@ To easily generate new instances of this content type (e.g., new `.md` files in
[page variables]: /variables-and-parms/page-variables/
[partials]: /templates/partial-templates/
[section]: /content-management/sections/
[site variables]: /variables-and-params/site-variables/
[site variables]: /variables/site-variables/
[spf13]: http://spf13.com/
content/templates/taxonomy-templates.md
+1 -1
View File
@@ -24,7 +24,7 @@ Hugo provides multiple ways to leverage taxonomies through your project:
## Introduction to the Template Lookup Order
{{< lookupexplanation >}}
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
## Taxonomy List Templates
content/themes/creating-a-theme.md
+1 -1
View File
@@ -35,7 +35,7 @@ which are archetypal content types used by the `hugo new` command.
{{% note "Use the Hugo Generator Tag" %}}
The [`.Hugo.Generator`](/variables-and-params/other/) tag is included in all themes featured in the [Hugo Them Showcase](/http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo. The generator tag is significant in that it allows the Hugo team to track Hugo's usage and popularity.
The [`.Hugo.Generator`](/variables/other/) tag is included in all themes featured in the [Hugo Them Showcase](/http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo. The generator tag is significant in that it allows the Hugo team to track Hugo's usage and popularity.
{{% /note %}}
## Layouts
content/themes/customizing-a-theme.md
+2 -2
View File
@@ -24,7 +24,7 @@ When you use a theme cloned from its git repository, do not edit the theme's fil
## Understanding the Theme Lookup Order
{{< lookupexplanation >}}
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
## Replacing Static Files
@@ -33,7 +33,7 @@ There are times where you want to include static assets that differ from version
Let's assume the theme you are using has jQuery 1.8 in the following location:
```bash
/themes/mytheme/static/js/jquery.min.js
/themes/<MYTHEME>/static/js/jquery.min.js
```
You want to replace jQuery with jQuery 1.7. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root.
tree.md → content/tree.txt
+8 -7
View File
@@ -1,6 +1,3 @@
## Content Files at a Glance
```
.
├── _index.md
├── about-hugo
@@ -13,6 +10,7 @@
│   └── why-i-built-hugo.md
├── commands
│   └── _index.md
├── concept.md
├── content-management
│   ├── _index.md
│   ├── archetypes.md
@@ -48,10 +46,11 @@
│   ├── base64decode.md
│   ├── base64encode.md
│   ├── chomp.md
│   ├── count.md
│   ├── countrunes.md
│   ├── countwords.md
│   ├── dateformat.md
│   ├── default-function.md
│   ├── default.md
│   ├── delimit.md
│   ├── dict.md
│   ├── echoparam.md
@@ -118,6 +117,7 @@
│   ├── time.md
│   ├── title.md
│   ├── trim.md
│   ├── truncate.md
│   ├── unix.md
│   ├── upper.md
│   ├── urlize.md
@@ -249,6 +249,7 @@
│   ├── data-templates.md
│   ├── go-template-primer.md
│   ├── homepage-template.md
│   ├── lists-in-hugo.md
│   ├── local-file-templates.md
│   ├── menu-templates.md
│   ├── pagination.md
@@ -266,6 +267,7 @@
│   ├── customizing-a-theme.md
│   ├── installing-and-using-themes.md
│   └── theme-showcase.md
├── tree.txt
├── troubleshooting
│   ├── _index.md
│   ├── accented-characters-in-urls.md
@@ -278,10 +280,9 @@
└── variables-and-params
├── _index.md
├── file-variables.md
├── other-variables.md
├── page-variables.md
├── shortcode-git-and-hugo-variables.md
├── site-variables.md
└── taxonomy-variables.md
15 directories, 265 files
```
15 directories, 270 files
content/variables-and-params/other-variables.md
+1 -1
View File
@@ -9,7 +9,7 @@ categories: [variables and params]
tags: [shortcodes,git]
draft: false
weight: 50
aliases: [/extras/gitinfo/,/variables-and-params/other/]
aliases: [/extras/gitinfo/,/variables/other/]
toc: true
needsreview: true
---
content/variables-and-params/page-variables.md
+3 -3
View File
@@ -43,7 +43,7 @@ See [`.Scratch`](/functions/scratch/) for page-scoped writable variables.
: the approximate number of words in the content.
`.Hugo`
: see [Hugo Variables](/variables-and-params/other/).
: see [Hugo Variables](/variables/other/).
`.IsHome`
: `true` in the context of the [home page](/templates/homepage-template/).
@@ -121,7 +121,7 @@ http://remarkjs.com)
: the [section](/content-management/sections/) this content belongs to.
`.Site`
: see [Site Variables](/variables-and-params/site-variables/).
: see [Site Variables](/variables/site-variables/).
`.Summary`
: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Content Summaries](/content-management/content-summaries/) for more details.
@@ -199,7 +199,7 @@ Two common situations where this type of front matter field could be introduced
This template would render as follows, assuming you've set [`uglyURLs`](/content-management/url-management/) to `false` in your [site `config`](/getting-started/configuration/):
{{% output "yourbaseurl/review/book01/index.html" %}}
{{% output file="yourbaseurl/review/book01/index.html" %}}
```html
<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
<p>It was recommended by my Mother.</p>
layouts/shortcodes/output.html
+4 -2
View File
@@ -1,4 +1,6 @@
<div class="code-copy" id="{{.Get 0 | urlize}}">
<div class="code-copy-header output"><div class="action-buttons"></div><span class="filename" title="{{.Get 0}}">{{.Get 0}}</span><i class="icon-{{index (split (.Get 0) ".") 1 }}"></i></div>
{{$file := .Get "file"}}
{{$icon := index (split $file ".") 1 }}
<div class="code-copy" id="{{$file | urlize}}">
<div class="code-copy-header output"><div class="action-buttons"></div><span class="filename" title="{{$file}}">{{$file}}</span><i class="icon-{{$icon}}"></i></div>
{{- .Inner -}}
</div>
layouts/shortcodes/readfile.html
+6 -1
View File
@@ -1 +1,6 @@
{{- .Get 0 | readFile -}}
{{$file := .Get "file"}}
{{- if eq (.Get "markdown") "true" -}}
{{- $file | readFile | markdownify -}}
{{- else -}}
{{ $file | readFile }}
{{- end -}}
readfile-content/lookupexplanation.md
+6
View File
@@ -0,0 +1,6 @@
Hugo uses a prioritized list called the *lookup order* as it traverses your files looking for the appropriate template to render your content. The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C, and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<mytheme>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][dry]. *Most sites will only need the default template files at the end of the lookup* (i.e. `_default/*.html`).
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
readfile-content/menuvars.md
+39
View File
@@ -0,0 +1,39 @@
`.URL`
: string
`.Name`
: string
`.Menu`
: string
`.Identifier`
: string
`.Pre`
: template.HTML
`.Post`
: template.HTML
`.Weight`
: int
`.Parent`
: string
`.Children`
: Menu
Note that menus also have the following functions available as well:
[`.HasChildren`](/functions/haschildren/)
: boolean
Additionally, there are some relevant functions available to menus on a page:
[`.IsMenuCurrent`](/functions/ismenucurrent/)
: (menu string, menuEntry *MenuEntry ) boolean
[`.HasMenuCurrent`](/functions/hasmenucurrent/)
: (menu string, menuEntry *MenuEntry) boolean
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
static/documents/gitlab-git-cheat-sheet.pdf
+130423
View File
File diff suppressed because one or more lines are too long
strategy.md
-166
View File
@@ -1,166 +0,0 @@
# Hugo Docs Concept Strategy, Tactics, and Requirements
> **Disclaimer:** WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the content strategy document.
**Updated 2017-02-21**
- [Assumptions](#assumptions)
- [Goals](#goals)
- [Audience](#audience)
- [Persona](#persona)
- [End User: Developer](#end-user-developer)
- [End User: Themes \(i.e. blogger/author/\)](#end-user-themes-ie-bloggerauthor)
- [Requirements](#requirements)
- [Technical](#technical)
- [SEO](#seo)
- [Editorial/Content](#editorialcontent)
- [UX/UI](#uxui)
- [Author Experience \(AX\)](#author-experience-ax)
- [Analytics/Metrics](#analyticsmetrics)
- [Visual Design](#visual-design)
## Assumptions
> **Note**: These assumptions are *empirical*. In other words, they are the result of me spending a large (and potentially unhealthy) amount of time on the [Hugo Discussion Forum](https://discuss.gohugo.io). Google analytics *may* provide more quantitative insight into actual Hugo docs usage. These are *assumptions* and not *criticisms*. I **LOVE** Hugo.
* The current documentation is
* confusing for new users
* a common complaint in the Hugo forums ([example discussion 1][],[example discussion 2][])
* lacks structure and therefore
* doesn't scale, as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown)
* is inconsistent in its terminology, style, and (sometimes) layout
* limits the efficacy of Alogolia's document search feature through redundant content groups, headings, etc
* does not leverage SEO for external search engines
* does not leverage Hugo's more powerful feature (e.g., there is only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or to web development in general. An example of this is the sparsity of basic vs advanced code samples through the templating functions.
* If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*;
* content modeling is king
* go DRY (e.g., with shortcodes)
* set required metadata (and use *archetypes*)
* develop for contribution guidelines to dev *and* docs
## Goals
New Hugo documentation should...
* reduce confusion surrounding Hugo concepts; e.g., `list`, `section`, `page`, and `content type` and thereby
* make it easier for new users to get up and running
* create better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io](http://themes.gohugo.io))
* reduce frequency of questions surrounding said concepts in the [Hugo Discussion Forum](https://discuss.gohugo.io)
* not require or assume any degree of Golang proficiency from end users;
* that said, Hugo can&mdash;and *should*&mdash;act as a bridge for users interested in learning Golang (e.g., inclusion of `godocref` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
* be easiest to expand and edit for *contributors** but even easier to understand by *end users*.
* be equally accessible via mobile, tablet, desktop, *and* offline.
* not include an "extras" section; i.e. since [this is the last place end users look to get up and running with Hugo](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3). Current *Extras* should be integrated into the new defined content groupings and site architecture.
* easily scaffold for future multilingual versions
## Audience
* Primary: Web developers interested in static site generators
* Secondary: Web publishers (bloggers, authors)
* Tertiary: Web developers interested in learning Golang
## Persona
### End User: SSG Developer
The SSG developer has
* basic proficiency in Git and DVCS
* no to little proficiency in Golang
* working proficiency in front-end development---HTML, CSS, JS---but not necessarily front-end build tools
* basic familiarity with at least one double-curly templating language (e.g., liquid, Twig, Swig, or Django)
* proficiency in the English language for the current version of the documentation
* proficiency in other languages (for future multilingual versions)
### End User: Themes (i.e. blogger/author/hobbyist)
The themes end user has
* limited proficiency in the command line/prompt
* proficiency in one of the [supported content formats](https://hugodocsconcept.netlify.com/content-management/supported-content-formats/)(specifically markdown)
* access to static hosting;
* limited proficiency in deploying a static website
## Requirements
### Technical
- [X] Built with Hugo
- [X] Performant (e.g., 80+ [Google Page Speed Score](https://developers.google.com/speed/pagespeed/insights/?url=https%3A%2F%2Fhugodocsconcept.netlify.com%2Fabout-hugo))
- [X] Front-end build tools for concatenation, minification, of static assets
- [X] Browser compatibility: modern (i.e. Chrome, Edge, Firefox, Safari) and IE11
- [ ] CDN
- [ ] AMP?
### SEO
- [X] [Open Graph Protocol](http://ogp.me/)
- [X] [schema.org](http://schema.org)
- [ ] [JSON+LD](https://developers.google.com/schemas/formats/json-ld), [validated](https://search.google.com/structured-data/testing-tool)
- [X] Consistent heading structure
- [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`)
- [X] SSL
- [ ] AMP?
### Editorial/Content
- [ ] Basic style guide
- The style guide should facilitate a more consistent UX for the site but not be so complex as to deter documentation contributors
- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/))
- [X] Standardized content types (see [WIP archetypes in source](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
- [X] New content model, including taxonomies ([see tags page][tagspage])
- [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
- [X] New site architecture and content groupings
- [ ] Single sample website (include in docs source, [`/static/example`](https://github.com/rdwatters/hugo-docs-concept/tree/master/static/example)) for consistent code samples or in-page tutorials
#### [Content Strategy Statement](http://contentmarketinginstitute.com/2016/01/content-on-strategy-templates/)
> The Hugo documentation increases the Hugo user base and strengthens the Hugo community by providing intuitive, beginner-friendly, regularly updated usage guides. Hugo documentation makes visitors feel excited and confident that Hugo is the ideal choice for static website development.
#### [Editorial Mission](http://contentmarketinginstitute.com/2015/10/statement-content-marketing/)
> The Hugo documentation is a joint effort between the Hugo maintainers and the open-source community. Hugo documentation is designed to promote Hugo, the world's fastest, friendliest, and most extensible static site generator. Hugo documentation is the primary vehicle by which the Hugo team reaches its target audiences. When visitors comes to the Hugo documentation, we want them to install Hugo, develop a new static website with our tool, and share their progress and insights with the Hugo community at large.
## UX/UI
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
- [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
- [X] Smooth scrolling
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](http://localhost:1313/contribute-to-hugo/contribute-to-the-hugo-docs/#admonition-short-codes))
- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums
## Author Experience (AX)
- [X] Easy scaffolding of content types (CLI)
- [X] Type-based content storage model and scope (archetypes)
## Analytics/Metrics
- [X] Google Analytics
- [ ] Content groupings (GA) to measure usage, behavior flow, and define content gaps
- [ ] Automated reports (GA)
> **Note:** These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
## Visual Design
- [X] Clean typography with open-source font
- [X] Optimal line length (50-80 characters)
- [X] Consistent vertical rhythm
- [X] Responsive
- [X] Flexbox
- [X] Typography (via ems)
- [X] Custom iconography
- [X] Design assets versioned with source ([see design resources directory][designresources])
- [X] [WCAG color contrast requirements](http://webaim.org/blog/wcag-2-0-and-link-colors/)
- [X] [Sass Guidelines for Source Organization](https://sass-guidelin.es/)
- [X] Abstracted color palette
- [X] Abstracted typefaces (multiple open-source fonts available)
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
[example discussion 1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
[example discussion 2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md
[tagspage]: https://hugodocsconcept.netlify.com/tags/
themes/hugodocs/layouts/_default/single.html
+20 -18
View File
@@ -2,23 +2,25 @@
{{$title := .Title}}
<span id="page-top"></span>
<main class="main">
<header class="content-header">
{{partial "breadcrumb.html" . }}
<h1 class="page-title {{.Section}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">{{ .Title | markdownify }}</h1>
{{partial "content-header-links.html" . }}
{{partial "tags.html" . }}
{{if .Params.needsreview }}
<div id="beingreviewed">WIP</div>
{{end}}
{{if .Params.outdated}}
<div id="outdated">OUTDATED</div>
{{end}}
{{$title := .Title}}
</header>
<div class="body-copy">
{{.Content}}
</div>
{{partial "content-footer.html" . }}
<article class="content" id="{{.Title | urlize}}">
<header class="content-header">
{{- partial "breadcrumb.html" . -}}
<h1 class="page-title {{.Section}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">{{ .Title | markdownify }}</h1>
{{- partial "content-header-links.html" . -}}
{{- partial "tags.html" . -}}
{{- if .Params.needsreview -}}
<div id="beingreviewed">WIP</div>
{{- end -}}
{{- if .Params.outdated -}}
<div id="outdated">OUTDATED</div>
{{- end -}}
{{ $title := .Title }}
</header>
<div class="body-copy">
{{.Content}}
</div>
{{- partial "content-footer.html" . -}}
</article>
</main>
{{partial "table-of-contents.html" . }}
{{- partial "table-of-contents.html" . -}}
{{ end }}
themes/hugodocs/layouts/partials/content-footer.html
+2 -3
View File
@@ -12,11 +12,10 @@
{{ else if eq .Kind "page" }}
{{ with .Site.GetPage "section" $section }}
<a href="{{.Permalink}}" class="prev-and-next-link prev-page">
<i class="fa fa-chevron-left"></i>
<div class="page-info">
<span>Previous</span>
<h5 class="{{$section}}">{{.Title}}{{if and (ne .Section "functions") (ne .Section "hosting-and-deployment")}} of {{.Section | humanize | title}}{{end}}</h5>
<h5 class="{{$section}}">{{ .LinkTitle }}</h5>
</div>
</a>
{{ end }}
@@ -41,4 +40,4 @@
</a>
{{end}}
{{end}}
</footer>
</footer>
themes/hugodocs/layouts/partials/lookup-explanation-markdown.html
-6
View File
@@ -1,6 +0,0 @@
Hugo uses a prioritized list called the *lookup order* as it traverses your files looking for the appropriate template to render your content. The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C, and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<mytheme>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][dry]. *Most sites will only need the default template files at the end of the lookup* (i.e. `_default/*.html`).
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
themes/hugodocs/pipeline/scss/components/_anchors.scss
+1 -23
View File
@@ -96,26 +96,4 @@ a.heading-link {
&:hover {
color: $default-anchor-underline-color;
}
}
// .body-copy {
// a[href*="github.com"]:after {
// content: '\f09b';
// font-family: 'fontello';
// color: inherit;
// display: inline-block;
// margin-left: .1em;
// @include size(1em);
// margin-right: .2em;
// text-align: center;
// }
// a[href*="discuss.gohugo.io"]:after {
// content: '\f03d';
// display: inline-block;
// font-family: 'fontello';
// margin-left: .1em;
// @include size(1em);
// margin-right: .2em;
// text-align: center;
// }
// }
}
themes/hugodocs/pipeline/scss/components/_shortcode-examples.scss
+5
View File
@@ -0,0 +1,5 @@
.twitter-tweet.twitter-tweet-rendered {
display:block;
margin-left:auto;
margin-right:auto;
}
themes/hugodocs/pipeline/scss/layout/_site-content.scss
+10 -16
View File
@@ -20,35 +20,29 @@
}
}
// main.main {
// width: 90%;
// display: block;
// margin-left: auto;
// margin-right: auto;
// max-width: $content-max-width;
// position: relative;
// min-height:calc(100vh - #{$site-header-height * 2});
// // overflow-x: hidden;
// @include MQ(L) {
// margin-left: 2em;
// }
// }
main.main {
width: 90%;
width: 100%;
display: block;
margin-left: auto;
margin-right: auto;
position: relative;
min-height:calc(100vh - #{$site-header-height * 2});
@include MQ(XL) {
width: 90%;
width: 100%;
margin-right: 0px;
max-width: calc(100vw - #{$site-navigation-width * 2} - 20px);
float: left;
padding-left: 1.5em;
padding-left: 0px;
padding-right: 0px;
}
}
article.content {
width: 90%;
margin-left: auto;
margin-right: auto;
}
header.content-header {
display: block;
clear: both;
themes/hugodocs/pipeline/scss/style.scss
+1
View File
@@ -34,6 +34,7 @@
@import 'components/tables';
@import 'vendor/featherlight.scss';
@import 'components/lookup-explanation';
@import 'components/shortcode-examples';
//major layout parts/chrome
@import 'layout/site-header';
themes/hugodocs/pipeline/scss/vendor/_highlightjs.scss
Vendored
+5
View File
@@ -1,6 +1,7 @@
/*
Monokai Sublime style. Derived from Monokai by noformnocontent http://nn.mit-license.org/
*/
/* SEE HUGO SPECIFIC CLASSES AT BOTTOM OF PAGE*/
.hljs {
display: block;
@@ -79,4 +80,8 @@ Monokai Sublime style. Derived from Monokai by noformnocontent http://nn.mit-lic
.hljs-deletion,
.hljs-meta {
color: $hugo-gray-light;
}
.language-toml.hljs .hljs-section {
color:$hugo-pink-light;
}