[Docker] Build a site on Hugo and publish it on GitHub
Overview
I will summarize the procedure for building a Hugo site on Docker and publishing it on GitHub.
Premise
--Basic knowledge of Git --I have a GitHub account --Basic knowledge of Docker --Terminal is available
environment
The working folder name is "Docker Hugo". For docker-compose.yml for starting Hugo's virtual environment, see [Docker] Building an environment for using Hugo.
DockerHugo
├── docker-compose.yml
Overall picture
The figure below shows the flow performed locally with the container.
Create a new Hugo site
Enter the following command in the container
container
hugo new site hoge
A hoge folder is created in the root folder (here, the "Docker Hugo" folder). The contents of the hoge folder are as follows
hoge
├── archetypes
│ └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
6 directories, 2 files
Download the theme you want to use
Many templates are provided by hugo. Find the template you want to use at themes.gohugo.io Reference: Hugo theme ranking site
Here, select Learn. Click [Demo] to see the sites that use the theme.
Click [Download] to display the github page.
Copy the link provided in [Code]
Start the terminal of the local PC and execute the following in the "DockerHugo" folder
Local PC
git init
git submodule add https://github.com/matcornic/hugo-theme-learn.git hoge/themes/learn
The contents of themes / learn folder are as follows
learn
├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── archetypes
│ └── default.md
├── data
│ └── webpack_assets.json
├── exampleSite
│ ├── config.toml
│ ├── content
│ │ ├── _index.md
│ │ ├── about
│ │ │ └── _index.md
│ │ ├── contact.md
│ │ └── post
│ │ ├── _index.md
│ │ ├── chapter-1.md
・
・
・
26 directories, 101 files
You can confirm that the files necessary for configuring the site such as html and css have been downloaded.
Added to config.toml
Run the following in the hoge folder on your local PC's terminal
Local PC
echo 'theme = "learn"' >> config.toml
Added to the config.toml file
config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "learn"
Add content file
When you run the hugo new command, the content files are stored below
content / specified folder name / file name
Run the following in the hoge folder of the container's terminal
container
hugo new posts/my-first-post.md
If you check the created file, the following items are added
my-first-post.md
---
title: "My First Post"
date: 2020-09-16T13:53:14Z
draft: true
---
The default is "draft: true" and drafts are not built ("hugo" command). Be sure to set "draft: false" if you want to build
Since this file is a file that describes the contents of the Web file, add it as follows
#title
Try to create a hoge site
Start Hugo server
Start the Hugo server to check in your browser before building
Do the following in the hugo folder of the container's terminal
container
hugo server -D
If you add "-D", draft is also displayed.
Check the created website
Open http: // localhost: 1313 / in your browser
Page customization will be described in a separate article
Modify the config.toml file
The overall configuration of the site is done in the config.toml file.
Changed as follows
config.toml
baseURL = "" #Not required if the relative path is set to true
languageCode = "ja" #Not necessary as it does not support multiple languages,"ja"Change to
title = "My New Hugo Site"
theme = "learn"
publishDir = "../docs" #File storage stored when the hugo command is executed
relativeURLs = true #Change to save as relative path (default is absolute path (relativeURLs)=false）)
See Configure Hugo for parameter details.
Supplementary explanation about the reason for changing to publishDir =" docs "
This time, we will publish the website on GitHub Pages. In Github Pages, you can only specify the [(roots)] or [docs] folder as the folder that stores the files that build the web page. So I changed it to publishDir =" ../ docs "
By default, the "public" folder is specified.
The following image is the setting screen of GitHub Pages
Supplementary explanation about the reason for setting relativeURLs =" true "
By changing from an absolute path to a relative path, it is now possible to handle folders even when moving.
Build static site
Execute the following in the "Docker Hugo" folder (root folder) of the container
container
hugo
Since I wrote "publishDir =" docs "" in config.toml, html and css files were generated in the docs folder.
docs $ tree
.
├── 404.html
├── categories
│ ├── index.html
│ └── index.xml
├── css
│ ├── atom-one-dark-reasonable.css
│ ├── auto-complete.css
│ ├── featherlight.min.css
・
・
・
8 directories, 82 files
Published on GitHub Pages
Publish to GitHub Pages using the git command or SourceTree See the article below for details ・ [Terminal] How to manage git / github -[SourceTree] Local / Remote Repository Management
reference
Recommended Posts