mirror of
https://github.com/gohugoio/hugo.git
synced 2024-07-02 23:30:00 +00:00
Some more random copyediting of Hugo docs
- Change "livereload" and "live reload" to "LiveReload";
- Add a `$ ` prompt before example command lines
(not exhaustive, work in progress);
- Remove unnecessary whitespace from partials;
- Revise the blackfriday options table in overview/configuration.md
to make it narrower.
- Manually set the language for highlight.js where appropriate
- Rename "404" to "Custom 404 page", and remove incorrect reference
to "homepage"
- Credit the author of tutorials/github_pages_blog.md
(Similar notes are necessary for other contributed pages where
"I" am not spf13 to avoid reader confusion.)
- Add CSS for `kbd` and `table` etc. to css/style.css;
- etc.
This commit is contained in:
Anthony Fok
parent
49f5eb5c84
commit
b0181e278b
|
|
@ -5,24 +5,24 @@ menu:
|
|||
parent: extras
|
||||
next: /extras/menus
|
||||
prev: /extras/crossreferences
|
||||
title: Live Reload
|
||||
title: LiveReload
|
||||
weight: 50
|
||||
---
|
||||
|
||||
Hugo may not be the first static site generator to utilize live reload
|
||||
Hugo may not be the first static site generator to utilize LiveReload
|
||||
technology, but it’s the first to do it right.
|
||||
|
||||
The combination of Hugo’s insane build speed and live reload make
|
||||
The combination of Hugo’s insane build speed and LiveReload make
|
||||
crafting your content pure joy. Virtually instantly after you hit save
|
||||
your rebuilt content will appear in your browser.
|
||||
|
||||
## Using livereload
|
||||
## Using LiveReload
|
||||
|
||||
Hugo comes with livereload built in. There are no additional packages to
|
||||
install. A common way to use hugo while developing a site is to have
|
||||
hugo run a server and watch for changes.
|
||||
Hugo comes with LiveReload built in. There are no additional packages to
|
||||
install. A common way to use Hugo while developing a site is to have
|
||||
Hugo run a server and watch for changes:
|
||||
|
||||
hugo server --watch
|
||||
$ hugo server --watch
|
||||
|
||||
This will run a full functioning web server while simultaneously
|
||||
watching your file system for additions, deletions or changes within
|
||||
|
|
@ -40,22 +40,18 @@ fast they are barely noticeable, you merely need to glance at your open
|
|||
browser and you will see the change already there.
|
||||
|
||||
This means that keeping the site open on a second monitor (or another
|
||||
half of your current monitor), allows you to see exactly what your
|
||||
half of your current monitor) allows you to see exactly what your
|
||||
content looks like without even leaving your text editor.
|
||||
|
||||
## Disabling livereload
|
||||
## Disabling LiveReload
|
||||
|
||||
Live reload accomplishes this by injecting javascript into the pages it
|
||||
LiveReload works by injecting JavaScript into the pages it
|
||||
creates that creates a web socket client to the hugo web socket server.
|
||||
|
||||
Awesome for development, but not something you would want to do in
|
||||
production. Since many people use `hugo server --watch` in production to
|
||||
instantly display any updated content, we’ve made it easy to disable the
|
||||
live reload functionality.
|
||||
|
||||
hugo server --watch --disableLiveReload
|
||||
|
||||
|
||||
|
||||
LiveReload functionality.
|
||||
|
||||
$ hugo server --watch --disableLiveReload
|
||||
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ And the following functions:
|
|||
|
||||
* **HasChildren** bool
|
||||
|
||||
Additionally there are some relevant functions available on the page:
|
||||
Additionally, there are some relevant functions available on the page:
|
||||
|
||||
* **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool
|
||||
* **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool
|
||||
|
|
@ -89,7 +89,7 @@ available.
|
|||
You can also add entries to menus that aren’t attached to a piece of
|
||||
content. This takes place in the sitewide [config file](/overview/configuration).
|
||||
|
||||
Here’s an example (in TOML):
|
||||
Here’s an example `config.toml`:
|
||||
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
|
|
@ -101,7 +101,7 @@ Here’s an example (in TOML):
|
|||
pre = "<i class='fa fa-road'></i>"
|
||||
weight = -100
|
||||
|
||||
Here’s an example (in YAML):
|
||||
And the equivalent example `config.yaml`:
|
||||
|
||||
---
|
||||
menu:
|
||||
|
|
@ -142,7 +142,7 @@ The following is an example:
|
|||
|
||||
<!--sidebar start-->
|
||||
<aside>
|
||||
<div id="sidebar" class="nav-collapse ">
|
||||
<div id="sidebar" class="nav-collapse">
|
||||
<!-- sidebar menu start-->
|
||||
<ul class="sidebar-menu">
|
||||
{{ $currentNode := . }}
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ This release represents over 90 code commits from 28 different contributors.
|
|||
This release represents over 110 code commits from 29 different contributors.
|
||||
|
||||
* Considerably faster... about 3 - 4x faster on average
|
||||
* [Live Reload](/extras/livereload). Hugo will automatically reload the browser when the build is complete
|
||||
* [LiveReload](/extras/livereload). Hugo will automatically reload the browser when the build is complete
|
||||
* Theme engine w/[Theme Repository](http://github.com/spf13/hugoThemes)
|
||||
* [Menu system](/extras/menus) with support for active page
|
||||
* [Builders](/extras/builders) to quickly create a new site, content or theme
|
||||
|
|
|
|||
|
|
@ -71,13 +71,38 @@ Here is a yaml configuration file which sets a few more options
|
|||
|
||||
[Blackfriday](https://github.com/russross/blackfriday) is the [Markdown](http://daringfireball.net/projects/markdown/) rendering engine used in Hugo. The Blackfriday configuration in Hugo is mostly a set of sane defaults that should fit most use cases.
|
||||
|
||||
But Hugo does expose some options -- in the table below matched with the corresponding flag in the [Blackfriday source](https://github.com/russross/blackfriday/blob/master/html.go):
|
||||
But Hugo does expose some options---as listed in the table below, matched with the corresponding flag in the [Blackfriday source](https://github.com/russross/blackfriday/blob/master/html.go):
|
||||
|
||||
<table class="table table-bordered">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Flag</th><th>Default</th><th>Blackfriday flag</th>
|
||||
</tr>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>angledQuotes</code></td>
|
||||
<td><code>false</code></td>
|
||||
<td><code>HTML_SMARTYPANTS_ANGLED_QUOTES</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="purpose-title">Purpose:</td>
|
||||
<td class="purpose-description" colspan="2">Enable angled double quotes (<code>« »</code>)</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>plainIdAnchors</code></td>
|
||||
<td><code>false</code></td>
|
||||
<td><code>FootnoteAnchorPrefix</code> and <code>HeaderIDSuffix</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="purpose-title">Purpose:</td>
|
||||
<td class="purpose-description" colspan="2">If <code>true</code>, then header and footnote IDs are generated without the document ID <small>(so, <code>#my-header</code> instead of <code>#my-header:bec3ed8ba720b9073ab75abcf3ba5d97</code>)</small></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Flag | Default | Blackfriday flag | Purpose
|
||||
--- | --- | --- | ---
|
||||
angledQuotes | false | HTML_SMARTYPANTS_ANGLED_QUOTES | Enable angled double quotes (`« »`)
|
||||
plainIdAnchors | false | FootnoteAnchorPrefix and HeaderIDSuffix | If true, then header and footnote IDs are generated without the document ID (so, `#my-header` instead of `#my-header:bec3ed8ba720b9073ab75abcf3ba5d97`)
|
||||
|
||||
**Note** that these flags must be grouped under the `blackfriday` key and can be set on **both site and page level**. If set on page, it will override the site setting.
|
||||
|
||||
|
|
@ -89,6 +114,6 @@ blackfriday:
|
|||
|
||||
## Notes
|
||||
|
||||
Config changes do not reflect with [Live Reload](/extras/livereload).
|
||||
Config changes are not reflected with [LiveReload](/extras/livereload).
|
||||
|
||||
Please restart `hugo server --watch` whenever you make a config change.
|
||||
|
|
|
|||
|
|
@ -25,11 +25,11 @@ Once downloaded it can be run from anywhere. You don't need to install
|
|||
it into a global location. This works well for shared hosts and other systems
|
||||
where you don't have a privileged account.
|
||||
|
||||
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
|
||||
is the most probable location.
|
||||
Ideally, you should install it somewhere in your `PATH` for easy use.
|
||||
`/usr/local/bin` is the most probable location.
|
||||
|
||||
If you have [Homebrew](http://brew.sh), installation is even easier. Just run
|
||||
`brew install hugo`.
|
||||
On OS X, if you have [Homebrew](http://brew.sh), installation is even
|
||||
easier: just run `brew install hugo`.
|
||||
|
||||
### Installing Pygments (optional)
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ you need to install the Python-based Pygments program. The procedure is outlined
|
|||
## Upgrading Hugo
|
||||
|
||||
Upgrading Hugo is as easy as downloading and replacing the executable you’ve
|
||||
placed in your path.
|
||||
placed in your `PATH`.
|
||||
|
||||
|
||||
## Installing from source
|
||||
|
|
@ -55,13 +55,13 @@ placed in your path.
|
|||
|
||||
### Get directly from GitHub:
|
||||
|
||||
go get -v github.com/spf13/hugo
|
||||
$ go get -v github.com/spf13/hugo
|
||||
|
||||
### Building Hugo
|
||||
|
||||
cd /path/to/hugo
|
||||
go build -o hugo main.go
|
||||
mv hugo /usr/local/bin/
|
||||
$ cd /path/to/hugo
|
||||
$ go build -o hugo main.go
|
||||
$ mv hugo /usr/local/bin/
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ Hugo boasts the following features:
|
|||
* Extremely fast build times (~1 ms per page)
|
||||
* Completely cross platform: Runs on Mac OS X, Linux and Windows
|
||||
* Easy [installation](/overview/installing)
|
||||
* Render changes [on the fly](/overview/usage) with [live reload](/extras/livereload) as you develop
|
||||
* Render changes [on the fly](/overview/usage) with [LiveReload](/extras/livereload) as you develop
|
||||
* Complete theme support
|
||||
* Host your site anywhere
|
||||
|
||||
|
|
|
|||
|
|
@ -10,28 +10,26 @@ title: Hugo Quickstart Guide
|
|||
weight: 10
|
||||
---
|
||||
|
||||
_This quickstart depends on features introduced in Hugo v0.11. If you
|
||||
have an earlier version of Hugo, you will need to [upgrade](/overview/installing/) before
|
||||
proceeding._
|
||||
> _Note: This quickstart depends on features introduced in Hugo v0.11. If you have an earlier version of Hugo, you will need to [upgrade](/overview/installing/) before proceeding._
|
||||
|
||||
## Step 1. Install Hugo
|
||||
|
||||
Go to [Hugo Releases](https://github.com/spf13/hugo/releases) and download the
|
||||
appropriate version for your os and architecture.
|
||||
appropriate version for your OS and architecture.
|
||||
|
||||
Save it somewhere specific as we will be using it in the next step.
|
||||
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](/overview/installing/)
|
||||
More complete instructions are available at [Installing Hugo](/overview/installing/).
|
||||
|
||||
## Step 2. Have Hugo Create a site for you
|
||||
|
||||
Hugo has the ability to create a skeleton site.
|
||||
Hugo has the ability to create a skeleton site:
|
||||
|
||||
hugo new site /path/to/site
|
||||
$ hugo new site /path/to/site
|
||||
|
||||
For the rest of the operations we will be executing all commands from within the site directory
|
||||
For the rest of the operations, we will be executing all commands from within the site directory.
|
||||
|
||||
cd /path/to/site
|
||||
$ cd /path/to/site
|
||||
|
||||
The new site will have the following structure
|
||||
|
||||
|
|
@ -45,31 +43,36 @@ Currently the site doesn’t have any content, nor is it configured.
|
|||
|
||||
## Step 3. Create Some Content
|
||||
|
||||
Hugo also has the ability to create content for you.
|
||||
Hugo also has the ability to create a skeleton content page:
|
||||
|
||||
hugo new about.md
|
||||
$ hugo new about.md
|
||||
|
||||
A new file is now created in `content/` with the following contents
|
||||
A new file is now created in `content/` with the following contents:
|
||||
|
||||
+++
|
||||
draft = true
|
||||
title = "about"
|
||||
date = 2014-05-20T10:04:31Z
|
||||
+++
|
||||
```
|
||||
+++
|
||||
date = "2015-01-08T08:36:54-07:00"
|
||||
draft = true
|
||||
title = "about"
|
||||
|
||||
+++
|
||||
|
||||
```
|
||||
|
||||
Notice the date is automatically set to the moment you created the content.
|
||||
|
||||
Place some content in this file below the `+++` in the Markdown format.
|
||||
Place some content in Markdown format below the `+++` in this file.
|
||||
For example:
|
||||
|
||||
For example you could put this
|
||||
```markdown
|
||||
## A headline
|
||||
|
||||
## A headline
|
||||
|
||||
Some Content
|
||||
Some Content
|
||||
```
|
||||
|
||||
For fun, let’s create another piece of content and place some Markdown in it as well.
|
||||
|
||||
hugo new post/first.md
|
||||
$ hugo new post/first.md
|
||||
|
||||
The new file is located at `content/post/first.md`
|
||||
|
||||
|
|
@ -80,16 +83,16 @@ We still lack any templates to tell us how to display the content.
|
|||
Hugo has rich theme support and a growing set of themes to choose from:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/spf13/hugoThemes themes
|
||||
$ git clone --recursive https://github.com/spf13/hugoThemes themes
|
||||
```
|
||||
|
||||
## Step 5. Run Hugo
|
||||
|
||||
Hugo contains its own high performance web server. Simply run `hugo
|
||||
Hugo contains its own high-performance web server. Simply run `hugo
|
||||
server` and Hugo will find an available port and run a server with
|
||||
your content:
|
||||
|
||||
hugo server --theme=hyde --buildDrafts
|
||||
$ hugo server --theme=hyde --buildDrafts
|
||||
2 pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
|
|
@ -105,11 +108,11 @@ We specified two options here:
|
|||
|
||||
To learn about what other options hugo has, run:
|
||||
|
||||
hugo help
|
||||
$ hugo help
|
||||
|
||||
To learn about the server options:
|
||||
|
||||
hugo help server
|
||||
$ hugo help server
|
||||
|
||||
## Step 6. Edit Content
|
||||
|
||||
|
|
@ -118,9 +121,9 @@ changes and automatically rebuild your site. Hugo will then
|
|||
communicate with your browser and automatically reload any open page.
|
||||
This even works in mobile browsers.
|
||||
|
||||
Stop the Hugo process by hitting ctrl+c. Then run the following:
|
||||
Stop the Hugo process by hitting <kbd>Ctrl</kbd>+<kbd>C</kbd>. Then run the following:
|
||||
|
||||
hugo server --theme=hyde --buildDrafts --watch
|
||||
$ hugo server --theme=hyde --buildDrafts --watch
|
||||
2 pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
|
|
@ -130,14 +133,14 @@ Stop the Hugo process by hitting ctrl+c. Then run the following:
|
|||
Web Server is available at http://localhost:1313
|
||||
Press ctrl+c to stop
|
||||
|
||||
Open your [favorite editor](http://vim.spf13.com), edit and save your content and watch as Hugo rebuilds and reloads automatically.
|
||||
Open your [favorite editor](http://vim.spf13.com), edit and save your content, and watch as Hugo rebuilds and reloads automatically.
|
||||
|
||||
It’s especially productive to leave a browser open on a second monitor
|
||||
and just glance at it whenever you save. You don’t even need to tab to
|
||||
your browser. Hugo is so fast that the new site will be there before
|
||||
you can look at the browser in most cases.
|
||||
|
||||
Change and save this file. Notice what happened in your terminal.
|
||||
Change and save this file. Notice what happened in your terminal:
|
||||
|
||||
Change detected, rebuilding site
|
||||
|
||||
|
|
|
|||
|
|
@ -12,9 +12,7 @@ title: Using Hugo
|
|||
weight: 30
|
||||
---
|
||||
|
||||
Make sure either hugo is in your path or provide a path to it.
|
||||
|
||||
|
||||
Make sure either `hugo` is in your `PATH` or provide a path to it.
|
||||
|
||||
$ hugo help
|
||||
A Fast and Flexible Static Site Generator
|
||||
|
|
@ -56,7 +54,7 @@ Make sure either hugo is in your path or provide a path to it.
|
|||
|
||||
## Common Usage Example
|
||||
|
||||
The most common use is probably to run hugo with your current
|
||||
The most common use is probably to run `hugo` with your current
|
||||
directory being the input directory.
|
||||
|
||||
$ hugo
|
||||
|
|
@ -76,7 +74,7 @@ is saved.
|
|||
Press ctrl+c to stop
|
||||
|
||||
Hugo can even run a server and create your site at the same time! Hugo
|
||||
implements [live reload](/extras/livereload) technology to automatically reload any open pages in
|
||||
implements [LiveReload](/extras/livereload) technology to automatically reload any open pages in
|
||||
all browsers (including mobile).
|
||||
|
||||
$ hugo server -ws ~/mysite
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
aliases:
|
||||
- /layout/404/
|
||||
date: 2013-08-21
|
||||
linktitle: "404"
|
||||
linktitle: "Custom 404 page"
|
||||
menu:
|
||||
main:
|
||||
parent: layout
|
||||
|
|
@ -14,18 +14,19 @@ weight: 100
|
|||
---
|
||||
|
||||
When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide
|
||||
your own 404 template by creating a 404.html file in the root.
|
||||
your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html file in the root.
|
||||
|
||||
404 pages are of the type "node" and have all the [node
|
||||
variables](/layout/variables/) available to use in the templates.
|
||||
|
||||
In addition to the standard node variables, the homepage has access to
|
||||
In addition to the standard node variables, the 404 page has access to
|
||||
all site content accessible from `.Data.Pages`.
|
||||
|
||||
▾ layouts/
|
||||
404.html
|
||||
|
||||
## 404.html
|
||||
|
||||
This is a basic example of a 404.html template:
|
||||
|
||||
{{ partial "header.html" . }}
|
||||
|
|
|
|||
|
|
@ -11,15 +11,17 @@ title: Hosting on GitHub Pages
|
|||
weight: 10
|
||||
---
|
||||
|
||||
## Intro
|
||||
> *This tutorial was contributed by [Spencer Lyon](http://sglyon.com/).*
|
||||
|
||||
Many Hugo users have expressed interest in seeing a tutorial for how to set up a blog that generated by Hugo and hosted on GitHub Pages. This tutorial will do just that. We only require that the reader has Hugo installed correctly and is comfortable with git and GitHub.
|
||||
## Introduction
|
||||
|
||||
Many Hugo users have expressed interest in seeing a tutorial for how to set up a blog that is generated by Hugo and hosted on GitHub Pages. This tutorial will do just that. We only require that the reader has Hugo installed correctly and is comfortable with git and GitHub.
|
||||
|
||||
During this tutorial, I will walk you through the main steps I took to create an example blog available at [http://spencerlyon2.github.io/hugo_gh_blog](http://spencerlyon2.github.io/hugo_gh_blog). The source code for this blog is on [GitHub](https://github.com/spencerlyon2/hugo_gh_blog). Readers are encouraged to download the example repository and follow along.
|
||||
|
||||
### Find a Home for Your Files
|
||||
|
||||
As our goal is to host a website using GitHub Pages, it is natural for us to host the content of the page in a GitHub repository. Thus, the first step is to either create a new repository on GitHub or create a new directory within an existing repository where the content of the website will live. To do this I created the repository [spencerlyon2/hugo_gh_blog](https://github.com/spencerlyon2/hugo_gh_blog).
|
||||
As our goal is to host a website using GitHub Pages, it is natural for us to host the content of the page in a GitHub repository. Thus, the first step is to either create a new repository on GitHub or create a new directory within an existing repository where the content of the website will live. To do this, I created the repository [spencerlyon2/hugo_gh_blog](https://github.com/spencerlyon2/hugo_gh_blog).
|
||||
|
||||
## Create the Blog
|
||||
|
||||
|
|
@ -47,11 +49,11 @@ Hugo assumes that you organize the content of your site in a meaningful way and
|
|||
▾ posts/
|
||||
```
|
||||
|
||||
### Create html Templates
|
||||
### Create HTML Templates
|
||||
|
||||
The next step is to define the look and feel of your new website. Because Hugo will generate the site using html templates written by the user (you), this step is very subjective. I will merely present one possible theme that could be used to generate a blog. I decided to base the example project on a Jekyll theme called [lanyon](http://lanyon.getpoole.com). The lanyon theme is pure css and a slightly modified version of the css is in the `/static/css` directory of the example repository. If you are following along, you should grab the `static` folder from the example repository and put it alongside the `content` folder you just created.
|
||||
The next step is to define the look and feel of your new website. Because Hugo will generate the site using HTML templates written by the user (you), this step is very subjective. I will merely present one possible theme that could be used to generate a blog. I decided to base the example project on a Jekyll theme called [Lanyon](http://lanyon.getpoole.com). The Lanyon theme is pure CSS and a slightly modified version of the CSS is in the `/static/css` directory of the example repository. If you are following along, you should grab the `static` folder from the example repository and put it alongside the `content` folder you just created.
|
||||
|
||||
Because there are so many files needed to fully compose a complete website, I will not be able to go trough each of them here. I will, however, show what the directory structure should look like when all is said and done:
|
||||
Because there are so many files needed to fully compose a complete website, I will not be able to go through each of them here. I will, however, show what the directory structure should look like when all is said and done:
|
||||
|
||||
```
|
||||
▾ <root>/
|
||||
|
|
@ -77,11 +79,11 @@ Because there are so many files needed to fully compose a complete website, I wi
|
|||
README.md
|
||||
```
|
||||
|
||||
Each of the files in the example repository is well commented with a description of what the file as a whole does as well as an explanation of all major components in the file. If you are new to web development and/or Hugo I encourage you to search through these files to get a feel for how Hugo templates work and how the site is stitched together.
|
||||
Each of the files in the example repository is well commented with a description of what the file as a whole does as well as an explanation of all major components in the file. If you are new to web development and/or Hugo, I encourage you to search through these files to get a feel for how Hugo templates work and how the site is stitched together.
|
||||
|
||||
### Add Some Content
|
||||
|
||||
The final step in creating the blog is to add some actual blog posts. To do this simply create one markdown file (with extension .md) for each new blog post. At the top of each file you should include a metadata section that tells Hugo some things about the post (see [docs](/content/front-matter)). For example, consider the yaml metadata section from the top of the file `/content/posts/newest.md` from the example repository
|
||||
The final step in creating the blog is to add some actual blog posts. To do this, simply create one Markdown file (with extension `.md`) for each new blog post. At the top of each file you should include a metadata section that tells Hugo some things about the post (see [docs](/content/front-matter)). For example, consider the yaml metadata section from the top of the file `/content/posts/newest.md` from the example repository:
|
||||
|
||||
---
|
||||
title: "Just another sample post"
|
||||
|
|
@ -99,9 +101,9 @@ The keys set in this section are the mandatory `title` and `date` as well as the
|
|||
|
||||
Once the site is set up and working properly, we need to push it to the correct branch of a GitHub repository so the website can be served through GitHub Pages. There are many ways to do this. Here I will show the workflow I currently use to manage my websites that are hosted through GitHub Pages.
|
||||
|
||||
GitHub Pages will serve up a website for any repository that has a branch called `gh-pages` with a valid `index.html` file at that branch's root. A typical workflow might be to keep the content of a website on the `master` branch of a repository and the generated website on the `gh-pages` branch. This provides nice separation between input and output, but can be very tedious to work with. As a workaround we will use the `git subtree` family of commands to have the `public` directory (or whatever `publishdir` is set to in your `config.yaml`) mirror the root of the `gh-pages` branch of the repository. This will allow us to do all our work on the `master` branch, run Hugo have have the site output into the `public` directory, and then push that directory directly to the correct place for GitHub Pages to serve our site.
|
||||
GitHub Pages will serve up a website for any repository that has a branch called `gh-pages` with a valid `index.html` file at that branch's root. A typical workflow might be to keep the content of a website on the `master` branch of a repository and the generated website on the `gh-pages` branch. This provides nice separation between input and output, but can be very tedious to work with. As a workaround, we will use the `git subtree` family of commands to have the `public` directory (or whatever `publishdir` is set to in your `config.yaml`) mirror the root of the `gh-pages` branch of the repository. This will allow us to do all our work on the `master` branch, run Hugo to have the site output into the `public` directory, and then push that directory directly to the correct place for GitHub Pages to serve our site.
|
||||
|
||||
To get this properly set up we will execute a series of commands at the terminal. I will include all of them in one place here for easy copy and paste, and will explain what each line does via comments. Note that this is to be run from the `<root>` directory (wherever the `content` and `layout` folders of your Hugo project live). Also note that you will need to change the commands that have the example repository GitHub address so that they point to your repo.
|
||||
To get this properly set up, we will execute a series of commands at the terminal. I will include all of them in one place here for easy copy and paste, and will explain what each line does via comments. Note that this is to be run from the `<root>` directory (wherever the `content` and `layout` folders of your Hugo project live). Also note that you will need to change the commands that have the example repository GitHub address so that they point to your repo.
|
||||
|
||||
# Create a new orphand branch (no commit history) named gh-pages
|
||||
git checkout --orphan gh-pages
|
||||
|
|
@ -150,14 +152,14 @@ After executing these commands and waiting for the GitHub servers to update, the
|
|||
|
||||
Now, as you add new posts to your blog, you will follow steps that look something like the following:
|
||||
|
||||
* Create the markdown source for the new post within the `content/posts` directory
|
||||
* Create the Markdown source for the new post within the `content/posts` directory
|
||||
* Preview your work by running Hugo in server mode with `hugo server --watch`
|
||||
* Run Hugo not in server mode so that the generated urls will be correct for the website
|
||||
* Add and commit the new post in `master` branch
|
||||
* Push the `master` branch
|
||||
* Push the public subtree to the remote `gh-pages` branch
|
||||
|
||||
The first two items in the previous list are simply a way to conveniently preview your content as you write. This is a dynamic and fairly streamlined process. All the remaining items, however, are the same every time you want to add new content to the website. To make this repetitive process easier, I have adapted a script from the source repository for the [Chimer Arta & Maker Space](https://github.com/chimera/chimeraarts.org) website that is highlighted in the [Hugo Showcase](/showcase). The script lives in a file called `deploy.sh` and has the following contents:
|
||||
The first two items in the previous list are simply a way to conveniently preview your content as you write. This is a dynamic and fairly streamlined process. All the remaining items, however, are the same every time you want to add new content to the website. To make this repetitive process easier, I have adapted a script from the source repository for the [Chimer Arts & Maker Space](https://github.com/chimera/chimeraarts.org) website that is highlighted in the [Hugo Showcase](/showcase). The script lives in a file called `deploy.sh` and has the following contents:
|
||||
|
||||
**Note:**
|
||||
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@
|
|||
</div>
|
||||
|
||||
<div class="nav title-row" id="top_menu">
|
||||
<h1 class="nav top-menu"> {{.Title}} </h1>
|
||||
<h1 class="nav top-menu">{{.Title}}</h1>
|
||||
</div>
|
||||
</header>
|
||||
<!--header end-->
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
<!--sidebar start-->
|
||||
<aside>
|
||||
<div id="sidebar" class="nav-collapse ">
|
||||
<div id="sidebar" class="nav-collapse">
|
||||
<!-- sidebar menu start-->
|
||||
<ul class="sidebar-menu">
|
||||
{{ $currentNode := . }}
|
||||
|
|
@ -16,7 +16,7 @@
|
|||
</a>
|
||||
<ul class="sub{{if $currentNode.HasMenuCurrent "main" . }} open{{end}}">
|
||||
{{ range .Children }}
|
||||
<li{{if $currentNode.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.Url}}"> {{ .Name }} </a> </li>
|
||||
<li{{if $currentNode.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.Url}}">{{ .Name }}</a> </li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{else}}
|
||||
|
|
|
|||
44
docs/static/css/style.css
vendored
44
docs/static/css/style.css
vendored
|
|
@ -457,3 +457,47 @@ input.gsc-search-button-v2 {
|
|||
.gsc-search-box-tools .gsc-search-box .gsc-input {
|
||||
padding-right: 1px !important;
|
||||
}
|
||||
|
||||
/* Styled keypress from Wikipedia */
|
||||
|
||||
kbd {
|
||||
border: 1px solid #aaa;
|
||||
-moz-border-radius: 0.2em;
|
||||
-webkit-border-radius: 0.2em;
|
||||
border-radius: 0.2em;
|
||||
-moz-box-shadow: 0.1em 0.2em 0.2em #ddd;
|
||||
-webkit-box-shadow: 0.1em 0.2em 0.2em #ddd;
|
||||
box-shadow: 0.1em 0.2em 0.2em #ddd;
|
||||
background-color: #f9f9f9;
|
||||
background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee);
|
||||
background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee);
|
||||
background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee);
|
||||
background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee);
|
||||
padding: 0.1em 0.3em;
|
||||
font-family: inherit;
|
||||
font-size: 0.85em;
|
||||
}
|
||||
|
||||
/* For the table used in overview/configuration */
|
||||
|
||||
table.table {
|
||||
margin: 1em 0;
|
||||
}
|
||||
|
||||
.table-bordered th,
|
||||
.table-bordered td {
|
||||
border: 2px solid #ddd;
|
||||
padding: 0 0.5em;
|
||||
}
|
||||
|
||||
td.purpose-title {
|
||||
text-align: right;
|
||||
vertical-align: top;
|
||||
border-right: 0;
|
||||
padding-right: 0.5em;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
td.purpose-description {
|
||||
border-left: 0;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue