A maniac guide to hugo publishing on github pages

This blog uses hugo and github pages. Except from the compulsive need to keep the local repository tidy, I am happy with them.

The code

I installed hugo as any other go programs, locally in $GOPATH with go get github.com/spf13/hugo and I update it with go get -u github.com/spf13/hugo.

Some might prefer other install methods from the hugo documentation.

The content

Run hugo new site /path/to/site to create a site skeleton, initialize as a git repository cd /path/to/site && git init and then run hugo new somecontent.md, see the hugo documentation to configure it further.

At this point, you should get something like:

├── archetypes/           --> content templates
├── config.toml           --> hugo global config
├── content/              --> your content
│   └── somecontent.md
├── layouts/              --> layout templates
└── static/               --> static files folder (css, js, images ...)

If you edit your somecontent.md file and run the hugo command, you should get:

├── archetypes
├── config.toml
├── content
│   └── content.md
├── layouts
├── public
│   ├── 404.html
│   ├── content
│   │   └── index.html
│   ├── index.html
│   ├── index.xml
│   ├── sitemap.xml
│   └── tags
│       ├── bartag
│       │   ├── index.html
│       │   └── index.xml
│       └── footag
│           ├── index.html
│           └── index.xml
└── static

Let’s say you add some files to the static folder, such as a js file, an image, run hugo and the public folder gets bigger again:

├── archetypes
├── config.toml
├── content
│   └── content.md
├── layouts
├── public
│   ├── 404.html
│   ├── content
│   │   └── index.html
│   ├── index.html
│   ├── index.xml
│   ├── js
│   │   └── some.js
│   ├── sitemap.xml
│   └── tags
│       ├── bartag
│       │   ├── index.html
│       │   └── index.xml
│       └── footag
│           ├── index.html
│           └── index.xml
└── static
    └── js
        └── some.js

So obviously, you don’t want to keep the public folder under git control but yet, you need to push its contents to github pages.

The style

Hugo provides many ways to customize how the result looks like:

You may want to use a theme as a git submodule if you find one that fits and just override its defaults with your preferences.

The images and other heavy documents

Images, Javascript libraries and other “heavy” files can be stored in the static folder. You will be able to preview while offline.

Offline, with a fat git repository, filled with vendor libs, large images. brr. I prefer to host:

I guess that one could move almost all non content related assets within the theme, imported as a submodule.

The old posts

I imported and curated old contents using various exports mechanisms and converters from ATOM to jekyll format. These tools won’t convert HTML to markdown but they will add the relevant metadata in the front matter , tags, categories, etc.

Search github for jekyll exporters

Fork me on GitHub