mirror of
https://github.com/gohugoio/hugo.git
synced 2026-09-01 19:22:38 +00:00
Do some copy editing
This commit is contained in:
Bjørn Erik Pedersen
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: The Benefits of Static Site Generators
|
||||
linktitle: The Benefits of Static
|
||||
description: Improved performance, security, ease of use, and exportability of content are just a few of the reasons static site generators are so appealing.
|
||||
description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
@@ -19,13 +19,11 @@ toc: false
|
||||
|
||||
The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
|
||||
|
||||
Creating the page dynamically requires the HTTP server to have enough memory and CPU to effectively run the generator nonstop. If not, your end user will wait in a queue for the page to be generated.
|
||||
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
|
||||
|
||||
Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page that is temporarily stored on a server. Sending a cached copy of a web page is faster than generating a new page at the time of request because the majority of the work is already done.
|
||||
Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
|
||||
|
||||
Hugo is in a family of generators that take caching a step further. All HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
|
||||
|
||||
Not running a website generator on your HTTP server has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
|
||||
This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
|
||||
|
||||
## More on Static Site Generators
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Hugo Features
|
||||
linktitle: Hugo Features
|
||||
description: Hugo boasts blistering speed, robust content management, and a powerful templating language that make it appropriate for all kinds of static websites.
|
||||
description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
@@ -18,7 +18,7 @@ toc: true
|
||||
|
||||
## General
|
||||
|
||||
* [Extremely fast][] build times (< .7 ms per page)
|
||||
* [Extremely fast][] build times (< 1 ms per page)
|
||||
* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
|
||||
* Renders changes on the fly with [LiveReload][] as you develop
|
||||
* [Powerful theming][]
|
||||
@@ -29,7 +29,7 @@ toc: true
|
||||
* Straightforward [organization for your projects][], including website sections
|
||||
* Customizable [URLs][]
|
||||
* Support for configurable [taxonomies][], including categories and tags
|
||||
* Ability to [sort content][] as you desire through powerful template [functions][]
|
||||
* [Sort content][] as you desire through powerful template [functions][]
|
||||
* Automatic [table of contents][] generation
|
||||
* [Dynamic menu][] creation
|
||||
* [Pretty URLs][] support
|
||||
@@ -38,8 +38,8 @@ toc: true
|
||||
|
||||
## Content
|
||||
|
||||
* Native Markdown support, as well as other languages through *external helpers* (see [supported formats][])
|
||||
* Support for TOML, YAML, and JSON metadata in [front matter][]
|
||||
* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
|
||||
* TOML, YAML, and JSON metadata support in [front matter][]
|
||||
* Customizable [homepage][]
|
||||
* Multiple [content types][]
|
||||
* Automatic and user defined [content summaries][]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: What is Hugo
|
||||
linktitle: What is Hugo
|
||||
description: Hugo is a fast and modern static site generator written in Go and designed to make website creation fun again.
|
||||
description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
@@ -21,7 +21,7 @@ Hugo is a general-purpose website framework. Technically speaking, Hugo is a [st
|
||||
|
||||
Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
|
||||
|
||||
We think of Hugo as the ideal website creation tool. Hugo provides nearly instant build times and the ability to rebuild whenever a change is made, which is invaluable when you are designing websites and creating content.
|
||||
We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
|
||||
|
||||
## How Fast is Hugo?
|
||||
|
||||
@@ -39,17 +39,6 @@ Hugo is for people who want to hand code their own website without worrying abou
|
||||
|
||||
Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
|
||||
|
||||
## Why I Built Hugo
|
||||
|
||||
I wrote Hugo ultimately for a few reasons. First, I was disappointed with WordPress, my then website solution. With it, I couldn't create content as efficiently as I wanted to.
|
||||
|
||||
WordPress sites rendered slowly and required I be online to write posts. WordPress is known for its constant security updates and horror stories of hacked blogs. I hated writing content in HTML instead of the much simpler Markdown. Overall, I felt like WordPress hindered more than helped. It kept me from writing great content.
|
||||
|
||||
I looked at existing static site generators like [Jekyll][], [Middleman][], and [Nanoc][]. All had complicated installation dependencies and an unacceptably long time to render my blog with hundreds of posts. I wanted a framework that would give me rapid feedback while making changes to the templates, and the 5-minute-plus render times were just too slow. In general, the static site generators were very blog-minded and didn't provide for other content types and flexible URLs.
|
||||
|
||||
I wanted to develop a fast and full-featured website framework without any dependencies. The [Go language][] seemed to have all the features I needed. I began developing Hugo in Go and fell in love with the language. I hope you will enjoy using Hugo (and [contributing to it][]) as much as I have writing it.
|
||||
|
||||
―Steve Francia ([@spf13][])
|
||||
|
||||
|
||||
[@spf13]: https://twitter.com/@spf13
|
||||
|
||||
@@ -18,6 +18,10 @@ aliases: [/content/archetypes/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
This section is outdated, see https://github.com/gohugoio/hugoDocs/issues/11
|
||||
{{% /note %}}
|
||||
|
||||
## What are Archetypes?
|
||||
|
||||
**Archetypes** are content files in the [archetypes directory][] of your project that contain preconfigured [front matter][] for your website's [content types][]. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the `hugo new` command.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Comments
|
||||
linktitle: Comments
|
||||
description: Hugo ships with an internal Disqus template that requires negligible effort to implement, but Disqus isn't the only commenting system that will work with your new Hugo website.
|
||||
description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-03-09
|
||||
@@ -17,8 +17,6 @@ aliases: [/extras/comments/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The most common interaction people ask for in static websites is the ability to add comments.
|
||||
|
||||
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
|
||||
|
||||
Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
---
|
||||
title: Cross References
|
||||
linktitle:
|
||||
description: Hugo makes it easy to link documents together with the ref and relref shortcodes, which safely provide links to headings inside of your content, whether across documents or within a document.
|
||||
description: Hugo makes it easy to link documents together.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-03-31
|
||||
@@ -12,12 +11,12 @@ menu:
|
||||
parent: "content-management"
|
||||
weight: 100
|
||||
weight: 100 #rem
|
||||
draft: false
|
||||
aliases: [/extras/crossreferences/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
Hugo makes it easy to link documents together with `ref` and `relref`, both of which are [built-in Hugo 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/`), respectively.
|
||||
|
||||
The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo 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/`), respectively.
|
||||
|
||||
## Using `ref` and `relref`
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Supported Content Formats
|
||||
linktitle: Supported Content Formats
|
||||
description: Markdown is natively supported in Hugo and is parsed by the feature-rich and incredibly speed Blackfriday parse. Hugo also provides support for additional syntaxes (eg, Asciidoc) via external helpers.
|
||||
description: Markdown and Emacs Org-Mode have native support, and additional formats (e.g. Asciidoc) come via external helpers.
|
||||
date: 2017-01-10
|
||||
publishdate: 2017-01-10
|
||||
lastmod: 2017-04-06
|
||||
@@ -17,9 +17,9 @@ aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-f
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Markdown
|
||||
**Markdown is the main content format** and comes in two flavours: The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in frontmatter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in frontmatter), both very fast markdown engines written in Golang.
|
||||
|
||||
Markdown is the native content format for Hugo and is rendered using the excellent [Blackfriday project][blackfriday], a blazingly fast parser written in Golang.
|
||||
For Emacs users, [goorgeous](https://github.com/chaseadamsio/goorgeous) provides built-in native support for Org mode (name your files `*.org` or set `markup = "org"` in frontmatter)
|
||||
|
||||
{{% note "Deeply Nested Lists" %}}
|
||||
Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations.
|
||||
@@ -74,13 +74,13 @@ The following shows how the example task list will look to the end users of your
|
||||
|
||||
### Emojis
|
||||
|
||||
Hugo comes with built-in support for emojis in your content, as well as ships with the [`emojify` function][]. To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config].
|
||||
To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][].
|
||||
|
||||
For a full list of emojis, see the [Emoji cheat sheet][emojis].
|
||||
|
||||
### Shortcodes
|
||||
|
||||
If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality to act as the intermediary between your content and templating. This is one of the most powerful features in Hugo and allows you to essentially create your own Markdown extensions very quickly.
|
||||
If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly.
|
||||
|
||||
See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own.
|
||||
|
||||
@@ -107,7 +107,7 @@ markdown: mmark
|
||||
```
|
||||
|
||||
{{% warning %}}
|
||||
Mmark support is still an *experimental* feature in Hugo. For example, shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/spf13/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/spf13/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/spf13/hugo/issues/2270)) are not fully supported. Contributions are welcome.
|
||||
Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/spf13/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/spf13/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/spf13/hugo/issues/2270)) are not fully supported. Contributions are welcome.
|
||||
{{% /warning %}}
|
||||
|
||||
## MathJax with Hugo
|
||||
@@ -225,6 +225,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
|
||||
[ascii]: http://asciidoc.org/
|
||||
[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering
|
||||
[blackfriday]: https://github.com/russross/blackfriday
|
||||
[mmark]: https://github.com/miekg/mmark
|
||||
[config]: /getting-started/configuration/
|
||||
[developer tools]: /tools/
|
||||
[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Menus
|
||||
linktitle: Menus
|
||||
description: Hugo's simple yet powerful menu system allows you to add content to menus with a high level of control and low level of effort.
|
||||
description: Hugo has a simple yet powerful menu system.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-03-31
|
||||
@@ -17,13 +17,11 @@ aliases: [/extras/menus/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
Hugo's simple yet powerful menu system allows you to add content to menus with a high degree of control and a very low amount of effort on the part of content authors.
|
||||
|
||||
{{% note "Lazy Blogger"%}}
|
||||
If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-blogger).
|
||||
{{% /note %}}
|
||||
|
||||
Hugo's robust menu features allow you to do the following:
|
||||
You can do this:
|
||||
|
||||
* Place content in one or many menus
|
||||
* Handle nested menus with unlimited depth
|
||||
|
||||
@@ -17,6 +17,10 @@ aliases: [/content/sections/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36
|
||||
{{% /note %}}
|
||||
|
||||
## Organization of Content Source
|
||||
|
||||
In Hugo, your content should be organized in a manner that reflects the rendered website.
|
||||
|
||||
@@ -193,14 +193,14 @@ To see even more options for adding syntax-highlighted code blocks to your websi
|
||||
If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
|
||||
|
||||
```html
|
||||
https://www.instagram.com/p/BMokmydjG-M/
|
||||
https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
```
|
||||
|
||||
#### Example `instagram` Input
|
||||
|
||||
{{% code file="instagram-input.md" %}}
|
||||
```md
|
||||
{{</* instagram BMokmydjG-M */>}}
|
||||
{{</* instagram BWNjjyYFxVx */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
@@ -208,7 +208,7 @@ You also have the option to hide the caption:
|
||||
|
||||
{{% code file="instagram-input-hide-caption.md" %}}
|
||||
```md
|
||||
{{</* instagram BMokmydjG-M hidecaption */>}}
|
||||
{{</* instagram BWNjjyYFxVx hidecaption */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
@@ -218,7 +218,7 @@ By adding the preceding `hidecaption` example, the following HTML will be added
|
||||
|
||||
{{% output file="instagram-hide-caption-output.html" %}}
|
||||
```html
|
||||
{{< instagram BMokmydjG-M hidecaption >}}
|
||||
{{< instagram BWNjjyYFxVx hidecaption >}}
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
@@ -226,7 +226,7 @@ By adding the preceding `hidecaption` example, the following HTML will be added
|
||||
|
||||
Using the preceding `instagram` with hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
|
||||
|
||||
{{< instagram BMokmydjG-M hidecaption >}}
|
||||
{{< instagram BWNjjyYFxVx hidecaption >}}
|
||||
|
||||
|
||||
### `ref` and `relref`
|
||||
@@ -294,7 +294,7 @@ For the preceding `speakerdeck` example, the following simulates the displayed e
|
||||
You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
|
||||
|
||||
```
|
||||
https://twitter.com/spf13/status/666616452582129664
|
||||
https://twitter.com/spf13/status/877500564405444608
|
||||
```
|
||||
|
||||
#### Example `tweet` Input
|
||||
@@ -303,7 +303,7 @@ Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
|
||||
|
||||
{{% code file="example-tweet-input.md" %}}
|
||||
```md
|
||||
{{</* tweet 666616452582129664 */>}}
|
||||
{{</* tweet 877500564405444608 */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
@@ -313,7 +313,7 @@ Using the preceding `tweet` example, the following HTML will be added to your re
|
||||
|
||||
{{% output file="example-tweet-output.html" %}}
|
||||
```html
|
||||
{{< tweet 666616452582129664 >}}
|
||||
{{< tweet 877500564405444608 >}}
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
@@ -321,7 +321,7 @@ Using the preceding `tweet` example, the following HTML will be added to your re
|
||||
|
||||
Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
|
||||
|
||||
{{< tweet 666616452582129664 >}}
|
||||
{{< tweet 877500564405444608 >}}
|
||||
|
||||
### `vimeo`
|
||||
|
||||
|
||||
@@ -16,4 +16,4 @@ aliases: []
|
||||
toc: false
|
||||
layout: documentation-home
|
||||
---
|
||||
Hugo is the world's fastest static website engine. It's written in Golang and developed by spf13 and friends. Below you will find some of the most common and helpful pages from our documentation.
|
||||
Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors). Below you will find some of the most common and helpful pages from our documentation.
|
||||
|
||||
Reference in New Issue
Block a user