Pelican |

Automated deployment of Hugo generated site to Github pages

Wed, 14 Sep 2016 20:54:16 +0000

In the last post, I listed the typical workflow of generating a static website with Hugo. Here I would like to share the issues I encountered and the tweaks I’ve made. The source codes for this site can be found .

Basic setting in my config.toml for the Academic Theme

Many beautifully designed themes are already . I decided to use the , because it’s specifically designed for academic uses, showcasing publications, personal profile, and projects. For more details, please see the in action.

In config.toml, one can set the universal variables used by Hugo to generate HTML pages. For example:

baseurl = "https://fischcheng.github.io/"
title = "Yu Cheng"
copyright = "&copy; 2016 Yu Cheng"
languageCode = "en-us"
theme = "hugo-academic"

Also some specific parameters used by the chosen theme:

[params.about]
 interests = ["Largescale ocean circulation", "climate variability and modeling"]
 str_interests = "Interests"
 str_education = "Education"

[[params.about.education]]
 course = "BSc in Atmospheric Sciences"
 institution = "National Taiwan University"
 year = 2010

In the academic theme, there are 7 sections on the homepage. The about and teaching sections are under content/home. The content of personal profile is from about.md, yet the entries in interests and education are configured in config.toml.

Three other types of contents are publication, post and project. Each has its unique page layouts, stored under corresponding folders under content. Add a line selected = true in the meta-data part in the publication entry to ensure that entry displayed in the selected publication section.

Next change following items to customize the navigation bar:

[[menu.main]]
 name = "Home"
 url = "#top"
 weight = 1

[[menu.main]]
 name = "Publications"
 url = "#publications"
 weight = 2

[[menu.main]]
 name = "Posts"
 url = "#posts"
 weight = 3

[[menu.main]]
 name = "Research"
 url = "#projects"
 weight = 4

[[menu.main]]
 name = "Works"
 url = "#works"
 weight = 5

[[menu.main]]
 name = "Contact"
 url = "#contact"
 weight = 6

Changing the name will tell Hugo to replace the navbar items and URL for the page that button linked to. I modified the default teaching.md page to works and renamed project section to research. Also, I enabled commenting by setting disqusShortname = "yucheng" in config.toml. And follow this snippet to add a new social network icon:

[[params.social]]
 icon = "envelope" # icon name for email
 icon_pack = "fa" # for font-awesome icons
 link = "mailto:username@xxx.xxx"

On top of the hugo-academic theme, I added an additional stylesheet under static/css. This changes the default color scheme from light blue to green. Besides, I changed the font of the navbar-brand, the title of my site by adding following lines:

.navbar-brand {
 text-transform: uppercase;
 font-weight: bold;
 font-size: 1.5em;
 color: #2b2b2b;
 font-family: 'Permanent Marker', cursive;
}

The contents within static/js and static/ccs will be included in the header.html after the default ccs stylesheets, so it’s totally possible to change color scheme without modifying anything in the themes/academic. However, to change fonts, I modified themes/academic/layouts/partials/header.html to load an additional font Permanent Marker from google fonts.

<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:400,700|Merriweather|Roboto+Mono|Permanent+Marker">

Github pages, user site or project site

Two kinds of site are supported on GitHub pages, the user/organization site, and the project site. For the former, the site itself is a repository, everything under master branch will be displayed under this address https://<username>.github.io, which is customizable. And the later is a website to showcase an existed repo. Without changing the original branch, everything under gh-pages branch can be accessed under http://<username>.github.io/<repository>. Github even provides an Automatic Generator to help to create a project site. More details can be found .

My website is an user site. Under this repo fischcheng.github.io, the source branch archived all changes to the source codes, and master branch store the Hugo-generated HTML pages.

Automated deployment using Wercker

The default way to build a hugo site is simple, invoke hugo under the site root. A public folder will be created, containing every HTML pages and copied stylesheets and static files (banner images and profile icons or so). Push this folder to the master branch, and voila, the site is online.

