mirror of
https://github.com/gohugoio/hugo.git
synced 2025-05-02 08:30:07 +03:00
Merge commit '5e078383a7'
This commit is contained in:
Bjørn Erik Pedersen
commit
ddc15ed41b
79 changed files with 6251 additions and 391 deletions
|
|
@ -12,7 +12,7 @@ toc: true
|
|||
|
||||
## The Config Toggler!
|
||||
|
||||
This is an example for the Config Toggle shortcode.
|
||||
This is an example for the Config Toggle shortcode.
|
||||
Its purpose is to let users choose a Config language by clicking on its corresponding tab. Upon doing so, every Code toggler on the page will be switched to the target language. Also, target language will be saved in user's `localStorage` so when they go to a different pages, Code Toggler display their last "toggled" config language.
|
||||
|
||||
{{% note %}}
|
||||
|
|
@ -27,7 +27,7 @@ baseURL: "https://yoursite.example.com/"
|
|||
title: "My Hugo Site"
|
||||
footnoteReturnLinkContents: "↩"
|
||||
permalinks:
|
||||
post: /:year/:month/:title/
|
||||
posts: /:year/:month/:title/
|
||||
params:
|
||||
Subtitle: "Hugo is Absurdly Fast!"
|
||||
AuthorName: "Jon Doe"
|
||||
|
|
|
|||
|
|
@ -18,6 +18,9 @@ aliases: [/overview/source-directory/,/overview/configuration/]
|
|||
toc: true
|
||||
---
|
||||
|
||||
|
||||
## Configuration File
|
||||
|
||||
Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
|
||||
site root) as the default site config file.
|
||||
|
||||
|
|
@ -35,6 +38,37 @@ hugo --config a.toml,b.toml,c.toml
|
|||
Multiple site config files can be specified as a comma-separated string to the `--config` switch.
|
||||
{{% /note %}}
|
||||
|
||||
TODO: distinct config.toml and others (the root object files)
|
||||
|
||||
## Configuration Directory
|
||||
|
||||
In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
|
||||
|
||||
- Each file represents a configuration root object, such as `Params`, `Menus`, `Languages` etc...
|
||||
- Each directory holds a group of files containing settings unique to an environment.
|
||||
- Files can be localized to become language specific.
|
||||
|
||||
|
||||
```
|
||||
config
|
||||
├── _default
|
||||
│ ├── config.toml
|
||||
│ ├── languages.toml
|
||||
│ ├── menus.en.toml
|
||||
│ ├── menus.zh.toml
|
||||
│ └── params.toml
|
||||
├── staging
|
||||
│ ├── config.toml
|
||||
│ └── params.toml
|
||||
└── production
|
||||
├── config.toml
|
||||
└── params.toml
|
||||
```
|
||||
|
||||
Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those.
|
||||
{{% note %}}
|
||||
Default environments are __development__ with `hugo serve` and __production__ with `hugo`.
|
||||
{{%/ note %}}
|
||||
## All Configuration Settings
|
||||
|
||||
The following is the full list of Hugo-defined variables with their default
|
||||
|
|
@ -163,7 +197,7 @@ noTimes (false)
|
|||
: Don't sync modification time of files.
|
||||
|
||||
paginate (10)
|
||||
: Default number of pages per page in [pagination](/templates/pagination/).
|
||||
: Default number of elements per page in [pagination](/templates/pagination/).
|
||||
|
||||
paginatePath ("page")
|
||||
: The path element used during pagination (https://example.com/page/2).
|
||||
|
|
@ -195,7 +229,7 @@ related
|
|||
relativeURLs (false)
|
||||
: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
|
||||
|
||||
refLinksErrorLevel ("ERROR")
|
||||
refLinksErrorLevel ("ERROR")
|
||||
: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this logg level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
|
||||
|
||||
refLinksNotFoundURL
|
||||
|
|
@ -280,7 +314,7 @@ baseURL: "https://yoursite.example.com/"
|
|||
title: "My Hugo Site"
|
||||
footnoteReturnLinkContents: "↩"
|
||||
permalinks:
|
||||
post: /:year/:month/:title/
|
||||
posts: /:year/:month/:title/
|
||||
params:
|
||||
Subtitle: "Hugo is Absurdly Fast!"
|
||||
AuthorName: "Jon Doe"
|
||||
|
|
@ -430,23 +464,22 @@ maxAge = -1
|
|||
```
|
||||
|
||||
|
||||
You can override any of these cache setting in your own `config.toml`.
|
||||
You can override any of these cache setting in your own `config.toml`.
|
||||
|
||||
### The keywords explained
|
||||
|
||||
:cacheDir
|
||||
`:cacheDir`
|
||||
: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
|
||||
|
||||
`:project`
|
||||
|
||||
The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
|
||||
: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
|
||||
|
||||
`:resourceDir`
|
||||
: This is the value of the `resourceDir` config option.
|
||||
|
||||
maxAge
|
||||
: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours).
|
||||
|
||||
|
||||
dir
|
||||
: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above).
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Running the `hugo new site` generator from the command line will create a direct
|
|||
.
|
||||
├── archetypes
|
||||
├── assets
|
||||
├── config.toml
|
||||
├── config
|
||||
├── content
|
||||
├── data
|
||||
├── layouts
|
||||
|
|
@ -48,8 +48,12 @@ By default, Hugo will create new content files with at least `date`, `title` (in
|
|||
[`assets`][]
|
||||
: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory.
|
||||
|
||||
[`config.toml`](/getting-started/configuration/)
|
||||
: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
|
||||
[`config`](/getting-started/configuration/)
|
||||
: Hugo ships with a large number of [configuration directives](https://gohugo.io/getting-started/configuration/#all-variables-yaml).
|
||||
The [config directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments.
|
||||
Projects with minimal settings and no need for environment awareness can use a single `config.toml` file at its root.
|
||||
|
||||
Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
|
||||
|
||||
[`content`][]
|
||||
: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][].
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ toc: true
|
|||
{{% note %}}
|
||||
This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing).
|
||||
|
||||
You also need [Git installed](https://git-scm.com/downloads) to run this tutorial.
|
||||
It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
|
|
@ -62,9 +62,18 @@ The above will create a new Hugo site in a folder named `quickstart`.
|
|||
See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/).
|
||||
|
||||
```bash
|
||||
cd quickstart;\
|
||||
git init;\
|
||||
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;\
|
||||
cd quickstart
|
||||
|
||||
# Download the theme
|
||||
git init
|
||||
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
|
||||
# Note for non-git users:
|
||||
# - If you do not have git installed, you can download the archive of the latest
|
||||
# version of this theme from:
|
||||
# https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
|
||||
# - Extract that .zip file to get a "gohugo-theme-ananke-master" directory.
|
||||
# - Rename that directory to "ananke", and move it into the "themes/" directory.
|
||||
# End of note for non-git users.
|
||||
|
||||
# Edit your config.toml configuration file
|
||||
# and add the Ananke theme.
|
||||
|
|
@ -81,7 +90,12 @@ hugo new posts/my-first-post.md
|
|||
```
|
||||
|
||||
|
||||
Edit the newly created content file if you want. Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
|
||||
Edit the newly created content file if you want.
|
||||
|
||||
|
||||
## Step 5: Start the Hugo server
|
||||
|
||||
Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
|
||||
|
||||
```
|
||||
▶ hugo server -D
|
||||
|
|
@ -108,8 +122,7 @@ Press Ctrl+C to stop
|
|||
**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).**
|
||||
|
||||
|
||||
|
||||
## Step 5: Customize the Theme
|
||||
## Step 6: Customize the Theme
|
||||
|
||||
Your new site already looks great, but you will want to tweak it a little before you release it to the public.
|
||||
|
||||
|
|
@ -124,7 +137,7 @@ title = "My New Hugo Site"
|
|||
theme = "ananke"
|
||||
```
|
||||
|
||||
Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server.
|
||||
Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server.
|
||||
|
||||
{{% note %}}
|
||||
**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away, though you may need to [clear your cache](https://kb.iu.edu/d/ahic).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue