A couple of internal links use `#toc_4` to attempt to locate a document
element within another document page. In both of these instances, there
is no element on the linked to pages with the id `#toc_4`. This commit
updates those links with the document elements which were the original
intended links, meaning these links now take you directly to the
intended element.
Signed-off-by: mattjmcnaughton <mattjmcnaughton@gmail.com>
Returns true if a given field value that is a slice / array of strings, integers or floats contains elements in common with the matching value. It follows the same rules as the intersect function.
Closes#1945
Useful if using or sharing files with users that use editors that
append a unicode byte order marker header (like Windows notepad).
This will still assume files are UTF-8 encoded.
Closes#2075
The procedure Start button --> Settings --> About was missing a step. Corrected it to: Start --> Settings --> System --> About. Also replaced ASCII arrows (-->) with Unicode right arrow character (U+2192).
If Page.Markup was not set by the user, it will now be set after
guessing from the file extension. This means, Page.Markup will be set in
any case. It can be used by a theme to differentiate between markup
types.
Fixes#1950
We should get some new ones in there.
Also shuffle the order. This also means no merging into 0.15-docs ...
Which also means we should get a release out there ... soon!
See #2055
Also See https://github.com/BurntSushi/toml/issues/129 for an explanation to the little bit ugly dates.
Meny people, including me, have a custom robots.txt in static.
Also remove that option from the command line; it doesn't feel
important enough.
Fixes ##2049
This disables highlighting for fenced code blocks without explicitly specified language. It also introduces a new `PygmentsCodeFencesGuessSyntax` config option (defaulting to false).
To enable syntax guessing again, add the following to your config file: `PygmentsCodeFencesGuessSyntax = true`
This is a breaking change.
While sorting on data sources with missing fields, a panic can occur in
pairList.Less if `Interface()` is called on a invalid `reflect.Value`.
This commit detects an invalid Value and replacing it with a zero value
for the comparison.
This also includes a refactor of the hugofs package and its usage.
The motivation for that is:
The Afero filesystems are brilliant. Hugo's way of adding a dozen of global variables for the different filesystems was a mistake. In readFile (and also in some other places in Hugo today) we need a way to restrict the access inside the working dir. We could use ioutil.ReadFile and implement the path checking, checking the base path and the dots ("..") etc. But it is obviously better to use an Afero BasePathFs combined witha ReadOnlyFs. We could create a use-once-filesystem and handle the initialization ourselves, but since this is also useful to others and the initialization depends on some other global state (which would mean to create a new file system on every invocation), we might as well do it properly and encapsulate the predefined set of filesystems. This change also leads the way, if needed, to encapsulate the file systems in a struct, making it possible to have several file system sets in action at once (parallel multilanguage site building? With Moore's law and all...)
Fixes#1551
It is a fairly costly operation:
```
benchmark old ns/op new ns/op delta
BenchmarkScratchGet-4 109 31.6 -71.01%
benchmark old allocs new allocs delta
BenchmarkScratchGet-4 0 0 +0.00%
benchmark old bytes new bytes delta
BenchmarkScratchGet-4 0 0 +0.00%
´´´
Add some helpful tasks to the Makefile to make it easier to test code quality
prior to committing. Use `make check` to run the standard checks. As of now,
the cyclo and lint tasks are not part of the standard checks since Hugo doesn't
pass those checks.
To strip away any HTML. May be useful for the .Title in head etc.
People may shoot themself in the foot with this, maybe ...
The replacement function is pretty fast.
NewContent is refactored to use the afero.Fs interface that should allow
full testing. This commit also pulls the metadata creation logic out of
NewContent and into a separate function to decrease the cyclomatic
complexity of NewContent.
The `intersect` function uses `in` to avoid adding duplicates to the
resulting set. We were passing `reflect.Value` items when we should
have been using `Value.Interface()` to send the actual data structure.
This fixes that.
See #1952
- updated the instructions to account for Windows 10 path editor
- linked to third-party editors for pre-10 Windows
- separated instructions for technical and non-technical users changed
D drive paths to C drive since D is the default optical drive on most
Windows systems
- cut the assumption about 64-bit Windows since 32-bit binary is also available
- cut the assumption about command line since we're giving GUI instructions
to non-technical users
- cut a bug in the doc where we had people typing D: at the command prompt
*after* submitting `cd D:\Hugo\Sites.` Recommend snipping 386 and AMD from
ZIP file names, since they don't add useful info and will just confuse novices.
This uses the Emoji map from https://github.com/kyokomi/emoji -- but with a custom replacement implementation.
The built-in are fine for most use cases, but in Hugo we do care about pure speed.
The benchmarks below are skewed in Hugo's direction as the source and result is a byte slice,
Kyokomi's implementation works best with strings.
Curious: The easy-to-use `strings.Replacer` is also plenty fast.
```
BenchmarkEmojiKyokomiFprint-4 20000 86038 ns/op 33960 B/op 117 allocs/op
BenchmarkEmojiKyokomiSprint-4 20000 83252 ns/op 38232 B/op 122 allocs/op
BenchmarkEmojiStringsReplacer-4 100000 21092 ns/op 17248 B/op 25 allocs/op
BenchmarkHugoEmoji-4 500000 5728 ns/op 624 B/op 13 allocs/op
```
Fixes#1891
This commit adds 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
This commit fixes a few things:
1. `given` is now a variadic parameter so that piping works properly
2. add separate template tests to make sure piping works
3. support time values
4. add more tests of the dfault function
Hugo has been confirmed which runs on Golang 1.6, as travis uses 1.6
vesion. Dockerfile must be consistend with it so it has to use golang:1.6
as base image than golang:1.5
We can of course skip reading the entire byte slice again and again.
This was a slip in the original implementation; functionally the same,
but is slightly faster, esp. for larger data sets with many shortcodes:
```
benchmark old ns/op new ns/op delta
BenchmarkReplaceShortcodeTokens-4 15505 14753 -4.85%
benchmark old allocs new allocs delta
BenchmarkReplaceShortcodeTokens-4 1 1 +0.00%
benchmark old bytes new bytes delta
BenchmarkReplaceShortcodeTokens-4 3072 3072 +0.00%
```
The original image was 2055px × 1252px, which was oversized
and did not fit the required dimension of 600px × 400px
(3:2 aspect ratio).
To fix, the image was cropped and resized to the required dimension,
and was further optimized:
$ pngquant --nofs -v --speed 1 --quality 65-80 shelan-tn.png
$ optipng -o7 -zm1-9 shelan-tn-or8.png
$ mv shelan-tn-or8.png shelan-tn.png
reducing its filesize from 334125 bytes to 26929 bytes.
See #1831
The common is the `where` func and this:
```
panic: reflect: call of reflect.Value.Type on zero Value [recovered]
panic: reflect: call of reflect.Value.Type on zero Value
```
There is no good reason to export all the template funcs:
* They're not used outside the templates.
* If usable in other packages, they should be moved (to helpers?)
* They create too broad an interface;
users of the tpl package don't see the forest for all the trees.
Add humanize (inflect.Humanize) to the template funcMap. Documentation and
tests are included.
Various code cleanups of the template funcs:
- Break pluralize and singularize out into stand-alone funcs.
- Sort the list of funcMap entries.
- Add some minimal godoc comments to all public funcs.
- Fix some issues found by golint and grind.
Started to increase coverage in helpers package, now at 74.9% of statements.
In the process, also a few minor changes have been applied to content.go.
* Content.go has undergone a formatting refactor regarding comments
* Unused function TruncateWords has been removed
* RenderingContext's "mmark" has been changed to use MmarkRender
* Content_test.go added to cover content.go's functionality
Site.ReadPagesFromSource returns nil chan error value when a site
content directory is empty but its receiver expects to be passed
something error values via the channel.
This fixes it by returning a channel which will be immediately closed.
Fix#1797
Fixed a path in a Page Params example to reflect real directory
structure, removed extra quotes from sample code, and fixed link to
Archetypes which read "cross-references" before.
See #1805
Expanded on the use of Page Params in the templates/variables.md
documentation. Added sample code for something that keeps coming up on
discuss.github.io
See #1772
Also, force DisableLiveReload to true when running "hugo --watch"
(build-only non-server mode) to prevent livereload.ForceRefresh(),
which would end up blocking watchConfig() forever, from being called
because livereload.Initialize() is never called in this case.
This fixes the bug where "hugo --watch" could only reload config.toml
once before it gets stuck for good at livereload.ForceRefresh().
This is also consistent with Hugo's existing behaviour:
Non-server "hugo --watch" has never injected livereload.js
since the inception of the "watch" feature in Hugo v0.12.
This fixes a exported field check condition in a way described at Go
issue https://golang.org/issue/12367
According to the issue comments, this fix should be safe under Go 1.6.
Remind user to always run "brew update" first in order to avoid
repeated bug reports from users who didn't do that.
See #824, #1067, #1537, #1633 and #1749
Update on the watcher copy static to copy only the
changed files and add an flag forceSyncStatic to
copy all statics always a static is changed
See #1644#1559
- Upgrade Bootswatch Yeti theme (3.2.0+3 → to 3.3.6)
- Upgrade Font Awesome (4.2.0 → 4.5.0)
- Upgrade jQuery (1.11.1 → 1.11.3)
Also keep the upstream filenames, e.g. bootstrap.min.css rather than
bootstrap.css for the minified CSS, and jquery-1.11.3.min.js rather than
jquery.js for the minified jQuery.
with the following added languages in anticipation of document expansion:
apache dockerfile dos less php powershell python tex yaml
To reproduce docs/static/js/highlight.pack.js on Debian/Ubuntu:
$ sudo apt-get install nodejs npm
$ wget https://github.com/isagalaev/highlight.js/archive/9.0.0.tar.gz
$ tar xzf 9.0.0.tar.gz
$ cd highlight.js-9.0.0/
$ npm install
$ nodejs tools/build.js markdown asciidoc xml css javascript \
ini yaml json go bash diff dockerfile dos powershell makefile \
apache nginx tex http php python ruby django haml handlebars \
scss less coffeescript
Then, copy the resulting build/highlight.pack.js as well as
src/styles/monokai-sublime.css to the appropriate Hugo docs directories.
because our bootstrap-theme.css was originally a customized
core bootstrap.css file from Bootstrap v3.0.0.
This rename helps to avoid confusion with Bootstrap’s official
bootstrap-theme.css files.
The GitHub octicons fonts, which, in our case, came with GitHub:buttons,
are not actually used on gohugo.io. Rather, the icons inside the GitHub
buttons are actually glyphs from Font Awesome.
The GitHub:buttons JavaScript code docs/static/js/buttons.js
from https://github.com/ntkme/github-buttons was referenced
in docs/layouts/partials/footer.html but never used.
Apparently, the actual code for the GitHub buttons on the upper-left
corner of gohugo.io documentation was written by @spf13 in
docs/static/js/scripts.js.
especially when the given `--source` path is a relative directory.
Also, when `--source` is specified, make WorkingDir an absolute path
from the very beginning, to be consistent with the case when `--source`
is not given. Otherwise, the function name helpers.AbsPathify(), which
prepends WorkingDir to a relative path, does not really make sense.
Fixes#1721
v0.15 had it, but I removed it inadvertently for 0.16-DEV
in commit 00d04774 in PR #1652.
Also add directory bash-completion for `--source`
for `hugo convert`, `hugo list` and `hugo new`.
See #1624, #1589
`where` template function's internal condition check function doesn't
check boolean values and always returns `false` silently.
This adds missing boolean value comparison to the function.
`where Values ".Param.key" true` like clause can be used.
Only "=", "==", "eq", "!=", "<>", "ne" operators are allowed to be used
with a boolean value. If an other operator is passed with it, the
condition check function returns `false` like before.
The crash was introduced by commit 00d04774 in PR #1652
where access to NoTimes was attempted even though --noTimes
was not defined for the config, check and benchmark commands.
Special thanks to @bep for the heads-up!
See also #1624 - CLI UX: Flags shouldn't be global
This is to ensure that only the relevant command-line flags
for a certain Hugo subcommand is shown to the end user,
reducing clutter and improving user experience.
Fixes#1624 - CLI UX: Flags shouldn't be global
The `gh` shortcode has two modes: users and issues. For user mode, pass a list
of `@username` arguments. For the issues/PR mode, pass a list of issue or PR
numbers. PRs link to the "issues/" URL since Github redirects to the correct
URL.
Thanks to @ryanclarke for suggesting an improved template.
Cobra, the CLI commander in use in Hugo, has some long awaited improvements in the error handling department.
This enables a more centralized error handling approach.
This commit introduces that by changing all the command funcs to `RunE`:
* The core part of the error logging, usage logging and `os.Exit(-1)` is now performed in one place and that one place only.
* The usage text is now only shown on invalid arguments etc. (user errors)
Fixes#1502
Hugo command provides "noTimes" flag but it doesn't affect synced files
timestamp regardless of whether the flag is specified or not.
This fixes it by adding a flag check and overwriting configuration if it
is specified.
Fix#1583
Hugo command doesn't copy site's "static" directory files to "public"
directory if a specified theme doesn't have "static" directory because
theme's "static" directory checking always returns an error.
This fixes it by just showing a warning message about theme's "static"
directory absence and not skipping following processes.
Fix#1655
Also add a note saying that these blackfriday flags are
very case-sensitive as of Hugo v0.15.
Thanks to @ryanclarke for noticing the change in behaviour.
See also spf13/hugo@5838420
It would be helpful to know whether a shortcode was called with positional or
named parameters. This commit adds a boolean `IsNamedParams` property to the
`ShortcodeWithPage` struct.
using pngquant and OptiPNG. Result:
arresteddevops-tn.png 154734 bytes → 47184 bytes
maximeguitare-tn.png 95571 bytes → 24183 bytes
ridingbytes-tn.png 262222 bytes → 66491 bytes
And a small one to an even smaller one too:
goin5minutes-tn.png 26220 bytes → 9297 bytes
Write and rename operations are often followed by CHMOD.
There may be valid use cases for rebuilding the site on CHMOD,
but that will require more complex logic than this simple conditional.
On OS X this seems to be related to Spotlight, see:
https://github.com/go-fsnotify/fsnotify/issues/15
A workaround is to put your site(s) on the Spotlight exception list,
but that may be a little mysterious for most end users.
So, for now, we skip reload on CHMOD.
This small commit will be a 100% improvement for most OS X-users.
Fixes#1587
Currently a `[]byte` copy is returned. In most cases this is the safe thing to do, but we should just modify/grow the slice as needed.
This is faster and consumes less memory:
```
benchmark old ns/op new ns/op delta
BenchmarkReplaceShortcodeTokens-4 7350 4419 -39.88%
benchmark old allocs new allocs delta
BenchmarkReplaceShortcodeTokens-4 5 1 -80.00%
benchmark old bytes new bytes delta
BenchmarkReplaceShortcodeTokens-4 4816 1152 -76.08%
```
This commit is aso a small spring cleaning of duplicated code in the different `PageConvert` methods.
Fixes#1516
Page.GroupByParam function internally uses Page.GetParam to get a
parameter value for a key of a page group but now Page.GetParam returns
a lowercase character string every time. It has no need to using
lowercase character string as a group key value and it confuse a
function user.
This fixes it to keep and return an original parameter string as a group
key value.
Fix#1564
Prevent some frequently occurring problems
* Ensure version number is between quotes
* Ensure git and SSH are installed for the deployment step
* Focus extra attention on the wercker.yml verification site
To allow the end users to disable any form of smart dashes
(LaTeX-style or not) while keeping the rest of Blackfriday
SmartyPants features.
Depends on https://github.com/russross/blackfriday/pull/190
"Add HTML_SMARTYPANTS_DASHES for toggling smart dashes"
to be accepted by Blackfriday developers.
All-around improvements to the README.
Each sentence now gets its own line to eliminate ultra-long lines in the
source (expect in bullet points--separating a bullet point into multiple
lines looks weird and decreases readability).
HTTPS links are now preferred to HTTP links and used where applicable.
Link to Mercurial's website corrected to www.mercurial-scm.org
Link to Hugo's docs is now accessible with [Hugo Documentatio][] since
it is used more than once in the README.
Multiline code blocks are now fenced rather than indented and include
syntax highlighting.
If flag is passed the site will be created inside non-empty folder
only if there are no existent folders or config with the same name
hugo creates.
Resolves: #1163
The lack of the directory would be worth to warn, since the directory is
created by "huge new site". But it doesn't have to fail the build.
This change fixes#759.
Inserts a code tag into Pygments output with the language-info that is present when using client-side highlighting (useful for CSS hooks)
```html
<code class="language-go" data-lang="go">
```
closes#1490
* add global `hasCJKLanguage` flag, if true, turn on auto-detecting CJKLanguage
* add `isCJKLanguage` frontmatter to force specify whether is CJKLanguage or not
* For .Summary: If isCJKLanguage is true, use the runes as basis for truncation, else keep as today.
* For WordCount: If isCJKLanguage is true, use the runes as basis for calculation, else keep as today.
* Unexport RuneCount
Fixes#1377
usage: hugo import jekyll jekyll_root_path target_path
Implemented:
* Create new hugo site
* Create config.yaml
* Convert all markdown contents.
* Copy all other files and folders to static
Fixes#101
Add validation before creating aliases:
* Prevent creating aliases outside webroot (public/ dir)
* Skip empty "" alias
* Skip "/" → "/index.html", which gets overwritten anyway
* Refuse to create Windows-invalid filenames on Windows;
warn on other platforms
* In case of invalid aliases, after skipping them,
return `err = nil` to prevent the error passing up
all the way to `hugolib.Render()` and causing Hugo to abort.
* Update alias tests.
Fixes#701: Add support for alias with whitespace
Fixes#1418: Add validation for alias
It currently handles --baseUrl to --baseURL, and --uglyUrls to --uglyURLs.
Special thanks to Eric Paris (@eparis) for writing the
"normalized name" support in Cobra, and for showing us
how it is used in Kubernetes.
See Issue #959
Increases clarity on the different between `section` and `type`.
The current `section` information here is wrong (sections can *not* be specified in front matter). This caused quite the headache. This change fixes this and also adds `type`, since it *can* be specified in front matter.
A new "published" setting that is the opposite of "draft" is added and
left intentionally undocumented.
This setting comes from jekyll and eases the transition to hugo
greatly. We leave it undocumented so that folks don't rely on it, but
also don't shoot themselves in the foot during a jekyll migration.
The foot-shooting occurs if they have only a few documents that were
drafts ("published: false") in the jekyll version of their site and
don't notice that they were published in the migration to hugo.
Simple ioutil.ReadFile is used for reading file contents but it reads
all of the file contents and copies them into the memory and is run in a
single goroutine. It causes much memory consumption at copying media
files in content directory to publish directory and it is not good at
performance.
This improves the both issue by replacing ReadFile with LazyFileReader.
It postpones reading the file contents until it is really needed. As the
result, actual file read is run in parallelized goroutine. It improves
performance especially in a really big site.
In addition, if this reader is called from io.Copy, it does not copy the
file contents into the memory but just copies them into destination
file. It improves much memory consumption issue when the site has many
media files.
Fix#1181
LazyFileReader is an io.Reader implementation to postpone reading the
file contents until it is really needed. It is introduced for improving
performance and memory consumption at reading media files in content
directory.
As of 2015-08-16, Viper no longer searches the CWD
for config file by default to avoid unintended surprises,
but Hugo relies on the original behaviour.
Fixed by calling
viper.AddConfigPath(".")
at the appropriate place.
See https://github.com/spf13/viper/issues/73 for more information.
Fixes#1363
Some of the thumbnails in Showcase were out of place
because of several irregularly sized thumbnails,
and some of them almost 300KB in filesize.
Resize them all to 600x400 (pixels), and use the `-tn.png`
suffix.
When necessary, the website snapshot is re-captured using
gnome-web-photo. Then, the following commands (or a combination
thereof) are used to crop and resize the image into a thumbnail,
and to reduce its filesize:
$ convert example.png -crop 900x600+0+0 \
-filter Lanczos2Sharp -distort Resize 600x400 \
example-tn.png
$ pngquant --nofs -v --speed 1 --quality 65-80 example-tn.png
$ optipng -o7 -zm1-9 example-tn-or8.png
$ mv example-tn-or8.png example-tn.png
To prevent "Showcase" from becoming "Showcases",
also to have the RSS feed display correct titles,
i.e. "Showcase on gohugo.io" rather than "Showcase on ".
As Hugo now supports more formats thanks to the new "external helpers"
feature recently introduced, and as requested by some people, I added
some lines in the doc:
* basically confirming it actually exists
* how to use it
'sort' template function used to accept only each element's struct field
name, method name and map key name as its second argument. This extends
it to accept a field/method/key chaining key string like
'Params.foo.bar' as the argument. It evaluates sub elements of each
array or map elements and sorts by them.
Typical use case would be sorting pages by user defined front matter
value. For example, sorting pages by 'Params.foo.bar' is possible by
writing the following template code
{{ range sort .Data.Pages "Params.foo.bar" }}
{{ .Content }}
{{ end }}
It ignores all leading and trailing dots so "Params.foo.bar" can be
written in ".Params.foo.bar"
This also fixes the issue that 'sort' cannot evaluate a pointer value.
Fix#1330
sort template function returns `[]interface{}` type slice value
regardless of its original element type.
This fixes it to keep the original element type. For example, if it
sorts `map[string]int` type value, it returns `[]int` slice value
instead of `[]interface{}` slice value.
When a YAML/TOML's delimiter character sequence is included in a
frontmatter string, parser mistakes it as a delimiter. This fixes it by
checking a character right before the delimiter sequence is '\n' or it
is the beginning of the frontmatter.
Fix#1320
This simplifies the retrieval of the HTML (no more need to extract the
part within body) and also removes the unwanted "Last Updated" part in
the article.
- Add a step to Contributor instructions for those modifying commands
- Change forum link to http (https does not work)
- Add "Sign the forum release thread" to contributor instructions
The custom sort functions used from the templates had some subtle data race- and related issues,
especially when used in the single page template.
This commit fixes this by making copies and protect the read and writes with a RWMutex.
The results are cached (it will typically be invoked *number of pages* times with exactly the same data).
This is, not surprisingly, also faster:
```
benchmark old ns/op new ns/op delta
BenchmarkSortByWeightAndReverse 14228 491 -96.55%
benchmark old allocs new allocs delta
BenchmarkSortByWeightAndReverse 1 0 -100.00%
benchmark old bytes new bytes delta
BenchmarkSortByWeightAndReverse 32 0 -100.00%
```
Fixes#1293
The documentation for the RSS templating is a little unclear.
http://gohugo.io/templates/rss/
Some users may attempt to look for a ```__internal``` directory rather than assume that's the aforementioned "Hugo own template."
Here's my suggestion.
This commit adds a new PygmentsCodeFences config option (default false), which if true will allow GitHub style backtick code fences around code, which will then be rendered by Pygments.
For example:
``` language
your code
```
can be used instead of {{< highlight language >}}your code {{< /highlight >}}.
Fixes#362
Previously if no language was specified, then illegal args would be passed to pygments, for example `pygments -l -fhtml`, which would result in pygments printing an error.
I could be wrong here, but it looks to me like .Site.Social.facebook is used in tpl/template_embedded.go, but the variable is never set. I've added a line to initializeSiteInfo to map the info from config into this variable.
In particular, RawContent() excludes the metadata header.
This is necessary in the use case of embedding remarkjs.com slides, as it needs
the unprocessed Markdown content to generate the slides.
`where` template function's internal condition check function always
returns `false` when a target value doesn't exist or it's nil value but
this behavior makes it difficult to filter values which doesn't have a
particular parameter.
To solve it, this adds nil value comparison to the function.
`where Values ".Param.key" nil` like clause can be used for the case
above.
Only "=", "==", "eq", "!=", "<>", "ne" operators are allowed to be used
with `nil`. If an other operator is passed with `nil`, the condition
check function returns `false` like before.
Fix#1232
There have been some changes to the ´helpers.GetThemesDirPath()´ so it now returns an empty string when no theme.
This is correct, but it broke the watch service (at lest on OSX), as `strings.HasPrefix("", "somestring") evaluates to true somehow, and content changes are incorrectly branded as static.
There are other issues in there, but that will come later ...
See #1236
Reduce duplication (`x + FilePathSeparator + y` a few lines away from `filepath.Join(x, y)`) and add a `GetThemeDir()` function to get the current theme's directory.
Also add a comment complaining about the `GetThemesDirPath()` function, which doesn't seem to do what its name would suggest. This might be a candidate for deprecation?
Even as a copy at the end is needed, this consumes way less memory on Go 1.4.2:
```benchmark old ns/op new ns/op delta
BenchmarkParsePage 145979 139964 -4.12%
BenchmarkReplaceShortcodeTokens 633574 631946 -0.26%
BenchmarkShortcodeLexer 195842 187938 -4.04%
benchmark old allocs new allocs delta
BenchmarkParsePage 87 87 +0.00%
BenchmarkReplaceShortcodeTokens 9424 9415 -0.10%
BenchmarkShortcodeLexer 274 274 +0.00%
benchmark old bytes new bytes delta
BenchmarkParsePage 141830 141830 +0.00%
BenchmarkReplaceShortcodeTokens 35219 25385 -27.92%
BenchmarkShortcodeLexer 30178 30177 -0.00%
```
See #1148
This commit replaces the regexp driven `replaceShortcodeTokens` with a handwritten one.
It wasnt't possible to handle the p-tags case without breaking performance.
This fix actually improves in that area:
```
benchmark old ns/op new ns/op delta
BenchmarkParsePage 142738 142667 -0.05%
BenchmarkReplaceShortcodeTokens 665590 575645 -13.51%
BenchmarkShortcodeLexer 176038 181074 +2.86%
benchmark old allocs new allocs delta
BenchmarkParsePage 87 87 +0.00%
BenchmarkReplaceShortcodeTokens 9631 9424 -2.15%
BenchmarkShortcodeLexer 274 274 +0.00%
benchmark old bytes new bytes delta
BenchmarkParsePage 141830 141830 +0.00%
BenchmarkReplaceShortcodeTokens 52275 35219 -32.63%
BenchmarkShortcodeLexer 30177 30178 +0.00%
```
Fixes#1148
Where `first` will return the first N items of a rangeable list,
`after` will return all items after the Nth item.
This allows the user to do something with the first N items and
something different with the remaining items after N.
`substr` template function takes one or two range arguments. Both
arguments must be int type values but if it is used with a calclation
function e.g. `add`, `len` etc, it causes a wrong type error.
This fixes the issue to allow the function to take other integer type
variant like `int64` etc.
This also includes a small fix on no range argument case.
Fix#1190
The following inside `config.toml` will ignore files ending with `.foo` and `.boo`.
```
watchIgnoreFiles = [ "\\.foo$", "\\.boo$" ]
```
The above is is a list of Reqular Expressions, but note the escaping of the `\` to make TOML happy.
Fixes#1189
Before this commit, taxonomy names were hyphenated, lower-cased and normalized -- then fixed and titleized on the archive page.
So what you entered in the front matter isn't necessarily what you got in the final site.
To preserve backwards compability, `PreserveTaxonomyNames` is default `false`.
Setting it to `true` will preserve what you type (the first characters is made toupper for titles), but normalized in URLs.
This also means that, if you manually construct URLs to the archive pages, you will have to pass the Taxonomy names through the `urlize` func.
Fixes#1180
So the taxonomy `Gérard Depardieu` gives paths on the form `gerard-depardieu`.
Unfortunately this introduces two imports from the `golang.org/`, but Unicode-normalization isn't something we'd want to write from scratch.
See https://blog.golang.org/normalization
See #1180
Section names are also used as the title of the list pages, but naming section folders as `Fish and Chips` and similar didn't work very well.
This commit fixes that.
This commit also changes the title casing of the section titles. Some may argue that this is a breaking change, but the old behaviour was also pretty broken,
even for languages that use title capitalizations, as it didn't follow any particular style guide, `fish and chips` became `Fish And Chips` etc.
Now it just turns the first letter into upper case, so `Fish and Chips` will be left as `Fish and Chips`.
People wanting the good old behaviour can use the `title` template func.
Fixes#1176
To determine if a page is the "Home Page" has inspired lots of creativity in the template department.
This commit makes it simpler: IsHome will tell the truth.
`where` tpl function doesn't support `time.Time` type so if people want
to compare such values, it's required that these values are converted
into `int` and compare them.
This improves it. If `time.Time` values are passed to `where`, it
converts them into `int` internally, compares them and returns the
result.
See also
http://discuss.gohugo.io/t/future-posts-and-past-posts/1229/3
This information was previously scattered around in the forums and
mailing list. Add it to the official docs to make things easier for new
users.
Fixes#1167
Taxonomy Term pages have variables in addition to those on "node"
pages. Documenting these variables with all the other node variables
makes them easier to find.
Fixes: #1155
Added clarification for RSS doc page.
* a little formatting to make key words jump out
* emphasize that you can create your own
* add how to link to the feed in <head>
* add what .RSSlink does
* added point that a link to an RSS feed should be of type application/rss+xml
Add a new command, genautocomplete, wich generates a Bash completion script (zsh and others later).
The script is by default written to `/etc/bash_completion.d/hugo.sh`; this can be set in `--completionfile=/some/file`.
Fixes#438
Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section.
Added Discourse to comments section.
Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum.
Added a bunch of clarifying narrative, looking at the discussion forum for what people are asking about, and what I myself was confused about.
* clearer separation of advantage of each style - server or client side - at the top
* inconsistent newlines (different column widths) so I just removed them from obvious paragraphs
* added that the highlight shortcode is not used for the client-side javascripts
* Hugo is taking crap for Pygments being slow, so tried to emphasize that's it's in Pygment's lap. I got your back, Hugo.
* On client-side added prism example
* More clarity on how the css and js needs to be added to your templates
* Explained how the client-side scripts work
Setting `RelativeURLs` to `true` will make all relative URLs in the site *really* relative.
And will do so with speed.
So:
In `/post/myblogpost.html`:
`/mycss.css` becomes `../mycss.css`
The same in `/index.html` will become:
`./mycss.css` etc.
Note that absolute URLs will not be touched (either external resources, or URLs constructed with `BaseURL`).
The speediness is about the same as before:
```
benchmark old ns/op new ns/op delta
BenchmarkAbsURL 17462 18164 +4.02%
BenchmarkAbsURLSrcset 18842 19632 +4.19%
BenchmarkXMLAbsURLSrcset 18643 19313 +3.59%
BenchmarkXMLAbsURL 9283 9656 +4.02%
benchmark old allocs new allocs delta
BenchmarkAbsURL 24 28 +16.67%
BenchmarkAbsURLSrcset 29 32 +10.34%
BenchmarkXMLAbsURLSrcset 27 30 +11.11%
BenchmarkXMLAbsURL 12 14 +16.67%
benchmark old bytes new bytes delta
BenchmarkAbsURL 3154 3404 +7.93%
BenchmarkAbsURLSrcset 2376 2573 +8.29%
BenchmarkXMLAbsURLSrcset 2569 2763 +7.55%
BenchmarkXMLAbsURL 1888 1998 +5.83%
```
Fixes#1104Fixes#622Fixes#937Fixes#157
Added bit about how the 404.html page has to be set to load automatically - auto on Github but needs config on other web servers.
Also tweaked the text a little to emphasize it's a node type, and explain a little more about where the 404 template should be saved.
Create new field in Node
Update Page to look for lastmod field in the front matter. If not present, then assign Date to Lastmod
Update Site, to assign a value to Lastmod (based on the same logic used for Date)
Fixes#733
`404.html` needs to be that and not `/404/` in the root.
There seem to be content pages in the wild with the name `404` (Hugo docs),
so this commit adds an extra check so only root 404 pages ignore the `uglifyURLs`setting.
Fixes#1140
Pretty sure it has worked at some point, but that PR probably has been rebased to pieces.
This refactors the fix by @dannys42 into a method, as this URL fix is applied several places.
Fixes#1114
Many minor fixes to make test logs more consistent and correct a
mispelling.
Standardize on "[%i] got X but expected Y" for log messages. Using
a consistent layout makes it easier to read the test results. This
was mostly changing "Got" to "got". Swapped the order of values on
several calls to bring them in line with the convention.
A few log messages had a sequence number added to identify the
exact scenario that failed. Otherwise, there would be no way to
ascertain which failed When there are many scenarios.
Correct spelling of "expected."
Fixes#1028
Merged be2097e1ad
[close#1040]
The current menu system works great, but is too much work if all you want is a simple menu with the sections as menu items, and having these menu items connected to the pages in a way that enables setting the correct menu item as active for both the section lists and the pages itself.
This commit adds a new option `SectionPagesMenu' which, if set, will create a new menu with that name with all the sections as menu items. The pages in the sections will behave as "shadow members" of these section items as `blogpage.HasMenuCurrent "sectionmenu" $sectionmenuitem` will return true.
If a menu item with the same `identifier` is defined in site config, *that* item will take precedence.
Bind by default to 127.0.0.1. Previously it always bound to all interfaces.
Always have log message display that the server is available on the
interface to which it is bound, instead of the baseUrl.
Fixes#1097
Speed is about the same as before, uses slightly less memory:
```
benchmark old ns/op new ns/op delta
BenchmarkAbsURL 17302 17713 +2.38%
BenchmarkXMLAbsURL 9463 9470 +0.07%
benchmark old allocs new allocs delta
BenchmarkAbsURL 28 24 -14.29%
BenchmarkXMLAbsURL 14 12 -14.29%
benchmark old bytes new bytes delta
BenchmarkAbsURL 3422 3144 -8.12%
BenchmarkXMLAbsURL 1985 1864 -6.10%
```
Fixes#1059
Related to @bjornerik 's answer in this discussion: http://discuss.gohugo.io/t/inserting-data-from-data-file-into-content-file-newbie-question/1002/3 ... I figured I'd make myself useful and add the reference to the index function, on the go template primer page.
Also, I moved the reference links to the bottom.
A general comment: as good as these docs are, the primer at this point makes some assumptions about audience knowledge, so some might find it lacking. Once I understand better, I might make some more clarifying edits.
A couple of edits to clarify that the layout/partials folder can contain arbitrarily-named subfolders, since I found the examples using ``{{ partial "post/tag/list" . }}`` confusing. Some folders are named specifically to work a certain way with hugo, but although the examples use key functional section and taxonomy names like post and tag, it does not matter what they are called. Hopefully this will help other newbs.
The previous implementation didn't easily support the use case "I want one base template for the single pages, another for the rest".
The new lookup order is:
1. <current-path>/<template-name>-baseof.ace, e.g. list-baseof.ace
2. <current-path>/baseof.ace
3. _default/<template-name>-baseof.ace, e.g. list-baseof.ace.
4. _default/baseof.ace
One of the first things that new users have to understand is the
difference between Hugo as a web server and Hugo as a web site
generator. Issue #852 asked for documentation to make that clear.
This patch updates the overview page with that information. It will
seem repetitive to users that understand the difference. Weigh that
against the needs of those that don't.
Reference #852
Fixes part of issue 1030. Previously hugo only listed the content
directory as being watched. Now we list all files being watched
according to `commands.getDirList()`. We also introduce a RemoveSubpaths
function and test in the helpers module to reduce noise in the command
line output by not showing subdirectories of ones already being watched.
For example, instead of:
`Watching for changes in $HOME/blog/content`
We get:
`Watching for changes in
$HOME/blog/{data,content,layouts,static,themes/my-theme}`
`Paginate`now returns error when
1) `.Paginate` is called after `.Paginator`
2) `.Paginate` is repeatedly called with different arguments
This should help remove some confusion.
This commit also introduces DistinctErrorLogger, to prevent spamming the log for duplicate rendering errors from the pagers.
Fixes#993
Adds step-by-step instructions for installing from both brew and
the official tarball. Not sure if steps for installing from source
belong here, so left them out.
Fixes#1005
As views looks like a regular template, but doesn't need a base template, we have to look inside it.
Altough really not needed by this commit, reading the full file content into memory just to do a substring search is a waste.
So this commit implements a `ReaderContains` func that in most cases should be much faster than doing an `ioutil.ReadAll` and `bytes.Contains`:
```
benchmark old ns/op new ns/op delta
BenchmarkReaderContains 78452 20260 -74.18%
benchmark old allocs new allocs delta
BenchmarkReaderContains 46 20 -56.52%
benchmark old bytes new bytes delta
BenchmarkReaderContains 46496 1258 -97.29%
```
Fixes#999
Commit 358dcce supposedly added ".adoc" extension recognition
for AsciiDoc, but one place was missed.
Thanks to @sjfloat for reporting the bug!
See discussions at #470.
That is whas was implemented, not Substr.
Also make the API more similar to Go's internal slice by making both the start and end indices optional.
See #990
This commit adds the interface ContentReWriter in the tranformer chain.
This is backed by two pooled byte buffers, alternating between being the reader or the writer.
This keeps the performance characteristic of the old implementation, but in a thread safe way.
Fixes#911
Benchmark old vs new:
benchmark old ns/op new ns/op delta
BenchmarkAbsURL 17614 17384 -1.31%
BenchmarkXMLAbsURL 9431 9248 -1.94%
benchmark old allocs new allocs delta
BenchmarkAbsURL 24 28 +16.67%
BenchmarkXMLAbsURL 12 14 +16.67%
benchmark old bytes new bytes delta
BenchmarkAbsURL 3295 3424 +3.92%
BenchmarkXMLAbsURL 1954 1987 +1.69%
Put version handling into the helpers package so it can be used by many,
and split version and suffix to make it possible to calculate the next Hugo version.
Thanks to @bep's new, brilliant helpers.Deprecated() function,
the following functions or variables are transitioned to their
new names, preserving backward compatibility for v0.14
and warning the user of upcoming obsolescence in v0.15:
* .Url → .URL (for node, menu and paginator)
* .Site.BaseUrl → .Site.BaseURL
* .Site.Indexes → .Site.Taxonomies
* .Site.Recent → .Site.Pages
* getJson → getJSON
* getCsv → getCSV
* safeHtml → safeHTML
* safeCss → safeCSS
* safeUrl → safeURL
Also fix related initialisms in strings and comments.
Continued effort in fixing #959.
See #470
* Based on existing support for reStructuredText files
* Handles content files with extensions `.asciidoc` and `.ad`
* Pipes content through `asciidoctor --safe -`.
If `asciidoctor` is not installed, then `asciidoc --safe -`.
* To make sure `asciidoctor` or `asciidoc` is found, after adding
a piece of AsciiDoc content, run `hugo` with the `-v` flag
and look for this message:
INFO: 2015/01/23 Rendering with /usr/bin/asciidoctor ...
Caveats:
* The final "Last updated" timestamp is currently not stripped.
* When `hugo` is run with `-v`, you may see a lot of these messages
INFO: 2015/01/23 Rendering with /usr/bin/asciidoctor ...
if you have lots of `*.ad`, `*.adoc` or `*.asciidoc` files.
* Some versions of `asciidoc` may have trouble with its safe mode.
To test if you are affected, try this:
$ echo "Hello" | asciidoc --safe -
asciidoc: ERROR: unsafe: ifeval invalid
asciidoc: FAILED: ifeval invalid safe document
If so, I recommend that you install `asciidoctor` instead.
Feedback and patches welcome!
Ideally, we should be using https://github.com/VonC/asciidocgo,
@VonC's wonderful Go implementation of Asciidoctor. However,
there is still a bit of work needed for asciidocgo to expose
its API so that Hugo can actually use it.
Until then, hope this "experimental AsciiDoc support through external
helpers" can serve as a stopgap solution for our community. :-)
2015-01-30: Updated for the replaceShortcodeTokens() syntax change
2015-02-21: Add `.adoc` extension as suggested by @Fale
Conflicts:
helpers/content.go
The `hugo help` output as shown in http://gohugo.io/overview/usage/
was not yet updated for v0.13. Thanks to @alebaffa for the heads up!
Also:
- Clarify that, after using `hugo server`, the bare `hugo` command
need to be run before deployment.
- Add a section on running `hugo` as production web server,
and add links to two blog posts of two Hugo users sharing
their experience.
Partially fixes: #852 and #937
First step to use initialisms that golint suggests,
for example:
Line 116: func GetHtmlRenderer should be GetHTMLRenderer
as see on http://goreportcard.com/report/spf13/hugo
Thanks to @bep for the idea!
Note that command-line flags (cobra and pflag)
as well as struct fields like .BaseUrl and .Url
that are used in Go HTML templates need more work
to maintain backward-compatibility, and thus
are NOT yet dealt with in this commit.
First step in fixing #959.
A local `node_modules` directory can easily contain
tens of thousands of files, easily exhausting the tiny
default max open files limit especially on OS X Yosemite,
in spite of the fact that Hugo already had code in place
since February 2014 to try to raise the maxfiles ulimit.
Also skip `.git` and `bower_components` directories.
The file watching situation will improve when
https://github.com/go-fsnotify/fsevents become ready,
but until then, we will be thrifty. :-)
Thanks to @chibicode for the suggestion.
See #168 for continued discussions.
The extra step isn't needed and this makes the code simpler.
And slightly faster:
benchmark old ns/op new ns/op delta
BenchmarkAbsUrl 19987 17498 -12.45%
BenchmarkXmlAbsUrl 10606 9503 -10.40%
benchmark old allocs new allocs delta
BenchmarkAbsUrl 28 24 -14.29%
BenchmarkXmlAbsUrl 14 12 -14.29%
benchmark old bytes new bytes delta
BenchmarkAbsUrl 3512 3297 -6.12%
BenchmarkXmlAbsUrl 2059 1963 -4.66%
`eq` and `ne` template functions don't work as expected when those are
used with a raw number and a calculated value by add, sub etc. It's
caused by both numbers type differences. For example, `eq 5 (add 2 3)`
returns `false` because raw 5 is `int` while `add 2 3` returns 5 with
`int64`
This normalizes `int`, `uint` and `float` type values to `int64`,
`uint64` and `float64` before comparing them. Other type of value is
passed to comparing function without any changes.
Fix#961
...
Prevent 404.html from prettifying into 404/index.html
Restore @realchaseadams's commit 348e123
"Force `UglyUrls` option to force `404.html` file name"
which got lost after some refactoring (commit 8db3c0b).
Remove the equivalent "force `UglyUrls`" code for `sitemap.xml`
because the refactored code now calls `renderAndWriteXML()`
which uses `WriteDestFile()` which does not prettify a filename.
Fixes#939 (reverted from commit c4c19ad303)
Restore @realchaseadams's commit 348e123
"Force `UglyUrls` option to force `404.html` file name"
which got lost after some refactoring (commit 8db3c0b).
Remove the equivalent "force `UglyUrls`" code for `sitemap.xml`
because the refactored code now calls `renderAndWriteXML()`
which uses `WriteDestFile()` which does not prettify a filename.
Fixes#939
See https://github.com/spf13/hugo/releases
What a pleasant surprise indeed!
How come I have never noticed them before?
And even `.deb` files are provided! How amazing!
Quote from @spf13: "I also think it's the better default
and should continue to be the case going forward."
Also mention the use of `hugo config` to check the current value
of `canonifyurls`, thanks to suggestion by @bep.
Fixes#802
- Clarify that Hugo may be built wherever Go is available;
- Add links to Git, Mercurial and Go;
- Unlist Bazaar: No libraries that Hugo depends on use it any more;
- Suggest the user to simply run `make` to build `hugo`
to get `hugo version` to display the commit hash.
Make sure that the file separator is added to the temp dir in all cases.
This prevents cache temp files being written to the root temp folder.
Fixes#910
Temporary workaround for the bug fix and resulting
behavioral change in purell.NormalizeURLString():
a leading '/' was inadvertently to relative links,
but no longer, see #878.
I think the real solution is to allow Hugo to
make relative URL with relative path,
e.g. "../../post/hello-again/", as wished by users
in issues #157, #622, etc., without forcing
relative URLs to begin with '/'.
Once the fixes are in, let's remove this kludge
and restore SanitizeUrl() to the way it was.
Fixes#878
Rationale: Test failing on Windows with errors like this:
utils_test.go:177: Error: Could not remove file "f".
Error: remove C:\Users\appveyor\AppData\Local\Temp\utils_test_747965610:
The process cannot access the file because it is being used by another
process.
This reverts commit 6b28e38cea.
Sorry for my premature merge of Pull Request #818.
And looks even faster:
Compared to previous attempt:
benchmark old ns/op new ns/op delta
BenchmarkAbsUrl 30902 27206 -11.96%
BenchmarkXmlAbsUrl 15389 14216 -7.62%
benchmark old allocs new allocs delta
BenchmarkAbsUrl 33 28 -15.15%
BenchmarkXmlAbsUrl 16 14 -12.50%
benchmark old bytes new bytes delta
BenchmarkAbsUrl 4167 3504 -15.91%
BenchmarkXmlAbsUrl 2057 2048 -0.44%
Compared to before I started all of this:
benchmark old ns/op new ns/op delta
BenchmarkAbsUrl 36219 27206 -24.88%
BenchmarkXmlAbsUrl 23903 14216 -40.53%
benchmark old allocs new allocs delta
BenchmarkAbsUrl 60 28 -53.33%
BenchmarkXmlAbsUrl 30 14 -53.33%
benchmark old bytes new bytes delta
BenchmarkAbsUrl 5842 3504 -40.02%
BenchmarkXmlAbsUrl 3754 2048 -45.44%
Fixes#816
This commit expands the test coverage for the utils/utils.go module.
The utils module uses the 'github.com/spf13/jwalterweatherman' (aka jww)
package for logging. The tests take the approach of examining the log
file that is produced by this module to verify correct behaviour. This
avoids refactoring the utils module.
The log file messages written by the jww module are of the form:
<log level>: yyyy/mm/dd <string|error message>
The checkLogFile function checks each of these parts in turn except for
the date string, which is currently ignored. The final part of the log
file format can either be a single error message, or a series of
strings followed by an error message. Both the error message and the
series of strings can be empty strings.
The log file is checked using a combination of the regex package,
along with the bufio scanner type. Each test logs to its own temporary
log file. This is achieved with standard test setup and teardown
functions.
One consequence of these tests is that StopOnErr has been refactored
into call a new unexported function doStopOnErr which contains the bulk
of the original logic. This allows the same testing approach to be used
with StopOnErr as with CheckErr and cutUsageMessage, rather than look at
the exit status code of the test itself.
An unfortunate side effect of this is that the author of the tests must
now know if a log file is expected or not. If doStopOnErr determines
that an empty error message would be written to the log file then
nothing is written. In the context of the tests this means that the log
file created by the test would have no contents. Consequently there
would be nothing for the test to examine. This situation is indicated by
the boolean flag logFileExoected in the testData struct, and processed
by the logFileIsExpectedAndValid function.
Although not ideal this was deemed a reasonable compromise.
Some variables are currently not documented and others are explained
across the document. So, I tried to pull an overview from the source.
Pls double check. I am not 100% sure, what the purpose of some variables
is or whether they are only relevant for previous versions. Thanks
This commit replaces the multuple `bytes.Containts` and `bytes.Replace` with a custom replacer that does one pass through the document and exploits the fact that there are two common prefixes we search for, `src=` and `href=`.
This is both faster and consumes less memory. There may be even better algos to use here, but we must leave some room for improvements for future versions.
This should also make it possible to solve #816.
```
benchmark old ns/op new ns/op delta
BenchmarkAbsUrl 25795 22597 -12.40%
BenchmarkXmlAbsUrl 17187 11166 -35.03%
benchmark old allocs new allocs delta
BenchmarkAbsUrl 60 33 -45.00%
BenchmarkXmlAbsUrl 30 16 -46.67%
benchmark old bytes new bytes delta
BenchmarkAbsUrl 5844 4167 -28.70%
BenchmarkXmlAbsUrl 3754 2069 -44.89%
```
Fixes#894
- Add copyright years and author to the top of the file
- Write the current year from time.Now() to LICENSE.md
- Correct comment regarding `os.MkdirAll(p, 0777)`
- In createConfig(), split the `map[string]string` definition into
multiple lines to facilitate future expansion. Also add a trailing
slash to sample "baseurl" definition.
- Update theme.toml template to match that listed at
https://github.com/spf13/hugoThemes/blob/master/README.md#themetoml
See #883 for an equivalent `struct` implementation
So that the date would come out correctly with
variations like `MetaDataFormat = "YAML"` in addition to
the normally expected `MetaDataFormat = "yaml"`.
Fixes#865.
Allocates less memory:
benchmark old ns/op new ns/op delta
BenchmarkStripHTML 6572 6695 +1.87%
benchmark old allocs new allocs delta
BenchmarkStripHTML 5 4 -20.00%
benchmark old bytes new bytes delta
BenchmarkStripHTML 848 737 -13.09%
Compared to 0.12:
benchmark old ns/op new ns/op delta
BenchmarkStripHTML 10210 6695 -34.43%
benchmark old allocs new allocs delta
BenchmarkStripHTML 6 4 -33.33%
benchmark old bytes new bytes delta
BenchmarkStripHTML 1456 737 -49.38%
go test -test.run=NONE -bench=".*" -test.benchmem=true ./helpers
Old vs new impl (string.Replace vs string.Replacer):
benchmark old ns/op new ns/op delta
BenchmarkStripHTML 10210 6572 -35.63%
benchmark old allocs new allocs delta
BenchmarkStripHTML 6 5 -16.67%
benchmark old bytes new bytes delta
BenchmarkStripHTML 1456 848 -41.76%
Tighten README for the sloppy reader
Tighten README for the sloppy reader
Fixing heads
tigheten markdown
tighten markdown
tighten markdown
tinker with headings
tinker with wording
fixing period spacing
moving the any dir stuff into the feature section
tweak overview
tweak overview
fixed option too
fix break:
Added a new Template.PrintErrors() function call,
used in hugolib/site.go#Process() so it does not clutter
up `go test -v ./...` results.
Special thanks to @tatsushid for mapping out the call trace
which makes it a lot easier to find the appropriate places
to place the Template.PrintErrors() call.
Fixes#316
The variable scope in the Go templates makes it hard, if possible at all, to write templates with counter variables or similar state.
This commit fixes that by adding a writable context to Node, backed by a map: Scratch.
This context has three methods, Get, Set and Add. The Add is tailored for counter variables, but can be used for any built-in numeric values or strings.
Use `{{ if not .Date.IsZero }}` to print dates only when they are
defined. This is to avoid things like
<lastBuildDate>Mon, 01 Jan 0001 00:00:00 +0000</lastBuildDate>
and
<lastmod>0001-01-01T00:00:00+00:00</lastmod>
showing up in index.xml (RSS) and sitemap.xml.
Pipe dates with ±hh:mm time zone through `safeHtml`
to prevent the `+` sign from turning into `+`.
Also make some shuffling to avoid blank lines in the output.
The paths were seen as changed but not static because of the backslashes in
ev.Name. Once the backslashes were added, I discovered that the JSON
sent to livereload was invalid and failed to work because it had backslashes.
Hence the code to replace the backslashes from the path to make them work
in JSON and for the URL.
With this fix, changes to a stylesheet are shown on the page, and if it's a
single file that changed, it's reflected in the browser without reloading the whole
page.
* Add meta author, description and generator tags
* Add Hugo version beside the logo and in the footer
* Suggest the user to run `go get -u -v` to update dependencies
* Requires Go 1.3+ rather than Go 1.1+
* Improve rendering/formatting in some places
* Add trailing slash to URLs where appropriate
* GitHub redirects all http requests to https, update accordingly
On Windows the binary name is hugo.exe and running hugo version results in
this error:
GetFileAttributesEx D:\Dev\Go\gopath\bin\hugo: The system cannot find the file specified.
This fixes that error and allows the binary name to be something other
than hugo on any OS.
Two new configuration properties, `Paginate` (default `0`) and `PaginatePath` (default `page`) are added.
Setting `paginate` to a positive value will split the list pages for the home page, sections and taxonomies into chunks of size of the `paginate` property.
A `.Paginator` is provided to help building a pager menu.
There are two ways to configure a `.Paginator`:
1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for "that page" (`.Data.Pages` will (like today) contain all the pages).
2. Select a sub-set of the pages with the available template functions and pass the slice to `.Paginate` : `{{ range (.Paginate (where .Data.Pages "Type" "post")).Pages }}`
**NOTE:** For a given Node, it's one of the options above. It's perfectly legitimate to iterate over the same pager more than once, but it's static and cannot change.
The `.Paginator` contains enough information to build a full-blown paginator interface.
The pages are built on the form (note: BLANK means no value, i.e. home page):
```
[SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
[SECTION/TAXONOMY/BLANK]/page/2/index.html
....
```
Fixes#96
When we have an absolute menu url specified in the config file
(e.g., `menu: { main: { name: "News", url: "/news" } }`),
its menu entry is generated by prefixing it with the BaseUrl.
The result is then run through prepUrl(), which uses helpers.Urlize to
convert urls such as 'My First Link' to 'my-first-link'.
The behaviour is backwards: we do not want to run helpers.Urlize on the
BaseUrl, only on the absolute component. Currently, a BaseUrl such as
'http://my.edu/ENG101' will be converted to 'http://my.edu/eng101',
resulting in broken links in all of my menus.
This commit switches the URL prep and BaseUrl prepending actions around. I
would argue that these URLs shouldn't be run through prepUrl anyway
because the site developer has specified them explicitly in a config file
and might be surprised for, e.g., URLs to change case, but that's another
commit for another time.
Make Blackfriday's `HTML_SMARTYPANTS_FRACTIONS` option
user-configurable. Defaults to `true` as before. See
discussions at:
http://discuss.gohugo.io/t/any-way-to-disable-smart-fractions/328
Thanks to @bjornerik and @spf13 for laying the groundwork
making it easy to expose Blackfriday's underlying configurable
options.
Setting per-page Blackfriday angledQuotes did not work
with TOML or JSON front matter, but it does work with YAML.
It turns out that page.Params("blackfriday") returns
type map[interface{}]interface{} for YAML, but
type map[string]interface{} for JSON and TOML.
This patch updates page.GetParam() to catch the latter,
with an error message if page.GetParam() does not recognize
a type. A test is also added.
If an archetype has deliberately empty front matter (e.g., to suppress
generation of the 'draft' field or to force a particular front matter type
instead of the default TOML), we should handle it gracefully rather than
panic ("assignment to entry in nil map").
canonifyUrls=true, RelPermalink and baseUrl with sub-path did not work.
This fixes that by adding a check for canonifyUrl=trues=true in RelPermalink().
So given
- baseUrl "http://somehost.com/sub/"
- the path "some-path/file.html"
For canonifyUrls=false RelPermalink() returns "/sub/some-path/file.html"
For canonifyUrls=true RelPermalink() returns "/some-path/file.html"
In the last case, the Url will be made absolute and clickable in a later step.
This commit also makes the menu urls defined in site config releative. To make them work with canonifying of urls, the context root is prepended if canonifying is turned off.
Fixes#519Fixes#711
This map can potentially be used many times for a given page, and altough the cost of re-creating the map should be minimal, caching it is simple -- and could save some GC and CPU cycles.
(Experimental) reStructuredText support was working in v0.12,
but was no longer handled after some refactoring in v0.13-DEV.
That experimental support is now restored.
Furthermore, check for both rst2html and rst2html.py in the PATH,
and execute whichever is found.
See #472 for more information.
Instead of `strings.TrimSpace()`, use `strings.Join(strings.Fields(s), " ")`
to collapse all whitespaces into single spaces, in order to match the
behaviour of helpers.TruncateWordsToWholeSentence(),
in order to detect non-truncated content correctly.
* template: _internal/_default/opengraph.html:39: unexpected EOF
* template: _internal/_default/schema.html:15: unexpected {{end}}
Also change the DateTime inside these templates to ISO 8601 format,
and skip <meta itemprop="datePublished"> if `publishdate` is not set.
Perhaps it would be a good idea to expose `func (Time) IsZero`
to our templates? :-)
- Add `safeUrl` template function (Fixes#347)
- Add TestSafeUrl() fashioned after @tatsushid great examples
- Disable `safeHtmlAttr` pending further discussions on its other
use cases because `safeUrl` is a cleaner solution to #347.
(There are also `safeJs` and `safeJsStr` that we could implement
if there are legitimate demands for them.)
- Rename `safeCSS` to `safeCss` (to follow the convention of `safeHtml`)
- Add/expand documentation on `safeHtml`, `safeCss` and `safeUrl`
This allows a template user to keep a safe HTML attribute or CSS string
as is in a template.
This is implementation of @anthonyfok great insight
Fix#784, #347
Found on @spf13's Twitter. :-)
Prevent the testimonial dates from wrapping.
Also fix a few minor problems to get the home page
to validate as proper HTML5.
Extracted from https://www.freebsd.org/logo/logo-simple.svg
for temporary use until a future Font Awesome release adds
the `fa-freebsd` glyph (github/FortAwesome/Font-Awesome#1116) :-)
Make .fa `display: inline` to prevent unwanted line-wrapping
Also make the menu item "Issue & Help" line up with the others.
Hopefully making them more semantic and easier to read,
though it is raw HTML so it is slightly more work to maintain.
Also made minor revisions to some of the variable descriptions
to be more informative, e.g. `:monthname` in permalinks use
full English names ("January" etc.)
Added Version, CommitHash and BuildDate to hugolib/hugo.go and used it in build
Removed commitHash and buildDate from commands/version.go and used hugolib vars
Removed getDateFormat function from commands/version.go
Conflicts:
README.md
docs/content/templates/variables.md
* Add link to https://travis-ci.org/spf13/hugo
* Correct heading levels in docs/content/community/mailing-list.md
* Mention RFC 3339 as the `date` format set by `hugo new`
* Mention that `hugo new` does not add `draft = true` when the user
provides an archetype
* List short examples of TOML and YAML side by side
* Compact the Math template functions into a table
* Put some notes into a blockquote
Make the sidebar menu slightly wider so the arrow
does not get pushed to the next line.
Also remove `text-transform: capitalize;` so we can have,
e.g., "Table of Contents" rather than "Table Of Contents".
When a user uses Vim to open a file, it briefly creates a
".filename.md.swx" file which needlessly triggers a website rebuild.
According to a comment in Vim's src/memline.c:
/*
* on MS-DOS compatible filesystems (e.g. messydos) file.doc.swp
* and file.doc are the same file. To guess if this problem is
* present try if file.doc.swx exists. If it does, we set
* buf->b_shortname and try file_doc.swp (dots replaced by
* underscores for this file), and try again. If it doesn't we
* assume that "file.doc.swp" already exists.
*/
General revisions to (hopefully) make the documentation
easier to understand and more comprehensive.
Revise "Strange EOF error" troubleshooting page to say that
a fix is in place for the upcoming Hugo v0.13.
Also add more external links, and cute icons from Font Awesome.
While following the github pages tutorial I found some issues. These are
the commands I ran that worked.
Added site variables to the docs from the code.
RSS 2.0 requires the email be listed in `<author>`,
and `UTC` as a timezone is not accepted, but `UT` or `GMT` are.
See #789 for more information. Thanks to @snej for the report!
This rewrites `extractFrontMatterDelims` function to make it work with
an archetype file without the final EOL and adds more detailed error
messages and comments.
It also removes `matches` and `matches_quick` functions which aren't
called anywhere.
- Change "livereload" and "live reload" to "LiveReload";
- Add a `$ ` prompt before example command lines
(not exhaustive, work in progress);
- Remove unnecessary whitespace from partials;
- Revise the blackfriday options table in overview/configuration.md
to make it narrower.
- Manually set the language for highlight.js where appropriate
- Rename "404" to "Custom 404 page", and remove incorrect reference
to "homepage"
- Credit the author of tutorials/github_pages_blog.md
(Similar notes are necessary for other contributed pages where
"I" am not spf13 to avoid reader confusion.)
- Add CSS for `kbd` and `table` etc. to css/style.css;
- etc.
Before this commit any error (typically a YAML typing error in front matter) would exit server on rebuild when running `hugo server -w`.
This is very annoying as it doesn't give you any chance to fix the typo other than doing a manual restart.
This commit fixes that by just logging these errors when these rebuilds happen when changes are detected.
Fixes#781
With two entries of frequently encountered or obscured troubles so far:
- "Categories with accented characters" Unicode NFC/NFD mismatch
on Mac OS X (See #739)
- `hugo new` aborts with cryptic EOF error (See #776)
This changes `echoParam` template function behavior to accept not only
an array or a slice and its index pair but also a map and its key pair.
This also changes the function that float and uint values are treated as
a valid result type of it.
Fix#771
I was initially confused about how to use summaries. The only example code I found in the docs was on the page for list nodes, but that uses `Render "summary"`, which is for views, not an article summary. I thought a little example here might clarify the issue for future users.
Having correct dates is important in Hugo. Previously date parsing errors were swallowed, leading to confusing results.
This commit adds ERROR logging when date or publishdate in front matter cannot be parsed into a time.Time.
It allows to use `where` template function like SQL `where` clause.
For example,
{{ range where .Data.Pages "Type" "!=" "post" }}
{{ .Content }}
{{ end }}
Now these operators are implemented:
=, ==, eq, !=, <>, ne, >=, ge, >, gt, <=, le, <, lt, in, not in
It also fixes `TestWhere` more readable
'where' template function used to accept only each element's struct
field name, method name and map key name as its second argument. This
extends it to accept dot chaining key like 'Params.foo.bar' as the
argument. It evaluates sub elements of each array elements and checks it
matches the third argument value.
Typical use case would be for filtering Pages by user defined front
matter value. For example, to filter pages which have 'Params.foo.bar'
and its value is 'baz', it is used like
{{ range where .Data.Pages "Params.foo.bar" "baz" }}
{{ .Content }}
{{ end }}
It ignores all leading and trailing dots so it can also be used with
".Params.foo.bar"
The flag `HTML_SMARTYPANTS_ANGLED_QUOTES` was added to Blackfriday on Black Friday. This configures rendering of double quotes as angled left and right quotes («
»).
Typical use cases would be either or, or combined, but never in the same
document. As an example would be a person from Norway; he has a blog in both
English and Norwegian (his native tongue); he would then configure Blackfriday
to use angled quotes for the Norwegian section, but keep them as reqular
double quotes for the English.
This commit adds configuration support for this new flag, configuration that can be set in the site configuration, but overridden in page front matter.
Fixes#605
Menu urls like /categories/новости-проекта would turn into /categories/d0bdd0bed0b2d0bed181d182d0b8-d0bfd180d0bed0b5d0bad182d0b0, which is illegal, while the directory under the categories/ is created with the original name. It results in 404 not found error.
This commit fixes that by make sure that SanitizeUrl() is called last.
Fixes#719
Since commit 3a8c12418a dated 2014-12-09,
commands.buildDate expects `date +%FT%T%z` rather than `date +%FT%T`.
Update README.md accordingly.
Also did a little copyediting.
- Rejigged the weight of the extras/ content for the new crossreferences
page.
- Used the new {{</*…*/>}} format for documenting highlighting and to
prevent a warning about the missing `fig` shortcode.
- `.Ref` and `.RelRef` take a reference (the logical filename for a
page, including extension and/or a document fragment ID) and return
a permalink (or relative permalink) to the referenced document.
- If the reference is a page name (such as `about.md`), the page
will be discovered and the permalink will be returned: `/about/`
- If the reference is a page name with a fragment (such as
`about.md#who`), the page will be discovered and used to add the
`page.UniqueID()` to the resulting fragment and permalink:
`/about/#who:deadbeef`.
- If the reference is a fragment and `.*Ref` has been called from
a `Node` or `SiteInfo`, it will be returned as is: `#who`.
- If the reference is a fragment and `.*Ref` has been called from
a `Page`, it will be returned with the page’s unique ID:
`#who:deadbeef`.
- `.*Ref` can be called from either `Node`, `SiteInfo` (e.g.,
`Node.Site`), `Page` objects, or `ShortcodeWithPage` objects in
templates.
- `.*Ref` cannot be used in content, so two shortcodes have been
created to provide the functionality to content: `ref` and `relref`.
These are intended to be used within markup, like `[Who]({{% ref
about.md#who %}})` or `<a href="{{% ref about.md#who %}}">Who</a>`.
- There are also `ref` and `relref` template functions (used to create
the shortcodes) that expect a `Page` or `Node` object and the
reference string (e.g., `{{ relref . "about.md" }}` or `{{
"about.md" | ref . }}`). It actually looks for `.*Ref` as defined on
`Node` or `Page` objects.
- Shortcode handling had to use a *differently unique* wrapper in
`createShortcodePlaceholder` because of the way that the `ref` and
`relref` are intended to be used in content.
filepath.Walk does not follow symbolic links.
There's no easy fix for that outside of Go, so the best we can do for now is to give notice to the end user by ERROR log statements.
This commit also fixes a related panic situation in GenerateTemplateNameFrom when the layout dir was a symbolic link.
Fixes#283
File handling was broken on Windows. This commit contains a revision of the path handling with separation of file paths and urls where needed.
There may be remaining issues and there may be better ways to do this, but it is easier to start that refactoring job with a set of passing tests.
Fixes#687Fixes#660
- Correct some typos
- Add backticks and commas where necessary
- Use fenced code blocks specifying "bash" as the language
to avoid weird highlighting
- Place commas outside of quotation marks surroundingn codes
to avoid possible confusion
- Suggest users to use the discussion forum rather than the
mailing list
The whole article should maybe be rewriten to have a better content flow (maybe adding a table of content), to introduce both possible strategies. But at least, the technical steps are there!
This small function feels important enough to maybe deserve more than these three lines, but this will have to do for now.
This assumes that #652 gets merged.
Enable blackfriday.EXTENSION_AUTO_HEADER_IDS to generate the name of the
header ID from the text in the header. Works for prefix and underline
headers.
- TOC extraction had to be modified to look for `<li><a href="#`>
instead of `#toc_` because of this change.
- Fixed a number of tests that depended on the presence of `toc_` with
as an `id` or as a `href` value.
- Renames the earlier parameter `footnoteref` to `documentId` as it more
accurately represents the nature of the parameter. The `documentId` is
appended to all generated headers through the new HTML renderer
parameter `HeaderIDSuffix`.
I have put the extra linker flags in a makefile to avoid having to remember the long command to get the commitHash in the version command.
See comment by tatsushid here:
https://github.com/spf13/hugo/issues/540
NB: only tested on Mac OS x 10.10.1 since that is what I have access to
The front matter convert-feature didn't work. It placed converted content in the wrong directory.
This commit fixes this by doing the smallest and safest change possible; the path logic here should maybe
be revisited and generalized.
Fixes#643
Some newly added shortcode tests compared maps in assertions.
This failed on Travis, as iteration order isn't guaranteed for maps since Go 1.
This commit fixes that by do a sort of the keys in the shortcode String() function.
- Prevent `.xml` generation for root section
- Remove redundant check for DisableRSS
- Fix permalinks for rel="alternate"
- Rename generated xml file to <type>/index.xml
- Add required description element in default template
- Make default RSS template validate on w3c (timezone format is still an issue)
Conflicts:
hugolib/site.go
- Change order of HasPrefix to match correct order
- Remove theme concatenation to _internal in last loop of
appendthemetemplates so it looks in the right place for internal
templates
Conflicts:
hugolib/site.go
This commit contains a restructuring and partial rewrite of the shortcode handling.
Prior to this commit rendering of the page content was mingled with handling of the shortcodes. This led to several oddities.
The new flow is:
1. Shortcodes are extracted from page and replaced with placeholders.
2. Shortcodes are processed and rendered
3. Page is processed
4. The placeholders are replaced with the rendered shortcodes
The handling of summaries is also made simpler by this.
This commit also introduces some other chenges:
1. distinction between shortcodes that need further processing and those who do not:
* `{{< >}}`: Typically raw HTML. Will not be processed.
* `{{% %}}`: Will be processed by the page's markup engine (Markdown or (infuture) Asciidoctor)
The above also involves a new shortcode-parser, with lexical scanning inspired by Rob Pike's talk called "Lexical Scanning in Go",
which should be easier to understand, give better error messages and perform better.
2. If you want to exclude a shortcode from being processed (for documentation etc.), the inner part of the shorcode must be commented out, i.e. `{{%/* movie 47238zzb */%}}`. See the updated shortcode section in the documentation for further examples.
The new parser supports nested shortcodes. This isn't new, but has two related design choices worth mentioning:
* The shortcodes will be rendered individually, so If both `{{< >}}` and `{{% %}}` are used in the nested hierarchy, one will be passed through the page's markdown processor, the other not.
* To avoid potential costly overhead of always looking far ahead for a possible closing tag, this implementation looks at the template itself, and is branded as a container with inner content if it contains a reference to `.Inner`
Fixes#565Fixes#480Fixes#461
And probably some others.
Following issues are fixed
1. Can't access fields and methods specified in GroupBy call
2. PagesGroup doesn't contain Pages. It's always empty.
3. When GroupBy is called with Section key, it doesn't work as expected
Update heading levels to confirm to the other tutorials. Create a similar front-matter using YAML, since I couldn't figure out how to get the menu:main:parent working as TOML.
- In `layouts/_default/taxonomy.html`, the `.Data` result does not
provide the same information that `layouts/_default/terms.html` does
for being able to identify the plural value of the term.
- This change adds `.Data.Singular` and `.Data.Plural` to provide
similar capabilities.
- This *may* be incompatible with templates that check for `{{ if ne
$taxonomy "Pages" }}` if the `page.Params` has either the singular or
plural values as keys.
FileAndExt has now be completely rewritten and now works as may
reasonably be expected. The test cases for:
ReplaceExtension
Filename
FileAndExt
now all pass.
The problem was the way path.Base was being used.
Firstly Base returns "." if the directory is empty, but it can also
return "." for the current directory, or ".." for the parent directory,
if these are the last elements in the path. Simply detecting the
presence of a "." in the returned string and truncating before the "."
does not therefore always result in a valid filename.
Secondly, Base strips any trailing slashes making is more difficult to
detect when the path does not end in a filename but in a directory name
i.e. a no filename case. Not detecting this incorrectly results in the
last directory name being returned as the filename.
The code has been updated to take account of of both situations so that:
1) An empty string for both the filename and extension is returned if the
path does not contain a filename (plus an optional extension). This
includes both the empty path case, and the ends in a directory case.
2) If the path represents a filename with an extension then both the
filename and the extension (minus any dots) are returned as non empty
strings.
3) If the path represents a filename without an extension then filename
will be returned as a non empty string (minus any dot) and the extension
will be returned as an empty string.
Updated the test cases in TestReplaceExtension to reflect the intent
of ReplaceExtension which is to accept a path and return only the file
name with a new extension. It's intentionally designed to strip out the
path and only provide the filename
Additional test cases have been added to both TestFilename and
TestFileAndExt to clarify behaviour with relative paths.
Oops, my bad.
Despite the function intending to test SafeWriteToDisk it was actually
calling WriteToDisk. WriteToDisk does not return the file exists error
that SafeWriteToDisk does, which the test checks for.
Added the new path modules test file. This replaces the old
helpers_test.go file.
The currently failing tests are:
TestReplaceExtension
TestFilename
TestFileAndExt
TestGuessSection
TestFindCWD
TestWriteToDisk
In addition the TestSafeWriteToDisk test case is currently disabled.
It will panic if enabled.
In addition there are some minor changes to path.go. They are:
Refactored MakePathToLower to simplify it.
Commented out, pending removal, Sanitize as it appears to be unused.
Fixed the resource leak in UnicodeSanitize
Conflicts:
helpers/path.go
Added the new url module test file. This replaces the original
helpers_test.go file.
The TestUrlPrep test currently fails.
The only minor change to url.go is to add some trace printf's to
UrlPrep.
Added the new general module's test file, general_test.go. This replaces the
helpers_test.go file.
There is also a minor defect fix in general.go's StripHTML function.
The correct xhtml tag for a break is <br /> not </br>. I've also removed
the unnecessary spaces before the replacement "\n".
The new test module also reflects this change.
Conflicts:
helpers/general.go
…`map[string]string` to `map[string]interface{}`.
This allows values other than `string` values to be saved to Author,
such as:
```toml
# config.toml
…
[Author]
name = "Austin Ziegler"
social-site = [ "Facebook", "Twitter", "GitHub" ]
```
My specific use-case is that I’m trying to make something work similar
whether it’s specified in `.Params.Author` or in `.Site.Author` without
introducing `.Site.Params.Author`.
`GroupBy` is modified to allow it to receive a method name argument for
example `Type` as its first argument. It is only allowed to call with
a method which takes no arguments and returns a result or a pair of
a result and an error.
The functions discussed at #443 are also added
- `ByPublishDate`: Order contents by `PublishDate` front matter variable
- `GroupByPublishDate(format, order)`: Group contents by `PublishDate`
front matter variable formatted in string like `GroupByDate`
- `GroupByParam(key, order)`: Group contents by `Param` front matter
variable specified by `key` argument
- `GroupByParamDate(key, format, order)`: Group contents by `Param`
front matter variable specified by `key` argument and formatted in
string like `GroupByDate`. It's effective against `time.Time` type
front matter variable
Prior to this commit, `HasMenuCurrent` and `IsMenuCurrent` on `Node` always returned false.
This made it hard (if possible at all) to mark the currently selected menu item/group for non-Page content (home page, category pages etc.), i.e. for menus defined in the site configuration.
This commit provides an implementation of these two methods.
Notable design choices:
* These menu items have a loose coupling to the the resources they navigate to; the `Url` is the best common identificator. To facilitate a consistent matching, and to get it in line with the menu items connected to `Page`, relative Urls (Urls starting with '/') for menu items in the site configuration are converted to permaLinks using the same rules used for others’.
* `IsMenuCurrent` only looks at the children of the current node; this is in line with the implementation on `Page`.
* Due to this loose coupling, `IsMenuCurrent` have to search downards in the tree to make sure that the node is inside the current menu. This could have been made simpler if it could answer `yes` to any match of any menu item matching the current resource.
This commit also adds a set of unit tests for the menu system.
Fixes#367
The Content-Type was not set for livereload.js and was interpreteted by the browser as text/plain.
This commit sets it to application/javascript.
Fixes#562
Prior to this commit only metadata were copied from archetype on content creation.
This commit includes the content if set in archetype. This is useful in situations with similar page structure.
Fixes#556
TOML and YAML handles integers differently, creating issues when using integer values from configuration or front matter in the First template function.
This currently works in YAML (parses into int), but not in TOML (parses into int64).
This commit modifies First so it accepts any int.
Fixes#551
The Intersect template-method would fail if one or both of the lists were nil (post vs page; post has tags, page has not).
This commit adds a nil-check and returns an empty result if any of the inputs are nil.
See #537
- Add backticks and commas where necessary
- Remove some trailing whitespace
- Add front matter example in TOML
- Fix typo in one of the tags in Showcase
- Add 多说 (Duoshuo) as an alternative to Disqus
- Use internal links (i.e. without gohugo.io) where possible
- Use a colon to set off an example
- Change "it's" to "its" where appropriate
- Use typographical (i.e. curly) apostrophe on the front page
where appropriate
- Capitalize "Github" as "GitHub"
The use of <!--more--> to set the breakpoint for the generated page summary is mentioned in a release note, but not in the doc itself.
Very useful - and it leaves the formatting in place.
If content pages are fully rendered in a list page, footnotes that use
the same reference (`[^fn]`) will have duplicated anchors. This change
builds on #526 to put the page filename (`Page.File.Name`) as part of
the anchor for a footnote.
This would fix discussion [116](http://discuss.gohugo.io/t/footnote-references-are-duplicated-on-list-pages/116).
- The config file can provide FootnoteAnchorPrefix, which will be used
by blackfriday when rendering to HTML. A value of `q:` has the effect
of making the anchor for a footnote `[^footie]` be `fn:q:footie`. The
default is `""`.
- The config file can provide FootnoteReturnLinkContents, which will be
used by blackfriday when rendering to HTML. A value of `^` has the
effect of making the return link be `^` instead of `[return]`.
updated installation page of documentation, and changed "Download" button on index.html to scroll to bottom where multiple installation options are featured
getting the scrolldown to work required removing the fixed positioning on #action and on the footer
Emphasizing to people (like me) who aren't familiar with Go that just because something's not mentioned in the Hugo docs doesn't mean it's not possible
Prior to this commit a dummy JavaScript filename was sent to LiveReload when changing a static file (CSS, image etc.), forcing a full browser reload of the page.
This commit fixes this by sending the relative file path of the changed static resource, enabling partial live reloading for CSS- and image-changes. If more than one static file happens to end up in the same changeevent-batch, it will fall back to do a full refresh. To enable this logic, the change events with names ending with ".goutputstream*" is now filtered out as temporary.
Changes in dynamic content behaves like before.
Issue #490
Node.Site.Recent is not really just recent pages, but all pages, so I figured it was better to add a new parameter with a more informative name.
I also changed the code slightly so that all pages are added to the list of pages before we start rendering shortcodes... this way you can use a shortcode to refer to another page. Previosuly, this had been broken, because the list ofg pages would not be fully populated while the shortcodes were being processed. The code that does this is not reading from disk or doing any rendering, so it shouldn't take any more time to do.
Among the various changes, most instances of
{{ template "partials/FILE.html" . }}
were changed to
{{ partial "FILE.html" . }}
Also, in main.go, change "2013" to "2013-14".
Enclose `{{ .Content }}` with a `{{ if .IsPage }}` test to avoid
the "Content is not a field of struct type *hugolib.Node" error.
Thanks to @spf13 for the tip! Fixes#366.
Also update example to Hugo v0.12 conventions:
- Convert config.yaml to config.toml to follow what
`hugo new site /path/to/site` generates
- Rename layouts/chrome to layouts/partials
- Convert `template` calls to `partial` calls
- Add .gitignore to ignore the `public` directory
- Add README.md with pointers to discussions in issues
to help bring newcomers up to speed with this multilingual example
- Convert config.yaml to config.toml to follow what
"hugo new site /path/to/site" generates
- Rename layouts/chrome to layouts/partials
- Convert "template" calls to "partial" calls
- Minor revisions to the text in example content
- Upgrade Bootswatch Yeti theme (3.1.1+1 → to 3.2.0+3)
- Upgrade Font Awesome (4.0.3 → 4.2.0)
- Upgrade jQuery (1.11.0 → 1.11.1)
The "@import url()" statement for loading Lato from Google Fonts
was ignored because "@import are not allowed after any valid statement
other than @charset and @import" according to the W3C CSS Validator.
Also remove the line for importing line-icons.css which no longer
exists.
This fixes#450. There are two problems:
1.) We're creating a new goroutine for every page.
2.) We're calling s.Pages = append(s.Pages, page) inside each goroutine.
1 is a problem if in that if you have a ton of pages, that's a ton of goroutines. It's not really useful to have more than a few goroutines at a time, and lots can actually make your code much slower, and, evidently, crash.
2 is a problem in that append is not thread safe. Sometimes it returns a new slice with a larger capacity, when the original slice isn't large enough. This can cause problems if two goroutines do this at the same time.
The solution for 1 is to use a limited number of workers (I chose 2*GOMAXPROCS as a nice guess).
The solution for 2 is to serialize access to s.Pages, which I did by doing it in a single goroutine.
Mainly this was a change to helpers.MakePermalink, but to get the local server to run correctly,
we needed to redirect the path of the request from /foo to /. In addition, I added tests for the
server's code for fixing up the base url with different config file & CLI options.
I noticed that config file changes do not work with Live Reload feature. This may be "fixed" in future but for now adding a note might avoid confusion.
It took me a long time to realize that /layouts/TYPE or SECTION/LAYOUT.html was supposed to be a single URL and not two urls (/layouts/TYPE) or (SECTION/LAYOUT.html) ... putting in the hyphens I think makes it much more clear it's all one URL, and only the middle part is an either-or.
git bisect identified 62dd1d4 as the breaking commit; when
github.com/spf13/viper was introduced, the Params field was always
empty.
Given a map in YAML in Viper, the return type is
`map[interface{}]interface{}`, _not_ `map[string]interface{}`, even if
`.SetDefault()` has been called with an item of
`map[string]interface{}{}` so the cast assertion on the `.Get("Params")`
always failed.
Viper stores Permalinks as a map[string]interface{}, so the type assertion
to PermalinkOverrides (map[string]PathPattern) will always fail.
We can, however, get Permalinks as a map[string]string, and convert each
value to a PathPattern.
When running hugo server like:
$ hugo server -s docs -b myhostname
the printed output now directs to http://myhostname:1313 instead of
(invariably) http://localhost:1313.
As per server(), BaseUrl is never empty, and the required value is always
found in Viper.
Two issues are addressed with this commit:
1. Some <pre> tags were inheriting the "Serif" font on Linux, causing
"code"-ish stuff to appear with proportional-width font instead of
monospaced-width font.
2. Font stack with "Helvetica Neue" ... has been changed to default to
sans-serif instead of "Serif", this produces a more consistent and
friendlier look on Windows in particular.
If you don't have access to the root domain of your site (eg a GitHub project
page) and you try to generate custom permalinks, they must begin with a slash.
Go's URL resolution library sees the leading slash and thinks "this URL starts
at the root", just like a filesystem - so it discards your subdomain and maps
all custom permalinks from the root of your site. Fine if you control the root
domain, not so useful if you don't.
Removing the check for a leading slash fixes this problem. You can now specify
custom permalinks that do not start with a slash, and they will map safely
regardless of what subdomain you upload the generated site under.
Tests have been updated for this commit so that they continue to function.
- previously it was ambiguous between the actual Step 1 and the "step 1" of the steps *within* Step 2 ("Clone into the hugo repository")
- also fixed a typo I guess
A photography-oriented blog using Foundation 5 by Zurb. Responsive
layout with padded large and full-width small views. A sample
"polaroid" shortcode is included for image showcases, as is a
"header" image directive in the frontmatter.
Modified markdownRender and markdownRenderWithTOC in hugolib/page.go to
use the same flags and extensions as were previously used when we simply
called blackfriday.MarkdownCommon to convert Markdown to HTML. These
flags/extensions were dropped during the refactor that added the
`.TableOfContents` page variable, and caused features like Markdown
tables to no longer work.
Modified the expected output for TestTableOfContents in page_test.go,
apparently changing the flags/extensions caused an `—` to become
`–`.
Added TableOfContents field to hugolib.Page struct. New function
getTableOfContents is used in convertMarkdown to set the TableOfContents
field.
Added new test file hugolib/page_toc_test.go with a simple test of the
new functionality.
Conflicts:
hugolib/page.go
Be able to inhibit AbsURL canonicalization of content, on a site
configuration basis. Advantages of being able to inhibit this include
making it easier to rendering on other hostnames, and being able to
include resources on http or https depending on how this page was
retrieved, avoiding mixed-mode client complaints without adding latency
for plain http.
I've added the website for the makerspace I founded into the hall of fame list as an example of what you can do with Hugo.
It's a work in progress (like everything) but should show people another example of using Hugo in the real world.
Hugo has made it much easier to update our website content without needing to use bloated or expensive tools.
Thanks!
Quite often file watcher gets many changes and each change triggered a
build. One build per second should be sufficient. Also added tracking for
new folders.
Fixed windows uses different filepath separator. The filepath.ToSlash
shouldn't be used, because it can cause errors in filepath suffix and prefix
testing since "c:\a" isn't a prefix of "c:/a/b/c".
The previous permissions (0764), were unusable (directories must
be executable) when generating files for use by another uid. The
Right Thing™ is to use mode 0777. The OS will subtract the process
umask (usually 022) to the for the final permissions.
Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
* extras/permalinks.md added, weighted to third in the extras menu
* examples added to layout/go-templates.md, using `.Site.Params`
* mention `.Site.Params` in layout/variables.md
* update meta/release-notes.md to mention `first` and the permalinks
* update overview/configuration.md to use reserved-for-documentation
domains and with another example, nudging towards permalinks and site
parameters, with three different data-types shown for the latter
Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
A sample config.yaml for a site might contain:
```yaml
permalinks:
post: /:year/:month/:title/
```
Then, any article in the `post` section, will have the canonical URL
formed via the permalink specification given.
Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
* Add `.Truncated` bool to each page; will be set true if the
`.Summary` is truncated and it's worth showing a "more" link of some
kind.
* Add `Params` to the site config, defining `.Site.Params` accessible
to each page; this lets the site maintainer associate arbitrary data
with names, on a site-wide basis.
* Provide a `First` function to templates:
* Use-case: `{{range First 5 .Site.Recent}}` or anything else which
is a simple iterable provided by hugolib
* Tests by me for `.Truncated` and `First`
Also @noahcampbell contributed towards this:
* Add UnitTest for `.Site.Params`:
> Digging into this test case a bit more, I'm realizing that we need
> to create a param test case to ensure that for each type we render
> (page, index, homepage, rss, etc.) that the proper fields are
> represented. This will help us refactor without fear in the
> future.
Sample config.yaml:
```yaml
title: "Test site"
params:
Subtitle: "More tests always good"
AuthorName: "John Doe"
SidebarRecentLimit: 5
```
Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
Remove the hugo-nav since it relied on a slow library. The current
build reimplements the absurl functionality based on string replace.
Discovered that my prior implementation missed the requirement for
making absolute paths (/path) absolute with the host, whereas a relative
path is left untouched. Updated the test cases to support this if this
is reimplemented.
Checks to make sure the xml document starts with <?xml. Previously, the
html translate package would write additional details into the document
that caused it to fail.
50% speedup. Fix#91
to run the benchmark:
go test -test.run=NONE -bench=".*" -test.benchmem=true ./transform/ > new.txt
to compare the results:
/usr/local/go/misc/benchcmp baseline.txt new.txt
Speedup and memory improvements
benchmark old ns/op new ns/op delta
BenchmarkChain 101219 50453 -50.15%
BenchmarkTransform 51625 45531 -11.80%
benchmark old allocs new allocs delta
BenchmarkChain 222 103 -53.60%
BenchmarkTransform 135 106 -21.48%
benchmark old bytes new bytes delta
BenchmarkChain 23919 10998 -54.02%
BenchmarkTransform 11858 10665 -10.06%
Removed these checks so a single file in content can generate a site.
For example, given a site with a content directory and an index.html,
running hugo -s dir will generate a project without any more input.
The render code path would use a fallback if there was an exception.
This change instead relies on explicit declaration of the layout to use
and includes a check to see if the layout indeed exists before
attempting to render it.
If a file named index.html exists in a directory, or root, it will be
rendered as if ugly urls are turned on. This allows for top level
content to not need a supporting layout file and content in content.
This change should not affect anyone who is using the perscribed way.
I also cleaned up a bunch of one off functions in site.go.
Allow content that is not markdown and does not need to be rendered to
exists in the content directory. Currently any valid html or xml
document can exist. Templates are applied to these documents as well.
If you need to have content that doesn't have templates or AbsUrlify
like operations, then continue to put this content in static and it will
be copied over.
As pages are read from the target, they will be assessed if they should
be rendered or not. The logic for IsRenderable is in the parser/page.go
and looks for anything exception '<'.
I want to move all logic to writing aliases to target so I can pave the
way for writing aliases specific to other runtimes (like .htaccess for
apache or a script for updating AWS or symlinking on a filesystem).
filepath was used inconsistently throughout the hugolib. With the
introduction of source and target modules, all path are normalized to
"/". This simplifies the processing of paths. It does mean that
contributors need to be aware of using path/filepath in any module other
than source or target is not recommended. The current exception is
hugolib/config.go
It started with wanting to move templates in template bundles and the
rest followed. I did my best to start grouping related functions
together, but there are some that I missed. There is also the method
Urlize that seems to be a special function used in both worlds. I'll
need to revisit this method.
Tests to ensure rendering dates in templates is working correctly.
Actually, I was running into invalid templates not giving warnings when
I was trying to render a date.
Introducing the target module in hugo. This provides the simple
interface for writing content given a label (filename) and a io.Reader
containing the content to be written.
If site.Target is not set, it defaults back to the original behavior of
writing to file system.
In hugolib/site_url_test.go I have an InMemoryTarget for testing
purposes and use it to see if the final output of a render matches.
Allow full control of summaries which can be rendered as html rather
than text. Using a `<!--more-->` html comment in your markdown / rst
you can indiciate where the summary should end and have the summary
converted to html.
Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
Conflicts:
hugolib/page_test.go
Provide unit test support RenderThing.
One observation is that creating the site.Tmpl variable is a one time
event. site.Tmpl doesn't like additional templates with the same name.
This means that updating a template while in --watch mode requires
throwing away the entire Site object and creating a new one. Not that
this is a bad idea, but it is something I discovered while working on
these unit tests.
An oversight on my behalf. The FromSlash method is used when writing
out the public file name. There is one place where the slashes are
required which is setting the output file. I replaced those instances
with filepath.Join which should do the right thing depending on the OS.
because the url lacks a trailing /, many webservers will issue a
redirect to the canonical url with trailing slash for directory index
w/index.htm(l).
Append a slash to avoid this.
When redirecting an alias from a .xhtml path, served with default content type,
a redirect only works if the html element has a xmlns attribute. This adds the
attribute when the alias path ends in .xhtml
sanitizeRegex was stripping dots in permalinks when generating
RenderIndexes (noted during feed/rss generation).
permalink was being set to `.../indexxml` instead of `.../index.xml`.
Adding "dot" to the regex whitelist fixed the issue.
when not using ugly urls, the feed permalink does not end up in the
expected location, and instead always behaves as if using ugly urls.
this fixes that behavior and inserts the feed xml file into the
directory as index.xml.
fixes#32
Interacting with timezones will result in checks against the filesystem.
This access, by definition, is an integration test. Creating a
*integration_test.go file will signify this change.
When interacting with Travis-ci.org, the ubuntu boxes plus go 1.1 do not
seem to support shortcode timezones, think PST. In this case, the tests
are skipped. This is not ideal, but the IRC #go-nuts channel has
indicated timezone support is still lacking. We should advise users of
hugo that timezone support may be an issue and report any odd behavior.
The workaround is to use numeric timezones (-08:00 for PST, etc.)
Any program, when asks to print their version, only prints that, and then
stops.
hugo checks the config (and prints a warning message if not found), and
proceeds to generate the site!
Yet, the user just wanted to check the version.
This patch makes sure hugo stops after printing the version.
The pflag package used in hugo has to use the "=" sign
for double dash options such as --source. Thus the original
example `--source ~/mysite` is already incorrect. Adding
the = sign though woul not fix things in this case, since
`--source=~/mysite` does not get resolved to /home/username/mysite,
but looks for the ./~/mysite directory within the current directory.
To resolve this, either the directory name has to be changed in
the docs not to use the "~" sign, or have to change to use the
single dash version of the command line flag. The latter seems
to be more in line with the rest of the example.
Leaving `--watch` as a double dash option to minimize the change,
though it could be either way, since the follow up example uses
the single dash version of both.
The filename path was being split using a unix specific path seperator. This fix uses the os.PathSeperator to ensure proper evaluation regardless of platform.
We welcome contributions to Hugo of any kind including documentation, themes, organization, tutorials, blog posts, bug reports, issues, feature requests, feature implementation, pull requests, answering questions on the forum, helping to manage issues, etc.
The Hugo community and maintainers are very active and helpful and the project benefits greatly from this activity.
If you have any questions about how to contribute or what to contribute, please ask on the [forum](http://discuss.gohugo.io).
## Code Contribution Guideline
We welcome your contributions.
To make the 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 discuss code changes.
* When you’re ready to create a pull request, be sure to:
* Sign the [CLA](https://cla-assistant.io/spf13/hugo)
* 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.
* **Write a good commit message.** 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."
* Make sure `go test ./...` passes, and `go build` completes. Our [Travis CI loop](https://travis-ci.org/spf13/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) will catch most things that are missing.
A really fast static site generator written in GoLang.
A Fast and Flexible Static Site Generator built with love by [spf13](http://spf13.com/) and [friends](https://github.com/spf13/hugo/graphs/contributors) in [Go][].
[](https://travis-ci.org/spf13/hugo)
[](https://gitter.im/spf13/hugo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Hugo is a static site generator written in GoLang. 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 makes use of markdown files with front matter for meta data.
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.
A typical website of moderate size can be
rendered in a fraction of a second. It is written to work well with any
kind of website including blogs, tumbles and docs.
# Getting Started
## Installing Hugo
Installation is very easy. Simply download the appropriate version for your
platform. Hugo is written in GoLang with support for Windows, Linux and OSX.
Please make sure that you place the executable in your path. `/usr/local/bin`
is the most probable location.
Hugo doesn't have any external dependencies, but can benefit from external
programs.
## Installing from source
Make sure you have a recent version of go installed. Hugo requires go 1.1+.
git clone https://github.com/spf13/hugo
cd hugo
go build -o hugo main.go
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.
## Source Directory Organization
Hugo is designed to work well for any kind of website including blogs, tumbles and docs.
Hugo takes a single directory and uses it as the input for creating a complete website.
#### Supported Architectures
Hugo has a very small amount of configuration, while remaining highly customizable.
It accomplishes by assuming that you will only provide templates with the intent of
using them.
Currently, we provide pre-built Hugo binaries for Windows, Linux, FreeBSD, NetBSD and OS X (Darwin) for x64, i386 and ARM architectures.
An example directory may look like:
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 9 and Solaris.
.
├── config.json
├── content
| ├── post
| | ├── firstpost.md
| | └── secondpost.md
| └── quote
| | ├── first.md
| | └── second.md
├── layouts
| ├── chrome
| | ├── header.html
| | └── footer.html
| ├── indexes
| | ├── category.html
| | ├── post.html
| | ├── quote.html
| | └── tag.html
| ├── post
| | ├── li.html
| | ├── single.html
| | └── summary.html
| ├── quote
| | ├── li.html
| | ├── single.html
| | └── summary.html
| ├── shortcodes
| | ├── img.html
| | ├── vimeo.html
| | └── youtube.html
| ├── index.html
| └── rss.xml
└── public
**Complete documentation is available at [Hugo Documentation][].**
This directory structure tells us a lot about this site:
## Choose How to Install
1. the website intends to have two different types of content, posts and quotes.
2. It will also apply two different indexes to that content, categories and tags.
3. It will be displaying content in 3 different views, a list, a summary and a full page view.
If you want to use Hugo as your site generator, simply install the Hugo binaries.
The Hugo binaries have no external dependencies.
Included with the repository is an example site ready to be rendered.
To contribute to the Hugo source code or documentation, you should [fork the Hugo GitHub project](https://github.com/spf13/hugo#fork-destination-box) and clone it to your local machine.
## Configuration
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.
The directory structure and templates provide the majority of the
configuration for a site. In fact a config file isn't even needed for many websites
since the defaults used follow commonly used patterns.
### Install Hugo as Your Site Generator (Binary Install)
The following is an example of a config file with the default values
Use the [installation instructions in the Hugo documentation](https://gohugo.io/overview/installing/).
Once the `get` completes, you should find your new `hugo` (or `hugo.exe`) executable sitting inside `$GOPATH/bin/`.
#### Indexes
An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
pages are good examples of indexes.
To update Hugo’s dependencies, use `go get` with the `-u` option.
go get -u -v github.com/spf13/hugo
#### Content Type(s)
Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability
to render content in a variety of ways as determined by the type.
## Contribute to Hugo
#### Chrome
Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice
it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may
likely find beneficial. As you create the rest of your templates you will include templates from the
/layout/chrome directory. I've found it helpful to include a header and footer template
in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html).
We welcome contributions to Hugo of any kind including documentation, themes, organization, tutorials, blog posts, bug reports, issues, feature requests, feature implementation, pull requests, answering questions on the forum, helping to manage issues, etc.
### Adding a new content type
The Hugo community and maintainers are very active and helpful and the project benefits greatly from this activity.
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
If you have any questions about how to contribute or what to contribute, please ask on the [forum](https://discuss.gohugo.io).
**Step 2:**
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
## Code Contribution Guideline
**Step 3:**
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
We welcome your contributions.
To make the process as seamless as possible, we ask for the following:
**Step 4:**
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. 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 layout/type directory with the same name.
* Go ahead and 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:
* Sign the [CLA](https://cla-assistant.io/spf13/hugo)
* 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.
* **Write a good commit message.** 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."
* Make sure `go test ./...` passes, and `go build` completes. Our [Travis CI loop](https://travis-ci.org/spf13/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) will catch most things that are missing.
For these, reviewing the example site will be very helpful in order to understand how these types work.
### Build Hugo with Your Changes
## Variables
```bash
cd /path/to/hugo
go build -o hugo main.go
mv hugo /usr/local/bin/
```
Hugo makes a set of values available to the templates. Go templates are context based. The following
are available in the context for the templates.
### Add Compile Information to Hugo
**.Title** The title for the content. <br>
**.Description** The description for the content.<br>
**.Keywords** The meta keywords for this content.<br>
**.Date** The date the content is published on.<br>
**.Indexes** These will use the field name of the plural form of the index (see tags and categories above)<br>
**.Permalink** The Permanent link for this page.<br>
**.FuzzyWordCount** The approximate number of words in the content.<br>
**.RSSLink** Link to the indexes' rss link <br>
To add compile information to Hugo, replace the `go build` command with the following *(replace `/path/to/hugo` with the actual path)*:
Any value defined in the front matter, including indexes will be made available under `.Params`.
Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
go build -ldflags "-X /path/to/hugo/hugolib.CommitHash=`git rev-parse --short HEAD 2>/dev/null` -X github.com/spf13/hugo/hugolib.BuildDate=`date +%FT%T%z`"
**.Params.Tags** <br>
**.Params.Categories** <br>
This will result in `hugo version` output that looks similar to:
Also available is `.Site` which has the following:
Hugo Static Site Generator v0.13-DEV-8042E77 buildDate: 2014-12-25T03:25:57-07:00
**.Site.BaseUrl** The base URL for the site as defined in the config.json file.<br>
**.Site.Indexes** The names of the indexes of the site.<br>
**.Site.LastChange** The date of the last change of the most recent content.<br>
**.Site.Recent** Array of all content ordered by Date, newest first<br>
Alternatively, just run `make` — all the “magic” above is already in the `Makefile`. :wink:
# Content
Hugo uses markdown files 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.
### Run Hugo
## 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.
// initHugoBuildCommonFlags initialize common flags related to the Hugo build.
// Called by initHugoBuilderFlags.
funcinitHugoBuildCommonFlags(cmd*cobra.Command){
cmd.Flags().BoolVar(&cleanDestination,"cleanDestinationDir",false,"Remove files from destination not found in static directories")
cmd.Flags().BoolVarP(&draft,"buildDrafts","D",false,"include content marked as draft")
cmd.Flags().BoolVarP(&future,"buildFuture","F",false,"include content with publishdate in the future")
cmd.Flags().BoolVar(&disable404,"disable404",false,"Do not render 404 page")
cmd.Flags().BoolVar(&disableRSS,"disableRSS",false,"Do not build RSS files")
cmd.Flags().BoolVar(&disableSitemap,"disableSitemap",false,"Do not build Sitemap file")
cmd.Flags().StringVarP(&source,"source","s","","filesystem path to read files relative from")
cmd.Flags().StringVarP(&contentDir,"contentDir","c","","filesystem path to content directory")
cmd.Flags().StringVarP(&layoutDir,"layoutDir","l","","filesystem path to layout directory")
cmd.Flags().StringVarP(&cacheDir,"cacheDir","","","filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/")
cmd.Flags().BoolVarP(&ignoreCache,"ignoreCache","",false,"Ignores the cache directory")
cmd.Flags().StringVarP(&destination,"destination","d","","filesystem path to write files to")
cmd.Flags().StringVarP(&theme,"theme","t","","theme to use (located in /themes/THEMENAME/)")
cmd.Flags().BoolVar(&uglyURLs,"uglyURLs",false,"if true, use /filename.html instead of /filename/")
cmd.Flags().BoolVar(&canonifyURLs,"canonifyURLs",false,"if true, all relative URLs will be canonicalized using baseURL")
cmd.Flags().StringVarP(&baseURL,"baseURL","b","","hostname (and path) to the root, e.g. http://spf13.com/")
cmd.Flags().BoolVar(&nitro.AnalysisOn,"stepAnalysis",false,"display memory and timing of different steps of the program")
cmd.Flags().BoolVar(&pluralizeListTitles,"pluralizeListTitles",true,"Pluralize titles in lists using inflect")
cmd.Flags().BoolVar(&preserveTaxonomyNames,"preserveTaxonomyNames",false,`Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")`)
cmd.Flags().BoolVarP(&forceSync,"forceSyncStatic","",false,"Copy all files when static is changed.")
cmd.Flags().BoolVarP(&noTimes,"noTimes","",false,"Don't sync modification time of files")
// Set bash-completion.
// Each flag must first be defined before using the SetAnnotation() call.
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 [spf13](http://spf13.com/) 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.
* Make sure `go test ./...` passes, and `go build` completes. Our [Travis CI loop](https://travis-ci.org/spf13/hugo) will catch most things that are missing. The exception: Windows. We run on Windows from time to time, but if you have access, please check on a Windows machine too.
## 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 read on. You probably know what to do.
# Building from source
## Clone locally (for contributors):
git clone https://github.com/spf13/hugo
cd hugo
go get
Because Go expects all of your libraries to be found in either
`$GOROOT` or `$GOPATH`, it's helpful to symlink the project to one
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` or `example-tn.jpg`. 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/spf13/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/spf13/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.
Know of a post, article or tutorial on Hugo? [Add it to this list](https://github.com/spf13/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 |
| ------ | ------ | -----: |
| [Webseitenmaschine - Statische Websites mit Hugo erzeugen (German / to buy)](http://www.heise.de/ct/ausgabe/2016-12-Statische-Websites-mit-Hugo-erzeugen-3211704.html ) | Christian Helmbold | 27 May 2016 |
| [CDNOverview: A CDN comparison site made with Hugo](https://www.cloakfusion.com/cdnoverview-cdn-comparison-site-made-hugo/) | Thijs de Zoete | 23 Feb 2016 |
| [Hugo: A Modern WebSite Engine That Just Works](https://github.com/shekhargulati/52-technologies-in-2016/blob/master/07-hugo/README.md) | Shekhar Gulati | 14 Feb 2016 |
| [Minify Hugo Generated HTML](http://ratson.name/blog/minify-hugo-generated-html/) | Ratson | 2 Feb 2016 |
| [Static site generators: el futuro de las webs estáticas (Hugo, Jekyll, Flask y otros)](http://sitelabs.es/static-site-generators-futuro-las-webs-estaticas/) | Eneko Sarasola | 9 Jan 2016 |
| [Writing a Lambda Function for Hugo](https://blog.jolexa.net/post/writing-a-lambda-function-for-hugo/) | Jeremy Olexa | 1 Jan 2016 |
| [Ein Blog mit Hugo erstellen - Tutorial (Deutsch/German)](http://privat.albicker.org/blog/tags/hugo/) | Bernhard Albicker | 30 Dec 2015 |
| [How to host Hugo static website generator on AWS Lambda](http://bezdelev.com/post/hugo-aws-lambda-static-website/) | Ilya Bezdelev | 15 Dec 2015 |
| [Migrating from Pelican to Hugo](http://www.softinio.com/post/migrating-from-pelican-to-hugo/) | Salar Rahmanian | 29 Nov 2015 |
| [Hugo + Uberspace + Git = Hubergit — eine Anleitung (German)](https://harms-ensink.name/post/hubergit/) | Christoph Harms-Ensink | 24 Nov 2015 |
| [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 | 12 Nov 2015 |
| [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 | 9 Nov 2015 |
| [Switching from Wordpress to Hugo](http://justinfx.com/2015/11/08/switching-from-wordpress-to-hugo/) | Justin Israel | 8 Nov 2015 |
| [Hands-on Experience with Hugo as a Static Site Generator](http://usersnap.com/blog/hands-on-experience-with-hugo-static-site-generator/) | Thomas Peham | 15 Oct 2015 |
| [Statische Webseites mit Hugo erstellen/Vortrag mit Foliensatz (deutsch)](http://sfd.koelnerlinuxtreffen.de/2015/HaraldWeidner/) | Harald Weidner | 19 Sep 2015 |
| [Moving from WordPress to Hugo](http://abhipandey.com/2015/09/moving-to-hugo/) | Abhishek Pandey | 15 Sep 2015 |
| [<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 | 29 Aug 2015 |
| [Static Site E-Commerce: Integrating Snipcart with Hugo](https://snipcart.com/blog/snipcart-hugo-integration) | Francis Tremblay | 13 Aug 2015 |
| [Hugo on Netlify — Insanely Fast Deploys](https://www.netlify.com/blog/2015/07/30/hugo-on-netlify-insanely-fast-deploys.html) | Mathias Biilmann | 30 July 2015 |
| [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 | 26 June 2015 |
| [<span lang="ja">Hugo向けの新しいテーマを作った</span> <small>(I created a new theme for Hugo)<small>](http://yet.unresolved.xyz/blog/2015/06/20/making-new-theme-robust-for-hugo/) | Daisuke Tsuji | 20 June 2015 |
| [Hugo - Gerando um site com conteúdo estático. (Portuguese Brazil)](http://blog.ffrizzo.com/posts/hugo/) | Fabiano Frizzo | 2 Jun 2015 |
| [An Introduction to Static Site Generators](http://davidwalsh.name/introduction-static-site-generators) | Eduardo Bouças | 20 May 2015 |
| [Hugo Still Rules](http://cheekycoder.com/2015/05/hugo-still-rules/) | Cheeky Coder | 18 May 2015 |
| [hugo - Static Site Generator](http://gscacco.github.io/post/hugo/) | G Scaccoio | 4 May 2015 |
| [Static Websites with Hugo on Google Cloud Storage](http://www.moxie.io/post/static-websites-with-hugo-on-google-cloud-storage/) | Moxie Input/Output | 2 Apr 2015 |
| [De nuevo iniciando un blog](http://alvarolizama.net/blog/denuevo-iniciando-un-blog/) | Alvaro Lizama | 29 Mar 2015 |
| [We moved our blog from Posthaven to Hugo after only three posts. Why?](http://blog.hypriot.com/post/moved-from-posthaven-to-hugo/) | Hypriot | 27 Mar 2015 |
| [Hugo is cool](http://tnt.wicast.tk/2015/03/23/hugo-is-cool/) <small>(<span lang="zh-CN">中文</span> Chinese)</small> | wicast | 23 Mar 2015 |
| [Top Static Site Generators in 2015](http://superdevresources.com/static-site-generators-2015/) | Kanishk Kunal | 12 Mar 2015 |
| [Moving to Hugo](http://abiosoft.com/moving-to-hugo/) | Abiola Ibrahim | 8 Mar 2015 |
| [Migrating a blog (yes, this one!) from Wordpress to Hugo](http://justindunham.net/migrating-from-wordpress-to-hugo/) | Justin Dunham | 13 Feb 2015 |
| [<span lang="ja">blogをoctopressからHugoに乗り換えたメモ</span>](http://blog.jigyakkuma.org/2015/02/11/hugo/) | jigyakkuma | 11 Feb 2015 |
| [<span lang="ja">Hugoでブログをつくった</span>](http://porgy13.github.io/post/new-hugo-blog/) | porgy13 | 7 Feb 2015 |
| [Hugo para crear sitios web estáticos](http://www.webbizarro.com/noticias/1076/hugo-para-crear-sitios-web-estaticos/) | Web Bizarro | 19 Aug 2014 |
| [Going with hugo](http://www.markuseliasson.se/article/going-with-hugo/) | Markus Eliasson | 18 Aug 2014 |
| [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 | 12 Aug 2014 |
| [Goodbye Octopress, Hello Hugo!](http://andreimihu.com/blog/2014/08/11/goodbye-octopress-hello-hugo/) | Andrei Mihu | 11 Aug 2014 |
| [Beautiful sites for Open Source projects](http://beautifulopen.com/2014/08/09/hugo/) | Beautiful Open | 9 Aug 2014 |
| [Hugo: Beyond the Defaults](http://npf.io/2014/08/hugo-beyond-the-defaults/) | Nate Finch | 8 Aug 2014 |
| [First Impressions of Hugo](https://peteraba.com/blog/first-impressions-of-hugo/) | Peter Aba | 6 Aug 2014 |
| [New Site Workflow](http://vurt.co.uk/post/new_website/) | Giles Paterson | 5 Aug 2014 |
| [How I Learned to Stop Worrying and Love the (Static) Web](http://cognition.ca/post/about-hugo/) | Joshua McKenty | 4 Aug 2014 |
| [Hugo - Static Site Generator](http://kenwoo.io/blog/hugo---static-site-generator/) | Kenny Woo | 3 Aug 2014 |
| [Hugo Is Friggin' Awesome](http://npf.io/2014/08/hugo-is-awesome/) | Nate Finch | 1 Aug 2014 |
| [<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) | 12 July 2014 |
| [Embedding Gists in Hugo](http://danmux.com/posts/embedded_gists/) | Dan Mull | 5 July 2014 |
| [An Introduction To Hugo](http://www.cirrushosting.com/web-hosting-blog/an-introduction-to-hugo/) | Dan Silber | 1 July 2014 |
| [Moving to Hugo](http://danmux.com/posts/hugo_based_blog/) | Dan Mull | 29 May 2014 |
| [<span lang="zh-CN">开源之静态站点生成器排行榜</span><br><small>(Leaderboard of open-source static website generators)</small>](http://code.csdn.net/news/2819909) | CSDN.net | 23 May 2014 |
| [How I deploy this site using Fabric](http://carlorat.me/quote/fabric/) | Carlo Ratam | 21 May 2014 |
| [Finally, a satisfying and effective blog setup](http://michaelwhatcott.com/now-powered-by-hugo/) | Michael Whatcott | 20 May 2014 |
| [Hugo from scratch](http://zackofalltrades.com/notes/2014/05/hugo-from-scratch/) | Zack Williams | 18 May 2014 |
| [Why I switched away from Jekyll](http://www.jakejanuzelli.com/why-I-switched-away-from-jekyll/) | Jake Januzelli | 10 May 2014 |
| [Latest Roundup of Useful Tools For Developers](http://codegeekz.com/latest-roundup-of-useful-tools-for-developers/) | CodeGeekz | 13 Feb 2014 |
| [Hugo: Static Site Generator written in Go](http://www.braveterry.com/2014/02/06/hugo-static-site-generator-written-in-go/) | Brave Terry | 6 Feb 2014 |
| [10 Useful HTML5 Tools for Web Designers and Developers](http://designdizzy.com/10-useful-html5-tools-for-web-designers-and-developers/) | Design Dizzy | 4 Feb 2014 |
| [Hugo – Fast, Flexible Static Site Generator](http://cube3x.com/hugo-fast-flexible-static-site-generator/) | Joby Joseph | 18 Jan 2014 |
| [Hugo: A new way to build static website](http://www.w3update.com/opensource/hugo-a-new-way-to-build-static-website.html) | w3update | 17 Jan 2014 |
| [Xaprb now uses Hugo](http://xaprb.com/blog/2014/01/15/using-hugo/) | Baron Schwartz | 15 Jan 2014 |
| [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 |
| [On Blog Construction](http://alexla.sh/post/on-blog-construction/) | Alexander Lash | 27 Dec 2013 |
| [Hugo](http://onethingwell.org/post/69070926608/hugo) | One Thing Well | 5 Dec 2013 |
| [In Praise Of Hugo](http://sound-guru.com/blog/post/hello-world/) | sound-guru.com | 19 Oct 2013 |
| [Hosting a blog on S3 and Cloudfront](http://www.danesparza.net/2013/07/hosting-a-blog-on-s3-and-cloudfront/) | Dan Esparza | 24 July 2013 |
Hugo v0.11 introduced the concept of a content builder. Using the
command: <code>hugo new <em>[relative new content path]</em></code>,
you can start a content file with the date and title automatically set.
While this is a welcome feature, active writers need more.
Hugo presents the concept of archetypes, which are archetypal content files
with pre-configured [front matter](/content/front-matter) which will
populate each new content file whenever you run the `hugo new` command.
## Example
### Step 1. Creating an archetype
In this example scenario, we have a blog with a single content type (blog post).
We will use ‘tags’ and ‘categories’ for our taxonomies, so let's create an archetype file with ‘tags’ and ‘categories’ pre-defined, as follows:
#### archetypes/default.md
```toml
+++
tags=["x","y"]
categories=["x","y"]
+++
```
> __CAVEAT:__ Some editors (e.g. Sublime, Emacs) do not insert an EOL (end-of-line) character at the end of the file (i.e. EOF). If you get a [strange EOF error](/troubleshooting/strange-eof-error/) when using `hugo new`, please open each archetype file (i.e. `archetypes/*.md`) and press <kbd>Enter</kbd> to type a carriage return after the closing `+++` or `---` as necessary.
### Step 2. Using the archetype
Now, with `archetypes/default.md` in place, let's create a new post in the `post` section with the `hugo new` command:
$ hugo new post/my-new-post.md
Hugo would create the file with the following contents:
#### content/post/my-new-post.md
```toml
+++
title="my new post"
date="2015-01-12T19:20:04-07:00"
tags=["x","y"]
categories=["x","y"]
+++
```
We see that the `title` and `date` variables have been added, in addition to the `tags` and `categories` variables which were carried over from `archetype/default.md`.
Congratulations! We have successfully created an archetype and used it for our new contents. But wait, what if I want to have different variables for another content type, like musicians? No problem.
### Creating custom archetypes
Earlier you created a new content type by adding a new subfolder to the content directory. In our case it's name would be `content/musician`. To use the corresponding archetype you just need to create a file named after the content type called `musician.md` in the `archetypes` directory, similar to the one below.
#### archetypes/musician.md
```toml
+++
name=""
bio=""
genre=""
+++
```
Now let's create a new musician.
$ hugo new musician/mozart.md
This time, Hugo recognizes the custom archetype and uses it instead of the default one. So the generated file's frontmatter now includes the variables `name`, `bio` and `genre`.
#### content/musician/mozart.md
```toml
+++
title="mozart"
date="2015-08-24T13:04:37+02:00"
name=""
bio=""
genre=""
+++
```
## Using a different front matter format
By default, the front matter will be created in the TOML format
regardless of what format the archetype is using.
You can specify a different default format in your site-wide config file
(e.g. `config.toml`) using the `MetaDataFormat` directive.
Possible values are `"toml"`, `"yaml"` and `"json"`.
## Which archetype is being used
The following rules apply:
* If an archetype with a filename that matches the content type being created, it will be used.
* If no match is found, `archetypes/default.md` will be used.
* If neither is present and a theme is in use, then within the theme:
* If an archetype with a filename that matches the content type being created, it will be used.
* If no match is found, `archetypes/default.md` will be used.
* If no archetype files are present, then the one that ships with Hugo will be used.
Hugo provides a simple archetype which sets the `title` (based on the
file name) and the `date` in RFC 3339 format based on
[`now()`](http://golang.org/pkg/time/#Now), which returns the current time.
> *Note: `hugo new` does not automatically add `draft = true` when the user
> provides an archetype. This is by design, rationale being that
> the archetype should set its own value for all fields.
> `title` and `date`, which are dynamic and unique for each piece of content,
> are the sole exceptions.*
Content type is automatically detected based on the path. You are welcome to declare which type to create using the `--kind` flag during creation.
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/):
With the use of the `.Summary` [page variable](/templates/variables/), Hugo can generate summaries of content for easily showing 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><!--more--></code> summary divider[^1] 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><!--more--></code> in your content file. :-)
Be careful to enter <code><!--more--></code> exactly, i.e. all lowercase with no whitespace, otherwise it would be treated as regular comment and ignored.
## Showing Summaries
You can show content summaries with the following code. You could do this, for example, on a [list](/templates/list/) node.
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.
Since 0.14, Hugo has defined a new concept called _external helpers_. It means that you can write your content using Asciidoc[tor], or reStructuredText. If you have files with associated extensions ([details](https://github.com/spf13/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65)), then Hugo will call external commands to generate the content.
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.
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.*
## 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:
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
<divid="disqus_thread"></div>
<scripttype="text/javascript">
(function(){
// Don't ever inject Disqus on localhost--it creates unwanted
// discussions from 'localhost:1313' on your Disqus account...
<noscript>Please enable JavaScript to view the <ahref="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<ahref="http://disqus.com/"class="dsq-brlink">comments powered by <spanclass="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/):
* [Discourse](http://www.discourse.org)
* [IntenseDebate](http://intensedebate.com/)
* [Livefyre](http://livefyre.com/)
* [Muut](http://muut.com/)
* [多说](http://duoshuo.com/) ([Duoshuo](http://duoshuo.com/), popular in China)
[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.
## Discourse
Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](http://discuss.gohugo.io).
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`.
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.
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.)
> 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
- 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).
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
As explained in [Source Organization](/overview/source-directory/), the `data` folder is where you can store additional data for Hugo to use when generating your site. 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.
Hugo provides the ability for you to highlight source code in _two different ways_ — 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.
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]:
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:
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Steve Francia
