Manage Publishers with Bissetii in Hugo

After configuring and writing your pages, it's time to manage to publishers. Hugo supports a wide varieties of publishers available on the Internet. Hence, Bissetii must be able to provide support most of them.

Run Hugo Server

Before performing publication, you need to know how to execute the Hugo server for your development hosting. That way, it allows everyone including Bissetii developers to synchonize your development and communications. The recommended Hugo server command would be:

1
2
3
4
5
6

$ cd .sites                           # enters the engine
$ hugo server --buildDrafts \
	--disableFastRender \
	--bind "localhost" \
	--baseURL "localhost" \
	--port 8080

The hugo server instruction is to:

  1. Render the draft regardless of the page status.
  2. Disable fast rendering to avoid unnecessary caching.
  3. Bind localhost domain for local access
  4. A working port number.

To ensure Bissetii works properly with restrictive output format (e.g. Accelerated Mobile Pages), Bissetii disabled Hugo’s auto-reload feature by default. Hence, you need to manually refresh the page to reflect your changes.

Also, be reminded that the hugo server will hold the terminal until it is completed. Hence, open a new terminal to execute it.

Build Your Website

Upon completing your development, you can proceed to build your site artifact for publications. The build command Bissetii team uses would be:

1
2

$ cd .sites                           # enters the engine
$ hugo --minify

Bissetii configured the default output path is the public/ directory located at your root directory (or 1 level above).

Commit to Publisher

With the compiled public/ artifact ready to be published, the next thing is to commit it. Depending on the server providers, each provider has its own set of implementations.

GitHub Pages

The most common static site generator hosting provider would be GitHub Pages. This section is for you if you’re using Github Pages as your primary hosting provider.

Manually Shift 404.html

Hugo compiled 404.html into the each language specific directory. Github Pages specifically mentions that they can only accept 1 404.html file at the root directory. Hence, you need to copy it out.

Example, say you have en language directory, your command would be something as such:

1

$ cp public/en/404.html public/.

DO NOT git commit your compiled public/ directory into your current branch.

Create gh-pages Branch

Bissetii strongly recommends to publish the artifact using the gh-pages branch method. This is because:

  1. It can avoid duplicated artifact copies.
  2. It avoids conflicting with your existing docs/ directory.
  3. It is easier, clearer, and simple to implement.

To start, simply create an empty gh-pages branch. If you already done it and have a gh-pages branch already, simply skip this step. Otherwise, the commands are as follows:

1
2
3
4
5
6

$ git checkout --orphan gh-pages
$ git reset --hard
$ git clean -fd
$ git commit --allow-empty -m "Init"
$ git push origin gh-pages:gh-pages
$ git checkout <back to your work branch>

Clean Up Old Artifact

For those who do not want to keep multiple artifact copy (no point keeping them since you can rebuild at any point of given time and commit ID), proceed to clean up the gh-pages branch to the first blank commit. The commands are:

1
2
3
4

$ git checkout gh-pages
$ git reset --hard "$(git log '--format=format:%H' | tail -1)"
$ git clean -fd
$ git checkout <back to your work branch>

Publish Your Artifact

Once you have the the gh-pages branch ready, proceed to publish your public/ directory. The command is:

1
2
3
4
5

$ git checkout gh-pages
$ git add -f public
$ git commit -m "Build output as of $(git log '--format=format:%H' -1)"
$ git push -f origin gh-pages
$ git checkout <back to your work branch>

GitLab Pages

GitLab Pages shares the same instructions as GitHub Pages. The only 1 extra one-time setup is to add the additional GitLab CI instructions into your gitlab-ci.yml file. They are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

image: debian:latest

pages:
    stage: build
    tags:
        - linux
    environment:
        name: production
    only:
        refs:
            - gh-pages
    artifacts:
        paths:
            - public
    script:
        - mkdir -p public
        - shopt -s extglob
        - mv !(public|.*) public

Basically, this is to instruct GitLab CI to package and publish the gh-pages branch artifacts into its GitLab Pages component. Otherwise, it would not work on GitLab since it is entirely depends on its GitLab CI to perform its repository processing.

Wrapping Up

That is all for managing publishers with Bissetii in Hugo. If you have any question to ask us directly, please feel free to raise it at our GitLab Issues Section. We will be happy to assist you.