Using HUGO as a wiki platform

As you may have noticed, static site generators are back in fashion:

Smashing magazine article

We are suggesting here a static site generator as a wiki platform that is easy to built and to maintain and use markdown format as your content. Developers seem to like markdown format so I suppose it is here to stay.

You should have in mind that "Static site" = {HTML, CSS, JAVASCRIPT} so a static site may not be so static as it sounds.

Among the 200+ static site generation software we distinguish the following:

• Jekyll?
• Octopress?
• FsBlog?
• Hugo!

We have chosen Hugo mainly for portability reasons.Hugo is written in Go. So there are no dependencies. Only one binary you download and use in any platform (linux, arm, mac os x, windows).

In our test installation we are using an 64bit ubuntu 14.04 server so we download hugo_0.14_linux_amd64.tar.gz

Extracting:

tar xvf hugo_0.14_linux_amd64.tar.gz

Moving the executable to the ~/bin directory as hugo and we are ready to use it!

mv /home/ckout/hugo/hugo_0.14_linux_amd64/hugo_0.14_linux_amd64 ~/bin/hugo

Create a new site:

hugo new site /home/ckout/wiki

cd to your site:

cd /home/ckout/wiki

We will use the theme hugo-bootstrap for this wiki so git clone it inside the "themes" directory:

cd themes/
git clone https://github.com/mmrath/hugo-bootstrap

On the github url of the theme we can find all the usage information.

We are using here the following configuration:

 config.toml

# hostname (and path) to the root eg. http://spf13.com/
contentdir = "content"
layoutdir = "layouts"
publishdir = "public"
builddrafts = false
baseurl = "docsrv.epilis.gr/"
#bind = "http://docsrv.epilis.gr"
port = "80"

# Site title
title = "IT Operations Wiki"

# Copyright
copyright = "(c) 2016 IT Operations."

# Language
languageCode = "en-EN"

# Metadata format
# "yaml", "toml", "json"
metaDataFormat = "toml"

# Theme to use (located in /themes/THEMENAME/)
theme = "hugo-bootstrap"

# Pagination
paginate = 10
paginatePath = "page"

# Enable Disqus integration
#disqusShortname = "your_disqus_shortname"

[permalinks]
    post = "/:year/:month/:day/:slug/"
    code = "/:slug/"

[taxonomies]
    tag = "tags"
    topic = "topics"

[author]
    name = "IT Operations"
    email = "yourname@example.com"

#
# All parameters below here are optional and can be mixed and matched.
#
[params]

    # You can use markdown here.
    brand = "EPILIS"
    topline = "IT Operations Documentation"
    footline = "code with <i class='fa fa-heart'></i>"

    # Text for the top menu link, which goes the root URL for the site.
    # Default (if omitted) is "Home".
    home = "home"

    # Select a syntax highight.
    # Check the static/css/highlight directory for options.
    highlight = "default"

    # Google Analytics.
    #googleAnalytics = "Your Google Analytics tracking code"

    # Sidebar social links.
    #github = "enten/hugo-boilerplate" # Your Github profile ID
    #bitbucket = "" # Your Bitbucket profile ID
    #linkedin = "" # Your LinkedIn profile ID (from public URL)
    #googleplus = "" # Your Google+ profile ID
    #facebook = "" # Your Facebook profile ID
    #twitter = "" # Your Twitter profile ID
    #youtube = ""  # Your Youtube channel ID
    #flattr = ""  # populate with your flattr uid

[blackfriday]
    angledQuotes = true
    fractions = false
    hrefTargetBlank = false
    latexDashes = true
    plainIdAnchors = true
    extensions = []
    extensionmask = []

In the data directory we created the Menu.toml file:

 Menu.toml

[about]
    Name = "About"
    IconClass = "fa-info-circle"
    URL = "/about"

[posts]
    Name = "Posts"
    Title = "Show list of posts"
    URL = "/post"

[tags]
    Name = "Tags"
    Title = "Show list of tags"
    URL = "/tags"

...and we created some marksown inside this directory:

/home/ckout/wiki/content/post/

The tags are referenced in every *.md article like that:

tags = [ "howto", "hugo", "markdown" ]

Now we are running Hugo server to browse our content (you need sudo if you want to play at port 80):

sudo hugo server --baseUrl=docsrv.epilis.gr --bind="0.0.0.0" --port=80 -w -v

The server is watching (-w) for changes in /home/ckout/wiki/{data,content,layouts,static,themes/hugo-bootstrap}

...and is serving here:

http://docsrv.epilis.gr/

The rendered content is living inside the "public" directory of your site so your can choose your favorite http server to serve your site in production environment.