mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-28 01:08:52 +00:00
Add mac install guide
This commit is contained in:
Ryan Watters
@@ -10,6 +10,235 @@ tags: [install,mac,osx]
|
||||
weight: 50
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: false
|
||||
toc: true
|
||||
needsreview: true
|
||||
notesforauthors:
|
||||
---
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You know how to open a terminal window.
|
||||
2. You're running a modern 64-bit Mac.
|
||||
3. You will use `~/Sites` as the starting point for your site.
|
||||
|
||||
## Pick Your Method
|
||||
|
||||
There are three ways to install Hugo on your Mac
|
||||
|
||||
1. The [Homebrew][brewlink] `brew` utility
|
||||
2. Distribution (i.e., tarball)
|
||||
3. Building from Source
|
||||
|
||||
There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case.
|
||||
|
||||
### Pros and Cons
|
||||
|
||||
There are pros and cons to each of the aforementioned methods:
|
||||
|
||||
1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update.
|
||||
|
||||
2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice.
|
||||
|
||||
3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options.
|
||||
|
||||
{{% note %}}
|
||||
Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew or Tarball.
|
||||
{{% /note %}}
|
||||
|
||||
## Installing Hugo with Brew
|
||||
|
||||
### Step 1: Install `brew` if you haven't already
|
||||
|
||||
Go to the `brew` website, <http://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
|
||||
|
||||
{{% input "install-brew.sh" %}}
|
||||
```bash
|
||||
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
|
||||
```
|
||||
{{% /input %}}
|
||||
|
||||
### Step 2: Run the `brew` Command to Install `hugo`
|
||||
|
||||
Whenever installing with Homebrew, it's a good idea to update the formulae and Homebrew itself by running the update command:
|
||||
|
||||
{{% input "update-brew.sh" %}}
|
||||
```bash
|
||||
$ brew update
|
||||
```
|
||||
{{% /input %}}
|
||||
|
||||
You can then install Hugo using `brew`:
|
||||
|
||||
{{% input "install-brew.sh" %}}
|
||||
```bash
|
||||
$ brew install hugo
|
||||
```
|
||||
{{% /input %}}
|
||||
|
||||
If Homebrew is working properly, you should see something similar to the following:
|
||||
|
||||
```bash
|
||||
==> Downloading https://homebrew.bintray.com/bottles/hugo-0.13_1.yosemite.bottle.tar.gz
|
||||
######################################################################## 100.0%
|
||||
==> Pouring hugo-0.13_1.yosemite.bottle.tar.gz
|
||||
🍺 /usr/local/Cellar/hugo/0.13_1: 4 files, 14M
|
||||
```
|
||||
|
||||
{{% note "Installing the Latest Hugo with Brew" %}}
|
||||
Replace `brew install hugo` with `brew install hugo --HEAD`
|
||||
if you want the absolute latest version in development.
|
||||
{{% /note %}}
|
||||
|
||||
`brew` should have updated your path to include Hugo. Confirm by opening a new terminal window and running a few commands:
|
||||
|
||||
```bash
|
||||
$ # show the location of the hugo executable
|
||||
$ which hugo
|
||||
/usr/local/bin/hugo
|
||||
|
||||
$ # show the installed version
|
||||
$ ls -l $( which hugo )
|
||||
lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo
|
||||
|
||||
$ # verify that hugo runs correctly
|
||||
$ hugo version
|
||||
Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00
|
||||
```
|
||||
|
||||
## Installing Hugo from Tarball
|
||||
|
||||
### Step 1: Decide on the location
|
||||
|
||||
When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:
|
||||
|
||||
1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.
|
||||
|
||||
2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases.
|
||||
|
||||
3. Install it in your `sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable.
|
||||
|
||||
All three locations will work for you. In the interest of brevity, this guide focuses on option #2.
|
||||
|
||||
### Step 2: Download the Tarball
|
||||
|
||||
1. Open <https://github.com/spf13/hugo/releases> in your browser.
|
||||
|
||||
2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release."
|
||||
|
||||
3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number.
|
||||
|
||||
4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps.
|
||||
|
||||
### Step 3: Confirm your download
|
||||
|
||||
Verify that the tarball wasn't corrupted during the download:
|
||||
|
||||
```bash
|
||||
$ tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
|
||||
-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
|
||||
-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
|
||||
-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md
|
||||
```
|
||||
|
||||
The `.md` files are documentation for Hugo. The other file is the executable.
|
||||
|
||||
### Step 4: Install Into Your `bin` Directory
|
||||
|
||||
```bash
|
||||
$ # create the directory if needed
|
||||
$ mkdir -p ~/bin
|
||||
|
||||
$ # make it the working directory
|
||||
$ cd ~/bin
|
||||
|
||||
$ # extract the tarball
|
||||
$ tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz
|
||||
Archive: hugo_X.Y_osx-64bit.tgz
|
||||
x ./
|
||||
x ./hugo
|
||||
x ./LICENSE.md
|
||||
x ./README.md
|
||||
|
||||
$ # verify that it runs
|
||||
$ ./hugo version
|
||||
Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
|
||||
```
|
||||
|
||||
You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
|
||||
|
||||
```bash
|
||||
$ # check if hugo is in the path
|
||||
$ which hugo
|
||||
/Users/USERNAME/bin/hugo
|
||||
```
|
||||
|
||||
If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:
|
||||
|
||||
```bash
|
||||
$ nano ~/.bash_profile
|
||||
```
|
||||
|
||||
Add a line to update your `PATH` variable:
|
||||
|
||||
```bash
|
||||
export PATH=$PATH:$HOME/bin
|
||||
```
|
||||
|
||||
Then save the file by pressing Control-X, then Y to save the file and return to the prompt.
|
||||
|
||||
Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again.
|
||||
|
||||
You've successfully installed Hugo.
|
||||
|
||||
## Building from Source
|
||||
|
||||
If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website][installgo] or via Homebrew using the following command:
|
||||
|
||||
```bash
|
||||
brew install go
|
||||
```
|
||||
|
||||
### Step 1: Get the Source
|
||||
|
||||
If you want to compile a specific version of Hugo, go to <https://github.com/spf13/hugo/releases> and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/spf13/hugo
|
||||
```
|
||||
|
||||
{{% warning "Sometimes \"Latest\" = \"Bugs\""%}}
|
||||
Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/spf13/hugo/issues/new).
|
||||
{{% /warning %}}
|
||||
|
||||
### Step 2: Compiling
|
||||
|
||||
Make the directory containing the source your working directory and then fetch Hugo's dependencies:
|
||||
|
||||
```bash
|
||||
mkdir -p src/github.com/spf13
|
||||
ln -sf $(pwd) src/github.com/spf13/hugo
|
||||
|
||||
# set the build path for Go
|
||||
export GOPATH=$(pwd)
|
||||
|
||||
go get
|
||||
```
|
||||
|
||||
This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change.
|
||||
|
||||
Once you have properly configured your directory, you can compile Hugo using the following command:
|
||||
|
||||
```bash
|
||||
go build -o hugo main.go
|
||||
```
|
||||
|
||||
Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you've installed Hugo, read the [Quickstart guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][hugodiscussion].
|
||||
|
||||
[brewlink]: https://brew.sh/
|
||||
[hugodiscussion]: https://discuss.gohugo.io "Visit the Hugo Discussion forum to tap into the community's collective knowledge about Hugo."
|
||||
[installgo]: https://golang.org/dl/
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
@@ -10,7 +10,565 @@ tags: [quick start,usage]
|
||||
weight: 10
|
||||
draft: false
|
||||
aliases: [/overview/quickstart/]
|
||||
toc: false
|
||||
toc: true
|
||||
needsreview: true
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
In this Quick Start guide, we will build an online bookshelf that lists books and their reviews.
|
||||
|
||||
{{% note %}}
|
||||
This quickstart depends on features introduced in Hugo v0.15. If you have an earlier version of Hugo, you will need to [upgrade](/overview/installing/) before proceeding.
|
||||
{{% /note %}}
|
||||
|
||||
{{% youtube w7Ft2ymGmfc %}}
|
||||
|
||||
## Step 1. Install Hugo
|
||||
|
||||
Go to [Hugo Releases](https://github.com/spf13/hugo/releases) and download the
|
||||
appropriate version for your OS and architecture.
|
||||
|
||||
Save the main executable as `hugo` (or `hugo.exe` on Windows) somewhere in your `PATH` as we will be using it in the next step.
|
||||
|
||||
More complete instructions are available
|
||||
at [Installing Hugo]({{< relref "overview/installing.md" >}}).
|
||||
|
||||
If you're on Windows, this quickstart will assume
|
||||
you're using [Git Bash](https://git-for-windows.github.io/)
|
||||
(also known as Git for Windows).
|
||||
Thus all commands will begin with the Bash prompt character (which is `$`).
|
||||
|
||||
Once `hugo` is installed, make sure to run the `help` command to verify `hugo` installation. Below you can see part of the `help` command output for brevity.
|
||||
|
||||
```bash
|
||||
$ hugo help
|
||||
```
|
||||
```
|
||||
hugo is the main command, used to build your Hugo site.
|
||||
|
||||
Hugo is a Fast and Flexible Static Site Generator
|
||||
built with love by spf13 and friends in Go.
|
||||
|
||||
Complete documentation is available at http://gohugo.io/.
|
||||
```
|
||||
|
||||
You can check `hugo` version using the command shown below.
|
||||
|
||||
```bash
|
||||
$ hugo version
|
||||
```
|
||||
```
|
||||
Hugo Static Site Generator v0.15 BuildDate: 2015-11-26T11:59:00+05:30
|
||||
```
|
||||
|
||||
## Step 2. Scaffold bookshelf hugo site
|
||||
|
||||
Hugo has commands that allows us to quickly scaffold a Hugo managed website. Navigate to a convenient location on your filesystem and create a new Hugo site `bookshelf` by executing the following command.
|
||||
|
||||
```bash
|
||||
$ hugo new site bookshelf
|
||||
```
|
||||
|
||||
Change directory to `bookshelf` and you will see the following directory layout.
|
||||
|
||||
```bash
|
||||
$ tree -a
|
||||
```
|
||||
```
|
||||
.
|
||||
|-- archetypes
|
||||
|-- config.toml
|
||||
|-- content
|
||||
|-- data
|
||||
|-- layouts
|
||||
`-- static
|
||||
|
||||
5 directories, 1 file
|
||||
```
|
||||
|
||||
As mentioned in the command output, `bookshelf` directory has 5 sub-directories and 1 file. Let's look at each of them one by one.
|
||||
|
||||
* **archetypes**: You can create new content files in Hugo using the `hugo new` command. When you run that command, it adds few configuration properties to the post like date and title. [Archetype]({{< relref "content/archetypes.md" >}}) allows you to define your own configuration properties that will be added to the post front matter whenever `hugo new` command is used.
|
||||
|
||||
* **config.toml**: Every website should have a configuration file at the root. By default, the configuration file uses `TOML` format but you can also use `YAML` or `JSON` formats as well. [TOML](https://github.com/toml-lang/toml) is minimal configuration file format that's easy to read due to obvious semantics. The configuration settings mentioned in the `config.toml` are applied to the full site. These configuration settings include `baseURL` and `title` of the website.
|
||||
|
||||
* **content**: This is where you will store content of the website. Inside content, you will create sub-directories for different sections. Let's suppose your website has three actions -- `blog`, `article`, and `tutorial` then you will have three different directories for each of them inside the `content` directory. The name of the section i.e. `blog`, `article`, or `tutorial` will be used by Hugo to apply a specific layout applicable to that section.
|
||||
|
||||
* **data**: This directory is used to store configuration files that can be
|
||||
used by Hugo when generating your website.
|
||||
You can write these files in YAML, JSON, or TOML format.
|
||||
|
||||
* **layouts**: The content inside this directory is used to specify how your content will be converted into the static website.
|
||||
|
||||
* **static**: This directory is used to store all the static content that your website will need like images, CSS, JavaScript or other static content.
|
||||
|
||||
## Step 3. Add content
|
||||
|
||||
Let's now add a post to our `bookshelf`. We will use the `hugo new` command to add a post. In January, I read [Good To Great](http://www.amazon.com/Good-Great-Some-Companies-Others/dp/0066620996/) book so we will start with creating a post for it. **Make sure you are inside the `bookshelf` directory.**
|
||||
|
||||
```bash
|
||||
$ hugo new post/good-to-great.md
|
||||
```
|
||||
```
|
||||
/Users/shekhargulati/bookshelf/content/post/good-to-great.md created
|
||||
```
|
||||
|
||||
The above command will create a new directory `post`
|
||||
inside the `bookshelf/content` directory
|
||||
and create `good-to-great.md` file inside it.
|
||||
|
||||
```bash
|
||||
$ tree -a content
|
||||
```
|
||||
```
|
||||
content
|
||||
`-- post
|
||||
`-- good-to-great.md
|
||||
|
||||
1 directory, 1 file
|
||||
```
|
||||
|
||||
The content inside the `good-to-great.md` file looks as shown below.
|
||||
|
||||
```
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
draft = true
|
||||
title = "good to great"
|
||||
|
||||
+++
|
||||
```
|
||||
|
||||
The content inside `+++` is the TOML configuration for the post.
|
||||
This configuration is called **front matter**.
|
||||
It enables you to define post configuration along with its content.
|
||||
By default, each post will have the three configuration properties shown above.
|
||||
|
||||
* **date** specifies the date and time at which post was created.
|
||||
* **draft** specifies that post is not ready for publication yet so it will not be in the generated site.
|
||||
* **title** specifies title for the post.
|
||||
|
||||
Let's add a small review for **Good to Great** book.
|
||||
|
||||
```
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
draft = true
|
||||
title = "Good to Great Book Review"
|
||||
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great.
|
||||
```
|
||||
|
||||
## Step 4. Serve content
|
||||
|
||||
Hugo has an inbuilt server that can serve your website content so that you can preview it. You can also use the inbuilt Hugo server in production. To serve content, execute the following command inside the `bookshelf` directory.
|
||||
|
||||
```bash
|
||||
$ hugo server
|
||||
```
|
||||
```
|
||||
0 of 1 draft rendered
|
||||
0 future content
|
||||
0 pages created
|
||||
0 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 9 ms
|
||||
Watching for changes in /Users/shekhargulati/bookshelf/{data,content,layouts,static}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
This will start the server on port `1313`.
|
||||
You can view your blog at http://localhost:1313/.
|
||||
When you go to the link, you will see nothing.
|
||||
There are couple of reasons for that:
|
||||
|
||||
1. As you can see in the `hugo server` command output, Hugo didn't render the draft. Hugo will only render drafts if you pass the `buildDrafts` flag to the `hugo server` command.
|
||||
2. We have not specified how Markdown content should be rendered. We have to specify a theme that Hugo can use. We will do that in the next step.
|
||||
|
||||
To render drafts, re-run the server with command shown below.
|
||||
|
||||
```bash
|
||||
$ hugo server --buildDrafts
|
||||
```
|
||||
```
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
1 pages created
|
||||
0 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 6 ms
|
||||
Watching for changes in /Users/shekhargulati/bookshelf/{data,content,layouts,static}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
If you go to [http://localhost:1313/](http://localhost:1313/),
|
||||
you still will not see anything as we have not specified a theme that Hugo should use.
|
||||
|
||||
## Step 5. Add theme
|
||||
|
||||
Themes provide the layout and templates that will be used by Hugo to render your website. There are a lot of Open-source themes available at [https://themes.gohugo.io/](https://themes.gohugo.io/) that you can use.
|
||||
|
||||
> **Hugo currently doesn’t ship with a `default` theme, allowing the user to pick whichever theme best suits their project.**
|
||||
|
||||
Themes should be added in the `themes` directory inside the repository root.
|
||||
|
||||
```bash
|
||||
$ cd themes
|
||||
```
|
||||
Now, you can clone one or more themes inside the `themes` directory.
|
||||
We will use the `robust` theme,
|
||||
but at a commit (in its history) that works with this quickstart.
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/dim0627/hugo_theme_robust.git
|
||||
$ (cd hugo_theme_robust; git checkout b8ce466)
|
||||
```
|
||||
|
||||
Leave the themes folder.
|
||||
|
||||
```bash
|
||||
$ cd ..
|
||||
```
|
||||
|
||||
|
||||
Start the server again.
|
||||
|
||||
```bash
|
||||
$ hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
```
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
1 pages created
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 10 ms
|
||||
Watching for changes in /Users/shekhargulati/bookshelf/{data,content,layouts,static,themes}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
> *Note: If Hugo doesn't find the specified theme in the `themes` directory,
|
||||
it will throw an exception as shown below.*
|
||||
```
|
||||
FATAL: 2016/02/14 Unable to find theme Directory: /Users/shekhargulati/bookshelf/themes/robust
|
||||
```
|
||||
|
||||
To view your website, you can go to http://localhost:1313/. You will see as shown below.
|
||||
|
||||
|
||||
|
||||
Let's understand the layout of the theme. A theme consists of the following:
|
||||
|
||||
* **theme.toml** is the theme configuration file that gives information
|
||||
about the theme like name and description of theme,
|
||||
author details, and theme license.
|
||||
|
||||
* **images** directory contains two images -- `screenshot.png` and `tn.png`. `screenshot.png` is the image of the list view and `tn.png` is the single post view.
|
||||
|
||||
* **layouts** directory contains different views for different content types.
|
||||
Every content type should have two files `single.html` and `list.html`.
|
||||
`single.html` is used for rendering a single piece of content.
|
||||
`list.html` is used to view a list of content items.
|
||||
For example, you will use `list.html` to view all the posts
|
||||
that have the `programming` tag.
|
||||
|
||||
* **static** directory stores all the static assets used by the template.
|
||||
Static assets could be JavaScript libraries like jQuery or CSS styles or images,
|
||||
or any other static content.
|
||||
This directory will be copied into the final site when rendered.
|
||||
|
||||
## Step 6. Use multiple themes
|
||||
|
||||
You can very easily test different layouts by switching between different themes.
|
||||
Let's suppose we want to try out the `bleak` theme.
|
||||
We clone the `bleak` theme inside the `bookshelf/themes` directory.
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/Zenithar/hugo-theme-bleak.git
|
||||
```
|
||||
|
||||
Restart the server using `hugo-theme-bleak` as shown below.
|
||||
|
||||
```bash
|
||||
$ hugo server --theme=hugo-theme-bleak --buildDrafts
|
||||
```
|
||||
|
||||
Now, the website will use the `bleak` theme
|
||||
and will be rendered differently as shown below.
|
||||
|
||||
|
||||
|
||||
## Step 7. Update config.toml and live reloading in action
|
||||
|
||||
Restart the server with the `robust` theme, as we will use it in this quickstart.
|
||||
|
||||
```bash
|
||||
$ hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
|
||||
The website uses the dummy values specified in `bookshelf/config.toml`.
|
||||
Let's update the configuration.
|
||||
|
||||
```toml
|
||||
baseURL = "http://example.org/"
|
||||
languageCode = "en-us"
|
||||
title = "Shekhar Gulati Book Reviews"
|
||||
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
```
|
||||
|
||||
Hugo has inbuilt support for live reloading.
|
||||
So, as soon as you save your changes it will apply the change
|
||||
and reload the web page. You will see the changes shown below.
|
||||
|
||||
|
||||
|
||||
The same is reflected in the Hugo server logs as well.
|
||||
As soon as you changed the configuration file,
|
||||
Hugo applied those changes to the affected pages.
|
||||
|
||||
```
|
||||
Config file changed: /Users/shekhargulati/bookshelf/config.toml
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
1 pages created
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 11 ms
|
||||
```
|
||||
|
||||
## Step 8. Customize robust theme
|
||||
|
||||
The `robust` theme is a good start towards our online bookshelf but we want to
|
||||
customize it a bit to meet the look and feel required for the bookshelf.
|
||||
Hugo makes it very easy to customize themes.
|
||||
You can also create your themes but we will not do that today.
|
||||
If you want to create your own theme, then you should refer to
|
||||
the [Hugo documentation]({{< relref "themes/creation.md" >}}).
|
||||
|
||||
The first change that we have to make is to use a different default image
|
||||
instead of the one used in the theme.
|
||||
The theme's default image used in both the list and single view page resides
|
||||
inside `themes/hugo_theme_robust/static/images/default.jpg`.
|
||||
We can easily override it by creating a simple directory structure
|
||||
inside the repository's `static` directory.
|
||||
|
||||
Create an images directory inside the `bookshelf/static` directory
|
||||
and copy an image with name `default.jpg` inside it.
|
||||
We will use the default image shown below.
|
||||
|
||||
|
||||
|
||||
Hugo will sync the changes and reload the website to use new image as shown below.
|
||||
|
||||
|
||||
|
||||
Now, we need to change the layout of the index page so that only images are shown instead of the text. The index.html inside the layouts directory of the theme refer to partial `li` that renders the list view shown below.
|
||||
|
||||
```html
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
|
||||
<div class="detail">
|
||||
<time>{{ with .Site.Params.DateForm }}{{ $.Date.Format . }}{{ else }}{{ $.Date.Format "Mon, Jan 2, 2006" }}{{ end }}</time>
|
||||
<h2 class="title">{{ .Title }}</h2>
|
||||
<div class="summary">{{ .Summary }}</div>
|
||||
</div>
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
|
||||
Create a new file li.html inside the `bookshelf/layouts/_default` directory. Copy the content shown below into the li.html. We have removed details of the book so that only image is shown.
|
||||
|
||||
```html
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
|
||||
Now, the website will be rendered as shown below.
|
||||
|
||||
|
||||
|
||||
Next, we want to remove information related to theme from the footer.
|
||||
So, create a new directory `partials` inside `bookshelf/layouts`.
|
||||
There, create a new file `default_foot.html` with the content copied
|
||||
from the theme's `layouts/partials/default_foot.html`.
|
||||
Replace the footer section with the one shown below.
|
||||
|
||||
```html
|
||||
<footer class="site">
|
||||
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}© {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
|
||||
<p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
|
||||
</footer>
|
||||
```
|
||||
|
||||
We also have to remove the sidebar on the right.
|
||||
Copy the `index.html` from the theme's `layouts` directory to
|
||||
the `bookshelf/layouts` directory.
|
||||
Remove the section related to the sidebar from the HTML:
|
||||
|
||||
```html
|
||||
<div class="col-sm-3">
|
||||
{{ partial "sidebar.html" . }}
|
||||
</div>
|
||||
```
|
||||
|
||||
So far we are using the default image but we would like to use the book image so that we can relate to the book. Every book review will define a configuration setting in its front matter. Update the `good-to-great.md` as shown below.
|
||||
|
||||
|
||||
```
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
draft = true
|
||||
title = "Good to Great Book Review"
|
||||
image = "good-to-great.jpg"
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
|
||||
Grab a (legal) image from somewhere, name it `good-to-great.jpg`,
|
||||
and place it in the `bookshelf/static/images` directory.
|
||||
|
||||
|
||||
After adding few more books to our shelf, the shelf appears as shown below.
|
||||
These are a few of the books that I have read within the last year.
|
||||
|
||||
|
||||
|
||||
|
||||
## Step 9. Make posts public
|
||||
|
||||
So far all the posts that we have written are in draft status.
|
||||
To make a draft public, you can either run a command
|
||||
or manually change the draft status in the post to `false`.
|
||||
|
||||
```bash
|
||||
$ hugo undraft content/post/good-to-great.md
|
||||
```
|
||||
|
||||
Now, you can start the server without the `buildDrafts` option.
|
||||
|
||||
```
|
||||
$ hugo server --theme=hugo_theme_robust
|
||||
```
|
||||
|
||||
## Step 10. Integrate Disqus
|
||||
|
||||
Disqus allows you to integrate comments in your static blog. To enable Disqus, you just have to set `disqusShortname` in the config.toml as shown below.
|
||||
|
||||
```
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
disqusShortname = <your disqus shortname>
|
||||
```
|
||||
|
||||
Now, commenting will be enabled in your blog.
|
||||
|
||||
|
||||
|
||||
## Step 11. Generate website
|
||||
|
||||
To generate Hugo website source you can use
|
||||
to deploy your website on GitHub pages,
|
||||
first edit `bookshelf/config.toml`, changing the `baseURL` line to:
|
||||
|
||||
```
|
||||
baseURL = "https://<your GitHub username>.github.io/bookshelf/"
|
||||
```
|
||||
|
||||
Then type the following command.
|
||||
|
||||
```bash
|
||||
$ hugo --theme=hugo_theme_robust
|
||||
```
|
||||
```
|
||||
0 draft content
|
||||
0 future content
|
||||
5 pages created
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 17 ms
|
||||
```
|
||||
|
||||
After you run the `hugo` command, a `bookshelf/public` directory
|
||||
will be created containing the generated website source.
|
||||
|
||||
BTW (in case you tried),
|
||||
the website isn't properly accessible via the `file:///` protocol.
|
||||
|
||||
## Step 12. Deploy bookshelf on GitHub pages
|
||||
|
||||
Let's version control your bookshelf:
|
||||
|
||||
```bash
|
||||
$ git init
|
||||
$ echo "/public/" >> .gitignore
|
||||
$ echo "/themes/" >> .gitignore
|
||||
$ git add --all
|
||||
$ git commit -m "Initial commit"
|
||||
```
|
||||
|
||||
Now the Git repositories under `bookshelf/themes`
|
||||
won't conflict with your `bookshelf` repository,
|
||||
and neither will a Git repository in `bookshelf/public`.
|
||||
|
||||
Create a new repository on GitHub named `bookshelf` (without a README).
|
||||
Once that's done, create a new Git repository on your local system
|
||||
in `bookshelf/public` and add remote:
|
||||
|
||||
```bash
|
||||
$ cd public
|
||||
$ git init
|
||||
$ git remote add origin git@github.com:<github-username>/bookshelf.git
|
||||
```
|
||||
|
||||
There, create and check out a new branch `gh-pages`.
|
||||
|
||||
```bash
|
||||
$ git checkout -b gh-pages
|
||||
Switched to a new branch 'gh-pages'
|
||||
```
|
||||
|
||||
Add all the files (within `bookshelf/public`) to the index,
|
||||
commit them, and push the changes to GitHub.
|
||||
|
||||
```bash
|
||||
$ git add --all
|
||||
$ git commit -m "bookshelf added"
|
||||
$ git push -f origin gh-pages
|
||||
```
|
||||
|
||||
In couple of minutes, your website will be live
|
||||
at `https://<github-username>.github.io/bookshelf/`.
|
||||
|
||||
Anytime, you can regenerate your site with:
|
||||
|
||||
```bash
|
||||
$ (cd ..; hugo --theme=hugo_theme_robust)
|
||||
$ git add --all
|
||||
$ git commit -m "<some change message>"
|
||||
$ git push -f origin gh-pages
|
||||
```
|
||||
|
||||
----
|
||||
|
||||
This quick start was originally written by [Shekhar Gulati](https://twitter.com/shekhargulati) in his [52 Technologies in 2016](https://github.com/shekhargulati/52-technologies-in-2016) blog series.
|
||||
|
||||
|
||||
@@ -12,12 +12,10 @@ toc: false
|
||||
draft: false
|
||||
aliases: []
|
||||
toc: true
|
||||
needsreview: true
|
||||
needsreview: false
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
By the end of this guide, you will have completed the following:
|
||||
|
||||
* Creating a basic Hugo project and website
|
||||
@@ -26,9 +24,7 @@ By the end of this guide, you will have completed the following:
|
||||
* Automating site deployments with a free tool called Wercker
|
||||
* Deploying your website to GitHub Pages for free hosting
|
||||
|
||||
### Assumptions
|
||||
|
||||
This guide was created with the following assumptions:
|
||||
## Assumptions
|
||||
|
||||
1. You have a working familiarity with using Git for version control
|
||||
2. You have a GitHub account
|
||||
|
||||
Reference in New Issue
Block a user