What if a single push to the source branch (or whatever name of your development branch) can trigger all the rest steps? Travis-CI was my old choice for the last version of this site, until I came across this wonderful guide on Hugo’s official . However, things changed a lot since that article was last edited and below I would like to detail all the issues I ran into and how I solved them.

is a continuous integration (CI) tool that helps developers to build, test and deploy their applications based on . A Wercker account can be easily hooked to a given Github or Bitbucket account, and one can create new applications from a chosen repository. After setting up, a push to the repository will automatically trigger the application. One of the biggest advantages of Wercker over Travis-CI is the collection of easily-located and well-documented steps. In our case, the application consists of two steps build hugo and deploy to GitHub.

Wercker dashboard: to find existed steps, click the Registry tab; to create your own applications and steps, access the Create tab.

The first task is to create the config.yml ( ) in the developing branch. Please follow the original Hugo guide to setup the link between a Wercker application to the Github. Below, I will only list out the discrepancies I encountered.

Build

Following the official guide, I used this to trigger Hugo to build HTML pages. However, my first try didn’t successfully generate the pages correctly, because the arjen/hugo-build step couldn’t find the hugo-academic theme. For easier tracking and updating, I forked the hugo-academic repo, and I later realized that, for a repo embedded within another repo, the former is counted as a submodule. For the build step to work as desired, I had to install git and initialize submodule to ensure that the build step can locate the hugo-academic theme. Kudos to this which helped me to track this issue down.

box: debian

build:
 steps:
 - script:
 name: install git
 code: |
 apt-get update
 apt-get install git -y
 - script:
 name: initialize git submodules
 code: |
 git submodule update --init --recursive
 - arjen/hugo-build@1.11.0:
 version: "0.15"
 theme: "hugo-academic"
 flags: --buildDrafts=true

Deploy

There is no more such thing as “Add deploy target” in Wercker. The interface has changed to the new “workflows of pipelines.” This change is so new that even the documentation on Wercker website has not changed yet. Their customer service still referred me to the old supporting materials.

So I poked around and realized that, even if the second deploy step is included in the wercker.yml, one still needs to manually add a new “pipeline” under the “workflow” tab. Upon creating a new pipeline, the “YML pipeline name” must be in the predefined names in the wercker.yml.

Here I used this to deploy the built site to GitHub. Each pipeline starts from scratch. So for the deploy pipeline, the git package needs to be installed again. One also has to setup the environment variable $Git_Token, acquired from Github setting.

deploy:
 steps:
 - script:
 name: install git
 code: |
 apt-get update && apt-get install git -y
 - leipert/git-push@0.7.6:
 gh_oauth: $Git_Token
 gh_pages: true
 basedir: public
 branch: master

Click deploy pipeline to setup included environment variables. Get the Github access token from Github profile setting.

Switch from Pelican to Hugo

Wed, 14 Sep 2016 01:16:30 +0000

Being a big fan of all things Python, I built the last two incarnations of this site with Pelican. I even went to the length to set up a Travis CI to automatically build and deploy to GitHub pages. That was the beginning of the summer and only two new posts ever since.

Recently, my boss has brought up the topic of building a group website. Also, there is a joint-project website needs to be done. Most other groups in the school have their group website, mostly hosted by Weebly, Wordpress or Wix. Those website services certainly have pros. For one, a Weebly site can easily allow multiple contributors. But most customization and advanced features are usually not free.

So, I shared my experience of hosting a static site on Github pages and showed off my Pelican-powered website. By generating your own website, hosted by some popular cloud services (i.e. Amazon S3 and Github), one has full control to the contents and styles. All other responsive features such as site analytics and commenting can be achieved by integrating with existed online services.

Static site generators

Options are plenty, to name a few, Jekyll, Octopress, Pelican, Middleman, and Hugo. They were written in different languages (Ruby, JavaScript, Python and Go, etc.) but serve the same goal – construct the bare bone of a website and render the contents to the publishable HTML pages.

