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

Merge commit 'dd78d5b23fe597f4461aa4199401b4e07c0612e2' as 'docs'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2017-06-26 20:46:06 +02:00
parent 31393f6024 5d9a670359
commit ab4e5da810
840 changed files with 26093 additions and 61186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2 -18
View File
@@ -1,18 +1,2 @@
hugo
docs/public*
/.idea
hugo.exe
*.test
*.prof
nohup.out
cover.out
*.swp
*.swo
.DS_Store
*~
vendor/*/
*.bench
coverage*.out
GoBuilds
dist
/.idea
/public
.gitmodules
View File
.goxc.json
-6
View File
@@ -1,6 +0,0 @@
{
"ArtifactsDest": "GoBuilds/",
"OutPath": "{{.Dest}}{{.PS}}{{.AppName}}{{.PS}}{{.Version}}{{.PS}}{{.AppName}}_{{.Version}}_{{.Os}}_{{.Arch}}{{.Ext}}",
"BuildConstraints": "linux windows darwin freebsd netbsd openbsd dragonfly",
"ConfigVersion": "0.9"
}
.mailmap
-3
View File
@@ -1,3 +0,0 @@
spf13 <steve.francia@gmail.com> Steve Francia <steve.francia@gmail.com>
bep <bjorn.erik.pedersen@gmail.com> Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
.travis.yml
-21
View File
@@ -1,21 +0,0 @@
language: go
sudo: required
go:
- 1.7.6
- 1.8.3
- tip
os:
- linux
- osx
matrix:
allow_failures:
- go: tip
fast_finish: true
install:
- make vendor
script:
- make hugo-race check
before_install:
# gem install must be run with sudo on OSX
- sudo gem install asciidoctor | gem install asciidoctor
- sudo pip install docutils
CONTRIBUTING.md
-161
View File
@@ -1,161 +0,0 @@
# Contributing to Hugo
We welcome contributions to Hugo of any kind including documentation, themes,
organization, tutorials, blog posts, bug reports, issues, feature requests,
feature implementations, pull requests, answering questions on the forum,
helping to manage issues, etc.
The Hugo community and maintainers are [very active](https://github.com/gohugoio/hugo/pulse/monthly) and helpful, and the project benefits greatly from this activity. We created a [step by step guide](https://gohugo.io/tutorials/how-to-contribute-to-hugo/) if you're unfamiliar with GitHub or contributing to open source projects in general.
## Table of Contents
* [Asking Support Questions](#asking-support-questions)
* [Reporting Issues](#reporting-issues)
* [Submitting Patches](#submitting-patches)
* [Code Contribution Guidelines](#code-contribution-guidelines)
* [Git Commit Message Guidelines](#git-commit-message-guidelines)
* [Vendored Dependencies](#vendored-dependencies)
* [Fetching the Sources From GitHub](#fetching-the-sources-from-github)
* [Using Git Remotes](#using-git-remotes)
* [Build Hugo with Your Changes](#build-hugo-with-your-changes)
* [Updating the Hugo Sources](#updating-the-hugo-sources)
## Asking Support Questions
We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions.
Please don't use the GitHub issue tracker to ask questions.
## Reporting Issues
If you believe you have found a defect in Hugo or its documentation, use
the GitHub [issue tracker](https://github.com/gohugoio/hugo/issues) to report the problem to the Hugo maintainers.
If you're not sure if it's a bug or not, start by asking in the [discussion forum](https://discourse.gohugo.io).
When reporting the issue, please provide the version of Hugo in use (`hugo version`) and your operating system.
## Submitting Patches
The Hugo project welcomes all contributors and contributions regardless of skill or experience level.
If you are interested in helping with the project, we will help you with your contribution.
Hugo is a very active project with many contributions happening daily.
Because we want to create the best possible product for our users and the best contribution experience for our developers,
we have a set of guidelines which ensure that all contributions are acceptable.
The guidelines are not intended as a filter or barrier to participation.
If you are unfamiliar with the contribution process, the Hugo team will help you and teach you how to bring your contribution in accordance with the guidelines.
### Code Contribution Guidelines
To make the contribution process as seamless as possible, we ask for the following:
* Go ahead and fork the project and make your changes. We encourage pull requests to allow for review and discussion of code changes.
* When you’re ready to create a pull request, be sure to:
* Sign the [CLA](https://cla-assistant.io/gohugoio/hugo).
* Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
* Run `go fmt`.
* Add documentation if you are adding new features or changing functionality. The docs site lives in `/docs`.
* Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.
* Ensure that `make check` succeeds. [Travis CI](https://travis-ci.org/gohugoio/hugo) (Linux and macOS) and [AppVeyor](https://ci.appveyor.com/project/gohugoio/hugo/branch/master) (Windows) will fail the build if `make check` fails.
* Follow the **Git Commit Message Guidelines** below.
### Git Commit Message Guidelines
This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource for learning how to write good commit messages,
the most important part being that each commit message should have a title/subject in imperative mood starting with a capital letter and no trailing period:
*"Return error on wrong use of the Paginator"*, **NOT** *"returning some error."*
Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*.
Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*.
Sometimes it makes sense to prefix the commit message with the packagename (or docs folder) all lowercased ending with a colon.
That is fine, but the rest of the rules above apply.
So it is "tpl: Add emojify template func", not "tpl: add emojify template func.", and "docs: Document emoji", not "doc: document emoji."
Please consider to use a short and descriptive branch name, e.g. **NOT** "patch-1". It's very common but creates a naming conflict each time when a submission is pulled for a review.
An example:
```text
tpl: Add custom index function
Add a custom index template function that deviates from the stdlib simply by not
returning an "index out of range" error if an array, slice or string index is
out of range. Instead, we just return nil values. This should help make the
new default function more useful for Hugo users.
Fixes #1949
```
### Vendored Dependencies
Hugo uses [govendor](https://github.com/kardianos/govendor) to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.
Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.
You **must use govendor** to fetch and manage Hugo's dependencies.
### Fetch the Sources From GitHub
```
go get github.com/kardianos/govendor
govendor get github.com/gohugoio/hugo
```
### Using Git Remotes
Due to the way Go handles package imports, the best approach for working on a
Hugo fork is to use Git Remotes. Here's a simple walk-through for getting
started:
1. Fetch the Hugo sources as described above.
1. Change to the Hugo source directory:
```
cd $HOME/go/src/github.com/gohugoio/hugo
```
1. Create a new branch for your changes (the branch name is arbitrary):
```
git checkout -b iss1234
```
1. After making your changes, commit them to your new branch:
```
git commit -a -v
```
1. Fork Hugo in GitHub.
1. Add your fork as a new remote (the remote name, "fork" in this example, is arbitrary):
```
git remote add fork git://github.com/USERNAME/hugo.git
```
1. Push the changes to your new remote:
```
git push --set-upstream fork iss1234
```
1. You're now ready to submit a PR based upon the new branch in your forked repository.
### Build Hugo with Your Changes
```bash
cd $HOME/go/src/github.com/gohugoio/hugo
make hugo
# or to install in $HOME/go/bin:
make install
```
### Updating the Hugo Sources
If you want to stay in sync with the Hugo repository, you can easily pull down
the source changes, but you'll need to keep the vendored packages up-to-date as
well.
```
git pull
make vendor
```
Dockerfile
-15
View File
@@ -1,15 +0,0 @@
FROM golang:1.8-alpine
ENV GOPATH /go
ENV USER root
RUN apk update && apk add git make
# pre-install known dependencies before the source, so we don't redownload them whenever the source changes
RUN go get github.com/kardianos/govendor \
&& govendor get github.com/gohugoio/hugo
COPY . $GOPATH/src/github.com/gohugoio/hugo
RUN cd $GOPATH/src/github.com/gohugoio/hugo \
&& make install test
Makefile
-83
View File
@@ -1,83 +0,0 @@
# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
PACKAGE = github.com/gohugoio/hugo
COMMIT_HASH = `git rev-parse --short HEAD 2>/dev/null`
BUILD_DATE = `date +%FT%T%z`
LDFLAGS = -ldflags "-X ${PACKAGE}/hugolib.CommitHash=${COMMIT_HASH} -X ${PACKAGE}/hugolib.BuildDate=${BUILD_DATE}"
NOGI_LDFLAGS = -ldflags "-X ${PACKAGE}/hugolib.BuildDate=${BUILD_DATE}"
.PHONY: vendor docker check fmt lint test test-race vet test-cover-html help
.DEFAULT_GOAL := help
vendor: ## Install govendor and sync Hugo's vendored dependencies
go get github.com/kardianos/govendor
govendor sync ${PACKAGE}
hugo: vendor ## Build hugo binary
go build ${LDFLAGS} ${PACKAGE}
hugo-race: vendor ## Build hugo binary with race detector enabled
go build -race ${LDFLAGS} ${PACKAGE}
install: vendor ## Install hugo binary
go install ${LDFLAGS} ${PACKAGE}
hugo-no-gitinfo: LDFLAGS = ${NOGI_LDFLAGS}
hugo-no-gitinfo: vendor hugo ## Build hugo without git info
docker: ## Build hugo Docker container
docker build -t hugo .
docker rm -f hugo-build || true
docker run --name hugo-build hugo ls /go/bin
docker cp hugo-build:/go/bin/hugo .
docker rm hugo-build
govendor: vendor # Deprecated: use "vendor" target
get: vendor # Deprecated: use "vendor"
gitinfo: hugo # Deprecated: use "hugo" target
install-gitinfo: install # Deprecated: use "install" target
no-git-info: hugo-no-gitinfo # Deprecated: use "hugo-no-gitinfo" target
check: test-race test386 fmt vet ## Run tests and linters
test386: ## Run tests in 32-bit mode
GOARCH=386 govendor test +local
test: ## Run tests
govendor test +local
test-race: ## Run tests with race detector
govendor test -race +local
fmt: ## Run gofmt linter
@for d in `govendor list -no-status +local | sed 's/github.com.gohugoio.hugo/./'` ; do \
if [ "`gofmt -l $$d/*.go | tee /dev/stderr`" ]; then \
echo "^ improperly formatted go files" && echo && exit 1; \
fi \
done
lint: ## Run golint linter
@for d in `govendor list -no-status +local | sed 's/github.com.gohugoio.hugo/./'` ; do \
if [ "`golint $$d | tee /dev/stderr`" ]; then \
echo "^ golint errors!" && echo && exit 1; \
fi \
done
vet: ## Run go vet linter
@if [ "`govendor vet +local | tee /dev/stderr`" ]; then \
echo "^ go vet errors!" && echo && exit 1; \
fi
test-cover-html: PACKAGES = $(shell govendor list -no-status +local | sed 's/github.com.gohugoio.hugo/./')
test-cover-html: ## Generate test coverage report
echo "mode: count" > coverage-all.out
$(foreach pkg,$(PACKAGES),\
govendor test -coverprofile=coverage.out -covermode=count $(pkg);\
tail -n +2 coverage.out >> coverage-all.out;)
go tool cover -html=coverage-all.out
check-vendor: ## Verify that vendored packages match git HEAD
@git diff-index --quiet HEAD vendor/ || (echo "check-vendor target failed: vendored packages out of sync" && echo && git diff vendor/ && exit 1)
help:
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
README.md
+2 -105
View File
@@ -1,106 +1,3 @@
![Hugo](https://raw.githubusercontent.com/gohugoio/hugoDocs/master/static/img/hugo-logo.png)
# Hugo Docs
A Fast and Flexible Static Site Generator built with love by [spf13](http://spf13.com/) and [friends](https://github.com/gohugoio/hugo/graphs/contributors) in [Go][].
[Website](https://gohugo.io) |
[Forum](https://discourse.gohugo.io) |
[Developer Chat (no support)](https://gitter.im/gohugoio/hugo) |
[Documentation](https://gohugo.io/overview/introduction/) |
[Installation Guide](https://gohugo.io/overview/installing/) |
[Contribution Guide](CONTRIBUTING.md) |
[Twitter](http://twitter.com/gohugoio)
[![GoDoc](https://godoc.org/github.com/gohugoio/hugo?status.svg)](https://godoc.org/github.com/gohugoio/hugo)
[![Linux and macOS Build Status](https://api.travis-ci.org/gohugoio/hugo.svg?branch=master&label=Linux+and+macOS+build "Linux and macOS Build Status")](https://travis-ci.org/gohugoio/hugo)
[![Windows Build Status](https://ci.appveyor.com/api/projects/status/a5mr220vsd091kua?svg=true&label=Windows+build "Windows Build Status")](https://ci.appveyor.com/project/bep/hugo/branch/master)
[![Dev chat at https://gitter.im/gohugoio/hugo](https://img.shields.io/badge/gitter-developer_chat-46bc99.svg)](https://gitter.im/spf13/hugo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Go Report Card](https://goreportcard.com/badge/github.com/gohugoio/hugo)](https://goreportcard.com/report/github.com/gohugoio/hugo)
## Overview
Hugo is a static HTML and CSS website generator written in [Go][].
It is optimized for speed, easy use and configurability.
Hugo takes a directory with content and templates and renders them into a full HTML website.
Hugo relies on Markdown files with front matter for meta data.
And you can run Hugo from any directory.
This works well for shared hosts and other systems where you don’t have a privileged account.
Hugo renders a typical website of moderate size in a fraction of a second.
A good rule of thumb is that each piece of content renders in around 1 millisecond.
Hugo is designed to work well for any kind of website including blogs, tumbles and docs.
#### Supported Architectures
Currently, we provide pre-built Hugo binaries for Windows, Linux, FreeBSD, NetBSD and macOS (Darwin) and [Android](https://gist.github.com/bep/a0d8a26cf6b4f8bc992729b8e50b480b) for x64, i386 and ARM architectures.
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.
**Complete documentation is available at [Hugo Documentation][].**
## Choose How to Install
If you want to use Hugo as your site generator, simply install the Hugo binaries.
The Hugo binaries have no external dependencies.
To contribute to the Hugo source code or documentation, you should [fork the Hugo GitHub project](https://github.com/gohugoio/hugo#fork-destination-box) and clone it to your local machine.
Finally, you can install the Hugo source code with `go`, build the binaries yourself, and run Hugo that way.
Building the binaries is an easy task for an experienced `go` getter.
### Install Hugo as Your Site Generator (Binary Install)
Use the [installation instructions in the Hugo documentation](https://gohugo.io/overview/installing/).
### Build and Install the Binaries from Source (Advanced Install)
Add Hugo and its package dependencies to your go `src` directory.
go get -v github.com/gohugoio/hugo
Once the `get` completes, you should find your new `hugo` (or `hugo.exe`) executable sitting inside `$GOPATH/bin/`.
To update Hugo’s dependencies, use `go get` with the `-u` option.
go get -u -v github.com/gohugoio/hugo
## Contributing to Hugo
For a complete guide to contributing to Hugo, see the [Contribution Guide](CONTRIBUTING.md).
We welcome contributions to Hugo of any kind including documentation, themes,
organization, tutorials, blog posts, bug reports, issues, feature requests,
feature implementations, pull requests, answering questions on the forum,
helping to manage issues, etc.
The Hugo community and maintainers are [very active](https://github.com/gohugoio/hugo/pulse/monthly) and helpful, and the project benefits greatly from this activity.
### Asking Support Questions
We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions.
Please don't use the GitHub issue tracker to ask questions.
### Reporting Issues
If you believe you have found a defect in Hugo or its documentation, use
the GitHub issue tracker to report the problem to the Hugo maintainers.
If you're not sure if it's a bug or not, start by asking in the [discussion forum](https://discourse.gohugo.io).
When reporting the issue, please provide the version of Hugo in use (`hugo version`).
### Submitting Patches
The Hugo project welcomes all contributors and contributions regardless of skill or experience level.
If you are interested in helping with the project, we will help you with your contribution.
Hugo is a very active project with many contributions happening daily.
Because we want to create the best possible product for our users and the best contribution experience for our developers,
we have a set of guidelines which ensure that all contributions are acceptable.
The guidelines are not intended as a filter or barrier to participation.
If you are unfamiliar with the contribution process, the Hugo team will help you and teach you how to bring your contribution in accordance with the guidelines.
For a complete guide to contributing code to Hugo, see the [Contribution Guide](CONTRIBUTING.md).
[![Analytics](https://ga-beacon.appspot.com/UA-7131036-6/hugo/readme)](https://github.com/igrigorik/ga-beacon)
[Go]: https://golang.org/
[Hugo Documentation]: https://gohugo.io/overview/introduction/
Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang.
appveyor.yml
-15
View File
@@ -1,15 +0,0 @@
init:
- copy c:\MinGW\bin\mingw32-make.exe c:\MinGW\bin\make.exe
- set PATH=%PATH%;C:\MinGW\bin;%GOPATH%\bin
- go version
- go env
# clones and cd's to path
clone_folder: C:\GOPATH\src\github.com\gohugoio\hugo
install:
- gem install asciidoctor
- pip install docutils
build_script:
- make hugo-race check
archetypes/default.md
+6
View File
@@ -0,0 +1,6 @@
+++
weight = 5
[menu]
[menu.main]
parent = "x"
+++
archetypes/showcase.md
+14
View File
@@ -0,0 +1,14 @@
---
date: 2013-07-01T07:32:00Z
description: ""
license: ""
licenseLink: ""
sitelink: http://spf13.com/
sourceLink: https://github.com/spf13/spf13.com
tags:
- personal
- blog
thumbnail: /img/spf13-tn.jpg
title: spf13.com
---
bench.sh
-35
View File
@@ -1,35 +0,0 @@
#!/usr/bin/env bash
# Convenience script to
# - For a given branch
# - Run benchmark tests for a given package
# - Do the same for master
# - then compare the two runs with benchcmp
benchFilter=".*"
if (( $# < 2 ));
then
echo "USAGE: ./bench.sh <git-branch> <package-to-bench> (and <benchmark filter> (regexp, optional))"
exit 1
fi
if [ $# -eq 3 ]; then
benchFilter=$3
fi
BRANCH=$1
PACKAGE=$2
git checkout $BRANCH
go test -test.run=NONE -bench="$benchFilter" -test.benchmem=true ./$PACKAGE > /tmp/bench-$PACKAGE-$BRANCH.txt
git checkout master
go test -test.run=NONE -bench="$benchFilter" -test.benchmem=true ./$PACKAGE > /tmp/bench-$PACKAGE-master.txt
benchcmp /tmp/bench-$PACKAGE-master.txt /tmp/bench-$PACKAGE-$BRANCH.txt
benchSite.sh
-9
View File
@@ -1,9 +0,0 @@
#!/bin/bash
# Send in a regexp mathing the benchmarks you want to run, i.e. './benchSite.sh "YAML"'.
# Note the quotes, which will be needed for more complex expressions.
# The above will run all variations, but only for front matter YAML.
echo "Running with BenchmarkSiteBuilding/${1}"
go test -run="NONE" -bench="BenchmarkSiteBuilding/${1}$" -test.benchmem=true ./hugolib -memprofile mem.prof -cpuprofile cpu.prof
bufferpool/bufpool.go
-38
View File
@@ -1,38 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Package bufferpool provides a pool of bytes buffers.
package bufferpool
import (
"bytes"
"sync"
)
var bufferPool = &sync.Pool{
New: func() interface{} {
return &bytes.Buffer{}
},
}
// GetBuffer returns a buffer from the pool.
func GetBuffer() (buf *bytes.Buffer) {
return bufferPool.Get().(*bytes.Buffer)
}
// PutBuffer returns a buffer to the pool.
// The buffer is reset before it is put back into circulation.
func PutBuffer(buf *bytes.Buffer) {
buf.Reset()
bufferPool.Put(buf)
}
bufferpool/bufpool_test.go
-27
View File
@@ -1,27 +0,0 @@
// Copyright 2016-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package bufferpool
import (
"github.com/stretchr/testify/assert"
"testing"
)
func TestBufferPool(t *testing.T) {
buff := GetBuffer()
buff.WriteString("do be do be do")
assert.Equal(t, "do be do be do", buff.String())
PutBuffer(buff)
assert.Equal(t, 0, buff.Len())
}
cache/partitioned_lazy_cache.go
Vendored
-80
View File
@@ -1,80 +0,0 @@
// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package cache
import (
"sync"
)
// Partition represents a cache partition where Load is the callback
// for when the partition is needed.
type Partition struct {
Key string
Load func() (map[string]interface{}, error)
}
type lazyPartition struct {
initSync sync.Once
cache map[string]interface{}
load func() (map[string]interface{}, error)
}
func (l *lazyPartition) init() error {
var err error
l.initSync.Do(func() {
var c map[string]interface{}
c, err = l.load()
l.cache = c
})
return err
}
// PartitionedLazyCache is a lazily loaded cache paritioned by a supplied string key.
type PartitionedLazyCache struct {
partitions map[string]*lazyPartition
}
// NewPartitionedLazyCache creates a new NewPartitionedLazyCache with the supplied
// partitions.
func NewPartitionedLazyCache(partitions ...Partition) *PartitionedLazyCache {
lazyPartitions := make(map[string]*lazyPartition, len(partitions))
for _, partition := range partitions {
lazyPartitions[partition.Key] = &lazyPartition{load: partition.Load}
}
cache := &PartitionedLazyCache{partitions: lazyPartitions}
return cache
}
// Get initializes the partition if not already done so, then looks up the given
// key in the given partition, returns nil if no value found.
func (c *PartitionedLazyCache) Get(partition, key string) (interface{}, error) {
p, found := c.partitions[partition]
if !found {
return nil, nil
}
if err := p.init(); err != nil {
return nil, err
}
if v, found := p.cache[key]; found {
return v, nil
}
return nil, nil
}
cache/partitioned_lazy_cache_test.go
Vendored
-92
View File
@@ -1,92 +0,0 @@
// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package cache
import (
"errors"
"testing"
"github.com/stretchr/testify/require"
)
func TestNewPartitionedLazyCache(t *testing.T) {
t.Parallel()
assert := require.New(t)
p1 := Partition{
Key: "p1",
Load: func() (map[string]interface{}, error) {
return map[string]interface{}{
"p1_1": "p1v1",
"p1_2": "p1v2",
"p1_nil": nil,
}, nil
},
}
p2 := Partition{
Key: "p2",
Load: func() (map[string]interface{}, error) {
return map[string]interface{}{
"p2_1": "p2v1",
"p2_2": "p2v2",
"p2_3": "p2v3",
}, nil
},
}
cache := NewPartitionedLazyCache(p1, p2)
v, err := cache.Get("p1", "p1_1")
assert.NoError(err)
assert.Equal("p1v1", v)
v, err = cache.Get("p1", "p2_1")
assert.NoError(err)
assert.Nil(v)
v, err = cache.Get("p1", "p1_nil")
assert.NoError(err)
assert.Nil(v)
v, err = cache.Get("p2", "p2_3")
assert.NoError(err)
assert.Equal("p2v3", v)
v, err = cache.Get("doesnotexist", "p1_1")
assert.NoError(err)
assert.Nil(v)
v, err = cache.Get("p1", "doesnotexist")
assert.NoError(err)
assert.Nil(v)
errorP := Partition{
Key: "p3",
Load: func() (map[string]interface{}, error) {
return nil, errors.New("Failed")
},
}
cache = NewPartitionedLazyCache(errorP)
v, err = cache.Get("p1", "doesnotexist")
assert.NoError(err)
assert.Nil(v)
_, err = cache.Get("p3", "doesnotexist")
assert.Error(err)
}
commands/benchmark.go
-112
View File
@@ -1,112 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"os"
"runtime"
"runtime/pprof"
"time"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
var (
benchmarkTimes int
cpuProfileFile string
memProfileFile string
)
var benchmarkCmd = &cobra.Command{
Use: "benchmark",
Short: "Benchmark Hugo by building a site a number of times.",
Long: `Hugo can build a site many times over and analyze the running process
creating a benchmark.`,
}
func init() {
initHugoBuilderFlags(benchmarkCmd)
initBenchmarkBuildingFlags(benchmarkCmd)
benchmarkCmd.Flags().StringVar(&cpuProfileFile, "cpuprofile", "", "path/filename for the CPU profile file")
benchmarkCmd.Flags().StringVar(&memProfileFile, "memprofile", "", "path/filename for the memory profile file")
benchmarkCmd.Flags().IntVarP(&benchmarkTimes, "count", "n", 13, "number of times to build the site")
benchmarkCmd.RunE = benchmark
}
func benchmark(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig(benchmarkCmd)
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
var memProf *os.File
if memProfileFile != "" {
memProf, err = os.Create(memProfileFile)
if err != nil {
return err
}
}
var cpuProf *os.File
if cpuProfileFile != "" {
cpuProf, err = os.Create(cpuProfileFile)
if err != nil {
return err
}
}
var memStats runtime.MemStats
runtime.ReadMemStats(&memStats)
memAllocated := memStats.TotalAlloc
mallocs := memStats.Mallocs
if cpuProf != nil {
pprof.StartCPUProfile(cpuProf)
}
t := time.Now()
for i := 0; i < benchmarkTimes; i++ {
if err = c.resetAndBuildSites(false); err != nil {
return err
}
}
totalTime := time.Since(t)
if memProf != nil {
pprof.WriteHeapProfile(memProf)
memProf.Close()
}
if cpuProf != nil {
pprof.StopCPUProfile()
cpuProf.Close()
}
runtime.ReadMemStats(&memStats)
totalMemAllocated := memStats.TotalAlloc - memAllocated
totalMallocs := memStats.Mallocs - mallocs
jww.FEEDBACK.Println()
jww.FEEDBACK.Printf("Average time per operation: %vms\n", int(1000*totalTime.Seconds()/float64(benchmarkTimes)))
jww.FEEDBACK.Printf("Average memory allocated per operation: %vkB\n", totalMemAllocated/uint64(benchmarkTimes)/1024)
jww.FEEDBACK.Printf("Average allocations per operation: %v\n", totalMallocs/uint64(benchmarkTimes))
return nil
}
commands/check.go
-23
View File
@@ -1,23 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"github.com/spf13/cobra"
)
var checkCmd = &cobra.Command{
Use: "check",
Short: "Contains some verification checks",
}
commands/commandeer.go
-62
View File
@@ -1,62 +0,0 @@
// Copyright 2017 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"github.com/gohugoio/hugo/deps"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugofs"
)
type commandeer struct {
*deps.DepsCfg
pathSpec *helpers.PathSpec
configured bool
}
func (c *commandeer) Set(key string, value interface{}) {
if c.configured {
panic("commandeer cannot be changed")
}
c.Cfg.Set(key, value)
}
// PathSpec lazily creates a new PathSpec, as all the paths must
// be configured before it is created.
func (c *commandeer) PathSpec() *helpers.PathSpec {
c.configured = true
return c.pathSpec
}
func (c *commandeer) initFs(fs *hugofs.Fs) error {
c.DepsCfg.Fs = fs
ps, err := helpers.NewPathSpec(fs, c.Cfg)
if err != nil {
return err
}
c.pathSpec = ps
return nil
}
func newCommandeer(cfg *deps.DepsCfg) (*commandeer, error) {
l := cfg.Language
if l == nil {
l = helpers.NewDefaultLanguage(cfg.Cfg)
}
ps, err := helpers.NewPathSpec(cfg.Fs, l)
if err != nil {
return nil, err
}
return &commandeer{DepsCfg: cfg, pathSpec: ps}, nil
}
commands/convert.go
-158
View File
@@ -1,158 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"errors"
"fmt"
"path/filepath"
"time"
"github.com/gohugoio/hugo/hugolib"
"github.com/gohugoio/hugo/parser"
"github.com/spf13/cast"
"github.com/spf13/cobra"
)
var outputDir string
var unsafe bool
var convertCmd = &cobra.Command{
Use: "convert",
Short: "Convert your content to different formats",
Long: `Convert your content (e.g. front matter) to different formats.
See convert's subcommands toJSON, toTOML and toYAML for more information.`,
RunE: nil,
}
var toJSONCmd = &cobra.Command{
Use: "toJSON",
Short: "Convert front matter to JSON",
Long: `toJSON converts all front matter in the content directory
to use JSON for the front matter.`,
RunE: func(cmd *cobra.Command, args []string) error {
return convertContents(rune([]byte(parser.JSONLead)[0]))
},
}
var toTOMLCmd = &cobra.Command{
Use: "toTOML",
Short: "Convert front matter to TOML",
Long: `toTOML converts all front matter in the content directory
to use TOML for the front matter.`,
RunE: func(cmd *cobra.Command, args []string) error {
return convertContents(rune([]byte(parser.TOMLLead)[0]))
},
}
var toYAMLCmd = &cobra.Command{
Use: "toYAML",
Short: "Convert front matter to YAML",
Long: `toYAML converts all front matter in the content directory
to use YAML for the front matter.`,
RunE: func(cmd *cobra.Command, args []string) error {
return convertContents(rune([]byte(parser.YAMLLead)[0]))
},
}
func init() {
convertCmd.AddCommand(toJSONCmd)
convertCmd.AddCommand(toTOMLCmd)
convertCmd.AddCommand(toYAMLCmd)
convertCmd.PersistentFlags().StringVarP(&outputDir, "output", "o", "", "filesystem path to write files to")
convertCmd.PersistentFlags().StringVarP(&source, "source", "s", "", "filesystem path to read files relative from")
convertCmd.PersistentFlags().BoolVar(&unsafe, "unsafe", false, "enable less safe operations, please backup first")
convertCmd.PersistentFlags().SetAnnotation("source", cobra.BashCompSubdirsInDir, []string{})
}
func convertContents(mark rune) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
h, err := hugolib.NewHugoSites(*cfg)
if err != nil {
return err
}
site := h.Sites[0]
if err = site.Initialise(); err != nil {
return err
}
if site.Source == nil {
panic("site.Source not set")
}
if len(site.Source.Files()) < 1 {
return errors.New("No source files found")
}
contentDir := site.PathSpec.AbsPathify(site.Cfg.GetString("contentDir"))
site.Log.FEEDBACK.Println("processing", len(site.Source.Files()), "content files")
for _, file := range site.Source.Files() {
site.Log.INFO.Println("Attempting to convert", file.LogicalName())
page, err := site.NewPage(file.LogicalName())
if err != nil {
return err
}
psr, err := parser.ReadFrom(file.Contents)
if err != nil {
site.Log.ERROR.Println("Error processing file:", file.Path())
return err
}
metadata, err := psr.Metadata()
if err != nil {
site.Log.ERROR.Println("Error processing file:", file.Path())
return err
}
// better handling of dates in formats that don't have support for them
if mark == parser.FormatToLeadRune("json") || mark == parser.FormatToLeadRune("yaml") || mark == parser.FormatToLeadRune("toml") {
newMetadata := cast.ToStringMap(metadata)
for k, v := range newMetadata {
switch vv := v.(type) {
case time.Time:
newMetadata[k] = vv.Format(time.RFC3339)
}
}
metadata = newMetadata
}
page.SetDir(filepath.Join(contentDir, file.Dir()))
page.SetSourceContent(psr.Content())
if err = page.SetSourceMetaData(metadata, mark); err != nil {
site.Log.ERROR.Printf("Failed to set source metadata for file %q: %s. For more info see For more info see https://github.com/gohugoio/hugo/issues/2458", page.FullFilePath(), err)
continue
}
if outputDir != "" {
if err = page.SaveSourceAs(filepath.Join(outputDir, page.FullFilePath())); err != nil {
return fmt.Errorf("Failed to save file %q: %s", page.FullFilePath(), err)
}
} else {
if unsafe {
if err = page.SaveSource(); err != nil {
return fmt.Errorf("Failed to save file %q: %s", page.FullFilePath(), err)
}
} else {
site.Log.FEEDBACK.Println("Unsafe operation not allowed, use --unsafe or set a different output path")
}
}
}
return nil
}
commands/env.go
-35
View File
@@ -1,35 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"runtime"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
var envCmd = &cobra.Command{
Use: "env",
Short: "Print Hugo version and environment info",
Long: `Print Hugo version and environment info. This is useful in Hugo bug reports.`,
RunE: func(cmd *cobra.Command, args []string) error {
printHugoVersion()
jww.FEEDBACK.Printf("GOOS=%q\n", runtime.GOOS)
jww.FEEDBACK.Printf("GOARCH=%q\n", runtime.GOARCH)
jww.FEEDBACK.Printf("GOVERSION=%q\n", runtime.Version())
return nil
},
}
commands/gen.go
-23
View File
@@ -1,23 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"github.com/spf13/cobra"
)
var genCmd = &cobra.Command{
Use: "gen",
Short: "A collection of several useful generators.",
}
commands/genautocomplete.go
-70
View File
@@ -1,70 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
var autocompleteTarget string
// bash for now (zsh and others will come)
var autocompleteType string
var genautocompleteCmd = &cobra.Command{
Use: "autocomplete",
Short: "Generate shell autocompletion script for Hugo",
Long: `Generates a shell autocompletion script for Hugo.
NOTE: The current version supports Bash only.
This should work for *nix systems with Bash installed.
By default, the file is written directly to /etc/bash_completion.d
for convenience, and the command may need superuser rights, e.g.:
$ sudo hugo gen autocomplete
Add ` + "`--completionfile=/path/to/file`" + ` flag to set alternative
file-path and name.
Logout and in again to reload the completion scripts,
or just source them in directly:
$ . /etc/bash_completion`,
RunE: func(cmd *cobra.Command, args []string) error {
if autocompleteType != "bash" {
return newUserError("Only Bash is supported for now")
}
err := cmd.Root().GenBashCompletionFile(autocompleteTarget)
if err != nil {
return err
}
jww.FEEDBACK.Println("Bash completion file for Hugo saved to", autocompleteTarget)
return nil
},
}
func init() {
genautocompleteCmd.PersistentFlags().StringVarP(&autocompleteTarget, "completionfile", "", "/etc/bash_completion.d/hugo.sh", "autocompletion file")
genautocompleteCmd.PersistentFlags().StringVarP(&autocompleteType, "type", "", "bash", "autocompletion type (currently only bash supported)")
// For bash-completion
genautocompleteCmd.PersistentFlags().SetAnnotation("completionfile", cobra.BashCompFilenameExt, []string{})
}
commands/gendoc.go
-86
View File
@@ -1,86 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"fmt"
"path"
"path/filepath"
"strings"
"time"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugofs"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
jww "github.com/spf13/jwalterweatherman"
)
const gendocFrontmatterTemplate = `---
date: %s
title: "%s"
slug: %s
url: %s
---
`
var gendocdir string
var gendocCmd = &cobra.Command{
Use: "doc",
Short: "Generate Markdown documentation for the Hugo CLI.",
Long: `Generate Markdown documentation for the Hugo CLI.
This command is, mostly, used to create up-to-date documentation
of Hugo's command-line interface for http://gohugo.io/.
It creates one Markdown file per command with front matter suitable
for rendering in Hugo.`,
RunE: func(cmd *cobra.Command, args []string) error {
if !strings.HasSuffix(gendocdir, helpers.FilePathSeparator) {
gendocdir += helpers.FilePathSeparator
}
if found, _ := helpers.Exists(gendocdir, hugofs.Os); !found {
jww.FEEDBACK.Println("Directory", gendocdir, "does not exist, creating...")
if err := hugofs.Os.MkdirAll(gendocdir, 0777); err != nil {
return err
}
}
now := time.Now().Format(time.RFC3339)
prepender := func(filename string) string {
name := filepath.Base(filename)
base := strings.TrimSuffix(name, path.Ext(name))
url := "/commands/" + strings.ToLower(base) + "/"
return fmt.Sprintf(gendocFrontmatterTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
}
linkHandler := func(name string) string {
base := strings.TrimSuffix(name, path.Ext(name))
return "/commands/" + strings.ToLower(base) + "/"
}
jww.FEEDBACK.Println("Generating Hugo command-line documentation in", gendocdir, "...")
doc.GenMarkdownTreeCustom(cmd.Root(), gendocdir, prepender, linkHandler)
jww.FEEDBACK.Println("Done.")
return nil
},
}
func init() {
gendocCmd.PersistentFlags().StringVar(&gendocdir, "dir", "/tmp/hugodoc/", "the directory to write the doc.")
// For bash-completion
gendocCmd.PersistentFlags().SetAnnotation("dir", cobra.BashCompSubdirsInDir, []string{})
}
commands/gendocshelper.go
-72
View File
@@ -1,72 +0,0 @@
// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
"github.com/gohugoio/hugo/docshelper"
"github.com/spf13/cobra"
)
type genDocsHelper struct {
target string
cmd *cobra.Command
}
func createGenDocsHelper() *genDocsHelper {
g := &genDocsHelper{
cmd: &cobra.Command{
Use: "docshelper",
Short: "Generate some data files for the Hugo docs.",
Hidden: true,
},
}
g.cmd.RunE = func(cmd *cobra.Command, args []string) error {
return g.generate()
}
// Note that ./docs is a submodule, and writing to that would be suboptimal.
// Let us assume that the default is a sibling project.
g.cmd.PersistentFlags().StringVarP(&g.target, "dir", "", "../hugoDocs/data", "data dir")
return g
}
func (g *genDocsHelper) generate() error {
fmt.Println("Generate docs data to", g.target)
targetFile := filepath.Join(g.target, "docs.json")
f, err := os.Create(targetFile)
if err != nil {
return err
}
defer f.Close()
enc := json.NewEncoder(f)
enc.SetIndent("", " ")
if err := enc.Encode(docshelper.DocProviders); err != nil {
return err
}
fmt.Println("Done!")
return nil
}
commands/genman.go
-66
View File
@@ -1,66 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"fmt"
"strings"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugofs"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
jww "github.com/spf13/jwalterweatherman"
)
var genmandir string
var genmanCmd = &cobra.Command{
Use: "man",
Short: "Generate man pages for the Hugo CLI",
Long: `This command automatically generates up-to-date man pages of Hugo's
command-line interface. By default, it creates the man page files
in the "man" directory under the current directory.`,
RunE: func(cmd *cobra.Command, args []string) error {
header := &doc.GenManHeader{
Section: "1",
Manual: "Hugo Manual",
Source: fmt.Sprintf("Hugo %s", helpers.CurrentHugoVersion),
}
if !strings.HasSuffix(genmandir, helpers.FilePathSeparator) {
genmandir += helpers.FilePathSeparator
}
if found, _ := helpers.Exists(genmandir, hugofs.Os); !found {
jww.FEEDBACK.Println("Directory", genmandir, "does not exist, creating...")
if err := hugofs.Os.MkdirAll(genmandir, 0777); err != nil {
return err
}
}
cmd.Root().DisableAutoGenTag = true
jww.FEEDBACK.Println("Generating Hugo man pages in", genmandir, "...")
doc.GenManTree(cmd.Root(), header, genmandir)
jww.FEEDBACK.Println("Done.")
return nil
},
}
func init() {
genmanCmd.PersistentFlags().StringVar(&genmandir, "dir", "man/", "the directory to write the man pages.")
// For bash-completion
genmanCmd.PersistentFlags().SetAnnotation("dir", cobra.BashCompSubdirsInDir, []string{})
}
commands/hugo.go
-1046
View File
File diff suppressed because it is too large Load Diff
commands/hugo_windows.go
-27
View File
@@ -1,27 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import "github.com/spf13/cobra"
func init() {
// This message to show to Windows users if Hugo is opened from explorer.exe
cobra.MousetrapHelpText = `
Hugo is a command-line tool for generating static website.
You need to open cmd.exe and run Hugo from there.
Visit http://gohugo.io/ for more information.`
}
commands/import_jekyll.go
-577
View File
@@ -1,577 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"bytes"
"errors"
"io"
"io/ioutil"
"os"
"path/filepath"
"regexp"
"strconv"
"strings"
"time"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugofs"
"github.com/gohugoio/hugo/hugolib"
"github.com/gohugoio/hugo/parser"
"github.com/spf13/afero"
"github.com/spf13/cast"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
func init() {
importCmd.AddCommand(importJekyllCmd)
}
var importCmd = &cobra.Command{
Use: "import",
Short: "Import your site from others.",
Long: `Import your site from other web site generators like Jekyll.
Import requires a subcommand, e.g. ` + "`hugo import jekyll jekyll_root_path target_path`.",
RunE: nil,
}
var importJekyllCmd = &cobra.Command{
Use: "jekyll",
Short: "hugo import from Jekyll",
Long: `hugo import from Jekyll.
Import from Jekyll requires two paths, e.g. ` + "`hugo import jekyll jekyll_root_path target_path`.",
RunE: importFromJekyll,
}
func init() {
importJekyllCmd.Flags().Bool("force", false, "allow import into non-empty target directory")
}
func importFromJekyll(cmd *cobra.Command, args []string) error {
if len(args) < 2 {
return newUserError(`Import from Jekyll requires two paths, e.g. ` + "`hugo import jekyll jekyll_root_path target_path`.")
}
jekyllRoot, err := filepath.Abs(filepath.Clean(args[0]))
if err != nil {
return newUserError("Path error:", args[0])
}
targetDir, err := filepath.Abs(filepath.Clean(args[1]))
if err != nil {
return newUserError("Path error:", args[1])
}
jww.INFO.Println("Import Jekyll from:", jekyllRoot, "to:", targetDir)
if strings.HasPrefix(filepath.Dir(targetDir), jekyllRoot) {
return newUserError("Target path should not be inside the Jekyll root, aborting.")
}
forceImport, _ := cmd.Flags().GetBool("force")
site, err := createSiteFromJekyll(jekyllRoot, targetDir, forceImport)
if err != nil {
return err
}
jww.FEEDBACK.Println("Importing...")
fileCount := 0
callback := func(path string, fi os.FileInfo, err error) error {
if err != nil {
return err
}
if fi.IsDir() {
return nil
}
relPath, err := filepath.Rel(jekyllRoot, path)
if err != nil {
return newUserError("Get rel path error:", path)
}
relPath = filepath.ToSlash(relPath)
draft := false
switch {
case strings.HasPrefix(relPath, "_posts/"):
relPath = "content/post" + relPath[len("_posts"):]
case strings.HasPrefix(relPath, "_drafts/"):
relPath = "content/draft" + relPath[len("_drafts"):]
draft = true
default:
return nil
}
fileCount++
return convertJekyllPost(site, path, relPath, targetDir, draft)
}
err = helpers.SymbolicWalk(hugofs.Os, jekyllRoot, callback)
if err != nil {
return err
}
jww.FEEDBACK.Println("Congratulations!", fileCount, "post(s) imported!")
jww.FEEDBACK.Println("Now, start Hugo by yourself:\n" +
"$ git clone https://github.com/spf13/herring-cove.git " + args[1] + "/themes/herring-cove")
jww.FEEDBACK.Println("$ cd " + args[1] + "\n$ hugo server --theme=herring-cove")
return nil
}
// TODO: Consider calling doNewSite() instead?
func createSiteFromJekyll(jekyllRoot, targetDir string, force bool) (*hugolib.Site, error) {
s, err := hugolib.NewSiteDefaultLang()
if err != nil {
return nil, err
}
fs := s.Fs.Source
if exists, _ := helpers.Exists(targetDir, fs); exists {
if isDir, _ := helpers.IsDir(targetDir, fs); !isDir {
return nil, errors.New("Target path \"" + targetDir + "\" already exists but not a directory")
}
isEmpty, _ := helpers.IsEmpty(targetDir, fs)
if !isEmpty && !force {
return nil, errors.New("Target path \"" + targetDir + "\" already exists and is not empty")
}
}
jekyllConfig := loadJekyllConfig(fs, jekyllRoot)
// Crude test to make sure at least one of _drafts/ and _posts/ exists
// and is not empty.
hasPostsOrDrafts := false
postsDir := filepath.Join(jekyllRoot, "_posts")
draftsDir := filepath.Join(jekyllRoot, "_drafts")
for _, d := range []string{postsDir, draftsDir} {
if exists, _ := helpers.Exists(d, fs); exists {
if isDir, _ := helpers.IsDir(d, fs); isDir {
if isEmpty, _ := helpers.IsEmpty(d, fs); !isEmpty {
hasPostsOrDrafts = true
}
}
}
}
if !hasPostsOrDrafts {
return nil, errors.New("Your Jekyll root contains neither posts nor drafts, aborting.")
}
mkdir(targetDir, "layouts")
mkdir(targetDir, "content")
mkdir(targetDir, "archetypes")
mkdir(targetDir, "static")
mkdir(targetDir, "data")
mkdir(targetDir, "themes")
createConfigFromJekyll(fs, targetDir, "yaml", jekyllConfig)
copyJekyllFilesAndFolders(jekyllRoot, filepath.Join(targetDir, "static"))
return s, nil
}
func loadJekyllConfig(fs afero.Fs, jekyllRoot string) map[string]interface{} {
path := filepath.Join(jekyllRoot, "_config.yml")
exists, err := helpers.Exists(path, fs)
if err != nil || !exists {
jww.WARN.Println("_config.yaml not found: Is the specified Jekyll root correct?")
return nil
}
f, err := fs.Open(path)
if err != nil {
return nil
}
defer f.Close()
b, err := ioutil.ReadAll(f)
if err != nil {
return nil
}
c, err := parser.HandleYAMLMetaData(b)
if err != nil {
return nil
}
return c.(map[string]interface{})
}
func createConfigFromJekyll(fs afero.Fs, inpath string, kind string, jekyllConfig map[string]interface{}) (err error) {
title := "My New Hugo Site"
baseURL := "http://example.org/"
for key, value := range jekyllConfig {
lowerKey := strings.ToLower(key)
switch lowerKey {
case "title":
if str, ok := value.(string); ok {
title = str
}
case "url":
if str, ok := value.(string); ok {
baseURL = str
}
}
}
in := map[string]interface{}{
"baseURL": baseURL,
"title": title,
"languageCode": "en-us",
"disablePathToLower": true,
}
kind = parser.FormatSanitize(kind)
var buf bytes.Buffer
err = parser.InterfaceToConfig(in, parser.FormatToLeadRune(kind), &buf)
if err != nil {
return err
}
return helpers.WriteToDisk(filepath.Join(inpath, "config."+kind), &buf, fs)
}
func copyFile(source string, dest string) error {
sf, err := os.Open(source)
if err != nil {
return err
}
defer sf.Close()
df, err := os.Create(dest)
if err != nil {
return err
}
defer df.Close()
_, err = io.Copy(df, sf)
if err == nil {
si, err := os.Stat(source)
if err != nil {
err = os.Chmod(dest, si.Mode())
if err != nil {
return err
}
}
}
return nil
}
func copyDir(source string, dest string) error {
fi, err := os.Stat(source)
if err != nil {
return err
}
if !fi.IsDir() {
return errors.New(source + " is not a directory")
}
err = os.MkdirAll(dest, fi.Mode())
if err != nil {
return err
}
entries, err := ioutil.ReadDir(source)
for _, entry := range entries {
sfp := filepath.Join(source, entry.Name())
dfp := filepath.Join(dest, entry.Name())
if entry.IsDir() {
err = copyDir(sfp, dfp)
if err != nil {
jww.ERROR.Println(err)
}
} else {
err = copyFile(sfp, dfp)
if err != nil {
jww.ERROR.Println(err)
}
}
}
return nil
}
func copyJekyllFilesAndFolders(jekyllRoot string, dest string) error {
fi, err := os.Stat(jekyllRoot)
if err != nil {
return err
}
if !fi.IsDir() {
return errors.New(jekyllRoot + " is not a directory")
}
err = os.MkdirAll(dest, fi.Mode())
if err != nil {
return err
}
entries, err := ioutil.ReadDir(jekyllRoot)
for _, entry := range entries {
sfp := filepath.Join(jekyllRoot, entry.Name())
dfp := filepath.Join(dest, entry.Name())
if entry.IsDir() {
if entry.Name()[0] != '_' && entry.Name()[0] != '.' {
err = copyDir(sfp, dfp)
if err != nil {
jww.ERROR.Println(err)
}
}
} else {
lowerEntryName := strings.ToLower(entry.Name())
exceptSuffix := []string{".md", ".markdown", ".html", ".htm",
".xml", ".textile", "rakefile", "gemfile", ".lock"}
isExcept := false
for _, suffix := range exceptSuffix {
if strings.HasSuffix(lowerEntryName, suffix) {
isExcept = true
break
}
}
if !isExcept && entry.Name()[0] != '.' && entry.Name()[0] != '_' {
err = copyFile(sfp, dfp)
if err != nil {
jww.ERROR.Println(err)
}
}
}
}
return nil
}
func parseJekyllFilename(filename string) (time.Time, string, error) {
re := regexp.MustCompile(`(\d+-\d+-\d+)-(.+)\..*`)
r := re.FindAllStringSubmatch(filename, -1)
if len(r) == 0 {
return time.Now(), "", errors.New("filename not match")
}
postDate, err := time.Parse("2006-1-2", r[0][1])
if err != nil {
return time.Now(), "", err
}
postName := r[0][2]
return postDate, postName, nil
}
func convertJekyllPost(s *hugolib.Site, path, relPath, targetDir string, draft bool) error {
jww.TRACE.Println("Converting", path)
filename := filepath.Base(path)
postDate, postName, err := parseJekyllFilename(filename)
if err != nil {
jww.WARN.Printf("Failed to parse filename '%s': %s. Skipping.", filename, err)
return nil
}
jww.TRACE.Println(filename, postDate, postName)
targetFile := filepath.Join(targetDir, relPath)
targetParentDir := filepath.Dir(targetFile)
os.MkdirAll(targetParentDir, 0777)
contentBytes, err := ioutil.ReadFile(path)
if err != nil {
jww.ERROR.Println("Read file error:", path)
return err
}
psr, err := parser.ReadFrom(bytes.NewReader(contentBytes))
if err != nil {
jww.ERROR.Println("Parse file error:", path)
return err
}
metadata, err := psr.Metadata()
if err != nil {
jww.ERROR.Println("Processing file error:", path)
return err
}
newmetadata, err := convertJekyllMetaData(metadata, postName, postDate, draft)
if err != nil {
jww.ERROR.Println("Convert metadata error:", path)
return err
}
jww.TRACE.Println(newmetadata)
content := convertJekyllContent(newmetadata, string(psr.Content()))
page, err := s.NewPage(filename)
if err != nil {
jww.ERROR.Println("New page error", filename)
return err
}
page.SetDir(targetParentDir)
page.SetSourceContent([]byte(content))
page.SetSourceMetaData(newmetadata, parser.FormatToLeadRune("yaml"))
page.SaveSourceAs(targetFile)
jww.TRACE.Println("Target file:", targetFile)
return nil
}
func convertJekyllMetaData(m interface{}, postName string, postDate time.Time, draft bool) (interface{}, error) {
url := postDate.Format("/2006/01/02/") + postName + "/"
metadata, err := cast.ToStringMapE(m)
if err != nil {
return nil, err
}
if draft {
metadata["draft"] = true
}
for key, value := range metadata {
lowerKey := strings.ToLower(key)
switch lowerKey {
case "layout":
delete(metadata, key)
case "permalink":
if str, ok := value.(string); ok {
url = str
}
delete(metadata, key)
case "category":
if str, ok := value.(string); ok {
metadata["categories"] = []string{str}
}
delete(metadata, key)
case "excerpt_separator":
if key != lowerKey {
delete(metadata, key)
metadata[lowerKey] = value
}
case "date":
if str, ok := value.(string); ok {
re := regexp.MustCompile(`(\d+):(\d+):(\d+)`)
r := re.FindAllStringSubmatch(str, -1)
if len(r) > 0 {
hour, _ := strconv.Atoi(r[0][1])
minute, _ := strconv.Atoi(r[0][2])
second, _ := strconv.Atoi(r[0][3])
postDate = time.Date(postDate.Year(), postDate.Month(), postDate.Day(), hour, minute, second, 0, time.UTC)
}
}
delete(metadata, key)
}
}
metadata["url"] = url
metadata["date"] = postDate.Format(time.RFC3339)
return metadata, nil
}
func convertJekyllContent(m interface{}, content string) string {
metadata, _ := cast.ToStringMapE(m)
lines := strings.Split(content, "\n")
var resultLines []string
for _, line := range lines {
resultLines = append(resultLines, strings.Trim(line, "\r\n"))
}
content = strings.Join(resultLines, "\n")
excerptSep := "<!--more-->"
if value, ok := metadata["excerpt_separator"]; ok {
if str, strOk := value.(string); strOk {
content = strings.Replace(content, strings.TrimSpace(str), excerptSep, -1)
}
}
replaceList := []struct {
re *regexp.Regexp
replace string
}{
{regexp.MustCompile("(?i)<!-- more -->"), "<!--more-->"},
{regexp.MustCompile(`\{%\s*raw\s*%\}\s*(.*?)\s*\{%\s*endraw\s*%\}`), "$1"},
{regexp.MustCompile(`{%\s*highlight\s*(.*?)\s*%}`), "{{< highlight $1 >}}"},
{regexp.MustCompile(`{%\s*endhighlight\s*%}`), "{{< / highlight >}}"},
}
for _, replace := range replaceList {
content = replace.re.ReplaceAllString(content, replace.replace)
}
replaceListFunc := []struct {
re *regexp.Regexp
replace func(string) string
}{
// Octopress image tag: http://octopress.org/docs/plugins/image-tag/
{regexp.MustCompile(`{%\s+img\s*(.*?)\s*%}`), replaceImageTag},
}
for _, replace := range replaceListFunc {
content = replace.re.ReplaceAllStringFunc(content, replace.replace)
}
return content
}
func replaceImageTag(match string) string {
r := regexp.MustCompile(`{%\s+img\s*(\p{L}*)\s+([\S]*/[\S]+)\s+(\d*)\s*(\d*)\s*(.*?)\s*%}`)
result := bytes.NewBufferString("{{< figure ")
parts := r.FindStringSubmatch(match)
// Index 0 is the entire string, ignore
replaceOptionalPart(result, "class", parts[1])
replaceOptionalPart(result, "src", parts[2])
replaceOptionalPart(result, "width", parts[3])
replaceOptionalPart(result, "height", parts[4])
// title + alt
part := parts[5]
if len(part) > 0 {
splits := strings.Split(part, "'")
lenSplits := len(splits)
if lenSplits == 1 {
replaceOptionalPart(result, "title", splits[0])
} else if lenSplits == 3 {
replaceOptionalPart(result, "title", splits[1])
} else if lenSplits == 5 {
replaceOptionalPart(result, "title", splits[1])
replaceOptionalPart(result, "alt", splits[3])
}
}
result.WriteString(">}}")
return result.String()
}
func replaceOptionalPart(buffer *bytes.Buffer, partName string, part string) {
if len(part) > 0 {
buffer.WriteString(partName + "=\"" + part + "\" ")
}
}
commands/import_jekyll_test.go
-126
View File
@@ -1,126 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"encoding/json"
"github.com/stretchr/testify/assert"
"testing"
"time"
)
func TestParseJekyllFilename(t *testing.T) {
filenameArray := []string{
"2015-01-02-test.md",
"2012-03-15-中文.markup",
}
expectResult := []struct {
postDate time.Time
postName string
}{
{time.Date(2015, time.January, 2, 0, 0, 0, 0, time.UTC), "test"},
{time.Date(2012, time.March, 15, 0, 0, 0, 0, time.UTC), "中文"},
}
for i, filename := range filenameArray {
postDate, postName, err := parseJekyllFilename(filename)
assert.Equal(t, err, nil)
assert.Equal(t, expectResult[i].postDate.Format("2006-01-02"), postDate.Format("2006-01-02"))
assert.Equal(t, expectResult[i].postName, postName)
}
}
func TestConvertJekyllMetadata(t *testing.T) {
testDataList := []struct {
metadata interface{}
postName string
postDate time.Time
draft bool
expect string
}{
{map[interface{}]interface{}{}, "testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"date":"2015-10-01T00:00:00Z","url":"/2015/10/01/testPost/"}`},
{map[interface{}]interface{}{}, "testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), true,
`{"date":"2015-10-01T00:00:00Z","draft":true,"url":"/2015/10/01/testPost/"}`},
{map[interface{}]interface{}{"Permalink": "/permalink.html", "layout": "post"},
"testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"date":"2015-10-01T00:00:00Z","url":"/permalink.html"}`},
{map[interface{}]interface{}{"permalink": "/permalink.html"},
"testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"date":"2015-10-01T00:00:00Z","url":"/permalink.html"}`},
{map[interface{}]interface{}{"category": nil, "permalink": 123},
"testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"date":"2015-10-01T00:00:00Z","url":"/2015/10/01/testPost/"}`},
{map[interface{}]interface{}{"Excerpt_Separator": "sep"},
"testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"date":"2015-10-01T00:00:00Z","excerpt_separator":"sep","url":"/2015/10/01/testPost/"}`},
{map[interface{}]interface{}{"category": "book", "layout": "post", "Others": "Goods", "Date": "2015-10-01 12:13:11"},
"testPost", time.Date(2015, 10, 1, 0, 0, 0, 0, time.UTC), false,
`{"Others":"Goods","categories":["book"],"date":"2015-10-01T12:13:11Z","url":"/2015/10/01/testPost/"}`},
}
for _, data := range testDataList {
result, err := convertJekyllMetaData(data.metadata, data.postName, data.postDate, data.draft)
assert.Equal(t, nil, err)
jsonResult, err := json.Marshal(result)
assert.Equal(t, nil, err)
assert.Equal(t, data.expect, string(jsonResult))
}
}
func TestConvertJekyllContent(t *testing.T) {
testDataList := []struct {
metadata interface{}
content string
expect string
}{
{map[interface{}]interface{}{},
`Test content\n<!-- more -->\npart2 content`, `Test content\n<!--more-->\npart2 content`},
{map[interface{}]interface{}{},
`Test content\n<!-- More -->\npart2 content`, `Test content\n<!--more-->\npart2 content`},
{map[interface{}]interface{}{"excerpt_separator": "<!--sep-->"},
`Test content\n<!--sep-->\npart2 content`, `Test content\n<!--more-->\npart2 content`},
{map[interface{}]interface{}{}, "{% raw %}text{% endraw %}", "text"},
{map[interface{}]interface{}{}, "{%raw%} text2 {%endraw %}", "text2"},
{map[interface{}]interface{}{},
"{% highlight go %}\nvar s int\n{% endhighlight %}",
"{{< highlight go >}}\nvar s int\n{{< / highlight >}}"},
// Octopress image tag
{map[interface{}]interface{}{},
"{% img http://placekitten.com/890/280 %}",
"{{< figure src=\"http://placekitten.com/890/280\" >}}"},
{map[interface{}]interface{}{},
"{% img left http://placekitten.com/320/250 Place Kitten #2 %}",
"{{< figure class=\"left\" src=\"http://placekitten.com/320/250\" title=\"Place Kitten #2\" >}}"},
{map[interface{}]interface{}{},
"{% img right http://placekitten.com/300/500 150 250 'Place Kitten #3' %}",
"{{< figure class=\"right\" src=\"http://placekitten.com/300/500\" width=\"150\" height=\"250\" title=\"Place Kitten #3\" >}}"},
{map[interface{}]interface{}{},
"{% img right http://placekitten.com/300/500 150 250 'Place Kitten #4' 'An image of a very cute kitten' %}",
"{{< figure class=\"right\" src=\"http://placekitten.com/300/500\" width=\"150\" height=\"250\" title=\"Place Kitten #4\" alt=\"An image of a very cute kitten\" >}}"},
{map[interface{}]interface{}{},
"{% img http://placekitten.com/300/500 150 250 'Place Kitten #4' 'An image of a very cute kitten' %}",
"{{< figure src=\"http://placekitten.com/300/500\" width=\"150\" height=\"250\" title=\"Place Kitten #4\" alt=\"An image of a very cute kitten\" >}}"},
{map[interface{}]interface{}{},
"{% img right /placekitten/300/500 'Place Kitten #4' 'An image of a very cute kitten' %}",
"{{< figure class=\"right\" src=\"/placekitten/300/500\" title=\"Place Kitten #4\" alt=\"An image of a very cute kitten\" >}}"},
}
for _, data := range testDataList {
result := convertJekyllContent(data.metadata, data.content)
assert.Equal(t, data.expect, result)
}
}
commands/limit_darwin.go
-85
View File
@@ -1,85 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"syscall"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
func init() {
checkCmd.AddCommand(limit)
}
var limit = &cobra.Command{
Use: "ulimit",
Short: "Check system ulimit settings",
Long: `Hugo will inspect the current ulimit settings on the system.
This is primarily to ensure that Hugo can watch enough files on some OSs`,
RunE: func(cmd *cobra.Command, args []string) error {
var rLimit syscall.Rlimit
err := syscall.Getrlimit(syscall.RLIMIT_NOFILE, &rLimit)
if err != nil {
return newSystemError("Error Getting Rlimit ", err)
}
jww.FEEDBACK.Println("Current rLimit:", rLimit)
jww.FEEDBACK.Println("Attempting to increase limit")
rLimit.Max = 999999
rLimit.Cur = 999999
err = syscall.Setrlimit(syscall.RLIMIT_NOFILE, &rLimit)
if err != nil {
return newSystemError("Error Setting rLimit ", err)
}
err = syscall.Getrlimit(syscall.RLIMIT_NOFILE, &rLimit)
if err != nil {
return newSystemError("Error Getting rLimit ", err)
}
jww.FEEDBACK.Println("rLimit after change:", rLimit)
return nil
},
}
func tweakLimit() {
var rLimit syscall.Rlimit
err := syscall.Getrlimit(syscall.RLIMIT_NOFILE, &rLimit)
if err != nil {
jww.ERROR.Println("Unable to obtain rLimit", err)
}
if rLimit.Cur < rLimit.Max {
rLimit.Max = 64000
rLimit.Cur = 64000
err = syscall.Setrlimit(syscall.RLIMIT_NOFILE, &rLimit)
if err != nil {
jww.WARN.Println("Unable to increase number of open files limit", err)
}
}
}
commands/limit_others.go
-32
View File
@@ -1,32 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// +build !darwin
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
func tweakLimit() {
// nothing to do
}
commands/list.go
-161
View File
@@ -1,161 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"path/filepath"
"github.com/gohugoio/hugo/hugolib"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
func init() {
listCmd.AddCommand(listDraftsCmd)
listCmd.AddCommand(listFutureCmd)
listCmd.AddCommand(listExpiredCmd)
listCmd.PersistentFlags().StringVarP(&source, "source", "s", "", "filesystem path to read files relative from")
listCmd.PersistentFlags().SetAnnotation("source", cobra.BashCompSubdirsInDir, []string{})
}
var listCmd = &cobra.Command{
Use: "list",
Short: "Listing out various types of content",
Long: `Listing out various types of content.
List requires a subcommand, e.g. ` + "`hugo list drafts`.",
RunE: nil,
}
var listDraftsCmd = &cobra.Command{
Use: "drafts",
Short: "List all drafts",
Long: `List all of the drafts in your content directory.`,
RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
c.Set("buildDrafts", true)
sites, err := hugolib.NewHugoSites(*cfg)
if err != nil {
return newSystemError("Error creating sites", err)
}
if err := sites.Build(hugolib.BuildCfg{SkipRender: true}); err != nil {
return newSystemError("Error Processing Source Content", err)
}
for _, p := range sites.Pages() {
if p.IsDraft() {
jww.FEEDBACK.Println(filepath.Join(p.File.Dir(), p.File.LogicalName()))
}
}
return nil
},
}
var listFutureCmd = &cobra.Command{
Use: "future",
Short: "List all posts dated in the future",
Long: `List all of the posts in your content directory which will be
posted in the future.`,
RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
c.Set("buildFuture", true)
sites, err := hugolib.NewHugoSites(*cfg)
if err != nil {
return newSystemError("Error creating sites", err)
}
if err := sites.Build(hugolib.BuildCfg{SkipRender: true}); err != nil {
return newSystemError("Error Processing Source Content", err)
}
for _, p := range sites.Pages() {
if p.IsFuture() {
jww.FEEDBACK.Println(filepath.Join(p.File.Dir(), p.File.LogicalName()))
}
}
return nil
},
}
var listExpiredCmd = &cobra.Command{
Use: "expired",
Short: "List all posts already expired",
Long: `List all of the posts in your content directory which has already
expired.`,
RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
c.Set("buildExpired", true)
sites, err := hugolib.NewHugoSites(*cfg)
if err != nil {
return newSystemError("Error creating sites", err)
}
if err := sites.Build(hugolib.BuildCfg{SkipRender: true}); err != nil {
return newSystemError("Error Processing Source Content", err)
}
for _, p := range sites.Pages() {
if p.IsExpired() {
jww.FEEDBACK.Println(filepath.Join(p.File.Dir(), p.File.LogicalName()))
}
}
return nil
},
}
commands/list_config.go
-66
View File
@@ -1,66 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.Print the version number of Hug
package commands
import (
"reflect"
"sort"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
"github.com/spf13/viper"
)
var configCmd = &cobra.Command{
Use: "config",
Short: "Print the site configuration",
Long: `Print the site configuration, both default and custom settings.`,
}
func init() {
configCmd.RunE = printConfig
}
func printConfig(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig(configCmd)
if err != nil {
return err
}
allSettings := cfg.Cfg.(*viper.Viper).AllSettings()
var separator string
if allSettings["metadataformat"] == "toml" {
separator = " = "
} else {
separator = ": "
}
var keys []string
for k := range allSettings {
keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
kv := reflect.ValueOf(allSettings[k])
if kv.Kind() == reflect.String {
jww.FEEDBACK.Printf("%s%s\"%+v\"\n", k, separator, allSettings[k])
} else {
jww.FEEDBACK.Printf("%s%s%+v\n", k, separator, allSettings[k])
}
}
return nil
}
commands/new.go
-399
View File
@@ -1,399 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"bytes"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"time"
"github.com/gohugoio/hugo/create"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugofs"
"github.com/gohugoio/hugo/hugolib"
"github.com/gohugoio/hugo/parser"
"github.com/spf13/afero"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
"github.com/spf13/viper"
)
var (
configFormat string
contentEditor string
contentType string
)
func init() {
newSiteCmd.Flags().StringVarP(&configFormat, "format", "f", "toml", "config & frontmatter format")
newSiteCmd.Flags().Bool("force", false, "init inside non-empty directory")
newCmd.Flags().StringVarP(&contentType, "kind", "k", "", "content type to create")
newCmd.PersistentFlags().StringVarP(&source, "source", "s", "", "filesystem path to read files relative from")
newCmd.PersistentFlags().SetAnnotation("source", cobra.BashCompSubdirsInDir, []string{})
newCmd.Flags().StringVar(&contentEditor, "editor", "", "edit new content with this editor, if provided")
newCmd.AddCommand(newSiteCmd)
newCmd.AddCommand(newThemeCmd)
}
var newCmd = &cobra.Command{
Use: "new [path]",
Short: "Create new content for your site",
Long: `Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.
You can also specify the kind with ` + "`-k KIND`" + `.
If archetypes are provided in your theme or site, they will be used.`,
RunE: NewContent,
}
var newSiteCmd = &cobra.Command{
Use: "site [path]",
Short: "Create a new site (skeleton)",
Long: `Create a new site in the provided directory.
The new site will have the correct structure, but no content or theme yet.
Use ` + "`hugo new [contentPath]`" + ` to create new content.`,
RunE: NewSite,
}
var newThemeCmd = &cobra.Command{
Use: "theme [name]",
Short: "Create a new theme",
Long: `Create a new theme (skeleton) called [name] in the current directory.
New theme is a skeleton. Please add content to the touched files. Add your
name to the copyright line in the license and adjust the theme.toml file
as you see fit.`,
RunE: NewTheme,
}
// NewContent adds new content to a Hugo site.
func NewContent(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
if cmd.Flags().Changed("editor") {
c.Set("newContentEditor", contentEditor)
}
if len(args) < 1 {
return newUserError("path needs to be provided")
}
createPath := args[0]
var kind string
createPath, kind = newContentPathSection(createPath)
if contentType != "" {
kind = contentType
}
ps, err := helpers.NewPathSpec(cfg.Fs, cfg.Cfg)
if err != nil {
return err
}
// If a site isn't in use in the archetype template, we can skip the build.
siteFactory := func(filename string, siteUsed bool) (*hugolib.Site, error) {
if !siteUsed {
return hugolib.NewSite(*cfg)
}
var s *hugolib.Site
if err := c.initSites(); err != nil {
return nil, err
}
if err := Hugo.Build(hugolib.BuildCfg{SkipRender: true, PrintStats: false}); err != nil {
return nil, err
}
s = Hugo.Sites[0]
if len(Hugo.Sites) > 1 {
// Find the best match.
for _, ss := range Hugo.Sites {
if strings.Contains(createPath, "."+ss.Language.Lang) {
s = ss
break
}
}
}
return s, nil
}
return create.NewContent(ps, siteFactory, kind, createPath)
}
func doNewSite(fs *hugofs.Fs, basepath string, force bool) error {
archeTypePath := filepath.Join(basepath, "archetypes")
dirs := []string{
filepath.Join(basepath, "layouts"),
filepath.Join(basepath, "content"),
archeTypePath,
filepath.Join(basepath, "static"),
filepath.Join(basepath, "data"),
filepath.Join(basepath, "themes"),
}
if exists, _ := helpers.Exists(basepath, fs.Source); exists {
if isDir, _ := helpers.IsDir(basepath, fs.Source); !isDir {
return errors.New(basepath + " already exists but not a directory")
}
isEmpty, _ := helpers.IsEmpty(basepath, fs.Source)
switch {
case !isEmpty && !force:
return errors.New(basepath + " already exists and is not empty")
case !isEmpty && force:
all := append(dirs, filepath.Join(basepath, "config."+configFormat))
for _, path := range all {
if exists, _ := helpers.Exists(path, fs.Source); exists {
return errors.New(path + " already exists")
}
}
}
}
for _, dir := range dirs {
if err := fs.Source.MkdirAll(dir, 0777); err != nil {
return fmt.Errorf("Failed to create dir: %s", err)
}
}
createConfig(fs, basepath, configFormat)
// Create a defaul archetype file.
helpers.SafeWriteToDisk(filepath.Join(archeTypePath, "default.md"),
strings.NewReader(create.ArchetypeTemplateTemplate), fs.Source)
jww.FEEDBACK.Printf("Congratulations! Your new Hugo site is created in %s.\n\n", basepath)
jww.FEEDBACK.Println(nextStepsText())
return nil
}
func nextStepsText() string {
var nextStepsText bytes.Buffer
nextStepsText.WriteString(`Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/, or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new `)
nextStepsText.WriteString(filepath.Join("<SECTIONNAME>", "<FILENAME>.<FORMAT>"))
nextStepsText.WriteString(`".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.`)
return nextStepsText.String()
}
// NewSite creates a new Hugo site and initializes a structured Hugo directory.
func NewSite(cmd *cobra.Command, args []string) error {
if len(args) < 1 {
return newUserError("path needs to be provided")
}
createpath, err := filepath.Abs(filepath.Clean(args[0]))
if err != nil {
return newUserError(err)
}
forceNew, _ := cmd.Flags().GetBool("force")
return doNewSite(hugofs.NewDefault(viper.New()), createpath, forceNew)
}
// NewTheme creates a new Hugo theme.
func NewTheme(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
if len(args) < 1 {
return newUserError("theme name needs to be provided")
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
createpath := c.PathSpec().AbsPathify(filepath.Join(c.Cfg.GetString("themesDir"), args[0]))
jww.INFO.Println("creating theme at", createpath)
if x, _ := helpers.Exists(createpath, cfg.Fs.Source); x {
return newUserError(createpath, "already exists")
}
mkdir(createpath, "layouts", "_default")
mkdir(createpath, "layouts", "partials")
touchFile(cfg.Fs.Source, createpath, "layouts", "index.html")
touchFile(cfg.Fs.Source, createpath, "layouts", "404.html")
touchFile(cfg.Fs.Source, createpath, "layouts", "_default", "list.html")
touchFile(cfg.Fs.Source, createpath, "layouts", "_default", "single.html")
touchFile(cfg.Fs.Source, createpath, "layouts", "partials", "header.html")
touchFile(cfg.Fs.Source, createpath, "layouts", "partials", "footer.html")
mkdir(createpath, "archetypes")
archDefault := []byte("+++\n+++\n")
err = helpers.WriteToDisk(filepath.Join(createpath, "archetypes", "default.md"), bytes.NewReader(archDefault), cfg.Fs.Source)
if err != nil {
return err
}
mkdir(createpath, "static", "js")
mkdir(createpath, "static", "css")
by := []byte(`The MIT License (MIT)
Copyright (c) ` + time.Now().Format("2006") + ` YOUR_NAME_HERE
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
`)
err = helpers.WriteToDisk(filepath.Join(createpath, "LICENSE.md"), bytes.NewReader(by), cfg.Fs.Source)
if err != nil {
return err
}
createThemeMD(cfg.Fs, createpath)
return nil
}
func mkdir(x ...string) {
p := filepath.Join(x...)
err := os.MkdirAll(p, 0777) // before umask
if err != nil {
jww.FATAL.Fatalln(err)
}
}
func touchFile(fs afero.Fs, x ...string) {
inpath := filepath.Join(x...)
mkdir(filepath.Dir(inpath))
err := helpers.WriteToDisk(inpath, bytes.NewReader([]byte{}), fs)
if err != nil {
jww.FATAL.Fatalln(err)
}
}
func createThemeMD(fs *hugofs.Fs, inpath string) (err error) {
by := []byte(`# theme.toml template for a Hugo theme
# See https://github.com/gohugoio/hugoThemes#themetoml for an example
name = "` + strings.Title(helpers.MakeTitle(filepath.Base(inpath))) + `"
license = "MIT"
licenselink = "https://github.com/yourname/yourtheme/blob/master/LICENSE.md"
description = ""
homepage = "http://example.com/"
tags = []
features = []
min_version = "0.24"
[author]
name = ""
homepage = ""
# If porting an existing theme
[original]
name = ""
homepage = ""
repo = ""
`)
err = helpers.WriteToDisk(filepath.Join(inpath, "theme.toml"), bytes.NewReader(by), fs.Source)
if err != nil {
return
}
return nil
}
func newContentPathSection(path string) (string, string) {
// Forward slashes is used in all examples. Convert if needed.
// Issue #1133
createpath := filepath.FromSlash(path)
var section string
// assume the first directory is the section (kind)
if strings.Contains(createpath[1:], helpers.FilePathSeparator) {
section = helpers.GuessSection(createpath)
}
return createpath, section
}
func createConfig(fs *hugofs.Fs, inpath string, kind string) (err error) {
in := map[string]string{
"baseURL": "http://example.org/",
"title": "My New Hugo Site",
"languageCode": "en-us",
}
kind = parser.FormatSanitize(kind)
var buf bytes.Buffer
err = parser.InterfaceToConfig(in, parser.FormatToLeadRune(kind), &buf)
if err != nil {
return err
}
return helpers.WriteToDisk(filepath.Join(inpath, "config."+kind), &buf, fs.Source)
}
commands/new_test.go
-122
View File
@@ -1,122 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"path/filepath"
"testing"
"github.com/gohugoio/hugo/hugofs"
"github.com/spf13/viper"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
// Issue #1133
func TestNewContentPathSectionWithForwardSlashes(t *testing.T) {
p, s := newContentPathSection("/post/new.md")
assert.Equal(t, filepath.FromSlash("/post/new.md"), p)
assert.Equal(t, "post", s)
}
func checkNewSiteInited(fs *hugofs.Fs, basepath string, t *testing.T) {
paths := []string{
filepath.Join(basepath, "layouts"),
filepath.Join(basepath, "content"),
filepath.Join(basepath, "archetypes"),
filepath.Join(basepath, "static"),
filepath.Join(basepath, "data"),
filepath.Join(basepath, "config.toml"),
}
for _, path := range paths {
_, err := fs.Source.Stat(path)
require.NoError(t, err)
}
}
func TestDoNewSite(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
require.NoError(t, doNewSite(fs, basepath, false))
checkNewSiteInited(fs, basepath, t)
}
func TestDoNewSite_noerror_base_exists_but_empty(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
require.NoError(t, fs.Source.MkdirAll(basepath, 777))
require.NoError(t, doNewSite(fs, basepath, false))
}
func TestDoNewSite_error_base_exists(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
require.NoError(t, fs.Source.MkdirAll(basepath, 777))
_, err := fs.Source.Create(filepath.Join(basepath, "foo"))
require.NoError(t, err)
// Since the directory already exists and isn't empty, expect an error
require.Error(t, doNewSite(fs, basepath, false))
}
func TestDoNewSite_force_empty_dir(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
require.NoError(t, fs.Source.MkdirAll(basepath, 777))
require.NoError(t, doNewSite(fs, basepath, true))
checkNewSiteInited(fs, basepath, t)
}
func TestDoNewSite_error_force_dir_inside_exists(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
contentPath := filepath.Join(basepath, "content")
require.NoError(t, fs.Source.MkdirAll(contentPath, 777))
require.Error(t, doNewSite(fs, basepath, true))
}
func TestDoNewSite_error_force_config_inside_exists(t *testing.T) {
basepath := filepath.Join("base", "blog")
_, fs := newTestCfg()
configPath := filepath.Join(basepath, "config.toml")
require.NoError(t, fs.Source.MkdirAll(basepath, 777))
_, err := fs.Source.Create(configPath)
require.NoError(t, err)
require.Error(t, doNewSite(fs, basepath, true))
}
func newTestCfg() (*viper.Viper, *hugofs.Fs) {
v := viper.New()
fs := hugofs.NewMem(v)
v.SetFs(fs.Source)
return v, fs
}
commands/release.go
-62
View File
@@ -1,62 +0,0 @@
// +build release
// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"github.com/gohugoio/hugo/releaser"
"github.com/spf13/cobra"
)
func init() {
HugoCmd.AddCommand(createReleaser().cmd)
}
type releaseCommandeer struct {
cmd *cobra.Command
// Will be zero for main releases.
patchLevel int
skipPublish bool
step int
}
func createReleaser() *releaseCommandeer {
// Note: This is a command only meant for internal use and must be run
// via "go run -tags release main.go release" on the actual code base that is in the release.
r := &releaseCommandeer{
cmd: &cobra.Command{
Use: "release",
Short: "Release a new version of Hugo.",
Hidden: true,
},
}
r.cmd.RunE = func(cmd *cobra.Command, args []string) error {
return r.release()
}
r.cmd.PersistentFlags().IntVarP(&r.patchLevel, "patch", "p", 0, "patch level, defaults to 0 for main releases")
r.cmd.PersistentFlags().IntVarP(&r.step, "step", "s", -1, "release step, defaults to -1 for all steps.")
r.cmd.PersistentFlags().BoolVarP(&r.skipPublish, "skip-publish", "", false, "skip all publishing pipes of the release")
return r
}
func (r *releaseCommandeer) release() error {
return releaser.New(r.patchLevel, r.step, r.skipPublish).Run()
}
commands/server.go
-309
View File
@@ -1,309 +0,0 @@
// Copyright 2016 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"fmt"
"net"
"net/http"
"net/url"
"os"
"runtime"
"strconv"
"strings"
"time"
"github.com/gohugoio/hugo/config"
"github.com/gohugoio/hugo/helpers"
"github.com/spf13/afero"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
var (
disableLiveReload bool
renderToDisk bool
serverAppend bool
serverInterface string
serverPort int
serverWatch bool
)
var serverCmd = &cobra.Command{
Use: "server",
Aliases: []string{"serve"},
Short: "A high performance webserver",
Long: `Hugo provides its own webserver which builds and serves the site.
While hugo server is high performance, it is a webserver with limited options.
Many run it in production, but the standard behavior is for people to use it
in development and use a more full featured server such as Nginx or Caddy.
'hugo server' will avoid writing the rendered and served content to disk,
preferring to store it in memory.
By default hugo will also watch your files for any changes you make and
automatically rebuild the site. It will then live reload any open browser pages
and push the latest content to them. As most Hugo sites are built in a fraction
of a second, you will be able to save and see your changes nearly instantly.`,
//RunE: server,
}
type filesOnlyFs struct {
fs http.FileSystem
}
type noDirFile struct {
http.File
}
func (fs filesOnlyFs) Open(name string) (http.File, error) {
f, err := fs.fs.Open(name)
if err != nil {
return nil, err
}
return noDirFile{f}, nil
}
func (f noDirFile) Readdir(count int) ([]os.FileInfo, error) {
return nil, nil
}
func init() {
initHugoBuilderFlags(serverCmd)
serverCmd.Flags().IntVarP(&serverPort, "port", "p", 1313, "port on which the server will listen")
serverCmd.Flags().StringVarP(&serverInterface, "bind", "", "127.0.0.1", "interface to which the server will bind")
serverCmd.Flags().BoolVarP(&serverWatch, "watch", "w", true, "watch filesystem for changes and recreate as needed")
serverCmd.Flags().BoolVarP(&serverAppend, "appendPort", "", true, "append port to baseURL")
serverCmd.Flags().BoolVar(&disableLiveReload, "disableLiveReload", false, "watch without enabling live browser reload on rebuild")
serverCmd.Flags().BoolVar(&renderToDisk, "renderToDisk", false, "render to Destination path (default is render to memory & serve from there)")
serverCmd.Flags().String("memstats", "", "log memory usage to this file")
serverCmd.Flags().String("meminterval", "100ms", "interval to poll memory usage (requires --memstats), valid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\".")
serverCmd.RunE = server
}
func server(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig(serverCmd)
if err != nil {
return err
}
c, err := newCommandeer(cfg)
if err != nil {
return err
}
if cmd.Flags().Changed("disableLiveReload") {
c.Set("disableLiveReload", disableLiveReload)
}
if serverWatch {
c.Set("watch", true)
}
if c.Cfg.GetBool("watch") {
serverWatch = true
c.watchConfig()
}
l, err := net.Listen("tcp", net.JoinHostPort(serverInterface, strconv.Itoa(serverPort)))
if err == nil {
l.Close()
} else {
if serverCmd.Flags().Changed("port") {
// port set explicitly by user -- he/she probably meant it!
return newSystemErrorF("Server startup failed: %s", err)
}
jww.ERROR.Println("port", serverPort, "already in use, attempting to use an available port")
sp, err := helpers.FindAvailablePort()
if err != nil {
return newSystemError("Unable to find alternative port to use:", err)
}
serverPort = sp.Port
}
c.Set("port", serverPort)
baseURL, err = fixURL(c.Cfg, baseURL)
if err != nil {
return err
}
c.Set("baseURL", baseURL)
if err := memStats(); err != nil {
jww.ERROR.Println("memstats error:", err)
}
// If a Destination is provided via flag write to disk
if destination != "" {
renderToDisk = true
}
// Hugo writes the output to memory instead of the disk
if !renderToDisk {
cfg.Fs.Destination = new(afero.MemMapFs)
// Rendering to memoryFS, publish to Root regardless of publishDir.
c.Set("publishDir", "/")
}
if err := c.build(serverWatch); err != nil {
return err
}
for _, s := range Hugo.Sites {
s.RegisterMediaTypes()
}
// Watch runs its own server as part of the routine
if serverWatch {
watchDirs := c.getDirList()
baseWatchDir := c.Cfg.GetString("workingDir")
for i, dir := range watchDirs {
watchDirs[i], _ = helpers.GetRelativePath(dir, baseWatchDir)
}
rootWatchDirs := strings.Join(helpers.UniqueStrings(helpers.ExtractRootPaths(watchDirs)), ",")
jww.FEEDBACK.Printf("Watching for changes in %s%s{%s}\n", baseWatchDir, helpers.FilePathSeparator, rootWatchDirs)
err := c.newWatcher(serverPort)
if err != nil {
return err
}
}
c.serve(serverPort)
return nil
}
func (c *commandeer) serve(port int) {
if renderToDisk {
jww.FEEDBACK.Println("Serving pages from " + c.PathSpec().AbsPathify(c.Cfg.GetString("publishDir")))
} else {
jww.FEEDBACK.Println("Serving pages from memory")
}
httpFs := afero.NewHttpFs(c.Fs.Destination)
fs := filesOnlyFs{httpFs.Dir(c.PathSpec().AbsPathify(c.Cfg.GetString("publishDir")))}
fileserver := http.FileServer(fs)
// We're only interested in the path
u, err := url.Parse(c.Cfg.GetString("baseURL"))
if err != nil {
jww.ERROR.Fatalf("Invalid baseURL: %s", err)
}
if u.Path == "" || u.Path == "/" {
http.Handle("/", fileserver)
} else {
http.Handle(u.Path, http.StripPrefix(u.Path, fileserver))
}
jww.FEEDBACK.Printf("Web Server is available at %s (bind address %s)\n", u.String(), serverInterface)
jww.FEEDBACK.Println("Press Ctrl+C to stop")
endpoint := net.JoinHostPort(serverInterface, strconv.Itoa(port))
err = http.ListenAndServe(endpoint, nil)
if err != nil {
jww.ERROR.Printf("Error: %s\n", err.Error())
os.Exit(1)
}
}
// fixURL massages the baseURL into a form needed for serving
// all pages correctly.
func fixURL(cfg config.Provider, s string) (string, error) {
useLocalhost := false
if s == "" {
s = cfg.GetString("baseURL")
useLocalhost = true
}
if !strings.HasSuffix(s, "/") {
s = s + "/"
}
// do an initial parse of the input string
u, err := url.Parse(s)
if err != nil {
return "", err
}
// if no Host is defined, then assume that no schema or double-slash were
// present in the url. Add a double-slash and make a best effort attempt.
if u.Host == "" && s != "/" {
s = "//" + s
u, err = url.Parse(s)
if err != nil {
return "", err
}
}
if useLocalhost {
if u.Scheme == "https" {
u.Scheme = "http"
}
u.Host = "localhost"
}
if serverAppend {
if strings.Contains(u.Host, ":") {
u.Host, _, err = net.SplitHostPort(u.Host)
if err != nil {
return "", fmt.Errorf("Failed to split baseURL hostpost: %s", err)
}
}
u.Host += fmt.Sprintf(":%d", serverPort)
}
return u.String(), nil
}
func memStats() error {
memstats := serverCmd.Flags().Lookup("memstats").Value.String()
if memstats != "" {
interval, err := time.ParseDuration(serverCmd.Flags().Lookup("meminterval").Value.String())
if err != nil {
interval, _ = time.ParseDuration("100ms")
}
fileMemStats, err := os.Create(memstats)
if err != nil {
return err
}
fileMemStats.WriteString("# Time\tHeapSys\tHeapAlloc\tHeapIdle\tHeapReleased\n")
go func() {
var stats runtime.MemStats
start := time.Now().UnixNano()
for {
runtime.ReadMemStats(&stats)
if fileMemStats != nil {
fileMemStats.WriteString(fmt.Sprintf("%d\t%d\t%d\t%d\t%d\n",
(time.Now().UnixNano()-start)/1000000, stats.HeapSys, stats.HeapAlloc, stats.HeapIdle, stats.HeapReleased))
time.Sleep(interval)
} else {
break
}
}
}()
}
return nil
}
commands/server_test.go
-58
View File
@@ -1,58 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"testing"
"github.com/spf13/viper"
)
func TestFixURL(t *testing.T) {
type data struct {
TestName string
CLIBaseURL string
CfgBaseURL string
AppendPort bool
Port int
Result string
}
tests := []data{
{"Basic http localhost", "", "http://foo.com", true, 1313, "http://localhost:1313/"},
{"Basic https production, http localhost", "", "https://foo.com", true, 1313, "http://localhost:1313/"},
{"Basic subdir", "", "http://foo.com/bar", true, 1313, "http://localhost:1313/bar/"},
{"Basic production", "http://foo.com", "http://foo.com", false, 80, "http://foo.com/"},
{"Production subdir", "http://foo.com/bar", "http://foo.com/bar", false, 80, "http://foo.com/bar/"},
{"No http", "", "foo.com", true, 1313, "//localhost:1313/"},
{"Override configured port", "", "foo.com:2020", true, 1313, "//localhost:1313/"},
{"No http production", "foo.com", "foo.com", false, 80, "//foo.com/"},
{"No http production with port", "foo.com", "foo.com", true, 2020, "//foo.com:2020/"},
{"No config", "", "", true, 1313, "//localhost:1313/"},
}
for i, test := range tests {
v := viper.New()
baseURL = test.CLIBaseURL
v.Set("baseURL", test.CfgBaseURL)
serverAppend = test.AppendPort
serverPort = test.Port
result, err := fixURL(v, baseURL)
if err != nil {
t.Errorf("Test #%d %s: unexpected error %s", i, test.TestName, err)
}
if result != test.Result {
t.Errorf("Test #%d %s: expected %q, got %q", i, test.TestName, test.Result, result)
}
}
}
commands/undraft.go
-157
View File
@@ -1,157 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"bytes"
"errors"
"os"
"time"
"github.com/gohugoio/hugo/parser"
"github.com/spf13/cobra"
)
var undraftCmd = &cobra.Command{
Use: "undraft path/to/content",
Short: "Undraft changes the content's draft status from 'True' to 'False'",
Long: `Undraft changes the content's draft status from 'True' to 'False'
and updates the date to the current date and time.
If the content's draft status is 'False', nothing is done.`,
RunE: Undraft,
}
// Undraft publishes the specified content by setting its draft status
// to false and setting its publish date to now. If the specified content is
// not a draft, it will log an error.
func Undraft(cmd *cobra.Command, args []string) error {
cfg, err := InitializeConfig()
if err != nil {
return err
}
if len(args) < 1 {
return newUserError("a piece of content needs to be specified")
}
location := args[0]
// open the file
f, err := cfg.Fs.Source.Open(location)
if err != nil {
return err
}
// get the page from file
p, err := parser.ReadFrom(f)
f.Close()
if err != nil {
return err
}
w, err := undraftContent(p)
if err != nil {
return newSystemErrorF("an error occurred while undrafting %q: %s", location, err)
}
f, err = cfg.Fs.Source.OpenFile(location, os.O_WRONLY|os.O_TRUNC, 0644)
if err != nil {
return newSystemErrorF("%q not be undrafted due to error opening file to save changes: %q\n", location, err)
}
defer f.Close()
_, err = w.WriteTo(f)
if err != nil {
return newSystemErrorF("%q not be undrafted due to save error: %q\n", location, err)
}
return nil
}
// undraftContent: if the content is a draft, change its draft status to
// 'false' and set the date to time.Now(). If the draft status is already
// 'false', don't do anything.
func undraftContent(p parser.Page) (bytes.Buffer, error) {
var buff bytes.Buffer
// get the metadata; easiest way to see if it's a draft
meta, err := p.Metadata()
if err != nil {
return buff, err
}
// since the metadata was obtainable, we can also get the key/value separator for
// Front Matter
fm := p.FrontMatter()
if fm == nil {
return buff, errors.New("Front Matter was found, nothing was finalized")
}
var isDraft, gotDate bool
var date string
L:
for k, v := range meta.(map[string]interface{}) {
switch k {
case "draft":
if !v.(bool) {
return buff, errors.New("not a Draft: nothing was done")
}
isDraft = true
if gotDate {
break L
}
case "date":
date = v.(string) // capture the value to make replacement easier
gotDate = true
if isDraft {
break L
}
}
}
// if draft wasn't found in FrontMatter, it isn't a draft.
if !isDraft {
return buff, errors.New("not a Draft: nothing was done")
}
// get the front matter as bytes and split it into lines
var lineEnding []byte
fmLines := bytes.Split(fm, []byte("\n"))
if len(fmLines) == 1 { // if the result is only 1 element, try to split on dos line endings
fmLines = bytes.Split(fm, []byte("\r\n"))
if len(fmLines) == 1 {
return buff, errors.New("unable to split FrontMatter into lines")
}
lineEnding = append(lineEnding, []byte("\r\n")...)
} else {
lineEnding = append(lineEnding, []byte("\n")...)
}
// Write the front matter lines to the buffer, replacing as necessary
for _, v := range fmLines {
pos := bytes.Index(v, []byte("draft"))
if pos != -1 {
v = bytes.Replace(v, []byte("true"), []byte("false"), 1)
goto write
}
pos = bytes.Index(v, []byte("date"))
if pos != -1 { // if date field wasn't found, add it
v = bytes.Replace(v, []byte(date), []byte(time.Now().Format(time.RFC3339)), 1)
}
write:
buff.Write(v)
buff.Write(lineEnding)
}
// append the actual content
buff.Write(p.Content())
return buff, nil
}
commands/undraft_test.go
-85
View File
@@ -1,85 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
// TODO Support Mac Encoding (\r)
import (
"bytes"
"strings"
"testing"
"time"
"github.com/gohugoio/hugo/parser"
)
var (
jsonFM = "{\n \"date\": \"12-04-06\",\n \"title\": \"test json\"\n}"
jsonDraftFM = "{\n \"draft\": true,\n \"date\": \"12-04-06\",\n \"title\":\"test json\"\n}"
tomlFM = "+++\n date= \"12-04-06\"\n title= \"test toml\"\n+++"
tomlDraftFM = "+++\n draft= true\n date= \"12-04-06\"\n title=\"test toml\"\n+++"
yamlFM = "---\n date: \"12-04-06\"\n title: \"test yaml\"\n---"
yamlDraftFM = "---\n draft: true\n date: \"12-04-06\"\n title: \"test yaml\"\n---"
)
func TestUndraftContent(t *testing.T) {
tests := []struct {
fm string
expectedErr string
}{
{jsonFM, "not a Draft: nothing was done"},
{jsonDraftFM, ""},
{tomlFM, "not a Draft: nothing was done"},
{tomlDraftFM, ""},
{yamlFM, "not a Draft: nothing was done"},
{yamlDraftFM, ""},
}
for i, test := range tests {
r := bytes.NewReader([]byte(test.fm))
p, _ := parser.ReadFrom(r)
res, err := undraftContent(p)
if test.expectedErr != "" {
if err == nil {
t.Errorf("[%d] Expected error, got none", i)
continue
}
if err.Error() != test.expectedErr {
t.Errorf("[%d] Expected %q, got %q", i, test.expectedErr, err)
continue
}
} else {
r = bytes.NewReader(res.Bytes())
p, _ = parser.ReadFrom(r)
meta, err := p.Metadata()
if err != nil {
t.Errorf("[%d] unexpected error %q", i, err)
continue
}
for k, v := range meta.(map[string]interface{}) {
if k == "draft" {
if v.(bool) {
t.Errorf("[%d] Expected %q to be \"false\", got \"true\"", i, k)
continue
}
}
if k == "date" {
if !strings.HasPrefix(v.(string), time.Now().Format("2006-01-02")) {
t.Errorf("[%d] Expected %v to start with %v", i, v.(string), time.Now().Format("2006-01-02"))
}
}
}
}
}
}
commands/version.go
-80
View File
@@ -1,80 +0,0 @@
// Copyright 2015 The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package commands
import (
"os"
"path/filepath"
"runtime"
"strings"
"time"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/hugolib"
"github.com/kardianos/osext"
"github.com/spf13/cobra"
jww "github.com/spf13/jwalterweatherman"
)
var versionCmd = &cobra.Command{
Use: "version",
Short: "Print the version number of Hugo",
Long: `All software has versions. This is Hugo's.`,
RunE: func(cmd *cobra.Command, args []string) error {
printHugoVersion()
return nil
},
}
func printHugoVersion() {
if hugolib.BuildDate == "" {
setBuildDate() // set the build date from executable's mdate
} else {
formatBuildDate() // format the compile time
}
if hugolib.CommitHash == "" {
jww.FEEDBACK.Printf("Hugo Static Site Generator v%s %s/%s BuildDate: %s\n", helpers.CurrentHugoVersion, runtime.GOOS, runtime.GOARCH, hugolib.BuildDate)
} else {
jww.FEEDBACK.Printf("Hugo Static Site Generator v%s-%s %s/%s BuildDate: %s\n", helpers.CurrentHugoVersion, strings.ToUpper(hugolib.CommitHash), runtime.GOOS, runtime.GOARCH, hugolib.BuildDate)
}
}
// setBuildDate checks the ModTime of the Hugo executable and returns it as a
// formatted string. This assumes that the executable name is Hugo, if it does
// not exist, an empty string will be returned. This is only called if the
// hugolib.BuildDate wasn't set during compile time.
//
// osext is used for cross-platform.
func setBuildDate() {
fname, _ := osext.Executable()
dir, err := filepath.Abs(filepath.Dir(fname))
if err != nil {
jww.ERROR.Println(err)
return
}
fi, err := os.Lstat(filepath.Join(dir, filepath.Base(fname)))
if err != nil {
jww.ERROR.Println(err)
return
}
t := fi.ModTime()
hugolib.BuildDate = t.Format(time.RFC3339)
}
// formatBuildDate formats the hugolib.BuildDate according to the value in
// .Params.DateFormat, if it's set.
func formatBuildDate() {
t, _ := time.Parse("2006-01-02T15:04:05-0700", hugolib.BuildDate)
hugolib.BuildDate = t.Format(time.RFC3339)
}
config.toml
+135
View File
@@ -0,0 +1,135 @@
title = "Hugo: A Fast and Flexible Website Generator"
baseurl = "http://gohugo.io/"
MetaDataFormat = "yaml"
pluralizeListTitles = false
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
[blackfriday]
plainIDAnchors = true
[outputs]
home = [ "HTML", "RSS", "REDIR" ]
[mediaTypes]
[mediaTypes."text/netlify"]
suffix = ""
delimiter = ""
[outputFormats]
[outputFormats.REDIR]
mediatype = "text/netlify"
baseName = "_redirects"
isPlainText = true
notAlternative = true
[params]
description = "Documentation of Hugo, a fast and flexible static site generator built with love by spf13, bep and friends in Go"
author = "Steve Francia (spf13) and friends"
release = "0.25-DEV"
[taxonomies]
tag = "tags"
group = "groups"
[[menu.main]]
name = "Download Hugo"
pre = "<i class='fa fa-download'></i>"
url = "https://github.com/gohugoio/hugo/releases"
weight = -200
[[menu.main]]
name = "Site Showcase"
pre = "<i class='fa fa-cubes'></i>"
url = "/showcase/"
weight = -180
[[menu.main]]
name = "Theme Showcase"
pre = "<i class='fa fa-puzzle-piece'></i>"
url = "http://themes.gohugo.io"
weight = -170
[[menu.main]]
name = "Press & Articles"
pre = "<i class='fa fa-bullhorn'></i>"
url = "/community/press/"
weight = -160
[[menu.main]]
name = "Discuss Hugo"
pre = "<i class='fa fa-comments'></i>"
url = "https://discourse.gohugo.io/"
weight = -150
[[menu.main]]
name = "About Hugo"
identifier = "about"
pre = "<i class='fa fa-heart'></i>"
weight = -110
[[menu.main]]
name = "Release Notes"
url = "/release-notes/"
pre = "<i class='fa fa-newspaper-o'></i>"
weight = -111
[[menu.main]]
name = "Getting Started"
identifier = "getting started"
pre = "<i class='fa fa-road'></i>"
weight = -100
[[menu.main]]
name = "Content"
identifier = "content"
pre = "<i class='fa fa-file-text'></i>"
weight = -90
[[menu.main]]
name = "Themes"
identifier = "themes"
pre = "<i class='fa fa-desktop'></i>"
weight = -85
[[menu.main]]
parent = "themes"
name = "Theme Showcase"
url = "http://themes.gohugo.io"
weight = -170
[[menu.main]]
name = "Templates"
identifier = "layout"
pre = "<i class='fa fa-columns'></i>"
weight = -80
[[menu.main]]
name = "Taxonomies"
identifier = "taxonomy"
pre = "<i class='fa fa-tags'></i>"
weight = -70
[[menu.main]]
name = "Extras"
identifier = "extras"
pre = "<i class='fa fa-gift'></i>"
weight = -60
[[menu.main]]
name = "Community"
identifier = "community"
pre = "<i class='fa fa-group'></i>"
weight = -50
[[menu.main]]
parent = "community"
name = "Discussion Forum"
url = "https://discourse.gohugo.io/"
weight = 150
[[menu.main]]
name = "Tutorials"
identifier = "tutorials"
pre = "<i class='fa fa-book'></i>"
weight = -40
[[menu.main]]
name = "Troubleshooting"
identifier = "troubleshooting"
pre = "<i class='fa fa-wrench'></i>"
weight = -30
[[menu.main]]
name = "Tools"
url = "/tools/"
pre = "<i class='fa fa-cogs'></i>"
weight = -25
[[menu.main]]
name = "Hugo Cmd Reference"
identifier = "commands"
pre = "<i class='fa fa-space-shuttle'></i>"
weight = -20
url = "/commands/"
config/configProvider.go
-26
View File
@@ -1,26 +0,0 @@
// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package config
// Provider provides the configuration settings for Hugo.
type Provider interface {
GetString(key string) string
GetInt(key string) int
GetBool(key string) bool
GetStringMap(key string) map[string]interface{}
GetStringMapString(key string) map[string]string
Get(key string) interface{}
Set(key string, value interface{})
IsSet(key string) bool
}
content/commands/hugo.md
+80
View File
@@ -0,0 +1,80 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo"
slug: hugo
url: /commands/hugo/
---
## hugo
hugo builds your site
### Synopsis
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
Complete documentation is available at http://gohugo.io/.
```
hugo [flags]
```
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml)
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disable404 do not render 404 page
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
--disableRSS do not build RSS files
--disableSitemap do not build Sitemap file
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
-h, --help help for hugo
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--pluralizeListTitles pluralize titles in lists using inflect (default true)
--preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--quiet build in quiet mode
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--uglyURLs if true, use /filename.html instead of /filename/
-v, --verbose verbose output
--verboseLog verbose logging
-w, --watch watch filesystem for changes and recreate as needed
```
### SEE ALSO
* [hugo benchmark](/commands/hugo_benchmark/) - Benchmark Hugo by building a site a number of times.
* [hugo check](/commands/hugo_check/) - Contains some verification checks
* [hugo config](/commands/hugo_config/) - Print the site configuration
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
* [hugo import](/commands/hugo_import/) - Import your site from others.
* [hugo list](/commands/hugo_list/) - Listing out various types of content
* [hugo new](/commands/hugo_new/) - Create new content for your site
* [hugo server](/commands/hugo_server/) - A high performance webserver
* [hugo undraft](/commands/hugo_undraft/) - Undraft changes the content's draft status from 'True' to 'False'
* [hugo version](/commands/hugo_version/) - Print the version number of Hugo
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_benchmark.md
+72
View File
@@ -0,0 +1,72 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo benchmark"
slug: hugo_benchmark
url: /commands/hugo_benchmark/
---
## hugo benchmark
Benchmark Hugo by building a site a number of times.
### Synopsis
Hugo can build a site many times over and analyze the running process
creating a benchmark.
```
hugo benchmark [flags]
```
### Options
```
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-n, --count int number of times to build the site (default 13)
--cpuprofile string path/filename for the CPU profile file
-d, --destination string filesystem path to write files to
--disable404 do not render 404 page
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
--disableRSS do not build RSS files
--disableSitemap do not build Sitemap file
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
-h, --help help for benchmark
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--memprofile string path/filename for the memory profile file
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--pluralizeListTitles pluralize titles in lists using inflect (default true)
--preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--renderToMemory render to memory (only useful for benchmark testing)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--uglyURLs if true, use /filename.html instead of /filename/
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_check.md
+37
View File
@@ -0,0 +1,37 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo check"
slug: hugo_check
url: /commands/hugo_check/
---
## hugo check
Contains some verification checks
### Synopsis
Contains some verification checks
### Options
```
-h, --help help for check
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_check_ulimit.md
+41
View File
@@ -0,0 +1,41 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo check ulimit"
slug: hugo_check_ulimit
url: /commands/hugo_check_ulimit/
---
## hugo check ulimit
Check system ulimit settings
### Synopsis
Hugo will inspect the current ulimit settings on the system.
This is primarily to ensure that Hugo can watch enough files on some OSs
```
hugo check ulimit [flags]
```
### Options
```
-h, --help help for ulimit
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo check](/commands/hugo_check/) - Contains some verification checks
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_config.md
+40
View File
@@ -0,0 +1,40 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo config"
slug: hugo_config
url: /commands/hugo_config/
---
## hugo config
Print the site configuration
### Synopsis
Print the site configuration, both default and custom settings.
```
hugo config [flags]
```
### Options
```
-h, --help help for config
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_convert.md
+44
View File
@@ -0,0 +1,44 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo convert"
slug: hugo_convert
url: /commands/hugo_convert/
---
## hugo convert
Convert your content to different formats
### Synopsis
Convert your content (e.g. front matter) to different formats.
See convert's subcommands toJSON, toTOML and toYAML for more information.
### Options
```
-h, --help help for convert
-o, --output string filesystem path to write files to
-s, --source string filesystem path to read files relative from
--unsafe enable less safe operations, please backup first
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON
* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_convert_toJSON.md
+44
View File
@@ -0,0 +1,44 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo convert toJSON"
slug: hugo_convert_toJSON
url: /commands/hugo_convert_tojson/
---
## hugo convert toJSON
Convert front matter to JSON
### Synopsis
toJSON converts all front matter in the content directory
to use JSON for the front matter.
```
hugo convert toJSON [flags]
```
### Options
```
-h, --help help for toJSON
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_convert_toTOML.md
+44
View File
@@ -0,0 +1,44 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo convert toTOML"
slug: hugo_convert_toTOML
url: /commands/hugo_convert_totoml/
---
## hugo convert toTOML
Convert front matter to TOML
### Synopsis
toTOML converts all front matter in the content directory
to use TOML for the front matter.
```
hugo convert toTOML [flags]
```
### Options
```
-h, --help help for toTOML
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_convert_toYAML.md
+44
View File
@@ -0,0 +1,44 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo convert toYAML"
slug: hugo_convert_toYAML
url: /commands/hugo_convert_toyaml/
---
## hugo convert toYAML
Convert front matter to YAML
### Synopsis
toYAML converts all front matter in the content directory
to use YAML for the front matter.
```
hugo convert toYAML [flags]
```
### Options
```
-h, --help help for toYAML
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
--unsafe enable less safe operations, please backup first
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_env.md
+40
View File
@@ -0,0 +1,40 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo env"
slug: hugo_env
url: /commands/hugo_env/
---
## hugo env
Print Hugo version and environment info
### Synopsis
Print Hugo version and environment info. This is useful in Hugo bug reports.
```
hugo env [flags]
```
### Options
```
-h, --help help for env
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_gen.md
+39
View File
@@ -0,0 +1,39 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo gen"
slug: hugo_gen
url: /commands/hugo_gen/
---
## hugo gen
A collection of several useful generators.
### Synopsis
A collection of several useful generators.
### Options
```
-h, --help help for gen
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo gen autocomplete](/commands/hugo_gen_autocomplete/) - Generate shell autocompletion script for Hugo
* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI.
* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_gen_autocomplete.md
+58
View File
@@ -0,0 +1,58 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo gen autocomplete"
slug: hugo_gen_autocomplete
url: /commands/hugo_gen_autocomplete/
---
## hugo gen autocomplete
Generate shell autocompletion script for Hugo
### Synopsis
Generates a shell autocompletion script for Hugo.
NOTE: The current version supports Bash only.
This should work for *nix systems with Bash installed.
By default, the file is written directly to /etc/bash_completion.d
for convenience, and the command may need superuser rights, e.g.:
$ sudo hugo gen autocomplete
Add `--completionfile=/path/to/file` flag to set alternative
file-path and name.
Logout and in again to reload the completion scripts,
or just source them in directly:
$ . /etc/bash_completion
```
hugo gen autocomplete [flags]
```
### Options
```
--completionfile string autocompletion file (default "/etc/bash_completion.d/hugo.sh")
-h, --help help for autocomplete
--type string autocompletion type (currently only bash supported) (default "bash")
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_gen_doc.md
+47
View File
@@ -0,0 +1,47 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo gen doc"
slug: hugo_gen_doc
url: /commands/hugo_gen_doc/
---
## hugo gen doc
Generate Markdown documentation for the Hugo CLI.
### Synopsis
Generate Markdown documentation for the Hugo CLI.
This command is, mostly, used to create up-to-date documentation
of Hugo's command-line interface for http://gohugo.io/.
It creates one Markdown file per command with front matter suitable
for rendering in Hugo.
```
hugo gen doc [flags]
```
### Options
```
--dir string the directory to write the doc. (default "/tmp/hugodoc/")
-h, --help help for doc
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_gen_man.md
+43
View File
@@ -0,0 +1,43 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo gen man"
slug: hugo_gen_man
url: /commands/hugo_gen_man/
---
## hugo gen man
Generate man pages for the Hugo CLI
### Synopsis
This command automatically generates up-to-date man pages of Hugo's
command-line interface. By default, it creates the man page files
in the "man" directory under the current directory.
```
hugo gen man [flags]
```
### Options
```
--dir string the directory to write the man pages. (default "man/")
-h, --help help for man
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_import.md
+39
View File
@@ -0,0 +1,39 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo import"
slug: hugo_import
url: /commands/hugo_import/
---
## hugo import
Import your site from others.
### Synopsis
Import your site from other web site generators like Jekyll.
Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
### Options
```
-h, --help help for import
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_import_jekyll.md
+43
View File
@@ -0,0 +1,43 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo import jekyll"
slug: hugo_import_jekyll
url: /commands/hugo_import_jekyll/
---
## hugo import jekyll
hugo import from Jekyll
### Synopsis
hugo import from Jekyll.
Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
```
hugo import jekyll [flags]
```
### Options
```
--force allow import into non-empty target directory
-h, --help help for jekyll
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo import](/commands/hugo_import/) - Import your site from others.
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_list.md
+42
View File
@@ -0,0 +1,42 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo list"
slug: hugo_list
url: /commands/hugo_list/
---
## hugo list
Listing out various types of content
### Synopsis
Listing out various types of content.
List requires a subcommand, e.g. `hugo list drafts`.
### Options
```
-h, --help help for list
-s, --source string filesystem path to read files relative from
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts
* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_list_drafts.md
+41
View File
@@ -0,0 +1,41 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo list drafts"
slug: hugo_list_drafts
url: /commands/hugo_list_drafts/
---
## hugo list drafts
List all drafts
### Synopsis
List all of the drafts in your content directory.
```
hugo list drafts [flags]
```
### Options
```
-h, --help help for drafts
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_list_expired.md
+42
View File
@@ -0,0 +1,42 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo list expired"
slug: hugo_list_expired
url: /commands/hugo_list_expired/
---
## hugo list expired
List all posts already expired
### Synopsis
List all of the posts in your content directory which has already
expired.
```
hugo list expired [flags]
```
### Options
```
-h, --help help for expired
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_list_future.md
+42
View File
@@ -0,0 +1,42 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo list future"
slug: hugo_list_future
url: /commands/hugo_list_future/
---
## hugo list future
List all posts dated in the future
### Synopsis
List all of the posts in your content directory which will be
posted in the future.
```
hugo list future [flags]
```
### Options
```
-h, --help help for future
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_new.md
+50
View File
@@ -0,0 +1,50 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo new"
slug: hugo_new
url: /commands/hugo_new/
---
## hugo new
Create new content for your site
### Synopsis
Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.
You can also specify the kind with `-k KIND`.
If archetypes are provided in your theme or site, they will be used.
```
hugo new [path] [flags]
```
### Options
```
--editor string edit new content with this editor, if provided
-h, --help help for new
-k, --kind string content type to create
-s, --source string filesystem path to read files relative from
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_new_site.md
+45
View File
@@ -0,0 +1,45 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo new site"
slug: hugo_new_site
url: /commands/hugo_new_site/
---
## hugo new site
Create a new site (skeleton)
### Synopsis
Create a new site in the provided directory.
The new site will have the correct structure, but no content or theme yet.
Use `hugo new [contentPath]` to create new content.
```
hugo new site [path] [flags]
```
### Options
```
--force init inside non-empty directory
-f, --format string config & frontmatter format (default "toml")
-h, --help help for site
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_new_theme.md
+44
View File
@@ -0,0 +1,44 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo new theme"
slug: hugo_new_theme
url: /commands/hugo_new_theme/
---
## hugo new theme
Create a new theme
### Synopsis
Create a new theme (skeleton) called [name] in the current directory.
New theme is a skeleton. Please add content to the touched files. Add your
name to the copyright line in the license and adjust the theme.toml file
as you see fit.
```
hugo new theme [name] [flags]
```
### Options
```
-h, --help help for theme
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-s, --source string filesystem path to read files relative from
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_server.md
+86
View File
@@ -0,0 +1,86 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo server"
slug: hugo_server
url: /commands/hugo_server/
---
## hugo server
A high performance webserver
### Synopsis
Hugo provides its own webserver which builds and serves the site.
While hugo server is high performance, it is a webserver with limited options.
Many run it in production, but the standard behavior is for people to use it
in development and use a more full featured server such as Nginx or Caddy.
'hugo server' will avoid writing the rendered and served content to disk,
preferring to store it in memory.
By default hugo will also watch your files for any changes you make and
automatically rebuild the site. It will then live reload any open browser pages
and push the latest content to them. As most Hugo sites are built in a fraction
of a second, you will be able to save and see your changes nearly instantly.
```
hugo server [flags]
```
### Options
```
--appendPort append port to baseURL (default true)
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
--bind string interface to which the server will bind (default "127.0.0.1")
-D, --buildDrafts include content marked as draft
-E, --buildExpired include expired content
-F, --buildFuture include content with publishdate in the future
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
--cleanDestinationDir remove files from destination not found in static directories
-c, --contentDir string filesystem path to content directory
-d, --destination string filesystem path to write files to
--disable404 do not render 404 page
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
--disableLiveReload watch without enabling live browser reload on rebuild
--disableRSS do not build RSS files
--disableSitemap do not build Sitemap file
--enableGitInfo add Git revision, date and author info to the pages
--forceSyncStatic copy all files when static is changed.
-h, --help help for server
--i18n-warnings print missing translations
--ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory
--meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms")
--memstats string log memory usage to this file
--noChmod don't sync permission mode of files
--noTimes don't sync modification time of files
--pluralizeListTitles pluralize titles in lists using inflect (default true)
-p, --port int port on which the server will listen (default 1313)
--preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
--renderToDisk render to Destination path (default is render to memory & serve from there)
-s, --source string filesystem path to read files relative from
--stepAnalysis display memory and timing of different steps of the program
-t, --theme string theme to use (located in /themes/THEMENAME/)
--themesDir string filesystem path to themes directory
--uglyURLs if true, use /filename.html instead of /filename/
-w, --watch watch filesystem for changes and recreate as needed (default true)
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_undraft.md
+42
View File
@@ -0,0 +1,42 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo undraft"
slug: hugo_undraft
url: /commands/hugo_undraft/
---
## hugo undraft
Undraft changes the content's draft status from 'True' to 'False'
### Synopsis
Undraft changes the content's draft status from 'True' to 'False'
and updates the date to the current date and time.
If the content's draft status is 'False', nothing is done.
```
hugo undraft path/to/content [flags]
```
### Options
```
-h, --help help for undraft
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/commands/hugo_version.md
+40
View File
@@ -0,0 +1,40 @@
---
date: 2017-06-22T21:51:29+02:00
title: "hugo version"
slug: hugo_version
url: /commands/hugo_version/
---
## hugo version
Print the version number of Hugo
### Synopsis
All software has versions. This is Hugo's.
```
hugo version [flags]
```
### Options
```
-h, --help help for version
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 22-Jun-2017
content/community/contributing.md
+111
View File
@@ -0,0 +1,111 @@
---
aliases:
- /doc/contributing/
- /meta/contributing/
lastmod: 2015-02-12
date: 2013-07-01
menu:
main:
parent: community
next: /tutorials/automated-deployments
prev: /community/mailing-list
title: Contributing to Hugo
weight: 30
---
All contributions to Hugo are welcome. Whether you want to scratch an itch or simply contribute to the project, feel free to pick something from the [roadmap]({{< relref "meta/roadmap.md" >}}) or contact the dev team via the [Forums](https://discourse.gohugo.io/) or [Gitter](https://gitter.im/gohugoio/hugo) about what may make sense to do next.
You should fork the project and make your changes. *We encourage pull requests to discuss code changes.*
When you're ready to create a pull request, be sure to:
* Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
* Run `go fmt`.
* Squash your commits into a single commit. `git rebase -i`. It's okay to force update your pull request.
* Run `make check` and ensure it succeeds. [Travis CI](https://travis-ci.org/gohugoio/hugo) and [Appveyor](https://ci.appveyor.com/project/gohugoio/hugo) will runs these checks and fail the build if `make check` fails.
## Contribution Overview
We wrote a [detailed guide]({{< relref "tutorials/how-to-contribute-to-hugo.md" >}}) for newcomers that guides you step by step to your first contribution. If you are more experienced, follow the guide below.
# Building from source
## Vendored Dependencies
Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.
Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.
You **must use govendor** to fetch Hugo's dependencies.
## Fetch the Sources
go get github.com/kardianos/govendor
govendor get github.com/gohugoio/hugo
## Running Hugo
cd $HOME/go/src/github.com/gohugoio/hugo
go run main.go
## Building Hugo
cd $HOME/go/src/github.com/gohugoio/hugo
make build
# or to install to $HOME/go/bin:
make install
# Showcase additions
You got your new website running and it's powered by Hugo? Great. You can add your website with a few steps to the [showcase](/showcase/).
First, make sure that you created a [fork](https://help.github.com/articles/fork-a-repo/) of Hugo on GitHub and cloned your fork on your local computer. Next, create a separate branch for your additions:
```
# You can choose a different descriptive branch name if you like
git checkout -b showcase-addition
```
Let's create a new document that contains some metadata of your homepage. Replace `example` in the following examples with something unique like the name of your website. Inside the terminal enter the following commands:
```
cd docs
hugo new showcase/example.md
```
You should find the new file at `content/showcase/example.md`. Open it in an editor. The file should contain a frontmatter with predefined variables like below:
```
---
date: 2016-02-12T21:01:18+01:00
description: ""
license: ""
licenseLink: ""
sitelink: http://spf13.com/
sourceLink: https://github.com/spf13/spf13.com
tags:
- personal
- blog
thumbnail: /img/spf13-tn.jpg
title: example
---
```
Add at least values for `sitelink`, `title`, `description` and a path for `thumbnail`.
Furthermore, we need to create the thumbnail of your website. **It's important that the thumbnail has the required dimensions of 600px by 400px.** Give your thumbnail a name like `example-tn.png`. Save it under `docs/static/img/`.
Check a last time that everything works as expected. Start Hugo's built-in server in order to inspect your local copy of the showcase in the browser:
hugo server
If everything looks fine, we are ready to commit your additions. For the sake of best practices, please make sure that your commit follows our [code contribution guideline](https://github.com/gohugoio/hugo#code-contribution-guideline).
git commit -m"docs: Add example.com to the showcase"
Last but not least, we're ready to create a [pull request](https://github.com/gohugoio/hugo/compare).
Don't forget to accept the contributor license agreement. Click on the yellow badge in the automatically added comment in the pull request.
[govendor]: https://github.com/kardianos/govendor
content/community/mailing-list.md
+51
View File
@@ -0,0 +1,51 @@
---
lastmod: 2015-05-25
date: 2013-07-01
menu:
main:
parent: community
next: /community/contributing
prev: /extras/urls
title: Mailing List
weight: 10
---
## Discussion Forum
Hugo has its own [discussion forum](https://discourse.gohugo.io/) powered by [Discourse](http://www.discourse.org/).
Please use this for all discussions, questions, etc.
### Twitter
Get the latest bite-sized news and themes from the Hugo community on Twitter by following [@gohugoio](http://twitter.com/gohugoio).
## Mailing List
Hugo has two mailing lists:
### Announcements
Very low traffic. Only releases will be emailed here.
https://groups.google.com/forum/#!forum/hugo-announce
### Discussion (Archive)
**This has been replaced with the [Hugo discussion forum](https://discourse.gohugo.io/).**
It is available for archival purposes.
https://groups.google.com/forum/#!forum/hugo-discuss
## Other Resources
### GoNuts
For general Go questions or discussion please refer to the Go mailing list.
https://groups.google.com/forum/#!forum/golang-nuts
### GitHub Issues
https://github.com/gohugoio/hugo/issues
content/community/press.md
+141
View File
@@ -0,0 +1,141 @@
---
lastmod: 2017-03-02
date: 2014-03-24T20:00:00Z
linktitle: Press
notoc: true
title: Press, Blogs and Media Coverage
weight: 20
---
### Help keep this list up to date
Know of a post, article or tutorial on Hugo? [Add it to this list](https://github.com/gohugoio/hugo/edit/master/docs/content/community/press.md).
## Press and Articles
Hugo has been featured in the following Blog Posts, Press and Media.
| Title | Author | Date |
| ------ | ------ | -----: |
| [Build, Test, And Deploy Statically Generated Websites With Hugo & CircleCI](https://circleci.com/blog/build-test-deploy-hugo-sites/)| Ricardo N Feliciano | 2017-05-31 |
| [Hugo Easy Gallery - Automagical PhotoSwipe image gallery with a one-line shortcode](https://www.liwen.id.au/heg/)| Li-Wen Yip | 2017-03-25 |
| [Hugo Tutorial: How to Build & Host a (Very Fast) Static E-Commerce Site](https://snipcart.com/blog/hugo-tutorial-static-site-ecommerce) | Snipcart | 2017-03-12 |
| [Automagical image gallery in Hugo with PhotoSwipe and jQuery](https://www.liwen.id.au/photoswipe/)| Li-Wen Yip | 2017-03-04 |
| [Adding Isso Comments to Hugo](https://stiobhart.net/2017-02-24-isso-comments/) | Stíobhart Matulevicz | 2017-02-24 |
| [Zero to HTTP/2 with AWS and Hugo](https://habd.as/zero-to-http-2-aws-hugo/) | Josh Habdas | 2017-02-16 |
| [How to Password Protect a Hugo Site](https://www.aerobatic.com/blog/password-protect-a-hugo-site/) | Aerobatic | 2017-02-19 |
| [Switching from Wordpress to Hugo](http://schnuddelhuddel.de/switching-from-wordpress-to-hugo/) | Mario Martelli | 2017-02-19 | ]
| [Deploy a Hugo site to Aerobatic with CircleCI ](https://www.aerobatic.com/blog/hugo-github-circleci/) | Aerobatic | 2017-02-14 |
| [NPM scripts for building and deploying Hugo site](https://www.aerobatic.com/blog/hugo-npm-buildtool-setup/) | Aerobatic | 2017-02-12 |
| [Getting started with Hugo and the plain-blog theme, on NearlyFreeSpeech.Net](https://www.penwatch.net/cms/get_started_plain_blog/) | Li-aung “Lewis” Yip | 2017-02-12 |
| [Build a Hugo site using Cloud9 IDE and host on App Engine](https://loyall.ch/lab/2017/01/build-a-static-website-with-cloud9-hugo-and-app-engine/)| Pascal Aubort | 2017-02-05 |
| [Hugo Continuous Deployment with Bitbucket Pipelines and Aerobatic](https://www.aerobatic.com/blog/hugo-bitbucket-pipelines/) | Aerobatic | 2017-02-04 |
| [How to use Firebase to host a Hugo site](https://www.m0d3rnc0ad.com/post/static-site-firebase/) | Andrew Cuga | 2017-02-04 |
| [A publishing workflow for teams using static site generators](https://www.keybits.net/post/publishing-workflow-for-teams-using-static-site-generators/) | Tom Atkins | 2017-01-02 |
| [How To Dynamically Use Google Fonts In A Hugo Website](https://stoned.io/web-development/hugo/How-To-Dynamically-Use-Google-Fonts-In-A-Hugo-Website/) | Hash Borgir | 2016-10-27 |
| [Embedding Facebook In A Hugo Template](https://stoned.io/web-development/hugo/Embedding-Facebook-In-A-Hugo-Template/) | Hash Borgir | 2016-10-22 |
| [通过 Gitlab-cl 将 Hugo blog 自动部署至 GitHub](https://zetaoyang.github.io/post/2016/10/17/gitlab-cl.html) <small>(Chinese, Continious integration)</small> | Zetao Yang | 2016-10-17 |
| [A Step-by-Step Guide: Hugo on Netlify](https://www.netlify.com/blog/2016/09/21/a-step-by-step-guide-hugo-on-netlify/) | Eli Williamson | 2016-09-21 |
| [Building our site: From Django & Wordpress to a static generator (Part I)](https://tryolabs.com/blog/2016/09/20/building-our-site-django-wordpress-to-static-part-i/) | Alan Descoins | 2016-09-20 |
| [Webseitenmaschine - Statische Websites mit Hugo erzeugen](http://www.heise.de/ct/ausgabe/2016-12-Statische-Websites-mit-Hugo-erzeugen-3211704.html) <small>(German, $)</small> | Christian Helmbold | 2016-05-27 |
| [Cómo hacer sitios web estáticos con Hugo y Go - Platzi](https://www.youtube.com/watch?v=qaXXpdiCHXE) <small>(Video tutorial)</small> | Verónica López | 2016-04-06 |
| [CDNOverview: A CDN comparison site made with Hugo](https://www.cloakfusion.com/cdnoverview-cdn-comparison-site-made-hugo/) | Thijs de Zoete | 2016-02-23 |
| [Hugo: A Modern WebSite Engine That Just Works](https://github.com/shekhargulati/52-technologies-in-2016/blob/master/07-hugo/README.md) | Shekhar Gulati | 2016-02-14 |
| [Minify Hugo Generated HTML](http://ratson.name/blog/minify-hugo-generated-html/) | Ratson | 2016-02-02 |
| [<span lang="ja">HugoのデプロイをWerckerからCircle CIに変更した</span> - log](http://log.deprode.net/logs/2016-01-17/) | Deprode | 2016-01-17 |
| [Static site generators: el futuro de las webs estáticas<br>(Hugo, Jekyll, Flask y otros)](http://sitelabs.es/static-site-generators-futuro-las-webs-estaticas/) | Eneko Sarasola | 2016-01-09 |
| [Writing a Lambda Function for Hugo](https://blog.jolexa.net/post/writing-a-lambda-function-for-hugo/) | Jeremy Olexa | 2016-01-01 |
| [Ein Blog mit Hugo erstellen - Tutorial](http://privat.albicker.org/tags/hugo.html) <small>(Deutsch/German)</small> | Bernhard Albicker | 2015-12-30 |
| [How to host Hugo static website generator on AWS Lambda](http://bezdelev.com/post/hugo-aws-lambda-static-website/) | Ilya Bezdelev | 2015-12-15 |
| [Migrating from Pelican to Hugo](http://www.softinio.com/post/migrating-from-pelican-to-hugo/) | Salar Rahmanian | 2015-11-29 |
| [Static Website Generators Reviewed: Jekyll, Middleman, Roots, Hugo](http://www.smashingmagazine.com/2015/11/static-website-generators-jekyll-middleman-roots-hugo-review/) | Mathias Biilmann Christensen | 2015-11-16 |
| [How To Deploy a Hugo Site to Production with Git Hooks on Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-deploy-a-hugo-site-to-production-with-git-hooks-on-ubuntu-14-04) | Justin Ellingwood | 2015-11-12 |
| [How To Install and Use Hugo, a Static Site Generator, on Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-hugo-a-static-site-generator-on-ubuntu-14-04) | Justin Ellingwood | 2015-11-09 |
| [Switching from Wordpress to Hugo](http://justinfx.com/2015/11/08/switching-from-wordpress-to-hugo/) | Justin Israel | 2015-11-08 |
| [Hands-on Experience with Hugo as a Static Site Generator](http://usersnap.com/blog/hands-on-experience-with-hugo-static-site-generator/) | Thomas Peham | 2015 -10-15 |
| [Statische Webseites mit Hugo erstellen/Vortrag mit Foliensatz (deutsch)](http://sfd.koelnerlinuxtreffen.de/2015/HaraldWeidner/) | Harald Weidner | 2015-09-19 |
| [Moving from WordPress to Hugo](http://abhipandey.com/2015/09/moving-to-hugo/) | Abhishek Pandey | 2015-09-15 |
| [<span lang="zh-CN">通过webhook将Hugo自动部署至GitHub Pages和GitCafe Pages</span> <small>(Automated&nbsp;deployment)</small>](http://blog.coderzh.com/2015/09/13/use-webhook-automated-deploy-hugo/) | CoderZh | 2015-09-13 |
| [<span lang="zh-CN">使用hugo搭建个人博客站点</span> <small>(Using Hugo to build a personal blog site)</small>](http://blog.coderzh.com/2015/08/29/hugo/) | CoderZh | 2015-08-29 |
| [Good-Bye Wordpress, Hello Hugo!](http://blog.arminhanisch.de/2015/08/blog-migration-zu-hugo/) <small>(German)</small> | Armin Hanisch | 2015-08-18 |
| [Générer votre site web statique avec Hugo <small>(Generate your static site with Hugo)<small>](http://www.linux-pratique.com/?p=191) | Benoît Benedetti | 2015-06-26 |
| [<span lang="ja">Hugo向けの新しいテーマを作った</span> <small>(I created a new theme for Hugo)<small>](https://yet.unresolved.xyz/blog/2016/10/03/how-to-make-of-hugo-theme/) | Daisuke Tsuji | 2015-06-20 |
| [Hugo - Gerando um site com conteúdo estático. (Portuguese Brazil)](http://blog.ffrizzo.com/posts/hugo/) | Fabiano Frizzo | 2015-06-02 |
| [An Introduction to Static Site Generators](http://davidwalsh.name/introduction-static-site-generators) | Eduardo Bouças | 2015-05-20 |
| [Hugo Still Rules](http://cheekycoder.com/2015/05/hugo-still-rules/) | Cheeky Coder | 2015-05-18 |
| [hugo - Static Site Generator](http://gscacco.github.io/post/hugo/) | G Scaccoio | 2015-05-04 |
| [<span lang="ja">WindowsでHugoを使う</span>](http://ureta.net/2015/05/hugo-on-windows/) | <span lang="ja">うれ太郎</span> | 2015-05-01 |
| [<span lang="ja">Hugoのshortcodesを用いてサイトにスライドなどを埋め込む</span>](http://blog.yucchiy.com/2015/04/29/hugo-shortcode/) | Yucchiy | 2015-04-29 |
| [<span lang="ja">HugoとCircleCIでGitHub PagesにBlogを公開してみたら超簡単だった</span>](http://hori-ryota.github.io/blog/create-blog-with-hugo-and-circleci/) | Hori Ryota | 2015-04-17 |
| [10 Best Static Site Generators](http://beebom.com/2015/04/best-static-site-generators) | Aniruddha Mysore | 2015-04-06 |
| [Goodbye WordPress; Hello Hugo](http://willwarren.com/2015/04/05/goodbye-wordpress-hello-hugo/) | Will Warren | 2015-04-05 |
| [Static Websites with Hugo on Google Cloud Storage](http://www.moxie.io/post/static-websites-with-hugo-on-google-cloud-storage/) | Moxie Input/Output | 2015-04-02 |
| [De nuevo iniciando un blog](https://alvarolizama.net/) | Alvaro Lizama | 2015-03-29 |
| [We moved our blog from Posthaven to Hugo after only three posts. Why?](http://blog.hypriot.com/post/moved-from-posthaven-to-hugo/) | Hypriot | 2015-03-27 |
| [Top Static Site Generators in 2015](http://superdevresources.com/static-site-generators-2015/) | Kanishk Kunal | 2015-03-12 |
| [Moving to Hugo](http://abiosoft.com/moving-to-hugo/) | Abiola Ibrahim | 2015-03-08 |
| [Migrating a blog (yes, this one!) from Wordpress to Hugo](http://justindunham.net/migrating-from-wordpress-to-hugo/) | Justin Dunham | 2015-02-13 |
| [<span lang="ja">blogをoctopressからHugoに乗り換えたメモ</span>](http://blog.jigyakkuma.org/2015/02/11/hugo/) | jigyakkuma | 2015-02-11 |
| [<span lang="ja">Hugoでブログをつくった</span>](http://porgy13.github.io/post/new-hugo-blog/) | porgy13 | 2015-02-07 |
| [<span lang="ja">Hugoにブログを移行した</span>](http://keichi.net/post/first/) | Keichi Takahashi | 2015-02-04 |
| [<span lang="zh-CN">Hugo静态网站生成器中文教程</span>](http://nanshu.wang/post/2015-01-31/) | Nanshu Wang | 2015-01-31 |
| [<span lang="ja">Hugo + GitHub Pages + Wercker CI = ¥0（無料）<br>でコマンド 1 発（自動化）でサイト<br>・ブログを公開・運営・分析・収益化</span>](http://qiita.com/yoheimuta/items/8a619cac356bed89a4c9) | Yohei Yoshimuta | 2015-01-31 |
| [Running Hugo websites on anynines](http://blog.anynines.com/running-hugo-websites-on-anynines/) | Julian Weber | 2015-01-30 |
| [MiddlemanからHugoへ移行した](http://re-dzine.net/2015/01/hugo/) | Haruki Konishi | 2015-01-21 |
| [WordPress から Hugo に乗り換えました](http://rakuishi.com/archives/wordpress-to-hugo/) | rakuishi | 2015-01-20 |
| [HUGOを使ってサイトを立ち上げる方法](http://qiita.com/syui/items/869538099551f24acbbf) | Syui | 2015-01-17 |
| [<span lang="ja">Jekyllが許されるのは小学生までだよね</span>](http://t32k.me/mol/log/hugo/) | Ishimoto Koji | 2015-01-16 |
| [Getting started with Hugo](http://anthonyfok.org/post/getting-started-with-hugo/) | Anthony Fok | 2015-01-12 |
| [<span lang="zh-CN">把这个博客静态化了</span> <small>(Migrate to Hugo)</small>](http://lich-eng.com/2015/01/03/migrate-to-hugo/)| Li Cheng | 2015-01-03 |
| [Porting my blog with Hugo](http://blog.srackham.com/posts/porting-my-blog-with-hugo/) | Stuart Rackham | 2014-12-30 |
| [Hugoを使ってみたときのメモ](http://machortz.github.io/posts/usinghugo/) | Machortz | 2014-12-29 |
| [OctopressからHugoへ移行した](http://deeeet.com/writing/2014/12/25/hugo/) | Taichi Nakashima | 2014-12-25 |
| [Migrating to Hugo From Octopress](http://nathanleclaire.com/blog/2014/12/22/migrating-to-hugo-from-octopress/) | Nathan LeClaire | 2014-12-22 |
| [Dynamic Pages with GoHugo.io](http://cyrillschumacher.com/2014/12/21/dynamic-pages-with-gohugo.io/) | Cyrill Schumacher | 2014-12-21 |
| [6 Static Blog Generators That Aren’t Jekyll](http://www.sitepoint.com/6-static-blog-generators-arent-jekyll/) | David Turnbull | 2014-12-08 |
| [Travel Blogging Setup](http://www.stou.dk/2014/11/travel-blogging-setup/) | Rasmus Stougaard | 2014-11-23 |
| [Hosting A Hugo Website Behind Nginx](http://www.bigbeeconsultants.co.uk/blog/hosting-hugo-website-behind-nginx) | Rick Beton | 2014-11-20 |
| [<span lang="zh-CN">使用Hugo搭建免费个人Blog</span> <small>(How to use Hugo)</small>](http://ulricqin.com/post/how-to-use-hugo/) | Ulric Qin <span lang="zh-CN">秦晓辉</span> | 2014-11-11 |
| [Built in Speed and Built for Speed by Hugo](http://cheekycoder.com/2014/10/built-for-speed-by-hugo/) | Cheeky Coder | 2014-10-30 |
| [Hugo para crear sitios web estáticos](http://www.webbizarro.com/noticias/1076/hugo-para-crear-sitios-web-estaticos/) | Web Bizarro | 2014-08-19 |
| [Going with hugo](http://www.markuseliasson.se/article/going-with-hugo/) | Markus Eliasson | 2014-08-18 |
| [Benchmarking Jekyll, Hugo and Wintersmith](http://fredrikloch.me/post/2014-08-12-Jekyll-and-its-alternatives-from-a-site-generation-point-of-view/) | Fredrik Loch | 2014-08-12 |
| [Goodbye Octopress, Hello Hugo!](http://andreimihu.com/blog/2014/08/11/goodbye-octopress-hello-hugo/) | Andrei Mihu | 2014-08-11 |
| [Beautiful sites for Open Source projects](http://beautifulopen.com/2014/08/09/hugo/) | Beautiful Open | 2014-08-09 |
| [Hugo: Beyond the Defaults](http://npf.io/2014/08/hugo-beyond-the-defaults/) | Nate Finch | 2014-08-08 |
| [First Impressions of Hugo](https://peteraba.com/blog/first-impressions-of-hugo/) | Peter Aba | 2014-06-06 |
| [New Site Workflow](http://vurt.co.uk/post/new_website/) | Giles Paterson | 2014-08-05 |
| [How I Learned to Stop Worrying and Love the (Static) Web](http://cognition.ca/post/about-hugo/) | Joshua McKenty | 2014-08-04 |
| [Hugo - Static Site Generator](http://kenwoo.io/blog/hugo---static-site-generator/) | Kenny Woo | 2014-08-03 |
| [Hugo Is Friggin' Awesome](http://npf.io/2014/08/hugo-is-awesome/) | Nate Finch | 2014-08-01 |
| [<span lang="zh-CN">再次搬家</span> <small>(Move from WordPress to Hugo)</small>](http://www.chingli.com/misc/move-from-wordpress-to-hugo/) | <span lang="zh-CN">青砾</span> (chingli) | 2014-07-12 |
| [Embedding Gists in Hugo](http://danmux.com/posts/embedded_gists/) | Dan Mull | 2014-07-05 |
| [An Introduction To Hugo](http://www.cirrushosting.com/web-hosting-blog/an-introduction-to-hugo/) | Dan Silber | 2014-07-01 |
| [Moving to Hugo](http://danmux.com/posts/hugo_based_blog/) | Dan Mull | 2014-05-29 |
| [<span lang="zh-CN">开源之静态站点生成器排行榜</span><br><small>(Leaderboard of open-source static website generators)</small>](http://code.csdn.net/news/2819909) | CSDN.net | 2014-05-23 |
| [Finally, a satisfying and effective blog setup](http://michaelwhatcott.com/now-powered-by-hugo/) | Michael Whatcott | 2014-05-20 |
| [Hugo from scratch](http://zackofalltrades.com/notes/2014/05/hugo-from-scratch/) | Zack Williams | 2014-05-18 |
| [Why I switched away from Jekyll](http://www.jakejanuzelli.com/why-I-switched-away-from-jekyll/) | Jake Januzelli | 2014-05-10 |
| [Welcome our new blog](http://blog.ninya.io/posts/welcome-our-new-blog/) | Ninya.io | 2014-04-11 |
| [Mission Not Accomplished](http://johnsto.co.uk/blog/mission-not-accomplished/) | Dave Johnston | 2014-04-03 |
| [Hugo - A Static Site Builder in Go](http://deepfriedcode.com/post/hugo/) | Deep Fried Code | 2014-03-30 |
| [Adventures in Angular Podcast](http://devchat.tv/adventures-in-angular/003-aia-gdes) | Matias Niemela | 2014-03-28 |
| [Hugo](http://bra.am/post/hugo/) | bra.am | 2014-03-23 |
| [Converting Blogger To Markdown](http://trishagee.github.io/project/atom-to-hugo/) | Trisha Gee | 2014-03-20 |
| [Moving to Hugo Static Web Pages](http://tepid.org/tech/hugo-web/) | Tobias Weingartner | 2014-03-16 |
| [New Blog Engine: Hugo](https://blog.afoolishmanifesto.com/posts/hugo/) | fREW Schmidt | 2014-03-15 |
| [Hugo + gulp.js = Huggle](http://ktmud.github.io/huggle/en/intro/) ([English](http://ktmud.github.io/huggle/en/intro/), [<span lang="zh-CN">中文</span>](http://ktmud.github.io/huggle/zh/intro/)) | Jesse Yang <span lang="zh-CN">杨建超</span> | 2014-03-08 |
| [Powered by Hugo](http://kieranhealy.org/blog/archives/2014/02/24/powered-by-hugo/) | Kieran Healy | 2014-02-24 |
| [<span lang="ja">静的サイトを素早く構築するために<br>GoLangで作られたジェネレータHugo</span>](http://hamasyou.com/blog/2014/02/21/hugo/)| <div lang="ja" style="line-height: 1.1;">Shogo Hamada<br>濱田章吾</div> | 2014-02-21 |
| [Latest Roundup of Useful Tools For Developers](http://codegeekz.com/latest-roundup-of-useful-tools-for-developers/) | CodeGeekz | 2014-02-13 |
| [Hugo: Static Site Generator written in Go](http://www.braveterry.com/2014/02/06/hugo-static-site-generator-written-in-go/) | Brave Terry | 2014-02-06 |
| [10 Useful HTML5 Tools for Web Designers and Developers](http://designdizzy.com/10-useful-html5-tools-for-web-designers-and-developers/) | Design Dizzy | 2014-02-04 |
| [Hugo – Fast, Flexible Static Site Generator](http://cube3x.com/hugo-fast-flexible-static-site-generator/) | Joby Joseph | 2014-01-18 |
| [Hugo: A new way to build static website](http://www.w3update.com/opensource/hugo-a-new-way-to-build-static-website.html) | w3update | 2014-01-17 |
| [Xaprb now uses Hugo](http://xaprb.com/blog/2014/01/15/using-hugo/) | Baron Schwartz | 2014-01-15 |
| [New jQuery Plugins And Resources That Web Designers Need](http://www.designyourway.net/blog/resources/new-jquery-plugins-and-resources-that-web-designers-need/) | Design Your Way | 2014-01-01 |
| [On Blog Construction](http://alexla.sh/post/on-blog-construction/) | Alexander Lash | 2013-12-27 |
| [Hugo](http://onethingwell.org/post/69070926608/hugo) | One Thing Well | 2013-12-05 |
| [In Praise Of Hugo](http://sound-guru.com/blog/post/hello-world/) | sound-guru.com | 2013-10-19 |
| [Hosting a blog on S3 and Cloudfront](http://www.danesparza.net/2013/07/hosting-a-blog-on-s3-and-cloudfront/) | Dan Esparza | 2013-07-24 |
content/content/archetypes.md
+330
View File
@@ -0,0 +1,330 @@
---
lastmod: 2016-10-01
date: 2014-05-14T02:13:50Z
menu:
main:
parent: content
next: /content/ordering
prev: /content/types
title: Archetypes
weight: 50
toc: true
---
Typically, each piece of content you create within a Hugo project will have [front matter](/content/front-matter/) that follows a consistent structure. If you write blog posts, for instance, you might use the following front matter for the vast majority of those posts:
```toml
+++
title = ""
date = ""
slug = ""
tags = [
""
]
categories = [
""
]
draft = true
+++
```
You can always add non-typical front matter to any piece of content, but since it takes extra work to develop a theme that handles unique metadata, consistency is simpler.
With this in mind, Hugo has a convenient feature known as *archetypes* that allows users to define default front matter for new pieces of content.
By using archetypes, we can:
1. **Save time**. Stop writing the same front matter over and over again.
2. **Avoid errors**. Reduce the odds of typos, improperly formatted syntax, and other simple mistakes.
3. **Focus on more important things**. Avoid having to remember all of the fields that need to be associated with each piece of content. (This is particularly important for larger projects with complex front matter and a variety of content types.)
Let's explore how they work.
## Built-in Archetypes
If you've been using Hugo for a while, there's a decent chance you've come across archetypes without even realizing it. This is because Hugo includes a basic, built-in archetype that is used by default whenever it generates a content file.
To see this in action, open the command line, navigate into your project's directory, and run the following command:
```bash
hugo new hello-world.md
```
This `hugo new` command creates a new content file inside the project's `content` directory — in this case, a file named `hello-world.md` — and if you open this file, you'll notice it contains the following front matter:
```toml
+++
date = "2017-05-31T15:18:11+10:00"
draft = true
title = "hello world"
+++
```
Here, we can see that three fields have been added to the document: a `title` field that is based on the file name we defined, a `draft` field that ensures this content won't be published by default, and a `date` field that is auto-populated with the current date and time in the [RFC 3339](https://stackoverflow.com/questions/522251/whats-the-difference-between-iso-8601-and-rfc-3339-date-formats) format.
This, in its most basic form, is an example of an archetype. To understand how useful they can be though, it's best if we create our own.
## Creating Archetypes
In this section, we're going to create an archetype that will override the built-in archetype, allowing us to define custom front matter that will be included in any content files that we generate with the `hugo new` command.
To achieve this, create a file named `default.md` inside the `archetypes` folder of a Hugo project. (If the folder doesn't exist, create it.)
Then, inside this file, define the following front matter:
```toml
+++
slug = ""
tags = []
categories = []
draft = true
+++
```
You'll notice that we haven't defined a `title` or `date` field. This is because Hugo will automatically add these fields to the beginning of the front matter. We do, however, need to define the `draft` field if we want it to exist in our front matter.
You'll also notice that we're writing the front matter in the TOML format. It's possible to define archetype front matter in other formats, but a setting needs to be changed in the configuration file for this to be possible. See the "[Archetype Formats](#archetype-formats)" section of this article for more details.
Next, run the following command:
```bash
hugo new my-archetype-example.md
```
This command will generate a file named `my-archetype-example.md` inside the `content` directory, and this file will contain the following output:
```toml
+++
categories = []
date = "2017-05-31T15:21:13+10:00"
draft = true
slug = ""
tags = []
title = "my archetype example"
+++
```
As we can see, the file contains the `title` and `date` property that Hugo created for us, along with the front matter that we defined in the `archetypes/default.md` file.
You'll also notice that the fields have been sorted into alphabetical order. This is an unintentional side-effect that stems from the underlying code libraries that Hugo relies upon. It is, however, [a known issue that is actively being discussed](https://github.com/gohugoio/hugo/issues/452).
## Section Archetypes
By creating the `archetypes/default.md` file, we've created a default archetype that is more useful than the built-in archetype, but since Hugo encourages us to [organize our content into sections](/content/sections/), each of which will likely have different front matter requirements, a "one-size-fits-all" archetype isn't necessarily the best approach.
To accommodate for this, Hugo allows us to create archetypes for each section of our project. This means, whenever we generate content for a certain section, the appropriate front matter for that section will be automatically included in the generated file.
To see this in action, create a "photo" section by creating a directory named "photo" inside the `content` directory.
Then create a file named `photo.md` inside the `archetypes` directory and include the following front matter inside this file:
```toml
+++
image_url = ""
camera = ""
lens = ""
aperture = ""
iso = ""
draft = true
+++
```
Here, the critical detail is that the `photo.md` file in the `archetypes` directory is named after the `photo` section that we just created. By sharing a name, Hugo can understand that there's a relationship between them.
Next, run the following command:
```bash
hugo new photo/my-pretty-cat.md
```
This command will generate a file named `my-pretty-cat.md` inside the `content/photo` directory, and this file will contain the following output:
```toml
+++
aperture = ""
camera = ""
date = "2017-05-31T15:25:18+10:00"
draft = true
image_url = ""
iso = ""
lens = ""
title = "my pretty cat"
+++
```
As we can see, the `title` and `date` fields are still included by Hugo, but the rest of the front matter is being generated from the `photo.md` archetype instead of the `default.md` archetype.
### Tip: Default Values
To make archetypes more useful, define default values for any fields that will always be set to a range of limited options. In the case of the `photo.md` archetype, for instance, you could include lists of the various cameras and lenses that you own:
```toml
+++
image_url = ""
camera = [
"Sony RX100 Mark IV",
"Canon 5D Mark III",
"iPhone 6S"
]
lens = [
"Canon EF 50mm f/1.8",
"Rokinon 14mm f/2.8"
]
aperture = ""
iso = ""
draft = true
+++
```
Then, after generating a content file, simply remove the values that aren't relevant. This saves you from typing out the same options over and over again while ensuring consistency in how they're written.
## Scaffolding Content
Archetypes aren't limited to defining default front matter. They can also be used to define a default structure for the body of Markdown documents.
For example, imagine creating a `review.md` archetype for the purpose of writing camera reviews. This is what the front matter for such an archetype might look like:
```toml
+++
manufacturer = ""
model = ""
price = ""
releaseDate = ""
rating = ""
+++
```
But reviews tend to follow strict formats and need to answer specific questions, and it's with these expectations of precise structure that archetypes can prove to be even more useful.
For the sake of writing reviews, for instance, we could define the structure of a review beneath the front matter of the `review.md` file:
```markdown
+++
manufacturer = ""
model = ""
price = ""
releaseDate = ""
rating = ""
+++
## Introduction
## Sample Photos
## Conclusion
```
Then, whenever we use the `hugo new` command to create a new review, not only will the default front matter be copied into the newly created Markdown document, but the body of the `review.md` archetype will also be copied.
To take this further though — and to ensure authors on multi-author websites are on the same page about how content should be written — we could include notes and reminders within the archetype:
```markdown
+++
manufacturer = ""
model = ""
price = ""
releaseDate = ""
rating = ""
+++
## Introduction
<!--
What is the selling point of the camera?
What has changed since last year's model?
Include a bullet-point list of key features.
-->
## Sample Photos
<!-- TODO: Take at least 12 photos in a variety of situations. -->
## Conclusion
<!--
Is this camera worth the money?
Does it accomplish what it set out to achieve?
Are there any specific groups of people who should/shouldn't buy it?
Would you recommend it to a friend?
Are there alternatives on the horizon?
-->
```
That way, each time we generate a new content file, we have a series of handy notes to push us closer to a piece of writing that's suitable for publishing.
(If you're wondering why the notes are wrapped in the HTML comment syntax, it's to ensure they won't appear inside the preview window of whatever Markdown editor the author happens to be using. They're not strictly necessary though.)
This is still a fairly simple example, but if your content usually contains a variety of components — headings, bullet-points, images, [short-codes](/extras/shortcodes/), etc — it's not hard to see the time-saving benefits of placing these components in the body of an archetype file.
## Theme Archetypes
Whenever you generate a content file with the `hugo new` command, Hugo will start by searching for archetypes in the `archetypes` directory, initially looking for an archetype that matches the content's section and falling-back on the `default.md` archetype (if one is present). If no archetypes are found in this directory, Hugo will continue its search in the `archetypes` directory of the currently active theme. In other words, it's possible for themes to come packaged with their own archetypes, ensuring that users of that theme format their content files with correctly structured front matter.
To allow Hugo to use archetypes from a theme, [that theme must be activated via the project's configuration file](/themes/usage/):
```toml
theme = "ThemeNameGoesHere"
```
If an archetype doesn't exist in the `archetypes` directory at the top-level of a project or inside the `archetypes` directory of an active theme, the built-in archetype will be used.
{{< figure src="/img/content/archetypes/archetype-hierarchy.png" alt="How Hugo Decides Which Archetype To Use" >}}
## Archetype Formats
By default, the `hugo new` command will generate front matter in the TOML format. This means, even if we define the front matter in our archetype files as YAML or JSON, it will be converted to the TOML format before it ends up in our content files.
Fortunately, this functionality can be overwritten.
Inside the project's configuration file, simply define a `metaDataFormat` property:
```toml
metaDataFormat = ""
```
Then set this property to any of the following values:
* toml
* yaml
* json
By defining this option, any front matter will be generated in your preferred format.
It's worth noting, however, that when generating front matter in the TOML format, you might encounter the following error:
```bash
Error: cannot convert type <nil> to TomlTree
```
This is because, to generate TOML, all of the fields in the front matter need to have a default value, even if that default value is just an empty string.
For example, this YAML would *not* successfully compile into the TOML format:
```yaml
---
slug:
tags:
categories:
draft:
---
```
But this YAML *would* successfully compile:
```yaml
---
slug: ""
tags:
-
categories:
-
draft: true
---
```
It's a subtle yet important detail to remember.
## Notes
* Prior to Hugo v0.13, some users received [an "EOF" error when using archetypes](https://github.com/gohugoio/hugo/issues/776), related to what text editor they used to create the archetype. As of Hugo v0.13, this error has been [resolved](https://github.com/gohugoio/hugo/pull/785).
content/content/example.md
+91
View File
@@ -0,0 +1,91 @@
---
aliases:
- /doc/example/
lastmod: 2015-12-23
date: 2013-07-01
linktitle: Example
menu:
main:
parent: content
prev: /content/multilingual
next: /content/using-index-md
notoc: true
title: Example Content File
weight: 70
---
Some things are better shown than explained. The following is a very basic example of a content file written in [Markdown](https://help.github.com/articles/github-flavored-markdown/):
**mysite/content/project/nitro.md → http://mysite.com/project/nitro.html**
With TOML front matter:
<pre><code class="language-toml">+++
date = "2013-06-21T11:27:27-04:00"
title = "Nitro: A quick and simple profiler for Go"
description = "Nitro is a simple profiler for your Golang applications"
tags = [ "Development", "Go", "profiling" ]
topics = [ "Development", "Go" ]
slug = "nitro"
project_url = "https://github.com/spf13/nitro"
+++
</code><code class="language-markdown"># Nitro
Quick and easy performance analyzer library for [Go](http://golang.org/).
## Overview
Nitro is a quick and easy performance analyzer library for Go.
It is useful for comparing A/B against different drafts of functions
or different functions.
## Implementing Nitro
Using Nitro is simple. First, use `go get` to install the latest version
of the library.
$ go get github.com/spf13/nitro
Next, include nitro in your application.
</code></pre>
You may also use the equivalent YAML front matter:
```yaml
---
lastmod: 2015-12-23
date: "2013-06-21T11:27:27-04:00"
title: "Nitro: A quick and simple profiler for Go"
description: "Nitro is a simple profiler for your Go lang applications"
tags: [ "Development", "Go", "profiling" ]
topics: [ "Development", "Go" ]
slug: "nitro"
project_url: "https://github.com/spf13/nitro"
---
```
`nitro.md` would be rendered as follows:
> # Nitro
>
> Quick and easy performance analyzer library for [Go](http://golang.org/).
>
> ## Overview
>
> Nitro is a quick and easy performance analyzer library for Go.
> It is useful for comparing A/B against different drafts of functions
> or different functions.
>
> ## Implementing Nitro
>
> Using Nitro is simple. First, use `go get` to install the latest version
> of the library.
>
> $ go get github.com/spf13/nitro
>
> Next, include nitro in your application.
The source `nitro.md` file is converted to HTML by the excellent
[Blackfriday](https://github.com/russross/blackfriday) Markdown processor,
which supports extended features found in the popular
[GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/).
content/content/front-matter.md
+119
View File
@@ -0,0 +1,119 @@
---
aliases:
- /doc/front-matter/
lastmod: 2015-12-23
date: 2013-07-01
menu:
main:
parent: content
next: /content/sections
prev: /content/organization
title: Front Matter
weight: 20
toc: true
---
The **front matter** is one of the features that gives Hugo its strength. It enables
you to include the meta data of the content right with it. Hugo supports a few
different formats, each with their own identifying tokens.
Supported formats:
* **[TOML][]**, identified by '`+++`'.
* **[YAML][]**, identified by '`---`'.
* **[JSON][]**, a single JSON object which is surrounded by '`{`' and '`}`', followed by a newline.
[TOML]: https://github.com/toml-lang/toml "Tom's Obvious, Minimal Language"
[YAML]: http://www.yaml.org/ "YAML Ain't Markup Language"
[JSON]: http://www.json.org/ "JavaScript Object Notation"
## TOML Example
<pre><code class="language-toml">+++
title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
date = "2012-04-06"
categories = [
"Development",
"VIM"
]
slug = "spf13-vim-3-0-release-and-new-website"
+++
</code><code class="language-markdown">Content of the file goes Here
</code></pre>
## YAML Example
```yaml
---
title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
lastmod: 2015-12-23
date: "2012-04-06"
categories:
- "Development"
- "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---
Content of the file goes Here
```
## JSON Example
```json
{
"title": "spf13-vim 3.0 release and new website",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
"tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
"date": "2012-04-06",
"categories": [
"Development",
"VIM"
],
"slug": "spf13-vim-3-0-release-and-new-website"
}
Content of the file goes Here
```
## Variables
There are a few predefined variables that Hugo is aware of and utilizes. The user can also create
any variable they want. These will be placed into the `.Params` variable available to the templates.
Field names are always normalized to lowercase (e.g. `camelCase: true` is available as `.Params.camelcase`).
### Required variables
* **title** The title for the content
* **description** The description for the content
* **date** The date the content will be sorted by
* **taxonomies** These will use the field name of the plural form of the index (see tags and categories above)
### Optional variables
* **aliases** An array of one or more aliases
(e.g. old published path of a renamed content)
that would be created to redirect to this content.
See [Aliases]({{< relref "extras/aliases.md" >}}) for details.
* **draft** If true, the content will not be rendered unless `hugo` is called with `--buildDrafts`
* **publishdate** If in the future, content will not be rendered unless `hugo` is called with `--buildFuture`
* **expirydate** Content already expired will not be rendered unless `hugo` is called with `--buildExpired`
* **type** The type of the content (will be derived from the directory automatically if unset)
* **isCJKLanguage** If true, explicitly treat the content as CJKLanguage (`.Summary` and `.WordCount` can work properly in CJKLanguage)
* **weight** Used for sorting
* **markup** *(Experimental)* Specify `"rst"` for reStructuredText (requires
`rst2html`) or `"md"` (default) for Markdown
* **slug** appears as tail of the url. It can be used to change the part of the url that is based on the filename.
* **url** The full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of the multilingual feature.
*If neither `slug` or `url` is present, the filename will be used.*
## Configure Blackfriday rendering
It's possible to set some options for Markdown rendering in the page's front matter as an override to the site wide configuration.
See [Configuration]({{< ref "overview/configuration.md#configure-blackfriday-rendering" >}}) for more.
content/content/markdown-extras.md
+49
View File
@@ -0,0 +1,49 @@
---
aliases:
- /doc/supported-formats/
lastmod: 2016-07-22
date: 2016-07-22
menu:
main:
parent: content
prev: /content/summaries
next: /content/multilingual
title: Markdown Extras
weight: 66
toc: false
---
Hugo provides some convenient markdown extensions.
## Task lists
Hugo supports GitHub styled task lists (TODO lists) for the Blackfriday renderer (md-files). See [Blackfriday config](/overview/configuration/#configure-blackfriday-rendering) for how to turn it off.
Example:
```markdown
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
```
Renders as:
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
And produces this HTML:
```html
<ul class="task-list">
<li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
<li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
<li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li>
<li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
</ul>
```
content/content/multilingual.md
+232
View File
@@ -0,0 +1,232 @@
---
date: 2016-01-02T21:21:00Z
menu:
main:
parent: content
prev: /content/markdown-extras
next: /content/example
title: Multilingual Mode
weight: 68
toc: true
---
Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). Define the available languages in a `Languages` section in your top-level `config.toml` (or equivalent).
Example:
```
DefaultContentLanguage = "en"
copyright = "Everything is mine"
[params.navigation]
help = "Help"
[Languages]
[Languages.en]
title = "My blog"
weight = 1
[Languages.en.params]
linkedin = "english-link"
[Languages.fr]
copyright = "Tout est à moi"
title = "Mon blog"
weight = 2
[Languages.fr.params]
linkedin = "lien-francais"
[Languages.fr.navigation]
help = "Aide"
```
Anything not defined in a `[Languages]` block will fall back to the global
value for that key (like `copyright` for the English (`en`) language in this example).
With the config above, all content, sitemap, RSS feeds, paginations
and taxonomy pages will be rendered below `/` in English (your default content language), and below `/fr` in French.
When working with params in frontmatter pages, omit the `params` in the key for the translation.
If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true` in your configuration.
Only the obvious non-global options can be overridden per language. Examples of global options are `BaseURL`, `BuildDrafts`, etc.
Taxonomies and Blackfriday configuration can also be set per language, example:
```
[Taxonomies]
tag = "tags"
[blackfriday]
angledQuotes = true
hrefTargetBlank = true
[Languages]
[Languages.en]
weight = 1
title = "English"
[Languages.en.blackfriday]
angledQuotes = false
[Languages.fr]
weight = 2
title = "Français"
[Languages.fr.Taxonomies]
plaque = "plaques"
```
### Translating your content
Translated articles are identified by the name of the content file.
Example of translated articles:
1. `/content/about.en.md`
2. `/content/about.fr.md`
You can also have:
1. `/content/about.md`
2. `/content/about.fr.md`
In which case the config variable `defaultContentLanguage` will be used to affect the default language `about.md`. This way, you can
slowly start to translate your current content without having to rename everything.
If left unspecified, the value for `defaultContentLanguage` defaults to `en`.
By having the same _base file name_, the content pieces are linked together as translated pieces.
If you need distinct URLs per language you can set the slug in the non-default language file. Just define the custom slug for the french translation in your `/content/about.fr.md` file:
```
---
slug: "a-propos"
---
```
You will get both `/about/` and `/a-propos/` URLs in your build, properly linked as translated pieces.
### Link to translated content
To create a list of links to translated content, use a template similar to this:
```
{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
{{ range .Translations }}
<li>
<a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
</li>
{{ end}}
</ul>
{{ end }}
```
The above can be put in a `partial` and included in any template, be it for a content page or the home page. It will not print anything if there are no translations for a given page, or if it is -- in the case of the home page, section listing etc. -- a site with only one language.
The above also uses the `i18n` func, see [Translation of strings](#translation-of-strings).
### Translation of strings
Hugo uses [go-i18n](https://github.com/nicksnyder/go-i18n) to support string translations. Follow the link to find tools to manage your translation workflows.
Translations are collected from the `themes/[name]/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to RFC 5646 with names such as `en-US.toml`, `fr.toml`, etc.
From within your templates, use the `i18n` function like this:
```
{{ i18n "home" }}
```
This uses a definition like this one in `i18n/en-US.toml`:
```
[home]
other = "Home"
```
Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
```
{{ i18n "wordCount" . }}
```
This uses a definition like this one in `i18n/en-US.toml`:
```
[wordCount]
other = "This article has {{ .WordCount }} words."
```
An example of singular and plural form:
```
[readingTime]
one = "One minute read"
other = "{{.Count}} minutes read"
```
And then in the template:
```
{{ i18n "readingTime" .ReadingTime }}
```
To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
```bash
hugo --i18n-warnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
### Menus
You can define your menus for each language independently. The [creation of a menu]({{< relref "extras/menus.md" >}}) works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
```toml
defaultContentLanguage = "en"
[languages.en]
weight = 0
languageName = "English"
[[languages.en.menu.main]]
url = "/"
name = "Home"
weight = 0
[languages.de]
weight = 10
languageName = "Deutsch"
[[languages.de.menu.main]]
url = "/"
name = "Startseite"
weight = 0
```
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version because it's the default content language that resides in the root directory.
```html
<ul>
{{- $currentPage := . -}}
{{ range .Site.Menus.main -}}
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
<a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
</li>
{{- end }}
</ul>
```
### Missing translations
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
While translating a Hugo site, it can be handy to have a visual indicator of missing translations. The `EnableMissingTranslationPlaceholders` config option will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
**Remember: Hugo will generate your website with these placeholders. It might not be suited for production environments.**
### Multilingual Themes support
To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there are more than one language, URLs must either come from the built-in `.Permalink` or `.URL`, be constructed with `relLangURL` or `absLangURL` template funcs -- or prefixed with `{{.LanguagePrefix }}`.
If there are more than one language defined, the`LanguagePrefix` variable will equal `"/en"` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string, so it is harmless for single-language sites.
content/content/ordering.md
+41
View File
@@ -0,0 +1,41 @@
---
lastmod: 2015-12-23
date: 2014-03-06
linktitle: Ordering
menu:
main:
parent: content
next: /content/summaries
prev: /content/archetypes
title: Ordering Content
weight: 60
---
Hugo provides you with all the flexibility you need to organize how your content is ordered.
By default, content is ordered by weight, then by date with the most
recent date first, but alternative sorting (by `title` and `linktitle`) is
also available. The order the content would appear is specified in
the [list template](/templates/list/).
_Both the `date` and `weight` fields are optional._
Unweighted pages appear at the end of the list. If no weights are provided (or
if weights are the same), `date` will be used to sort. If neither is provided,
content will be ordered based on how it's read off the disk, and no order is
guaranteed.
## Assigning weight to content
```toml
+++
weight = 4
title = "Three"
date = "2012-04-06"
+++
Front Matter with Ordered Pages 3
```
## Ordering Content Within Taxonomies
Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/).
content/content/organization.md
+175
View File
@@ -0,0 +1,175 @@
---
aliases:
- /doc/organization/
lastmod: 2015-09-27
date: 2013-07-01
linktitle: Organization
menu:
main:
parent: content
next: /content/supported-formats
prev: /overview/source-directory
title: Content Organization
weight: 10
toc: true
---
Hugo uses files (see [supported formats](/content/supported-formats/)) with headers commonly called the *front matter*. Hugo
respects the organization that you provide for your content to minimize any
extra configuration, though this can be overridden by additional configuration
in the front matter.
## Organization
In Hugo, the content should be arranged in the same way they are intended for
the rendered website. Without any additional configuration, the following will
just work. Hugo supports content nested at any level. The top level is special
in Hugo and is used as the [section](/content/sections/).
.
└── 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`**
.
└── 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
## Destinations
Hugo believes that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site. As displayed above, the organization of the source content will be
mirrored in the destination.
Notice that the first level `about/` page URL was created using a directory
named "about" with a single `_index.md` file inside. Find out more about `_index.md` specifically in [content for the homepage and other list pages](https://gohugo.io/overview/source-directory#content-for-home-page-and-other-list-pages).
There are times when one would need more control over their content. In these
cases, there are a variety of things that can be specified in the front matter
to determine the destination of a specific piece of content.
The following items are defined in order; latter items in the list will override
earlier settings.
### filename
This isn't in the front matter, but is the actual name of the file minus the
extension. This will be the name of the file in the destination.
### slug
Defined in the front matter, the `slug` can take the place of the filename for the
destination.
### filepath
The actual path to the file on disk. Destination will create the destination
with the same path. Includes [section](/content/sections/).
### section
`section` is determined by its location on disk and *cannot* be specified in the front matter. See [section](/content/sections/).
### type
`type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [type](/content/types/).
### path
`path` can be provided in the front matter. This will replace the actual
path to the file on disk. Destination will create the destination with the same
path. Includes [section](/content/sections/).
### url
A complete URL can be provided. This will override all the above as it pertains
to the end destination. This must be the path from the baseURL (starting with a "/").
When a `url` is provided, it will be used exactly. Using `url` will ignore the
`--uglyURLs` setting.
## Path breakdown in Hugo
### Content
. path slug
. ⊢-------^----⊣ ⊢------^-------⊣
content/extras/indexes/category-example/index.html
. section slug
. ⊢--^--⊣ ⊢------^-------⊣
content/extras/indexes/category-example/index.html
. section slug
. ⊢--^--⊣⊢--^--⊣
content/extras/indexes/index.html
### Destination
permalink
⊢--------------^-------------⊣
http://spf13.com/projects/hugo
baseURL section slug
⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣
http://spf13.com/projects/hugo
baseURL section slug
⊢-----^--------⊣ ⊢--^--⊣ ⊢--^--⊣
http://spf13.com/extras/indexes/example
baseURL path slug
⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣
http://spf13.com/extras/indexes/example
baseURL url
⊢-----^--------⊣ ⊢-----^-----⊣
http://spf13.com/projects/hugo
baseURL url
⊢-----^--------⊣ ⊢--------^-----------⊣
http://spf13.com/extras/indexes/example
**section** = which type the content is by default
* based on content location
* front matter overrides
**slug** = name.ext or name/
* based on content-name.md
* front matter overrides
**path** = section + path to file excluding slug
* based on path to content location
**url** = relative URL
* defined in front matter
* overrides all the above
content/content/sections.md
+54
View File
@@ -0,0 +1,54 @@
---
lastmod: 2015-12-23
date: 2013-07-01
menu:
main:
parent: content
next: /content/types
notoc: true
prev: /content/front-matter
title: Sections
weight: 30
---
Hugo believes that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site (see [Organization](/content/organization/)). Following this pattern Hugo
uses the top level of your content organization as **the Section**.
The following example site uses two sections, "post" and "quote".
{{< nohighlight >}}.
└── content
├── 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/
{{< /nohighlight >}}
## Section Lists
Hugo will automatically create pages for each section root that list all
of the content in that section. See [List Templates](/templates/list/)
for details on customizing the way they appear.
Section pages can also have a content file and frontmatter, see [Source Organization]({{< relref "overview/source-directory.md#content-for-home-page-and-other-list-pages" >}}).
## Sections and Types
By default everything created within a section will use the content type
that matches the section name.
Section defined in the front matter have the same impact.
To change the type of a given piece of content, simply define the type
in the front matter.
If a layout for a given type hasn't been provided, a default type template will
be used instead provided it exists.
content/content/summaries.md
+54
View File
@@ -0,0 +1,54 @@
---
lastmod: 2015-01-27
date: 2013-07-01
menu:
main:
parent: content
notoc: true
prev: /content/ordering
next: /content/markdown-extras
title: Summaries
weight: 65
---
With the use of the `.Summary` [page variable](/templates/variables/), Hugo can generate summaries of content to show snippets in summary views. The summary view snippets are automatically generated by Hugo. Where a piece of content is split for the content summary depends on whether the split is Hugo-defined or user-defined.
Content summaries may also provide links to the original content, usually in the form of a "Read More..." link, with the help of the `.RelPermalink` or `.Permalink` variable, as well as the `.Truncated` boolean variable to determine whether such "Read More..." link is necessary.
## Hugo-defined: automatic summary split
By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` variable, which you may use in your templates.
* Pros: Automatic, no additional work on your part.
* Cons: All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all lumped into one paragraph. Some people like it, but some people don't.
## User-defined: manual summary split:
Alternatively, you may add the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider[^1] (for org content, use <code># more</code>) where you want to split the article. Content prior to the summary divider will be used as that content's summary, and stored into the `.Summary` variable with all HTML formatting intact.
[^1]: The **summary divider** is also called "more tag", "excerpt separator", etc. in other literature.
* Pros: Freedom, precision, and improved rendering. All formatting is preserved.
* Cons: Need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or <code># more</code> for org content) in your content file. :-)
Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> (or <code># more</code> for org content) exactly, i.e. all lowercase with no whitespace, otherwise it would be treated as regular comment and ignored.
If there is nothing but spaces and newlines after the summary divider then `.Truncated` will be false.
## Showing Summaries
You can show content summaries with the following code. You could do this, for example, on a [list](/templates/list/) page.
{{ range first 10 .Data.Pages }}
<div class="summary">
<h4><a href="{{ .RelPermalink }}">{{ .Title }}</a></h4>
{{ .Summary }}
</div>
{{ if .Truncated }}
<div class="read-more-link">
<a href="{{ .RelPermalink }}">Read More…</a>
</div>
{{ end }}
{{ end }}
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.
content/content/supported-formats.md
+27
View File
@@ -0,0 +1,27 @@
---
aliases:
- /doc/supported-formats/
lastmod: 2015-08-01
date: 2015-08-01
menu:
main:
parent: content
next: /content/front-matter
prev: /content/organization
title: Supported Formats
weight: 15
toc: true
---
Since 0.14, Hugo has defined a new concept called _external helpers_. It means that you can write your content using Asciidoc[tor], reStructuredText or Org-Mode. If you have files with associated extensions ([details](https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65)), then Hugo will call external commands to generate the content (the exception being Org-Mode content, which is parsed natively).
This means that you will have to install the associated tool on your machine to be able to use those formats.
For example, for Asciidoc files, Hugo will try to call __asciidoctor__ or __asciidoc__ command.
To use those formats, just use the standard extension and the front matter exactly as you would do with natively supported _.md_ files.
Notes:
* as these are external commands, generation performance for that content will heavily depend on the performance of those external tools.
* this feature is still in early stage, hence feedback is even more welcome.
content/content/types.md
+80
View File
@@ -0,0 +1,80 @@
---
lastmod: 2015-09-28
date: 2013-07-01
linktitle: Types
menu:
main:
parent: content
next: /content/archetypes
prev: /content/sections
title: Content Types
weight: 40
toc: true
---
Hugo has full support for different types of content. A content type can have a
unique set of meta data, template and can be automatically created by the `hugo new`
command through using content [archetypes](/content/archetypes/).
A good example of when multiple types are needed is to look at [Tumblr](https://www.tumblr.com/). A piece
of content could be a photo, quote or post, each with different meta data and
rendered differently.
## Assigning a content type
Hugo assumes that your site will be organized into [sections](/content/sections/)
and each section will use the corresponding type. If you are taking advantage of
this, then each new piece of content you place into a section will automatically
inherit the type.
Alternatively, you can set the type in the meta data under the key "`type`".
## Creating new content of a specific type
Hugo has the ability to create a new content file and populate the front matter
with the data set corresponding to that type. Hugo does this by utilizing
[archetypes](/content/archetypes/).
To create a new piece of content, use:
hugo new relative/path/to/content.md
For example, if I wanted to create a new post inside the post section, I would type:
hugo new post/my-newest-post.md
## Defining a content type
Creating a new content type is easy in Hugo. You simply provide the templates and archetype
that the new type will use. You only need to define the templates, archetypes and/or views
unique to that content type. Hugo will fall back to using the general templates and default archetype
whenever a specific file is not present.
*Remember, all of the following are optional:*
### Create Type Directory
Create a directory with the name of the type in `/layouts`. Type is always singular. *E.g. `/layouts/post`*.
### Create single template
Create a file called `single.html` inside your directory. *E.g. `/layouts/post/single.html`*.
### Create list template
Create a file called `post.html` inside the section lists template directory, `/layouts/section`. *E.g. `/layouts/section/post.html`*.
### Create views
Many sites support rendering content in a few different ways, for
instance, a single page view and a summary view to be used when
displaying a [list of contents on a single page](/templates/list).
Hugo makes no assumptions here about how you want to display your
content, and will support as many different views of a content type
as your site requires. All that is required for these additional
views is that a template exists in each `/layouts/TYPE` directory
with the same name.
### Create a corresponding archetype
Create a file called <code><em>type</em>.md</code> in the `/archetypes` directory. *E.g. `/archetypes/post.md`*.
More details about archetypes can be found at the [archetypes docs](/content/archetypes/).
content/content/using-index-md.md
+118
View File
@@ -0,0 +1,118 @@
---
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 frontmatter 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 frontmatter 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 hierarchy found in the [Content - List Template](/templates/list/) docs.
3. The Home page, though technically a List page, can have [its 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 frontmatter and frontmatter can have markdown content - meaning \_index.md files are the way to _provide_ frontmatter 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 frontmatter 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 frontmatter/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/naive example of this would be:
```html
{{ partial "header.html" . }}
<main>
{{ .Content }}
{{ range .Paginator.Pages }}
{{ partial "summary.html" . }}
{{ end }}
{{ partial "pagination.html" . }}
</main>
{{ partial "sidebar.html" . }}
{{ partial "footer.html" . }}
```
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 organise an \_index.md file
To add content and frontmatter 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 frontmatter/content to the home page.
content/extras/aliases.md
+103
View File
@@ -0,0 +1,103 @@
---
aliases:
- /doc/redirects/
- /doc/alias/
- /doc/aliases/
lastmod: 2015-12-23
date: 2013-07-09
menu:
main:
parent: extras
next: /extras/analytics
prev: /taxonomies/methods
title: Aliases
---
For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
Luckily, redirects can be handled easily with _aliases_ in Hugo.
## Example
Given a post on your current Hugo site, with a path of:
``content/posts/my-awesome-blog-post.md``
... you create an "aliases" section in the frontmatter of your post, and add previous paths to that.
### TOML frontmatter
```toml
+++
...
aliases = [
"/posts/my-original-url/",
"/2010/01/01/even-earlier-url.html"
]
...
+++
```
### YAML frontmatter
```yaml
---
...
aliases:
- /posts/my-original-url/
- /2010/01/01/even-earlier-url.html
...
---
```
Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on.
## Important Behaviors
1. *Hugo makes no assumptions about aliases. They also don't change based
on your UglyURLs setting. You need to provide absolute path to your webroot
and the complete filename or directory.*
2. *Aliases are rendered prior to any content and will be overwritten by
any content with the same location.*
## Multilingual example
On [multilingual sites]({{< relref "content/multilingual.md" >}}), each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
In `/posts/my-new-post.es.md`:
```yaml
---
aliases:
- /es/posts/my-original-post/
---
```
## How Hugo Aliases Work
When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target.
Assuming a baseURL of `mysite.tld`, the contents of the html file will look something like:
```html
<!DOCTYPE html>
<html>
<head>
<title>http://mysite.tld/posts/my-original-url</title>
<link rel="canonical" href="http://mysite.tld/posts/my-original-url"/>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta http-equiv="refresh" content="0; url=http://mysite.tld/posts/my-original-url"/>
</head>
</html>
```
The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.
## Customizing
You may customize this alias page by creating an alias.html template in the
layouts folder of your site. In this case, the data passed to the template is
* Permalink - the link to the page being aliased
* Page - the Page data for the page being aliased
content/extras/analytics.md
+28
View File
@@ -0,0 +1,28 @@
---
date: 2016-02-06
linktitle: Analytics
menu:
main:
parent: extras
next: /extras/builders
prev: /extras/aliases
title: Analytics in Hugo
---
Hugo ships with prebuilt internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes.
## Configuring Google Analytics
Provide your tracking id in your configuration file, e.g. config.yaml.
googleAnalytics = "UA-123-45"
## Example
Include the internal template in your templates like so:
{{ template "_internal/google_analytics.html" . }}
For async include the async template:
{{ template "_internal/google_analytics_async.html" . }}
content/extras/builders.md
+56
View File
@@ -0,0 +1,56 @@
---
lastmod: 2015-12-24
date: 2014-05-26
linktitle: Builders
menu:
main:
parent: extras
next: /extras/comments
prev: /extras/analytics
title: Hugo Builders
---
Hugo provides the functionality to quickly get a site, theme or page
started.
## New Site
Want to get a site built quickly?
{{< nohighlight >}}$ hugo new site <i>path/to/site</i>
{{< /nohighlight >}}
Hugo will create all the needed directories and files to get started
quickly.
Hugo will only touch the files and create the directories (in the right
places), [configuration](/overview/configuration/) and content are up to
you... but luckily we have builders for content (see below).
## New Theme
Want to design a new theme?
$ hugo new theme THEME_NAME
Run from your working directory, this will create a new theme with all
the needed files in your themes directory. Hugo will provide you with a
license and theme.toml file with most of the work done for you.
Follow the [Theme Creation Guide](/themes/creation/) once the builder is
done.
## New Content
You will use this builder the most of all. Every time you want to create
a new piece of content, the content builder will get you started right.
Leveraging [content archetypes](/content/archetypes/) the content builder
will not only insert the current date and appropriate metadata, but it
will pre-populate values based on the content type.
$ hugo new relative/path/to/content
This assumes it is being run from your working directory and the content
path starts from your content directory. Now, Hugo watches your content directory by default and rebuilds your entire website if any change occurs.
content/extras/comments.md
+99
View File
@@ -0,0 +1,99 @@
---
lastmod: 2015-08-04
date: 2014-05-26
linktitle: Comments
menu:
main:
parent: extras
next: /extras/crossreferences
prev: /extras/builders
title: Comments in Hugo
---
As Hugo is a static site generator, the content produced is static and doesn’t interact with the users. The most common interaction people ask for is comment capability.
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to website via JavaScript.
Your theme may already support Disqus, but even it if doesn’t, it is easy to add.
# Disqus Support
## Adding Disqus to a template
Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear:
{{ template "_internal/disqus.html" . }}
## Configuring Disqus
That template requires you to set a single value in your site config file, e.g. config.yaml.
disqusShortname = "XYW"
Additionally, you can optionally set the following in the front matter
for a given piece of content:
* **disqus_identifier**
* **disqus_title**
* **disqus_url**
## Conditional Loading of Disqus Comments
Users have noticed that enabling Disqus comments when running the Hugo web server on localhost causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in your `partials` folder that looks like this:
```html
<div id="disqus_thread"></div>
<script type="text/javascript">
(function() {
// Don't ever inject Disqus on localhost--it creates unwanted
// discussions from 'localhost:1313' on your Disqus account...
if (window.location.hostname == "localhost")
return;
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
var disqus_shortname = '{{ .Site.DisqusShortname }}';
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
```
Notice that there is a simple `if` statement that detects when you are running on localhost and skips the initialization of the Disqus comment injection.
Now, reference the partial template from your page template:
{{ partial "disqus.html" . }}
# Alternatives
A few alternatives exist to [Disqus](https://disqus.com/):
* [txtpen](https://txtpen.com)
* [Discourse](http://www.discourse.org)
* [IntenseDebate](http://intensedebate.com/)
* [Livefyre](http://www.adobe.com/marketing-cloud/enterprise-content-management/ugc-content-platform.html)
* [Muut](http://muut.com/)
* [多说](http://duoshuo.com/) ([Duoshuo](http://duoshuo.com/), popular in China)
* [isso](http://posativ.org/isso/) (Self-hosted, Python)
* [Kaiju](https://github.com/spf13/kaiju)
## Kaiju
[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](http://spf13.com/) (Hugo’s author) to bring easy and fast real time discussions to the web.
Written using Go, Socket.io and MongoDB, it is very fast and easy to deploy.
It is in early development but shows promise. If you have interest, please help by contributing whether via a pull request, an issue or even just a tweet. Everything helps.
## txtpen
[txtpen](https://txtpen.com) adds highlighting an in-line commenting similar to Medium to your Hugo blog.
## Discourse
Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](https://discourse.gohugo.io).
content/extras/crossreferences.md
+153
View File
@@ -0,0 +1,153 @@
---
lastmod: 2015-12-23
date: 2014-11-25
menu:
main:
parent: extras
next: /extras/robots-txt
prev: /extras/comments
title: Cross-References
toc: true
---
Hugo makes it easy to link documents together with the `ref` and `relref` shortcodes. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`).
## Using `ref` and `relref`
```django
{{</* ref "document" */>}}
{{</* ref "#anchor" */>}}
{{</* ref "document#anchor" */>}}
{{</* relref "document" */>}}
{{</* relref "#anchor" */>}}
{{</* relref "document#anchor" */>}}
```
The single parameter to `ref` is a string with a content _document name_ (`about.md`), an in-document _anchor_ (`#who`), or both (`about.md#who`).
### Document Names
The _document name_ is the name of a document including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result.
{{</* relref "blog/post.md" */>}} ⇒ `/blog/post/`
{{</* relref "post.md" */>}} ⇒ `/blog/post/`
If you have multiple sections with the same filename, you should only use the relative path format, because the behaviour is _undefined_. So, if I also have a document `link/post.md`, the output of `ref` is unknown for `post.md`.
{{</* relref "blog/post.md" */>}} ⇒ `/blog/post/`
{{</* relref "post.md" */>}} ⇒ `/blog/post/` (maybe)
{{</* relref "post.md" */>}} ⇒ `/link/post/` (maybe)
{{</* relref "link/post.md" */>}} ⇒ `/link/post/`
A relative document name must *not* begin with a slash (`/`).
{{</* relref "/blog/post.md" */>}} ⇒ `""`
### Anchors
When an _anchor_ is provided by itself, the current page’s unique identifier will be appended; when an _anchor_ is provided with a document name, the found page's unique identifier will be appended.
{{</* relref "#who" */>}} ⇒ `#who:9decaf7`
{{</* relref "blog/post.md#who" */>}} ⇒ `/blog/post/#who:badcafe`
More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
### Examples
* `{{</* ref "blog/post.md" */>}}` ⇒ `http://1.com/blog/post/`
* `{{</* ref "post.md#tldr" */>}}` ⇒ `http://1.com/blog/post/#tldr:caffebad`
* `{{</* relref "post.md" */>}}` ⇒ `/blog/post/`
* `{{</* relref "blog/post.md#tldr" */>}}` ⇒ `/blog/post/#tldr:caffebad`
* `{{</* ref "#tldr" */>}}` ⇒ `#tldr:badcaffe`
* `{{</* relref "#tldr" */>}}` ⇒ `#tldr:badcaffe`
## Hugo Heading Anchors
When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`.
`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
{{</* relref "extras/crossreferences.md#hugo-heading-anchors" */>}}
/extras/crossreferences/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
> What follows is a deeper discussion of *why* and *how* Hugo generates heading anchors. It is not necessary to know this to use `ref` and `relref`, but it may be useful in understanding how some anchors may not match your expectations.
### How to Generate a Heading Anchor
Convert the text of the heading to lowercase.
Hugo: A Fast & Modern Static Web Engine
hugo: a fast & modern static web engine
Replace anything that isn't an ASCII letter (`a-z`) or number (`0-9`) with a dash (`-`).
hugo: a fast & modern static web engine
hugo--a-fast---modern-static-web-engine
Get rid of extra dashes.
hugo--a-fast---modern-static-web-engine
hugo-a-fast-modern-static-web-engine
You have just converting the text of a heading to a suitable anchor. If your document has unique heading text, all of the anchors will be unique, too.
#### Specifying Heading Anchors
You can also tell Hugo to use a particular heading anchor.
# Hugo: A Fast & Modern Static Web Engine {#hugo-main}
Hugo will use `hugo-main` as the heading anchor.
### What About Duplicate Heading Anchors?
The technique outlined above works well enough, but some documents have headings with identical text, like the [shortcodes](/extras/shortcodes/) page—there are three headings with the text "Example". You can specify heading anchors manually:
### Example {#example-1}
### Example {#example-2}
### Example {#example-3}
It’s easy to forget to do that all the time, and Hugo is smart enough to do it for you. It just adds `-x` to the end of each heading it has already seen.
* `### Example` ⇒ `example`
* `### Example` ⇒ `example-1`
* `### Example` ⇒ `example-2`
Sometimes it's a little harder, but Hugo can recover from those, too, by adding more suffixes:
* `# Heading` ⇒ `heading`
* `# Heading 1` ⇒ `heading-1`
* `# Heading` ⇒ `heading-1-1`
* `# Heading` ⇒ `heading-1-2`
* `# Heading 1` ⇒ `heading-2`
This can even affect specified heading anchors that come after a generated heading anchor.
* `# My Heading` ⇒ `my-heading`
* `# My Heading {#my-heading}` ⇒ `my-heading-1`
> This particular collision and override is unfortunate, but unavoidable because Hugo processes each heading for collision detection as it sees it during conversion.
This technique works well for documents rendered on individual pages, like blog posts. What about on Hugo list pages?
### Unique Heading Anchors in Lists
Hugo converts each document from Markdown independently. it doesn’t know that `blog/post.md` has an "Example" heading that will collide with the "Example" heading in `blog/post2.md`. Even if it did know this, the addition of `blog/post3.md` should not cause the anchors for the headings in the other blog posts to change.
Enter the document’s unique identifier. To prevent this sort of collision on
list pages, Hugo always appends the document's to a generated heading anchor.
So, the "Example" heading in `blog/post.md` actually turns into
`#example:81df004…`, and the "Example" heading in `blog/post2.md` actually
turns into `#example:8cf1599…`. All you have to know is the heading anchor that
was generated, not the document identifier; `ref` and `relref` take care of the
rest for you.
<a href='{{</* relref "blog/post.md#example" */>}}'>Post Example</a>
<a href='/blog/post.md#81df004…'>Post Example</a>
[Post Two Example]({{</* relref "blog/post2.md#example" */>}})
<a href='/blog/post2.md#8cf1599…'>Post Two Example</a>
Now you know.
content/extras/datadrivencontent.md
+142
View File
@@ -0,0 +1,142 @@
---
aliases:
- /doc/datadrivencontent/
lastmod: 2016-03-03
date: 2015-02-14
menu:
main:
parent: extras
next: /extras/gitinfo
prev: /extras/datafiles
title: Data-driven Content
toc: true
---
Data-driven content with a static site generator? Yes, it is possible!
In addition to the [data files](/extras/datafiles/) feature, we have also
implemented the feature "Data-driven Content", which lets you load
any [JSON](http://www.json.org/) or
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file
from nearly any resource.
"Data-driven Content" currently consists of two functions, `getJSON`
and `getCSV`, which are available in **all template files**.
## Implementation details
### Calling the functions with an URL
In any HTML template or Markdown document, call the functions like this:
{{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }}
or, if you use a prefix or postfix for the URL, the functions
accept [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }}
The separator for `getCSV` must be put in the first position and can only
be one character long.
All passed arguments will be joined to the final URL; for example:
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
will resolve internally to:
{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }}
Finally, you can range over an array. This example will output the
first 5 gists for a GitHub user:
<ul>
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
{{ range first 5 $gistJ }}
{{ if .public }}
<li><a href="{{ .html_url }}" target="_blank">{{ .description }}</a></li>
{{ end }}
{{ end }}
</ul>
### Example for CSV files
For `getCSV`, the one-character long separator must be placed in the
first position followed by the URL.
<table>
<thead>
<tr>
<th>Name</th>
<th>Position</th>
<th>Salary</th>
</tr>
</thead>
<tbody>
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
{{ $sep := "," }}
{{ range $i, $r := getCSV $sep $url }}
<tr>
<td>{{ index $r 0 }}</td>
<td>{{ index $r 1 }}</td>
<td>{{ index $r 2 }}</td>
</tr>
{{ end }}
</tbody>
</table>
The expression `{{index $r number}}` must be used to output the nth-column from
the current row.
### Caching of URLs
Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`.
The variable `$TMPDIR` will be resolved to your system-dependent
temporary directory.
With the command-line flag `--cacheDir`, you can specify any folder on
your system as a caching directory.
You can also set `cacheDir` in the main configuration file.
If you don't like caching at all, you can fully disable caching with the
command line flag `--ignoreCache`.
### Authentication when using REST URLs
Currently, you can only use those authentication methods that can
be put into an URL. [OAuth](http://en.wikipedia.org/wiki/OAuth) or
other authentication methods are not implemented.
### Loading local files
To load local files with the two functions `getJSON` and `getCSV`, the
source files must reside within Hugo's working directory. The file
extension does not matter but the content does.
It applies the same output logic as in the topic: *Calling the functions with an URL*.
## LiveReload
There is no chance to trigger a [LiveReload](/extras/livereload/) when
the content of an URL changes. However, when a local JSON/CSV file changes,
then a LiveReload will be triggered of course. Symlinks are not supported.
**URLs and LiveReload**: If you change any local file and the LiveReload
is triggered, Hugo will either read the URL content from the cache or, if
you have disabled the cache, Hugo will re-download the content.
This can create huge traffic and you may also reach API limits quickly.
As downloading of content takes a while, Hugo stops processing
your Markdown files until the content has been downloaded.
## Examples
- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
- GitHub Starred Repositories [in a posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
- More? Please tell us!
content/extras/datafiles.md
+106
View File
@@ -0,0 +1,106 @@
---
aliases:
- /doc/datafiles/
lastmod: 2015-08-04
date: 2015-01-22
menu:
main:
parent: extras
next: /extras/datadrivencontent
prev: /extras/robots-txt
title: Data Files
---
In addition to the [built-in variables](/templates/variables/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
**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`.
## The Data Folder
The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages - rather they're meant to supplement the content files. This feature can extend the content in case your frontmatter would grow immensely. Or perhaps you want to show a larger dataset in a template (see example below). In both cases it's a good idea to outsource the data in their own file.
These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`.
**The keys in this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).**
This is best explained with an example:
## Example: Jaco Pastorius' Solo Discography
[Jaco Pastorius](http://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example. [John Patitucci](http://en.wikipedia.org/wiki/John_Patitucci) is another bass giant.
The example below is a bit constructed, but it illustrates the flexibility of Data Files. It uses TOML as file format.
Given the files:
* `data/jazz/bass/jacopastorius.toml`
* `data/jazz/bass/johnpatitucci.toml`
`jacopastorius.toml` contains the content below, `johnpatitucci.toml` contains a similar list:
```
discography = [
"1974 – Modern American Music … Period! The Criteria Sessions",
"1974 – Jaco",
"1976 - Jaco Pastorius",
"1981 - Word of Mouth",
"1981 - The Birthday Concert (released in 1995)",
"1982 - Twins I & II (released in 1999)",
"1983 - Invitation",
"1986 - Broadway Blues (released in 1998)",
"1986 - Honestly Solo Live (released in 1990)",
"1986 - Live In Italy (released in 1991)",
"1986 - Heavy'n Jazz (released in 1992)",
"1991 - Live In New York City, Volumes 1-7.",
"1999 - Rare Collection (compilation)",
"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
"2007 - The Essential Jaco Pastorius (compilation)"
]
```
The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single bass player by adding the filename without the suffix, e.g. `.Site.Data.jazz.bass.jacopastorius`.
You can now render the list of recordings for all the bass players in a template:
```
{{ range $.Site.Data.jazz.bass }}
{{ partial "artist.html" . }}
{{ end }}
```
And then in `partial/artist.html`:
```
<ul>
{{ range .discography }}
<li>{{ . }}</li>
{{ end }}
</ul>
```
Discover a new favourite bass player? Just add another TOML-file.
## Example: Accessing named values in a Data File
Assuming you have the following YAML structure to your `User0123.yml` Data File located directly in `data/`
```
Name: User0123
"Short Description": "He is a **jolly good** fellow."
Achievements:
- "Can create a Key, Value list from Data File"
- "Learns Hugo"
- "Reads documentation"
```
To render the `Short Description` in your `layout` File following code is required.
```
<div>Short Description of {{.Site.Data.User0123.Name}}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
```
Note the use of the `markdownify` template function. This will send the description through the Blackfriday Markdown rendering engine.
content/extras/gitinfo.md
+50
View File
@@ -0,0 +1,50 @@
---
aliases:
- /doc/gitinfo/
lastmod: 2016-12-11
date: 2016-12-11
menu:
main:
parent: extras
next: /extras/livereload
prev: /extras/datadrivencontent
title: GitInfo
---
Hugo provides a way to integrate Git data into your site.
## Prerequisites
1. The Hugo site must be in a Git-enabled directory.
1. The Git executable must be installed and in your system `PATH`.
1. Enable the GitInfo feature in Hugo by using `--enableGitInfo` on the command
line or by setting `enableGitInfo` to `true` in your site configuration.
## The GitInfo Object
The `GitInfo` object contains the following fields:
AbbreviatedHash
: abbreviated commit hash, e.g. `866cbcc`
AuthorName
: author name, respecting `.mailmap`
AuthorEmail
: author email address, respecting `.mailmap`
AuthorDate
: the author date
Hash
: commit hash, e.g. `866cbccdab588b9908887ffd3b4f2667e94090c3`
Subject
: commit message subject, e.g. `tpl: Add custom index function`
## Performance Considerations
The Git integrations should be fairly performant, but it does add some time to the build, which depends somewhat on the Git history size.
content/extras/highlighting.md
+197
View File
@@ -0,0 +1,197 @@
---
aliases:
- /extras/highlight/
lastmod: 2015-10-27
date: 2013-07-01
menu:
main:
parent: extras
next: /extras/toc
prev: /extras/shortcodes
title: Syntax Highlighting
toc: true
---
Hugo provides the ability for you to highlight source code in _two different ways_ &mdash; either pre-processed server side from your content, or to defer the processing to the client side, using a JavaScript library.
**The advantage of server side** is that it doesn’t depend on a JavaScript library and consequently works very well when read from an RSS feed.
**The advantage of client side** is that it doesn’t cost anything when building your site and some of the highlighting scripts available cover more languages than Pygments does.
## Server-side
For the pre-processed approach, highlighting is performed by an external Python-based program called [Pygments](http://pygments.org/) and is triggered via an embedded Hugo shortcode (see example below). If Pygments is absent from the path, it will silently simply pass the content along unhighlighted.
### Pygments
If you have never worked with Pygments before, here is a brief primer:
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH, otherwise Hugo cannot find it.
On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
Hugo gives you two options that you can set with the variable `pygmentsuseclasses` (default `false`) in `config.toml` (or `config.yaml`).
1. Color-codes for highlighting keywords are directly inserted if `pygmentsuseclasses = false` (default). See in the example below. The color-codes depend on your choice of the `pygmentsstyle` (default `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code.
2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color-codes. For class-names to be meaningful, you need to include a `.css`-file in your website representing your color-scheme. You can either generate this `.css`-files according to this [description](http://pygments.org/docs/cmdline/) or download the standard ones from the [GitHub pygments-css repository](https://github.com/richleland/pygments-css).
### Usage
Highlighting is carried out via the in-built shortcode `highlight`. `highlight` takes exactly one required parameter of language, and requires a closing shortcode. Note that `highlight` is _not_ used for client-side javascript highlighting.
### Example
```
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
```
### Example Output
```
<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>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Data.Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
```
### Options
Options to control highlighting can be added as a quoted, comma separated key-value list as the second argument in the shortcode. The example below will highlight as language `go` with inline line numbers, with line number 2 and 3 highlighted.
```
{{</* highlight go "linenos=inline,hl_lines=2 3" */>}}
var a string
var b string
var c string
var d string
{{</* / highlight */>}}
```
Supported keywords: `style`, `encoding`, `noclasses`, `hl_lines`, `linenos`. Note that `style` and `noclasses` will override the similar setting in the global config.
The keywords are the same you would using with Pygments from the command line, see the [Pygments doc](http://pygments.org/docs/) for more info.
### Code fences
It is also possible to add syntax highlighting with GitHub flavoured code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's configuration file.
````
``` html
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
```
````
### Disclaimers
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* Languages available depends on your Pygments installation.
## Client-side
Alternatively, code highlighting can be done in client-side JavaScript.
Client-side syntax highlighting is very simple to add. You'll need to pick
a library and a corresponding theme. Some popular libraries are:
- [Highlight.js]
- [Prism]
- [Rainbow]
- [Syntax Highlighter]
- [Google Prettify]
### Highlight.js example
This example uses the popular [Highlight.js] library, hosted by [Yandex], a popular Russian search engine.
In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your specific theme, there will be a snippet that will be included in every generated HTML page, such as `header.html` or `header.includes.html`. Simply add the css and js to initialize [Highlight.js]:
~~~
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/styles/default.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
~~~
### Prism example
Prism is another popular highlighter library, used on some major sites. Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages, like so:
```html
...
<link href="/css/prism.css" rel="stylesheet" />
...
```
... and add `prism.js` near the bottom of your `<body>` tag, again in whatever Hugo partial template is appropriate for your site or theme.
```html
...
<script src="/js/prism.js"></script>
...
</body>
```
In this example, the local paths indicate that your own copy of these files are being added to the site, typically under `./static/`.
### Using Client-side highlighting
To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` tags, with the language expressed in a class attribute on the `<code>` tag, such as `class="language-abc"`, where the `abc` is the code the highlighter script uses to represent that language.
The script would be looking for classes like `language-go`, `language-html`, or `language-css`. If you look at the page's source, it would be marked up like so:
~~~html
<pre>
<code class="language-css">
body {
font-family: "Noto Sans", sans-serif;
}
</code>
</pre>
~~~
The markup in your content pages (e.g. `my-css-tutorial.md`) needs to look like the following, with the name of the language to be highlighted entered directly after the first "fence", in a fenced code block:
<pre><code class="language-css">&#126;&#126;&#126;css
body {
font-family: "Noto Sans", sans-serif;
}
&#126;&#126;&#126;</code></pre>
When passed through the highlighter script, it would yield something like this output when viewed on your rendered page:
~~~css
body {
font-family: "Noto Sans", sans-serif;
}
~~~
Please see individual libraries' documentation for how to implement each of the JavaScript-based libraries.
[Prism]: http://prismjs.com
[Highlight.js]: http://highlightjs.org/
[Rainbow]: http://craig.is/making/rainbows
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://github.com/google/code-prettify
[Yandex]: http://yandex.ru/
content/extras/livereload.md
+74
View File
@@ -0,0 +1,74 @@
---
lastmod: 2016-08-09
date: 2014-05-26
menu:
main:
parent: extras
next: /extras/menus
prev: /extras/gitinfo
title: LiveReload
---
Hugo may not be the first static site generator to utilize LiveReload
technology, but it’s the first to do it right.
The combination of Hugo’s insane build speed and LiveReload make
crafting your content pure joy. Virtually instantly after you hit save
your rebuilt content will appear in your browser.
## Using LiveReload
Hugo comes with LiveReload 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:
{{< nohighlight >}}$ hugo server
{{< /nohighlight >}}
This will run a full functioning web server while simultaneously
watching your file system for additions, deletions or changes within
your:
* static files
* content
* data files
* layouts
* current theme
* configuration files
Whenever anything changes, Hugo will rebuild the site while continuing to serve
the content. As soon as the build is finished, it will tell the
browser and silently reload the page. Because most Hugo builds are so
fast they are barely noticeable, you merely need to glance at your open
browser and you will see the change, already there.
This means that keeping the site open on a second monitor (or another
half of your current monitor) allows you to see exactly what your
content looks like, without even leaving your text editor.
## Disabling Watch
If for some reason you don't want the Hugo server's watch functionality,
just do:
{{< nohighlight >}}$ hugo server --watch=false
{{< /nohighlight >}}
## Disabling LiveReload
LiveReload works by injecting JavaScript into the pages Hugo generates,
which creates a connection from the browser web socket client to the
Hugo web socket server.
Awesome for development, but not something you would want to do in
production. Since many people use `hugo server` in production to
instantly display any updated content, we’ve made it easy to disable the
LiveReload functionality:
{{< nohighlight >}}$ hugo server --disableLiveReload
{{< /nohighlight >}}
## Notes
You must have a closing `</body>` tag for LiveReload to work.
Hugo injects the LiveReload `<script>` before this tag.
content/extras/localfiles.md
+57
View File
@@ -0,0 +1,57 @@
---
aliases:
- /doc/localfiles/
lastmod: 2016-09-12
date: 2015-06-12
menu:
main:
parent: extras
next: /extras/urls
notoc: true
prev: /extras/toc
title: Traversing Local Files
---
## Traversing Local Files
Using Hugo's function `readDir`,
you can traverse your web site's files on your server.
## Using _readDir_
The `readDir` function returns an array
of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo).
It takes a single, string argument: a path.
This path can be to any directory of your web site
(as found on your server's filesystem).
Whether the path is absolute or relative makes no difference,
because&mdash;at least for `readDir`&mdash;the root of your web site (typically `./public/`)
in effect becomes both:
1. The filesystem root; and
1. The current working directory.
## New Shortcode
So, let's create a new shortcode using `readDir`:
**layouts/shortcodes/directoryindex.html**
```html
{{< readfile "layouts/shortcodes/directoryindex.html" >}}
```
For the files in any given directory,
this shortcode usefully lists their basenames and sizes,
while providing links to them.
Already&mdash;actually&mdash;this shortcode
has been included in this very web site.
So, let's list some of its CSS files.
(If you click on their names, you can reveal the contents.)
{{< directoryindex path="/static/css" pathURL="/css" >}}
<br />
This is the call that rendered the above output:
```html
{{</* directoryindex path="/static/css" pathURL="/css" */>}}
```
By the way,
regarding the pathURL argument, the initial slash `/` is important.
Otherwise, it becomes relative to the current web page.
content/extras/menus.md
+393
View File
@@ -0,0 +1,393 @@
---
lastmod: 2015-08-04
date: 2014-05-14T02:36:37Z
toc: true
menu:
main:
parent: extras
next: /extras/pagination
prev: /extras/livereload
title: Menus
---
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.
*TIP:* If all you want is a simple menu for your sections, see [Section Menu for "the Lazy Blogger"]({{< relref "#section-menu-for-the-lazy-blogger" >}}).
Some of the features of Hugo Menus:
* 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?
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`.
If you make use of the [multilingual feature]({{< relref "content/multilingual.md#menus">}}) you can define menus language independent.
A menu entry has the following properties:
* `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() bool`
Additionally, the `Page` object has two functions, which can be used when rendering menus:
* `IsMenuCurrent (menu string, menuEntry *MenuEntry ) bool`
* `HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool`
See [Menu Functions](#menu-functions) for explanations of these functions, and [Rendering Nested Menus](#rendering-nested-menus) for an example of their use.
## Adding content to menus
Hugo supports a couple of different methods of adding a piece of content
to the front matter.
### Simple
If all you need to do is add an entry to a menu, the simple form works
well.
**A single menu:**
---
menu: "main"
---
**Multiple menus:**
---
menu: ["main", "footer"]
---
### Advanced
If more control is required, then the advanced approach gives you the
control you want. All of the menu entry properties listed above are
available.
---
menu:
main:
parent: 'extras'
weight: 20
---
## Adding (non-content) entries to a 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`:
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
weight = -110
identifier = "about"
url = "/about/"
[[menu.main]]
name = "getting started"
pre = "<i class='fa fa-road'></i>"
weight = -100
url = "/getting-started/"
And the equivalent example `config.yaml`:
---
menu:
main:
- Name: "about hugo"
Pre: "<i class='fa fa-heart'></i>"
Weight: -110
Identifier: "about"
URL: "/about/"
- Name: "getting started"
Pre: "<i class='fa fa-road'></i>"
Weight: -100
URL: "/getting-started/"
---
**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`.
## 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 following order is used to determine an Identifier:
> Name > LinkTitle > Title.
This means that the title will be used unless
linktitle is present, etc. In practice Name and Identifier are never
displayed and only used to structure relationships.
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.
## Rendering menus
Hugo makes no assumptions about how your rendered HTML will be
structured. Instead, it provides all of the functions you will need to be
able to build your menu however you want.
The following is an example:
<!--sidebar start-->
<aside>
<div id="sidebar" class="nav-collapse">
<!-- sidebar menu start-->
<ul class="sidebar-menu">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
{{ if .HasChildren }}
<li class="sub-menu{{if $currentPage.HasMenuCurrent "main" . }} active{{end}}">
<a href="javascript:;" class="">
{{ .Pre }}
<span>{{ .Name }}</span>
<span class="menu-arrow arrow_carrot-right"></span>
</a>
<ul class="sub">
{{ range .Children }}
<li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
{{ end }}
</ul>
{{else}}
<li>
<a href="{{.URL}}">
{{ .Pre }}
<span>{{ .Name }}</span>
</a>
{{end}}
</li>
{{end}}
<li> <a href="https://github.com/gohugoio/hugo/issues" target="blank">Questions and Issues</a> </li>
<li> <a href="#" target="blank">Edit this Page</a> </li>
</ul>
<!-- sidebar menu end-->
</div>
</aside>
<!--sidebar end-->
> **Note**: use the `absLangURL` or `relLangURL` if your theme makes use of the [multilingual feature]({{< relref "content/multilingual.md" >}}). In contrast to `absURL` and `relURL` it adds the correct language prefix to the url. [Read more]({{< relref "templates/functions.md#urls" >}}).
## Section Menu for "the Lazy Blogger"
To enable this menu, add this to your site config, i.e. `config.toml`:
```
SectionPagesMenu = "main"
```
The menu name can be anything, but take a note of what it is.
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
```
<nav class="sidebar-nav">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{.URL}}">{{ .Name }}</a>
{{ end }}
</nav>
```
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
```
[[menu.main]]
name = "This is the blog section"
weight = -110
identifier = "blog"
url = "/blog/"
```
**Note** that the `identifier` must match the section name.
## Menu Functions
Suppose you have the menu structure shown below.
```
[menu.main]
│
├───colour
│ │
│ ├───warm
│ │ ├───orange
│ │ ├───red
│ │ └───yellow
│ │
│ └───cool
│ ├───blue
│ ├───green
│ └───purple
│
└───tool
├───hammer
├───shovel
└───saw
```
For each menu item, you can determine:
* If the menu item has any children: `.HasChildren()`
* If the menu item is a parent of the page you are currently rendering: `.Page.HasMenuCurrent()`
* If the menu item **is** the page you are currently rendering: `.Page.IsMenuCurrent()`
For example, if you are currently rendering the page `/colour/warm`, the values of `.HasChildren`, `HasMenuCurrent`, and `IsMenuCurrent` would be as shown below:
```
[menu.main] | | | |
│ | | | |
├───colour | HasMenuCurrent | | HasChildren |
│ ├───<< WARM >> | | IsMenuCurrent | HasChildren |
│ │ ├───orange | | | |
│ │ ├───red | | | |
│ │ └───yellow | | | |
│ └───cool | | | HasChildren |
│ ├───blue | | | |
│ ├───green | | | |
│ └───purple | | | |
└───tool | | | HasChildren |
├───hammer | | | |
├───shovel | | | |
└───saw | | | |
```
## Rendering nested menus
Hugo supports nested menus with as many levels as you like.
Nested menus can be rendered using a recursive partial template, such as the example below.
```
<!-- layouts/index.html, layouts/_default/single.html, ... -->
<h1>{{ .Title }}</h1>
<!-- Put this line in your main template, at the place where you want to
render the menu. -->
{{ partial "menu_include.html" . }}
```
```
<!-- layouts/partials/menu_include.html -->
{{ partial "menu_recursive.html" (dict "menu" .Site.Menus.main "page" . "site" .Site) }}
```
```
<!-- layouts/partials/menu_recursive.html -->
{{ $page := .page }}
{{ $site := .site }}
<ul>
{{ range .menu }}
{{ $is := $page.IsMenuCurrent "main" . }}
{{ $has := $page.HasMenuCurrent "main" . }}
{{ if .HasChildren }}
<li>
<a href="{{ .URL }}">
{{ .Name }}
{{ if $is }}[Is]{{ end }}
{{ if $has }}[Has]{{ end }}
{{ if .HasChildren }}[Children]{{ end }}
</a>
<!-- If the menu item has children, include this partial template again (recursively) -->
{{ partial "menu_recursive.html" (dict "menu" .Children "page" $page "site" $site) }}
</li>
{{ else }}
<li>
<a href="{{ .URL }}">
{{ .Name }}
{{ if $is }}[Is]{{ end }}
{{ if $has }}[Has]{{ end }}
{{ if .HasChildren }}[Children]{{ end }}
</a>
</li>
{{ end }}
{{ end }}
</ul>
```
This example code renders the words `[Is]`, `[Has]`, and `[Children]` to demonstrate how the `IsMenuCurrent()`, `HasMenuCurrent()`, and `HasChildren()` functions work.
You can customise this example to implement features such as:
* Highlight the current item, by applying a CSS style:
<a href="{{ .URL }}"{{ if $is }} class="active"{{ end }}>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Highlight parents of the current item, by applying a CSS style:
<a href="{{ .URL }}"{{ if $has }} class="parent-active"{{ end }}>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Only render sub-menus for parents of the current menu item, and the current menu item itself:
{{ if or $is $has }}
{{ partial "menu_recursive.html" (dict "menu" .Children "page" $page "site" $site) }}
{{ end }}
A working example, implementing these features, is shown below.
```
<!-- layouts/partials/menu_recursive.html -->
{{ $page := .page }}
{{ $site := .site }}
<ul>
<!-- Menu items sorted alphabetically by name -->
{{ range .menu.ByName }}
{{ $is := $page.IsMenuCurrent "main" . }}
{{ $has := $page.HasMenuCurrent "main" . }}
{{ if .HasChildren }}
<li>
<a href="{{ .URL }}" class="{{ if $is }} active{{ end }}{{ if $has }} parent-active{{ end }}">
{{ .Name }}
<!-- Show a » symbol if there is a sub-menu we haven't rendered -->
{{ if not (or $is $has) }}»{{ end }}
</a>
<!-- Only render sub-menu for parent items and the current item -->
{{ if or $is $has }}
{{ partial "menu_recursive.html" (dict "menu" .Children "page" $page "site" $site) }}
{{ end }}
</li>
{{ else }}
<li>
<a href="{{ .URL }}" class="{{ if $is }}active{{end}}">{{ .Name }}</a>
</li>
{{ end }}
{{ end }}
</ul>
```
content/extras/output-formats.md
+185
View File
@@ -0,0 +1,185 @@
---
aliases:
- /doc/output-formats/
- /doc/custom-output/
date: 2017-03-22T08:20:13+01:00
menu:
main:
parent: extras
title: Output Formats
weight: 5
toc: true
---
Hugo `0.20` introduced the powerful feature **Custom Output Formats**; Hugo isn't just that "static HTML with an added RSS feed" anymore. _Say hello_ to calendars, e-book formats, Google AMP, and JSON search indexes, to name a few.
This page describes how to properly configure your site with the media types and output formats you need.
## Media Types
A [media type](https://en.wikipedia.org/wiki/Media_type) (also known as MIME type and content type) is a two-part identifier for file formats and format contents transmitted on the Internet.
This is the full set of built-in media types in Hugo:
{{< datatable "media" "types" "Type" "Suffix" >}}
**Note:**
* It is possible to add custom media types or change the defaults (if you, say, want to change the suffix to `asp` for `text/html`).
* The `Suffix` is the value that will be used for URLs and filenames for that media type in Hugo.
* The `Type` is the identifier that must be used when defining new `Output Formats` (see below).
* The `Delimiter` defaults to ".", but can be changed or even blanked out to support, as an example, Netlify's `_redirect` files.
* The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser.
To add or modify a media type, define it in a `mediaTypes` section in your site config (either for all sites or for a given language).
Example in `config.toml`:
```toml
[mediaTypes]
[mediaTypes."text/enriched"]
suffix = "enr"
[mediaTypes."text/html"]
suffix = "asp"
```
The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type.
## Output Formats
Given a media type and some additional configuration, you get an `Output Format`.
This is the full set of built-in output formats in Hugo:
{{< datatable "output" "formats" "Name" "MediaType" "Path" "BaseName" "Rel" "Protocol" "IsPlainText" "IsHTML" "NoUgly" "NotAlternative">}}
**Note:**
* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined, as long as _they resolve to a unique path on the file system_. In the table above, the best example of this is `AMP` vs. `HTML`: We have given `AMP` a value for `Path` so it doesn't overwrite the `HTML` version, i.e. we can now have both `/index.html` and `/amp/index.html`.
* The `MediaType` must match the `Type` of an already defined media type (see above).
* You can define new or redefine built-in output formats (if you, as an example, want to put `AMP` pages in a different path).
To add or modify a media type, define it in a `outputFormats` section in your site config (either for all sites or for a given language).
Example in `config.toml`:
```toml
[outputFormats.MyEnrichedFormat]
mediaType = "text/enriched"
baseName = "myindex"
isPlainText = true
protocol = "bep://"
```
The above example is fictional, but if used for the home page on a site with `baseURL` `http://example.org`, it will produce a plain text home page with the URL `bep://example.org/myindex.enr`.
All the available configuration options for output formats and their default values:
Field | Description
--- | ---
**Name** | The output format identifier. This is used to define what output format(s) you want for your pages.
**MediaType**|This must match the `Type` of a defined media type. |
**Path** | Sub path to save the output files.
**BaseName** | The base filename for the list filenames (home page etc.). **Default:** _index_.
**Rel** | Can be used to create `rel` values in `link` tags. **Default:** _alternate_.
**Protocol** | Will replace the "http://" or "https://" in your `baseURL` for this output format.
**IsPlainText** | Use Go's plain text templates parser for the templates. **Default:** _false_.
**IsHTML** | Used in situations only relevant for `HTML` type of formats, page aliases being one example.|
**NoUgly** | If `uglyURLs` is enabled globally, this can be used to turn it off for a given output format. **Default:** _false_.
**NotAlternative** | Enable if it doesn't make sense to include this format in an the `.AlternativeOutputFormats` format listing on `Page`, `CSS` being one good example. Note that we use the term "alternative" and not "alternate" here, as it does not necessarily replace the other format, it is an alternative representation. **Default:** _false_.
## Output Formats for your pages
A `Page` in Hugo can be rendered to multiple representations on the file system: In its default configuration all will get an `HTML` page and some of them will get an `RSS` page (home page, sections etc.).
This can be changed by defining an `outputs` list of output formats in either the `Page` front matter or in the site configuration (either for all sites or per language).
Example from site config in `config.toml`:
```toml
[outputs]
home = [ "HTML", "AMP", "RSS"]
page = [ "HTML"]
```
Note:
* The output definition is per `Page` `Kind`(`page`, `home`, `section`, `taxonomy`, `taxonomyTerm`).
* The names used must match the `Name` of a defined `Output Format`.
* Any `Kind` without a definition will get `HTML`.
* These can be overriden per `Page` in front matter (see below).
* When `outputs` is specified, only the formats defined in outputs will be rendered
A `Page` with `YAML` front matter defining some output formats for that `Page`:
```yaml
---
date: "2016-03-19"
outputs:
- html
- amp
- json
---
```
Note:
* The names used for the output formats are case insensitive.
* The first output format in the list will act as the default.
* The default output format is used when generating links to other pages in menus, etc.
## Link to Output Formats
`Page` has both `.OutputFormats` (all formats including the current) and `.AlternativeOutputFormats`, the latter useful for creating a `link rel` list in your `head` section:
```
{{ range .AlternativeOutputFormats -}}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end -}}
```
Note that `.Permalink` on `RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined).
This is how you link to a given output format:
```
{{ with .OutputFormats.Get "json" -}}
<a href="{{ .Permalink }}">{{ .Name }}</a>
{{- end }}
```
From content files, you can use the `ref` or `relref` shortcodes:
```
[Neat]({{</* ref "blog/neat.md" "amp" */>}})
[Who]({{</* relref "about.md#who" "amp" */>}})
```
## Templates for your Output Formats
Of course, for a new Output Format to render anything useful, we need a template for it.
**The fundamental thing to understand about this is that we in `Hugo 0.20` now also look at Output Format´s `Name` and MediaType´s `Suffix` when we choose the templates to use to render a given `Page`.**
And with so many possible variations, this is best explained with some examples:
{{< datatable "output" "layouts" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
**Note:**
* All of the above examples can use a base template, see [Blocks]({{< relref "templates/blocks.md" >}}).
* All of the above examples can also include partials.
Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not.
Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format (`[partial name].[OutputFormat].[suffix])`.
The partial below is a plain text template (Output Format is `CSV`, and since this is the only output format with the suffix `csv`, we don't need to include the Output Format's `Name`):
```
{{ partial "mytextpartial.csv" . }}
```
Also note that plain text partials can currently only be included in plain text templates, and vice versa. See [this issue](https://github.com/gohugoio/hugo/issues/3273) for some background.

Some files were not shown because too many files have changed in this diff Show More