Skip to content

Commit a7ed4f9

Browse files
annegentleannegentle
authored
Merge pull request #249 from justwriteclick/ag-hugo-updates
Update hugo tutorial
2 parents 4167db0 + 650e003 commit a7ed4f9

File tree

2 files changed

+62
-54
lines changed

2 files changed

+62
-54
lines changed

‎_learn/03-hugo-go-netlify.md‎

Lines changed: 62 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,12 @@ You can also set up Docker and then use this [Docker image](https://hub.docker.c
3333

3434
```
3535
$ hugo version
36-
Hugo Static Site Generator v0.74.3/extended darwin/amd64 BuildDate: unknown
36+
hugo v0.135.0+extended darwin/amd64 BuildDate=2024-09-27T13:17:08Z VendorInfo=brew
3737
```
3838

3939
## Starting a Hugo site
4040

41-
For a Hugo static site, you can choose your specific theme after you create the source files. The theme we'll use in this tutorial is [hugo-theme-learn](https://themes.gohugo.io/hugo-theme-learn/). To start a new site in the current folder, run:
41+
For a Hugo static site, you can choose your specific theme after you create the source files. The theme we'll use in this tutorial is [hugo-theme-relearn](https://themes.gohugo.io/themes/hugo-theme-relearn/). To start a new site in the current folder, run:
4242

4343
```
4444
$ hugo new site docs-as-code
@@ -48,95 +48,103 @@ For a Hugo static site, you can choose your specific theme after you create the
4848
1. Take a look at the files created in the directory with an `ls` command:
4949
```
5050
$ ls -A
51-
archetypes content layouts themes
52-
config.toml data static
51+
archetypes content hugo.toml layouts themes
52+
assets data i18n static
5353
```
5454

5555
1. Initialize the current directory as a Git repository, which will enable you to bring the theme in as a Git submodule.
5656
```
5757
$ git init
58-
Initialized empty Git repository in /Users/annegentle/src/src/hugo-example/.git/
58+
Initialized empty Git repository in /Users/agentle/src/hugo-example/.git/
5959
```
6060

61-
1. Edit `config.toml` in any text editor you like to get started. Choose a title for your site and the theme, in our case, `hugo-theme-learn`. The theme name in your configuration file must match the name of the specific theme directory inside the `/themes` directory, so we will add those files in the next step.
61+
1. Edit `hugo.toml` in any text editor you like to get started. Choose a title for your site and the theme, in our case, `hugo-theme-relearn`. (Find the [installation documentation for the Relearn Theme here](https://mcshelby.github.io/hugo-theme-relearn/basics/installation/index.html).) The theme name in your configuration file must match the name of the specific theme directory inside the `/themes` directory, so we will add those files in the next step.
6262
```
6363
baseURL = "http://example.org/"
6464
languageCode = "en-us"
6565
title = "Learning Hugo Site"
66-
theme = "hugo-theme-learn"
66+
[module]
67+
[[module.imports]]
68+
path = 'github.com/McShelby/hugo-theme-relearn'
6769
```
6870
1. To get the theme files in the `/themes` directory, and keep them updated, use a `git submodules` command to get the required theme files as well as keep them updated.
6971
```
70-
$ git submodule add https://github.com/matcornic/hugo-theme-learn.git themes/hugo-theme-learn
72+
$ hugo mod init example.com
73+
```
74+
The terminal returns something like this:
75+
```
76+
go: creating new go.mod: module example.com
77+
go: to add module requirements and sums:
78+
go mod tidy
79+
```
80+
Next, add the theme as a Git submodule with this command:
81+
```
82+
$ git submodule add --depth 1 https://github.com/McShelby/hugo-theme-relearn.git themes/hugo-theme-relearn
7183
```
7284
1. For Hugo, the `content` folder contains the site source content. For your home page, make an `_index.md` document in the `content` folder and write it with Markdown content. Switch back up one level since you just cloned the theme files.
7385
```
7486
$ cd ..
75-
$ hugo new _index.md
87+
$ hugo new --kind home _index.md
88+
Content "/Users/agentle/src/hugo-example/hugo-example/content/_index.md" created
7689
```
77-
1. Next, add a new page using the `hugo` command, `hugo new`:
90+
1. Next, add a new chapter page using the `hugo` command, `hugo new`:
7891
```
79-
$ hugo new prerequisites.md
80-
/Users/agentle/src/hugo-example/doc-machine/content/prerequisites.md created
92+
$ hugo new --kind chapter get-started/_index.md
93+
/Users/agentle/src/hugo-example/content/get-started/_index.md created
8194
```
82-
1. You can keep adding files with the `hugo new` command so that the Markdown files are pre-populated with the front matter:
95+
1. You can keep adding files with the `hugo new` command so that the Markdown files are pre-populated with the front matter such as:
8396
```
84-
---
85-
title: "Prerequisites"
86-
date: 2018-06-16T10:38:19-05:00
87-
draft: true
88-
---
97+
+++
98+
archetype = "chapter"
99+
title = "Get Started"
100+
weight = 1
101+
+++
89102
```
90103

91104
## Build a Hugo site locally
92105

93106
Once you've prepared your local system, you can build locally and review the site in your browser.
94107

95-
For Hugo, it's important to know that draft pages are only served when using the `-D` parameter.
108+
For Hugo, it's important to know that draft pages, where `draft = true` is in the front matter, won't be served.
96109

97-
1. Run the `hugo server` command with the `-D` parameter (to serve draft pages).
110+
1. Run the `hugo server` (or `hugo serve`) command to run a local server with your draft website.
98111

99112
```
100-
$ hugo server -D
101-
102-
| EN
103-
+------------------+----+
104-
Pages | 12
105-
Paginator pages | 0
106-
Non-page files | 0
107-
Static files | 67
108-
Processed images | 0
109-
Aliases | 0
110-
Sitemaps | 1
111-
Cleaned | 0
112-
113-
Total in 48 ms
114-
Watching for changes in /Users/agentle/src/hugo-example/doc-machine/{content,data,layouts,static,themes}
115-
Watching for config changes in /Users/agentle/src/hugo-example/doc-machine/config.toml
116-
Serving pages from memory
117-
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
118-
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
119-
Press Ctrl+C to stop
113+
$ hugo server
114+
115+
Watching for changes in /Users/agentle/src/hugo-learn/{archetypes,assets,content,data,i18n,layouts,static,themes}
116+
Watching for config changes in /Users/agentle/src/hugo-learn/hugo.toml, /Users/agentle/src/hugo-learn/themes/hugo-theme-relearn/hugo.toml, /Users/agentle/src/hugo-learn/go.mod
117+
Start building sites …
118+
hugo v0.135.0+extended darwin/amd64 BuildDate=2024-09-27T13:17:08Z VendorInfo=brew
119+
120+
WARN deprecated: .Sites.First was deprecated in Hugo v0.127.0 and will be removed in a future release. Use .Sites.Default instead.
121+
WARN deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in a future release. Use hugo.IsMultilingual instead.
122+
123+
| EN
124+
-------------------+------
125+
Pages | 11
126+
Paginator pages | 0
127+
Non-page files | 0
128+
Static files | 182
129+
Processed images | 0
130+
Aliases | 0
131+
Cleaned | 0
132+
133+
Built in 276 ms
134+
Environment: "development"
135+
Serving pages from disk
136+
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
137+
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
138+
Press Ctrl+C to stop
120139
```
121-
2. Open the **Web Server** URL, `http://localhost:1313/` in your local browser to view the site. (By default, the theme may be purple instead of green.)
140+
2. Open the **Web Server** URL, `http://localhost:1313/` in your local browser to view the site.
122141
![Example Hugo site](/images/learn/hugo-docs-page.png)
123142
3. Press `Ctrl+C` in the server terminal to stop the Hugo server.
124143
4. You can add your files to a Git commit. Refer to [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/) for a documentation workflow with your Hugo site.
125144

126145
## Modify the Hugo theme
127146

128-
By default, the Hugo Theme "Learn" has a purple sidebar. How about changing the color and logo displayed in the sidebar? Here's how. While we're at it, let's make sure to configure the search tool that works best with this theme.
129-
130-
1. Edit the `config.toml` file and add these lines to the `config.toml` file. This example shows setting the `themeVariant` to `green`.
131-
```
132-
[params]
133-
themeVariant = "green"
134-
```
135-
1. You can make sure that the theme works with the `lunr.js` [JavaScript search engine](https://lunrjs.com/) by adding these lines to the `config.toml` file.
136-
```
137-
[outputs]
138-
home = [ "HTML", "RSS", "JSON"]
139-
```
147+
The Hugo Theme "Relearn" has many ways to [customize the theme](https://mcshelby.github.io/hugo-theme-relearn/basics/customization/index.html), including activating print support and a dedicated search page. Refer to the [Relearn theme documentation](https://mcshelby.github.io/hugo-theme-relearn/) for details.
140148

141149
## What's next
142150

@@ -152,5 +160,5 @@ home = [ "HTML", "RSS", "JSON"]
152160

153161
## Additional references
154162

155-
* [Hugo Quickstart](https://gohugo.io/getting-started/quick-start/)
163+
* [Hugo Quick start](https://gohugo.io/getting-started/quick-start/)
156164
* [Hugo Themes web site](https://themes.gohugo.io/)

‎images/learn/hugo-docs-page.png‎

133 KB
Loading

0 commit comments

Comments
 (0)