Not every site generators were created equal. Folks from different languages tend to choose the one they are familiar with. That was why I used Pelican initially. For the time-being, I realized that Pelican community is not very active, and theme options seems a bit thin. Jekyll is more matured, and there are already numerous professional-like themes available. However, it is Hugo that caught my eyes.

Hugo has certainly attracted many people from Jekyll. The binary itself is written in Go, and no other dependencies are necessary. It renders Markdown file to HTML really fast (we are talking about millisecond here.) Its structure makes switching between themes and customization overwriting the chosen theme super easy. Also, Hugo was the name I had during the 7-day intensive Spanish program that I completed in the past summer.

hugo

Hugo workflow

Let me walk you through the basics of building a Hugo-powered website. For more details, readers are referred to the official Hugo

Install Hugo binary: for OS X (and the future Mac OS) users, it’s recommended to do it through homebrew, just like for most open-source software.
```
 brew install hugo
```
Create a new site under the desired root directory:
```
 hugo new site sitename
```

The generated directory have the following layout:

 .
|-- archetypes
|-- config.toml
|-- content
|-- data
|-- layouts
`-- static
5 directories, 1 file

Create new posts under the content folder:
```
 hugo new post/postname.md
```
config.toml is the key configuration file to let Hugo know how to render the contents.
Pick a theme from or build your own. To apply a theme, one needs to create a themes folder under the root, and git clone or make a new-theme directory under this folder. Then switching themes can be achieved by adding a line in config.toml file like this theme = "hugo-academic", or tell hugo which theme to build with using this command hugo server --theme=hugo_theme_name
Check the results by running a virtual server, which automatically listens to any changes you make and render HTML in real time. Go to to see your shiny new site in action.
```
 hugo server --watch
