Updating mapstruct.org

As MapStruct itself, this web site is open-source, too. You can find it’s source code here.

The website is built using the Hugo static site generator. So it’s recommended to spend a few minutes reading the Getting Started section of the Hugo docs if you are not familiar with it yet.

The site is deployed to GitHub Pages (as a “project page”, using the “gh-pages” branch).

Set-up

Install Hugo by following the instructions given on its homepage. E.g. using brew if you are on OS X:

brew update && brew install hugo

Make sure that you are using Git 2.5 or later due the worktree feature used for publication (see below). Check out the web site’s source code and assign the name “upstream” to the remote repository by running:

git clone git@github.com:mapstruct/mapstruct.org.git
git remote rename origin upstream

Set up a tracking branch for the “gh-pages” branch:

git fetch upstream && git branch --track gh-pages upstream/gh-pages

Local preview

Hugo comes with a built-in server for previewing the web site locally. Start it by running:

hugo server --buildDrafts

The server injects some magic JavaScript which enables auto-reload of rendered pages in the browser as the source files are edited.

Content authoring

Web site contents are written using Markdown, source files are located under content. You can mark a new page, e.g. a news post, as a draft which will cause it to be ignored when generating the production website:

---
title: "My blog post"
draft: true
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit...

For news posts a short summary is shown on the home page and the news landing page. Add the “more” comment to your posts after the part of the post that should be shown in the summary, e.g. an introductory first paragraph:

---
title: "My blog post"
---
Two or three sentences as a teaser.

<!--more-->

And then the remainder of the post.

Adding an entry to the team page

The team page is a data-driven page. If you want to be listed on the page, add a new file to data/team following the structure of the existing files in that directory.

Publishing to mapstruct.org

The web site is generated by running the hugo command. This generates the HTML pages in the public directory. The contents of that directory then needs to be synchronized with the “upstream/gh-pages” branch.

To make publication as smooth as possible, the script scripts/publish.sh is taking care of the regeneration. It removes any existing contents from public, calls hugo and afterwards removes some generated files which are not needed.

For synchronizing public with the local “gh-pages” branch the script creates a git worktree with the “gh-pages” branch in public and commits the generated files into the “gh-pages” branch. You then only need to push that branch to upstream.

A typical editing process will look like this (assuming you start on the master directory):

# update local branches
git fetch upstream
git merge upstream/master

# do your changes...

# commit; then re-generate and update gh-pages
git commit -a -m "Some website change"
./scripts/publish.sh

# deploy
git push upstream gh-pages
git push upstream master