TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-18 20:54:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

Fix broken URLs for tags pages

Browse Source
This commit is contained in:
Ryan Watters 2017-03-12 19:36:32 -05:00
parent a4f76cfca0
commit c315f532b5
7 changed files with 35 additions and 1912 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
config.toml
View File

@ -33,7 +33,7 @@ logFile = ""
metaDataFormat = "yaml"
# This intelligently adds an "s" to the titles of list pages
pluralizelisttitles = false
preserveTaxonomyNames = true
preserveTaxonomyNames = false
# This sets the title of the directory where hugo builds and pushes the final site when running "Hugo" (ie, without "server")
publishdir = "public"
pygmentsUseClasses = true

59
content/concept.md
View File

@ -13,55 +13,59 @@ aliases: []
toc: true
---
## Introduction
## Background
The claims made in this strategic document are largely *empirical* and pulled from two major sources:
The claims made in this document are largely *empirical* and pulled from two major sources:
* My experience starting 18 months ago as a new Hugo user.
* Conversations with fellow Hugo users and noted trends within the [Discussion Forum][forum].
{{% note "What the hell is all of this, Ryan?" %}}
At the bottom of this document is a section that starts with [most important questions for the Hugo team](#ideal-workflow) and continues with a very high-level description of an *ideal* content strategy process. This has only been included to provide insight for those unfamiliar with fundamental content strategy concepts.
I am submitting these changes because I have been given [explicit permission to do so](https://discuss.gohugo.io/t/roadmap-to-hugo-v1-0/2278/34). Project kickoff was in November 2016 as a result of [this forum thread on a proposed source re-organization](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506). See also [this Discuss thread from @bep re: a new restructure and redesign](https://discuss.gohugo.io/t/documentation-restructure-and-design/1891/10).
{{% note "What is this document, Ryan?" %}}
At the bottom of this document is a section that starts with the [most important questions for the Hugo team](#ideal-workflow) and continues with a very high-level description of an *ideal* content strategy process. This has only been included to provide insight for those unfamiliar with basic content strategy..
{{% /note %}}
{{% warning "Disclaimer" %}}
WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document. It'll get better. I promise.
WIP. Before any colleagues banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document. It'll get better. I promise.
{{% /warning %}}
## Strategy, Tactics, and Requirements
### Assumptions
First and foremost, the biggest shortcomings of the current documentation are a matter of *content* more than visual or UX design.
The biggest shortcomings of the current documentation are more a matter of *content* than visual design.
In addition, this project was started with the assumptions that the Hugo documentation
Additionally, current Hugo documentation
* is confusing for new users
* is a common complaint in the Hugo forums ([forum discussion 1][ex1], [forum discussion 2][ex2])
* lacks structure and is therefore
* unscalable, as demonstrated by patch pages (e.g. [here][patch1] and [here][patch2]) that seem out of place, require unnecessary drill-down, or duplicate content in other areas of the docs, thus requiring duplicative efforts to update
* unscalable, as demonstrated by patch pages (e.g. [here][patch1] and [here][patch2]) that seem out of place, require unnecessary drill-down, or duplicate content in other areas of the docs, thus requiring duplicative efforts to keep updated
* inconsistent in its terminology, style, and (sometimes) layout
* limited in effective use of Alogolia's document search (i.e., due to redundant content grouping, headings, etc)
* limited in effective use of Algolia's document search (i.e., due to redundant content grouping, headings, etc)
* difficult to optimize for external search engines (SEO)
* does not leverage Hugo's more powerful features (e.g., only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development; a prime example is the sparsity of basic and advanced code samples for templating functions, some of which may still be wholly undocumented
* lacks well-defined contribution and editorial guidelines for those interested in submitting or editing documentation
* is not up to date
* often unusable on smart phones or other mobile devices
* needs reworking of its URL structure to represent a more intuitive mental model for end users ([Discuss][ds1])
### Goals
New Hugo documentation should...
* reduce confusion surrounding Hugo concepts; e.g., `list`, `section`, `page`, `kind`, and `content type` with the intention of
* reduce confusion surrounding core Hugo concepts; e.g., `list`, `section`, `page`, `kind`, and `content type` with the intention of
* making it easier for new users to get up and running
* creating better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io][hugothemes])
* reducing the frequency of beginner-level questions in the [Hugo Discussion Forum][forum]
* not require, or assume, any degree of Golang proficiency from end users;
* that said, Hugo can—and *should*—act as a bridge for users interested in learning Golang. An implementationn example of this strategic point is the inclusion of `godocref:` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
* that said, Hugo can—and *should*—act as a bridge for users interested in learning Golang. An implemented example of this strategic point is the inclusion of `godocref:` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
* be easiest to expand and edit for *contributors** but even easier to understand by *end users*
* if you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*;
* content modeling is king
* go DRY (e.g., by leveraging shortcodes whenever possible)
* go DRY (e.g., via shortcodes)
* set required metadata (e.g., via section-specific *archetypes*)
* develop contribution guidelines for both development *and* documentation
* be equally accessible via mobile, tablet, desktop, and offline.
@ -98,7 +102,7 @@ The themes end user has
* limited proficiency in the command line/prompt
* proficiency in one of the [supported content formats](https://hugodocsconcept.netlify.com/content-management/formats/)(specifically markdown)
* access to static hosting;
* access to static hosting
* limited proficiency in deploying a static website
### Requirements
@ -118,7 +122,7 @@ The following are high-level requirements for the documentation site.
- [X] [Open Graph Protocol](http://ogp.me/)
- [X] [schema.org](http://schema.org)
- [ ] [JSON+LD](https://developers.google.com/schemas/formats/json-ld), [validated](https://search.google.com/structured-data/testing-tool)
- [X] [JSON+LD](https://developers.google.com/schemas/formats/json-ld), [validated](https://search.google.com/structured-data/testing-tool)
- [X] Consistent heading structure
- [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`)
- [X] SSL
@ -127,19 +131,19 @@ The following are high-level requirements for the documentation site.
#### Accessibility
- [ ] Aria roles
- [ ] Alt text for all images
- [X] Aria roles
- [X] Alt text for all images
- [X] `title` attribute for links
#### Editorial and Content
- [ ] Basic style guide
- [X] Basic style guide
- The style guide should facilitate a more consistent UX for the site but not be so complex as to deter documentation contributors
- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute/documentation/))
- [X] Standardized content types (see [WIP archetypes in source](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
- [X] New content model, including taxonomies ([see tags page][tagspage])
- [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
- [X] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
- [X] New site architecture and content groupings
- [ ] Single sample website (include in docs source, [`/static/example`](https://github.com/rdwatters/hugo-docs-concept/tree/master/static/example)) for consistent code samples or in-page tutorials
#### Content Strategy Statement
@ -155,7 +159,7 @@ The following are high-level requirements for the documentation site.
## UX/UI
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
- [X] Copyable and/or downloadable code blocks (via highlight.js and clipboard.js, extended for hugo-specific keywords); see [this specific request from @bep for this feature](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506/10?u=rdwatters)
- [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
- [X] Smooth scrolling
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](/contribute/documentation/#admonition-short-codes))
@ -171,6 +175,7 @@ The following are high-level requirements for the documentation site.
- [X] Google Analytics
- [ ] Content groupings (GA) to measure usage, behavior flow, and define content gaps
- [ ] Automated reports (GA)
- [ ] Potential for using Google Sheets CSV for published content on the docs
{{% note %}}
The preceding analytics and metrics are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
@ -184,7 +189,7 @@ The preceding analytics and metrics are separate from usage statics re: Hugo dow
- [X] Responsive
- [X] Flexbox
- [X] Typography (via ems)
- [X] Custom iconography
- [X] Custom iconography (i.e., via Fontello rather than FontAwesome bloat)
- [X] Design assets versioned with source ([see design resources directory][designresources])
- [X] [WCAG color contrast requirements](http://webaim.org/blog/wcag-2-0-and-link-colors/)
- [X] [Sass Guidelines for Source Organization](https://sass-guidelin.es/)
@ -194,7 +199,7 @@ The preceding analytics and metrics are separate from usage statics re: Hugo dow
## Annotated Content Changes
The following is an *abbreviated* listing of *substantive* changes made to the current documentation's source content and organization. Sections here are ordered according to the current site navigation. The changes delimited here do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.
The following is an *abbreviated* listing of *substantive* changes made to the current documentation's source content and organization. Sections here are ordered according to the current site navigation. The changes delimited here do *not* include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.
### Download Hugo
@ -203,22 +208,24 @@ This is no longer a site navigation link and is instead a button along with "Fil
### Site Showcase
Site showcase has stayed more or less as is, including styling, etc. However...
* The showcase archetype has changed for simplicity.
* The showcase archetype has been refined for simplicity and now has new [contribution guidelines](/contribute/documentation).
* To keep compatibility, all [showcase content files][showcasefiles] have been edited to reflect the new content type. This will also be updated in the ["docs" page of the contribute section](/contribute/documentation/)
### Press & Articles
* The press and article pages has been moved under "News" along with "Release Notes". Also, this whole section is lower on the navigation because it's less frequently visited---I'm assuming---than just about everything on the site.
* The press and article pages have been moved under "News" along with "Release Notes". Also, this whole section is lower on the navigation because it's less frequently visited---I'm assuming---than just about everything on the site.
* Like everything else, I've kept up with changes to the docs upstream on GitHub, but in this case, I also includes a [half dozen *new* articles as well](/news/press-and-articles/).
### About Hugo
* Content is more or less the same, but I've cleaned up a lot of the language, and copy edited for consistency throughout. I've also added in some extra frills (e.g. resources that extoll and teach more about the benefits of SSGs on [/about/benefist](/about/benefits/)).
* Content is more or less the same, but I've cleaned up a lot of the language, and copy edited for consistency throughout. I've also added in some extra frills (e.g. resources that extoll and teach more about the benefits of SSGs on [/about/benefits](/about/benefits/)).
* Release notes are now in the "News" section, although I'm still iffy on this decision. I can gladly move this back into "About" to give it a higher degree of discoverability in the menu.
### Getting Started
* The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options—e.g. Arjen's Wercker tutorial—are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.
* **[[UPDATE 2017-03-12]]**
* The Quick Start need to be completely reworked; this could include a walkthrough of a new default theme (#)
* ~~The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options—e.g. Arjen's Wercker tutorial—are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.~~
### Content

18
content/tutorials/_index.md
View File

@ -1,18 +0,0 @@
---
title: Tutorials
linktitle: Overview
description:
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
tags: [tutorials,learning]
weight: 01
draft: false
hidesectioncontents: false
slug:
aliases:
notesforauthors:
---
Hugo tutorials are developed and submitted by the Hugo community.

174
content/tutorials/creating-a-multilingual-site.md
View File

@ -1,174 +0,0 @@
---
title: Creating a Multilingual Site
linktitle: Multilingual Site
godocref:
description:
date: 2015-07-08
publishdate: 2015-07-08
lastmod: 2015-12-24
categories: [tutorials]
tags: [internationalization,multilingual,i18n,tutorials]
authors: ["Rick Cogley"]
aliases: [/tutorials/create-a-multilingual-site/]
draft: false
toc: true
hugoversion: 16
---
{{% note %}}
Since v0.17, Hugo has built-in support for the creation of multilingual websites. Read the [multilingual documentation](/content-management/multilingual/) for more information.
{{% /note %}}
## 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 front matter 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.

1503
content/tutorials/creating-a-new-theme.md
View File

File diff suppressed because it is too large Load Diff

189
content/tutorials/migrate-from-jekyll-to-hugo.md
View File

@ -1,189 +0,0 @@
---
title: Migrate from Jekyll Hugo
linktitle: Migrate from Jekyll to Hugo
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
hugoversion: 14
toc: true
aliases: [/tutorials/migrate-from-jekyll/]
wip: 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).

2
layouts/_default/terms.html
View File

@ -19,7 +19,7 @@
{{$val := $value.Name | urlize}}
{{$valurl := add $dataPlural $val}}
<tr>
<td><a href="{{ $valurl | relURL}}">{{ $value.Name }}</a></td>
<td><a href="{{ $valurl | relURL}}">{{ replace $value.Name "-" " " }}</a></td>
<td>{{ $value.Count }}</td>
</tr>
{{ end }}