```
Build the pages by invoking hugo. Generated HTML pages will by default be stored under public folder. It is this folder you need to find a home to host.

comments and tips

Posts are usually written in Markdown, though it also supports other markup languages. Markdown is really elegant and easy to use, definitely worth picking up.
The equivalent of extension in Hugo is shortcodes, which are stored under layout/shortcodes directory. These pre-defined snippets can allow site-owner to embed Youtube, Vimeo players and individual tweet into their posts.
Most themes support Disqus for commenting or google-analytic for analyzing website usage.
The format of metadata in the markdown files might be different from those using other site-generators. So, migrating old posts to Hugo needs some works (could be easily down with some simple parsing scripts.)
Add customized CSS stylesheet under static to overwrite settings in the chosen theme.

Renovate this place and new goals

Tue, 05 Jul 2016 16:06:00 +0000

I’ve just spent the long weekend updating my nearly-abandoned website. This year, I have passed my qualifying exam (February), and the paper I’ve been working on for almost an year is now finally accepted.

The website has been changed to a GitHub user-page, instead of a project-page. Also, now the website is automatically generated by Travis-CI, a very popular service recently, testing and deploying the codes to ensure portability. All the changes and new posts are made on my laptop. Html pages are built by Pelican/Python3, on the /source branch. A push to the remote host will trigger Travis-CI. With a little help from ghp-import, the Travis-CI-generated pages will be force-pushed to the /master branch. Voila, that is the website now you are looking at.

Through this little-over-two-days endeavor, I now had more knowledge on Github, Travis-CI, and more control on my own website templates. Now it’s just the matter of keeping things rolling – I made the resolution to post more frequently. In fact, I have just updated the Work page to include some of my recent presentations and abstracts. I will also post some of the notes from our group meeting.

Building a static blog with Pelican

Tue, 10 Jun 2014 12:05:00 +0000

Once upon a time…

I spent a summer using Microsoft Frontpage to build a website, hosted by my highschool’s server. Then I also had my first experience with PHP, javascript, html, css, cgi (common gateway interface, I haven’t seen such things for a while!) However, some popular free-webpage services just kept popping out the years after, as “blog” became a everyday word. All of a sudden, a vibrant and powerful “blog”, usually implemented with guestbook and albums is just few clicks away. Thus, I stop writing my own webpages. That was ten years ago. Years later, even MS Frontpage is discontinued. End of last summer, every students in RSMAS got an mail about annual progress report, and building your personal page is listed as a requirment. I first cheated by adding a new blog using wordpress, refusing to revisit my old friends, being afraid of spending too much time on such distractions. However, these distractions just won’t dispear even though I tried hard to ignore… Therefore, after the tiring semster with TA and seminar talk, I came back to revisit some other interesting stuffs I’ve had no time to spend on for the past few months.

Pelican: I love this bird!!

I’ve heard about Django quite often, so it was my first try. Lacking of PHP knowledge, and a personal site needs not to have some log-in or user-management functions, I decided to build a static blog. By accident, I noticed that lots of technical blogs are hosted by Github, and powered by Jekyll, Octopress or Pelican. The reason that I chose Pelican, is simply because it’s python/jinja2 based. And I happened to find some very good references:

{% img http://www.allaboutbirds.org/guide/PHOTO/LARGE/brown_pelican_5.jpg 400 500 %}

Overview

Pelican is a static site engine powered by python, using templates based on Jinja2. It supports both reStructuredText and Markdown, as well as asciiDoc and html, which makes writing new posts extremely easy. The center of a pelican-powered site is the configuration.py file, which controls the basic settings of your site, including side bar, navigation bar options, disqus-comments, tags, categories, twitter supports, and PATH. All the original files (including .md, .rst files) are stored in /contents, and all the html generated by Pelican go to /output folder. Simply upload the /output folder to your web-host, and T’ADA, your website is on. For details of installation and deployment, pleace check official Pelican documentation.

Themes

One of the reasons that I chose Pelican is the active community on Github. As mentioned above, pelican templates are generated by Jinja2, which is a template engine powered by Python. A set of themes including templates of different pages and stylesheets. There are many high-quality themes available on github, which can be easily downloaded using following command:

:::bash
git clone https://github.com/getpelican/pelican-themes

This blog is powered by pelican-bootstraps3 theme; few other themes I would also like to try are Pelican-pure, Mockingbird and Notmyidea. Additional stylesheet can be easily integrated by changing the setting in configuration.py. To switch between different themes, just modify this line in your configuration.py.

:::python
THEME = "pelican-bootstrap3" # or whatever themes you like

Customize

This is a more tricky part, due to my limited knowledge of CSS and Jinja2. So far I’ve only managed to change the background color, font size, line-height and link-hover style of my header. Even though the syntax of CSS is very straightforward, lacking of nested structure, it is very difficult to read the CCS stylesheet by someone else: one must figure out the class/ID names of each elements in the html files, and locate corresponding tags in the minified CSS file. I’ve found a Sublime-Text package to unminify the CSS, yet still find it difficult to change even a single property. Currently, I am attempting to use SASS/COMPASS to rewrite the stylesheet.

Plugins

One of greatest feature of Pelican is to include modular plugins into your static site. Same as Pelican-themes, these plugins can be downloaded easily from github.

:::bash
git clone https://github.com/getpelican/pelican-plugins.git

Curretnly, I am using the Liquid-tags plugin by to enable Youtube video, iPython notebook, code-block and image insertion in my blog posts, as well as the Math-rendering. Other plugins such as Gravatar and internal-links are very easily to be implemented, in fact, just two lines in the configuration.py. The idea of plugins, are similar to the idea of importing libraries in the beginning of every Python scripts.

:::python
# Plugins
PLUGIN_PATH = '/Users/yucheng/Desktop/Other/MyPage/pelican-plugin'
PLUGINS = ['liquid_tags.img', 'liquid_tags.video',
'liquid_tags.youtube', 'liquid_tags.vimeo',
'liquid_tags.include_code', 'liquid_tags.notebook','render_math']

Summary

Pelican is a really powerful static-site generator, using Python. All options you may play with are in the configuration.py and the syltesheet.css. The official documentation of Pelican is rather complete, not to mention the active developer-base. If you are a Python lover, it won’t take you too long to setup a really polished and somehow-dynamic static site. So, look no further, among numerous static-site engines, Pelican is definitely one of the best.