blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 15:28:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix typos and revise text on install and tutorial pages

Browse Source
This commit is contained in:
Ryan Watters
2017-02-21 02:58:01 -06:00
parent d04a24578e
commit cbb0461c2f
9 changed files with 2061 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/getting-started/install-hugo.md
+1 -1
View File
@@ -432,7 +432,7 @@ you need to install the Python-based Pygments program. The procedure is outlined
## Next Steps
Now that you've installed Hugo, read the [Quickstart guide](/getting-started/quick-start/) and explore the rest of the documentation, starting with an [explanation of how to best use the Hugo docs][usingthehugodocs]. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][hugodiscussion].
Now that you've installed Hugo, read the [Quick Start guide](/getting-started/quick-start/) and explore the rest of the documentation, starting with an [explanation of how to best use the Hugo docs][usingthehugodocs]. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][hugodiscussion].
[brew]: https://brew.sh/
[highlight shortcode]: /content-management/shortcodes/#highlight
content/troubleshooting/accented-characters-in-urls.md
-1
View File
@@ -12,7 +12,6 @@ draft: false
slug:
aliases: [/troubleshooting/categories-with-accented-characters/]
toc: true
notesforauthors: "All troubleshooting docs should include two h2-headings, one for 'Trouble:' and one for 'Solution:'. Additional h2-headings include 'Discussion Forum Threads', 'Related Hugo Issues', and 'Additional References'."
---
## Trouble: Categories with accented characters
content/tutorials/create-a-multilingual-site.md
+171
View File
@@ -0,0 +1,171 @@
---
title: Create a Multilingual Site
linktitle:
godocref:
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [tutorials]
tags: [internationalization,multilingual,i18n,tutorials]
authors: ["Rick Cogley"]
aliases: []
draft: false
needsreview: true
---
> **Note:** Since v0.17 Hugo has built-in support for the creation of multilingual website. [Read more about it](/content-management/multilingual/).
## Introduction
Hugo allows you to create a multilingual site from its built-in tools. This tutorial will show one way to do it, and assumes:
* You already know the basics about creating a Hugo site
* You have a separate domain name for each language
* You'll use `/data` files for some translation strings
* You'll use single, combined `layout` and `static` folders
* You'll use a subfolder for each language under `content` and `public`
## Site Configs
Create your site configs in the root of your repository, for example for an English and Japanese site.
**English Config `config_en.toml`**:
~~~toml
baseURL = "http://acme.com/"
title = "Acme Inc."
contentDir = "content/en"
publishDir = "public/en"
[params]
locale = "en-US"
~~~
**Japanese Config `config_ja.toml`**:
~~~toml
baseURL = "http://acme.jp/"
title = "有限会社アクミー"
contentDir = "content/ja"
publishDir = "public/ja"
[params]
locale = "ja-JP"
~~~
If you had more domains and languages, you would just create more config files. The standard `config.toml` is what Hugo will run as a default, but since we're creating language-specific ones, you'll need to specify each config file when running `hugo server` or just `hugo` before deploying.
## Prep Translation Strings in `/data`
Create `.yaml` (or `.json` or `.toml`) files for each language, under `/data/translations`.
**English Strings `en-US.yaml`**:
~~~yaml
topSlogan: Acme Inc.
topSubslogan: You'll love us
...
~~~
**Japanese Strings `ja-JP.yaml`**:
~~~yaml
topSlogan: 有限会社アクミー
topSubslogan: キット勝つぞ
...
~~~
In some cases, where there is more complex formatting within the strings you want to show, it might be better to employ some conditional logic in your template, to display a block of html per language.
## Reference Strings in templates
Now you can reference the strings in your templates. One way is to do it like in this `layouts/index.html`, leveraging the fact that you have the locale set:
~~~html
<!DOCTYPE html>
<html lang="{{ .Site.Params.locale }}">
...
<head>
<meta charset="utf-8">
<title>{{ if eq .Site.Params.locale "en-US" }}{{ if .IsHome }}Welcome to {{ end }}{{ end }}{{ .Title }}{{ if eq .Site.Params.locale "ja-JP" }}{{ if .IsHome }}へようこそ{{ end }}{{ end }}{{ if ne .Title .Site.Title }} : {{ .Site.Title }}{{ end }}</title>
...
</head>
<body>
<div class="container">
<h1 class="header">{{ ( index $.Site.Data.translations $.Site.Params.locale ).topSlogan }}</h1>
<h3 class="subheader">{{ ( index $.Site.Data.translations $.Site.Params.locale ).topSubslogan }}</h3>
</div>
</body>
</html>
~~~
The above shows both techniques, using an `if eq` and `else if eq` to check the locale, and using `index` to pull strings from the data file that matches the locale set in the site's config file.
## Customize Dates
At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content:
~~~toml
1: "janvier"
2: "février"
3: "mars"
4: "avril"
5: "mai"
6: "juin"
7: "juillet"
8: "août"
9: "septembre"
10: "octobre"
11: "novembre"
12: "décembre"
~~~
... then index the non-English date names in your templates like so:
~~~html
<time class="post-date" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" | safeHTML }}">
Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
</time>
~~~
This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file.
## Create Multilingual Content
Now you can create markdown content in your languages, in the `content/en` and `content/ja` folders. The frontmatter stays the same on the key side, but the values would be set in each of the languages.
## Run Hugo Server or Deploy Commands
Once you have things set up, you can run `hugo server` or `hugo` before deploying. You can create scripts to do it, or as shell functions. Here are sample basic `zsh` functions:
**Live Reload with `hugo server`**:
~~~shell
function hugoserver-com {
cd /Users/me/dev/mainsite
hugo server --buildDrafts --verbose --source="/Users/me/dev/mainsite" --config="/Users/me/dev/mainsite/config_en.toml" --port=1377
}
function hugoserver-jp {
cd /Users/me/dev/mainsite
hugo server --buildDrafts --verbose --source="/Users/me/dev/mainsite" --config="/Users/me/dev/mainsite/config_ja.toml" --port=1399
}
~~~
**Deploy with `hugo` and `rsync`**:
~~~shell
function hugodeploy-acmecom {
rm -rf /tmp/acme.com
hugo --config="/Users/me/dev/mainsite/config_en.toml" -s /Users/me/dev/mainsite/ -d /tmp/acme.com
rsync -avze "ssh -p 22" --delete /tmp/acme.com/ me@mywebhost.com:/home/me/webapps/acme_com_site
}
function hugodeploy-acmejp {
rm -rf /tmp/acme.jp
hugo --config="/Users/me/dev/mainsite/config_ja.toml" -s /Users/me/dev/mainsite/ -d /tmp/acme.jp
rsync -avze "ssh -p 22" --delete /tmp/acme.jp/ me@mywebhost.com:/home/me/webapps/acme_jp_site
}
~~~
Adjust to fit your situation, setting dns, your webserver config, and other settings as appropriate.
content/tutorials/creating-a-multilingual-site.md
-16
View File
@@ -1,16 +0,0 @@
---
title: Create a Multilingual Site
linktitle:
godocref:
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [tutorials]
tags: [internationalization,multilingual,i18n,tutorials]
author: ""
authorurl: ""
originalurl: ""
aliases: []
draft: false
---
content/tutorials/creating-a-new-theme.md
+1708
View File
File diff suppressed because it is too large Load Diff
content/tutorials/migrate-from-jekyll-to-hugo.md
+178 -4
View File
@@ -1,14 +1,188 @@
---
title: Migrate from Jekyll Hugo
linktitle: Migrate from Jekyll to Hugo
description: This tutorial walks you through using the `hugo import jekyll` command added to v0.15 to convert your current content from the popular Ruby static site generator.
description: This tutorial walks you through converting your Jekyll site to a Hugo site through examples of the differences between Jekyll and Hugo templating. Note that v0.15 and above of Hugo has a built-in `hugo import jekyll` command to greatly facilitate this task.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [tutorials]
tags: [migrations,jekyll, command line]
authors: [Alexandre Normand]
weight:
draft: false
slug:
aliases: []
---
toc: true
aliases: [/tutorials/migrate-from-jekyll/]
needsreview: true
---
{{% note "Support for Jekyll Imports" %}}
Hugo 0.15 comes with a `hugo import jekyll` command, see [import from Jekyll](/commands/hugo_import_jekyll/).
{{% /note %}}
## Move static content to `static`
Jekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there.
With Jekyll, something that looked like
```bash
▾ <root>/
▾ images/
logo.png
```
should become
```bash
▾ <root>/
▾ static/
▾ images/
logo.png
```
Additionally, you'll want any files that should reside at the root (e.g., `CNAME`) to be moved to the `static` directory.
## Create your Hugo Configuration File
Hugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.
## Set Your Configuration Publish Folder to `_site`
The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:
1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
```
git submodule deinit _site
git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
```
2. Or, change the Hugo configuration to use `_site` instead of `public`.
```
{
..
"publishDir": "_site",
..
}
```
## Convert Jekyll templates to Hugo templates
That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.
As a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net/) took me no more than a few hours.
## Convert Jekyll Plugins to Hugo shortcodes
Jekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.
### Implementation
As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.
Jekyll's plugin:
```ruby
module Jekyll
class ImageTag < Liquid::Tag
@url = nil
@caption = nil
@class = nil
@link = nil
// Patterns
IMAGE_URL_WITH_CLASS_AND_CAPTION =
IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens)
super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1
@url = $3
@caption = $7
@link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1
@url = $3
@caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1
@caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1
@url = $3
elsif markup =~ IMAGE_URL
@url = $1
end
end
def render(context)
if @class
source = "<figure class='#{@class}'>"
else
source = "<figure>"
end
if @link
source += "<a href=\"#{@link}\">"
end
source += "<img src=\"#{@url}\">"
if @link
source += "</a>"
end
source += "<figcaption>#{@caption}</figcaption>" if @caption
source += "</figure>"
source
end
end
end
Liquid::Template.register_tag('image', Jekyll::ImageTag)
```
is written as this Hugo shortcode:
```html
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }}
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
{{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
```
### Usage
I simply changed:
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):
{{%/* fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" */%}}
As a bonus, the shortcode named parameters are, arguably, more readable.
## Finishing touches
### Fix content
Depending on the amount of customization that was done with each post with Jekyll, this step will require more or less effort. There are no hard and fast rules here except that `hugo server` is your friend. Test your changes and fix errors as needed.
### Clean up
You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.
## A Practical Example in a Diff
[Hey, it's Alex](http://heyitsalex.net/) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).
static/css/style.min.css
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
themes/hugodocs/pipeline/scss/components/_breadcrumb.scss
+1 -1
View File
@@ -93,5 +93,5 @@
}
}
}
}
}
themes/hugodocs/pipeline/scss/components/_table-of-contents.scss
+1
View File
@@ -49,6 +49,7 @@ aside#toc {
transform: scale(1);
border-left: 1px solid $hugo-gray-light;
border-radius: 0px;
max-width:320px;
}
}