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

Add finalized views.md and usage.md

Browse Source
This commit is contained in:
Ryan Watters
2017-03-09 19:08:32 -06:00
parent 60c2babf0e
commit c1437ea459
8 changed files with 82 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/getting-started/directory-structure.md
+1 -3
View File
@@ -19,8 +19,6 @@ website.
## Directory Scaffolding in `new hugo site`
The top level of a source directory will typically have the following elements:
```bash
@@ -34,7 +32,7 @@ The top level of a source directory will typically have the following elements:
config.toml
```
Learn more about the different directories and what their purpose is:
You can learn more about each component of a newly scaffolded site in its respective documentation:
* [config](/getting-started/configuration/)
* [data](/templates/data-templates/)
content/getting-started/installing.md
+7 -10
View File
@@ -14,11 +14,7 @@ aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overv
toc: true
---
## Quick Install
Hugo is written in [Golang](https://golang.org/) with support for multiple platforms.
The latest release can be found at [Hugo Releases][releases].
Hugo is written in [Golang](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].
Hugo currently provides pre-built binaries for the following:
@@ -29,6 +25,8 @@ Hugo currently provides pre-built binaries for the following:
Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., for other operating systems, including DragonFly BSD, OpenBSD, Plan&nbsp;9 and Solaris. See <http://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures.
## Quick Install
### Binary (Cross-platform)
Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.
@@ -45,7 +43,7 @@ brew update && brew install hugo
```
{{% /code %}}
For more detailed explanations, read the installation guides that follow for [Windows](#installing-hugo-on-windows) and [Mac OS X](#installing-hugo-on-mac-osx).
For more detailed explanations, read the installation guides that follow for installing on Mac OS X and Windows.
### Source
@@ -72,7 +70,7 @@ You may run `go get` with the `-u` option to update Hugo's dependencies:
go get -u -v github.com/spf13/hugo
```
## <i class="fa fa-apple"></i> OS X
## <i class="icon-apple"></i>OS X
### Assumptions
@@ -293,7 +291,7 @@ go build -o hugo main.go
Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
## <i class="fa fa-windows"></i> Windows
## <i class="icon-windows"></i>Windows
The following aims to be a complete guide to installing Hugo on your Windows PC.
@@ -408,7 +406,7 @@ C:\Hugo\Sites\example.com&gt;dir
{{< youtube c8fJIRNChmU >}}
## <i class="fa fa-linux"></i> Linux
## <i class="icon-linux"></i>Linux
### Installing From Snap
@@ -426,7 +424,6 @@ Install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch
Be aware that Hugo is built from source. This means that additional tools like Git and Go (the programming language Hugo is written in) will be installed as well.
{{% /note %}}
```bash
sudo pacman -S yaourt
yaourt -S hugo
content/getting-started/usage.md
+47 -70
View File
@@ -9,11 +9,12 @@ categories: [getting started]
tags: [usage,livereload,command line,flags]
weight: 40
draft: false
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/]
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
toc: true
wip: true
---
The following is a description of the most command commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI.
## Testing Installation
Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command:
@@ -88,11 +89,13 @@ Flags:
-w, --watch watch filesystem for changes and recreate as needed
```
## Common Usage
## The `hugo` Command
The most common usage is probably to run `hugo` with your current directory being the input directory.
This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field. The site Hugo renders into `public/` is ready to be deployed to your web server.
This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field.
The site Hugo renders into `public/` is ready to be deployed to your web server:
```bash
hugo
@@ -105,60 +108,46 @@ hugo
in 90 ms
```
## Instant Feedback During Development
## Draft, Future, and Expired Content
If you are working on things and want to see the changes immediately, by default Hugo will watch the file system for changes and rebuild your site as soon as a file is saved:
Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish:
```bash
hugo -s ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Press Ctrl+C to stop
```
1. Content with a future `publishdate` value
2. Content with `draft: true` status
3. Content with a past `expirydate` value
Hugo can even run a server and create a site preview at the same time! Hugo implements LiveReload technology to automatically reload any open pages in all JavaScript-enabled browsers, including mobile. This is the easiest and most common way to develop a Hugo web site:
All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]:
```bash
hugo server -ws ~/Code/hugo/docs
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Serving pages from /Users/spf13/Code/hugo/docs/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop
```
Hugo may not be the first static site generator to utilize LiveReload
technology, but it’s the first to do it right.
1. `--buildFuture`
2. `--buildDrafts`
3. `--buildExpired`
The combination of Hugo’s insane build speed and LiveReload make
crafting your content pure joy. Your updated content appears virtually instantly in your browser as soon as you save your changes.
## LiveReload
### LiveReload
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server and watch for changes:
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes:
```bash
hugo server
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static}
Serving pages from /Users/yourname/sites/yourhugosite/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop
```
This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following the following areas of your [project organization][dirs]
This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]:
* `/static/*`
* `/content/*`
* `/data/*`
* `/layouts/*`
* `/themes/<only your current theme>/*`
* `/themes/<CURRENT-THEME>/*`
* `config`
Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page.
@@ -166,26 +155,26 @@ Whenever you make changes, Hugo will simultaneously rebuild the site and continu
Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor.
{{% note "Closing `</body>` Tag"%}}
You must have a closing `</body>` tag for LiveReload to work.
Hugo injects the LiveReload `<script>` before this tag.
Hugo injects the LiveReload `<script>` before the closing `</body>` in your templates and will therefore not work if this tag is not present..
{{% /note %}}
### Disabling LiveReload's Watch Feature
### Disabling LiveReload
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the
Hugo web socket server.
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the Hugo web socket server.
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. As such, we’ve provided multiple methods made it easy to disable the LiveReload functionality:
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. The following methods make it easy to disable LiveReload:
```bash
hugo server --watch=false
```
Or...
```bash
hugo server --disableLiveReload
```
The latter flag can be omitted by adding the following key-value to your `config` file:
The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively:
```toml
disableLiveReload = true
@@ -197,17 +186,15 @@ disableLiveReload: true
## Deploying Your Website
After running `hugo server` for local web development, you need to do a final `hugo` run **without the `server` part of the command** to rebuild your site. You may then **deploy your site** by copying the `public/` directory (by FTP, SFTP, WebDAV, Rsync, `git push`, etc.) to your production web server.
After running `hugo server` for local web development, you need to do a final `hugo` run *without the `server` part of the command* to rebuild your site. You may then deploy your site by copying the `public/` directory to your production web server.
Since Hugo generates a static website, your site can be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Amazon S3][] with [CloudFront][], [Firebase Hosting][], or any other cheap (or even free) static web hosting service.
[Apache][], [nginx][], [IIS][]...any web server software will work.
Since Hugo generates a static website, your site can be hosted *anywhere* using any web server. See [Hosting and Deployments][] for methods for hosting and automating deployments contributed by the Hugo community.
{{% warning "Generated Files are **NOT** Removed on Site Build" %}}
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the directory you specified with `-d`/`--destination`) before running the `hugo` command, or you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the publish directory you specified via flag or configuration file) before running the `hugo` command. If you do not remove these files, you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
{{% /warning %}}
### Destination Directories for Dev vs Deploy
### Dev vs Deploy Destinations
Hugo does not remove generated files before building. An easy workaround is to use different directories for development and production.
@@ -223,7 +210,7 @@ When the content is ready for publishing, use the default `public/` dir:
hugo -s ~/Code/hugo/docs
```
This prevents content you're not yet ready to share from accidentally becoming available.
This prevents draft content from accidentally becoming available.
### Using Hugo's Server in Production
@@ -233,14 +220,12 @@ No other web server software (e.g., Apache, nginx, IIS) is necessary.
Here is the command:
{{% code file="hugo-production-server.sh" %}}
```bash
hugo server --baseURL=http://yoursite.org/ \
--port=80 \
--appendPort=false \
--bind=87.245.198.50
```
{{% /code %}}
Note the `bind` option, which is the interface to which the server will bind (defaults to `127.0.0.1`: fine for most development use cases). Some hosts, such as Amazon Web Services, run NAT (network address translation); sometimes it can be hard to figure out the actual IP address. Using `--bind=0.0.0.0` will bind to all interfaces.
@@ -250,17 +235,9 @@ Interested? Here are some great tutorials contributed by Hugo users:
* [hugo, syncthing](http://fredix.xyz/2014/10/hugo-syncthing/) (French) by Frédéric Logier (@fredix)
[Amazon S3]: http://aws.amazon.com/s3/
[Apache]: http://httpd.apache.org/ "Apache HTTP Server"
[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
[commands]: /commands/
[config]: /getting-started/configuration/
[dirs]: /getting-started/directory-structure/
[DreamHost]: http://www.dreamhost.com/
[Firebase Hosting]: https://firebase.google.com/docs/hosting/
[GitHub Pages]: https://pages.github.com/
[GitLab]: https://about.gitlab.com
[GoDaddy]: https://www.godaddy.com/
[Heroku]: https://www.heroku.com/
[IIS]: http://www.iis.net/
[install]: /getting-started/installing/
[nginx]: http://nginx.org/
[front matter]: /content-management/front-matter/
[hosting]: /hosting-and-deployments/
[install]: /getting-started/installing/
content/templates/content-view-templates.md → content/templates/views.md
+16 -32
View File
@@ -9,27 +9,20 @@ categories: [templates]
tags: [views]
weight: 70
draft: false
aliases: [/templates/views/]
aliases: []
toc: true
wip: true
---
In addition to the [single page content template][singletemplates], Hugo can render alternative views of your content. These are especially useful in [list templates][listtemplates].
Hugo's flexibility allows you to render alternative views for specific content. These alternative **content views** are especially useful in [list templates][lists].
Content views are appropriate for cases like the following:
The following are common use cases for content views:
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
## Creating a Content View
To create a new view, simply create a template in each of your different
content type directories with the view name. In the following example, we
have created a "li" view and a "summary" view for our two content types
of post and project. As you can see, these sit next to the [single
content view](/templates/content/) template "single.html". You can even
provide a specific view for a given type and continue to use the
\_default/single.html for the primary view.
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```bash
▾ layouts/
@@ -43,7 +36,7 @@ provide a specific view for a given type and continue to use the
summary.html
```
Hugo also has support for a default content template to be used in the event that a specific template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as layouts for other types who eventually fall trickle down to this directory.
Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
```bash
@@ -58,40 +51,35 @@ Hugo also has support for a default content template to be used in the event tha
The following is the [lookup order][lookup] for content views:
* `/layouts/<TYPE>/<VIEW>.html`
* `/layouts/\_default/<VIEW>.html`
* `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
* `/themes/<THEME>/layouts/\_default/<VIEW>.html`
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
## Example: Content View Inside a List
The following example demonstrates how to use content views inside of your [list page templates][listtemplates].
The following example demonstrates how to use content views inside of your [list templates][lists].
### `list.html`
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument.
This `list.html` content view template is part of a larger `section.html` default template used for [spf13.com][spf]. ([See source on GitHub][spfsourcesection].)
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
{{% code file="layouts/_default/list.html" download="list.html" %}}
```
<section id="main">
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
</main>
```
{{% /code %}}
### `summary.html`
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables/) for a complete list.
This `summary.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourcesummary].)
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
{{% code file="layouts/_default/summary.html" download="summary.html" %}}
```html
@@ -110,12 +98,8 @@ This `summary.html` content view template is used for [spf13.com][spf]. ([See so
### `li.html`
Hugo will pass the entire page object to the view template. See [Page Variables][pagevars] for a complete list of variables Hugo makes available to you.
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
This `li.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourceli].)
{{% code file="layouts/_default/li.html" download="li.html" %}}
```html
<li>
@@ -125,11 +109,11 @@ This `li.html` content view template is used for [spf13.com][spf]. ([See source
```
{{% /code %}}
[listtemplates]: /templates/lists/
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[pagevars]: /variables/page-variables/
[render]: /functions/render/
[singletemplates]: /templates/single-page-templates/
[single]: /templates/single-page-templates/
[spf]: http://spf13.com
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
layouts/partials/style-embed.html
+1 -1
View File
File diff suppressed because one or more lines are too long
pipeline/scss/components/_site-search.scss
+8 -9
View File
@@ -7,9 +7,9 @@
margin-right: 20px;
font-size: 1.2em;
z-index: 60;
color:$hugo-pink;
@include MQ(L){
top:.3em;
color: $hugo-pink;
@include MQ(L) {
top: .3em;
}
}
@@ -25,7 +25,6 @@ form#site-search-form {
transform:translateY(-#{$site-header-height});
background-color: $body-bg-color;
z-index: 19;
box-shadow: 0 3px 6px rgba($hugo-pink, 0.15), 0 3px 6px rgba($hugo-pink, 0.3);
&.search-open {
transition: transform .3s ease-in-out;
transform: translateY(0);
@@ -57,12 +56,12 @@ form#site-search-form {
#search-input {
transition: opacity .3 ease-in-out;
opacity: 1;
border-bottom:3px solid $hugo-pink;
border-bottom: 3px solid $hugo-pink;
&::after {
display:inline-block;
content:'';
width:1em;
border-bottom:3px solid $hugo-pink;
display: inline-block;
content: '';
width: 1em;
border-bottom: 3px solid $hugo-pink;
}
}
}
pipeline/scss/components/_table-of-contents.scss
+1
View File
@@ -81,6 +81,7 @@ nav#TableOfContents {
li code {
font-family: $base-font-family;
}
li.active > a > code {
color: inherit;
font-weight: inherit;
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long