Oh no, you found it!

setup_hugo

Hugo

  • static side generator which uses markup-files (.md, .org, .asciidoc, rst, pandoc, etc.) for generating html
  • extremely configurable/customisable (and dependent on) via themes

Why

  • easy side setup
  • easy adding of content for different posts
  • simple theme extension/change (actually not that easy -.-)
  • cool and individuality of the themes/ side structure

Some Hugo-Terminology

  • front matter

    at the top of each content file is metadata (front matter) that:
- Describes the content
- Augments the content
- Establishes relationships with other content
- Controls the published structure of your site
- Determines template selection

  • archetype

    template for new files in the content directory, using a predefined =front matter= and markdown; 
located in the 'archetype' directory, e.g.: =default.md=

  • paginate

    To split a list page into two or more subsets.

  • shortcodes

    special template used to render a part of the site, they are *called from content pages*, e.g. for a special audio/video player

Setup and Usage

How to setup

Initial setup

# install, in my case it was packaged for archlinux
sudo pacman -S hugo

# initialise a directory with hugos directory structure
hugo new side SIDENAME

cd SIDENAME

Adding/Creating a theme

mkdir themes/ && cd themes/

# then either  clone a theme...
git clone URL_TO_THEM_REPO
# ... or create one
hugo new theme THEME_NAME

How to generate the side

Static

# in the main directory with the 'hugo.toml'
hugo
  • creates public/ directory with the static content

Development server

  • updated as you change your content, very handy (needs of course Javascript)
hugo server # or hugo -s

# to fully re-render the page when content or theme changes
hugo server --disableFastRender
  • NOTE: maybe delete the public/ directory when switching themes or when drastically changing the theme

Extending the blog/Continuous usage of hugo

  • archetype are what you usually use to create a new side to have a skeleton, especially for the front matter, to use it, call this in the home directory of the hugo side:

    # creates a new side in SECTION_NAME using the '.org' archetype as a startingpoint
hugo new content content/SECTION_NAME/SIDE_NAME.org

  • the archetype for the .org file in this example looks like this (default.org):

    #+DATE: {{ .Date }}
#+DRAFT: true
#+TITLE: {{ replace .File.ContentBaseName "-" " " | title }}
#+CATEGORIY: default
#+KEYWORDS[]:
#+DESCRIPTION:

* {{ replace .File.ContentBaseName "-" " " | title }}
    • this already inserts the CATEGORIY and KEYWORDS structure, enables a DRAFT and sets the default title from the filename, removing '-' in the name

Deploying the Side

  • simply just transfer the public/ folder to the server you want to deploy the side on:

    # in the root of the hugo blog directory
rsync \
   --chown http:http \ # used for sever which runs as user and group http
   -avz --delete \  # use (a)rchive mode in (v)erbose output 
                    # and compress(z) for transfer 
                    # and --delete files on the remote, that are not in src
   public/ \ # src
   SERVER_ADDRESS:/path/to/server/root/ # remote destination directory

Working with themes

  • a theme has the same structure as the main side, you could also do just everything in the theme directory
  • this theme: A Fine Theme

Important things to understand

  • template lookup order
  • template types
  • template context
  • front matter
  • Taxonomy
  • Render Hooks
  • shortcode template

Folder Structure

  • e.g.:

    .
├── archetypes
│   ├── default.md
│   └── default.org
├── assets
│   ├── css
│   │   └── main.css
│   └── js
│       └── main.js
├── data
├── hugo.toml
├── i18n
├── _shortcodes
│   ├── audio_player.html
│   └── image.html
├── layouts
│   ├── baseof.html
│   ├── home.html
│   ├── page.html
│   ├── _partials
│   │   ├── footer.html
│   │   ├── head
│   │   │   ├── css.html
│   │   │   └── js.html
│   │   ├── header.html
│   │   ├── head.html
│   │   ├── menu.html
│   │   └── terms.html
│   ├── posts
│   │   └── section.html
│   ├── section.html
│   ├── taxonomy.html
│   └── term.html
└── static
    ├── IMAGE.jpg

how it works

  • archetypes for default entrypoints of new posts
  • assets and static for content that gets just copied to public directory when building
  • i18n for translations

  • layouts: most important, define the structure; some filenames are reserved:

    • base filename: baseof.html, starting point of the website, includes other
    • home.html, page.html, section.html, taxonomy.html, term.html: used for different page-types and contain the main-function
    • _partials/: folder with 'building blocks' used in the different pages

Menu

  • automatic

    • to enable automatic menu entries in your side, use this in your hugo.toml

      sectionPagesMenu = "main"
  • front matter
  • manual

Custom Taxonomy/Section Page

Templating System

  • iteration
  • main
Tags: