Royal Theme for Hugo

This is a port of the Sphinx theme of the same name I made for the French RPG Maker community RPG Maker Alliance (RMA). Even though Hugo is mostly used for blogs, it does documentations pretty well!

The theme is responsive and should work on every platform. However it is centered and has a fixed max width. The theme is currently available in English and French (see the i18n folder)

You can see a live example running at wiki.gamedevalliance.com

Installation

Royal require the extended version of Hugo. Clone the repo inside the themes folder of your Hugo installation like so :

cd themes
git clone https://github.com/princesseuh/hugo-royal-theme

Alternatively you can add the theme as a Git Submodule, making it easier for other users to pull your repo

Then in your site's config.toml, set the theme :

theme = "hugo-royal-theme"

And there you go! You should now have a working installation using this beautiful theme. Check below for more information on how to enable and customize all of its features.

Configuration

This theme does not require any specific setting to work, however certain features are disabled if certain files or parameters are missing. Unlike the Sphinx version, there's no RMA branded assets included in the theme

Menus

Royal uses Hugo's Menus feature to generate the header and left sidebar menus (the right sidebar however is automatically generated from the table of content)

For the header, the menu is called global. You can populate it by editing your config.toml file like so :

[[menu.global]]
name = "Website"
weight = 1
identifier = "website"
url = "https://princesseuh.net"

[[menu.global]]
name = "Twitter"
weight = 2
identifier = "twitter"
url = "https://twitter.com/VanillaHoys"

The header menu currently doesn't support parents and submenus.

For the left sidebar, the menu is called docs. Like for the header, you can populate it by editing the config.toml, however only childs will actually be clickable (there is currently no way to change this)

So for instance, to add a link through the config file you need to do it like this :

[[menu.docs]]
name = "GitHub Links"
identifier = "meta"

[[menu.docs]]
name = "Source Code"
parent = "meta"
url = "https://github.com/princesseuh/hugo-royal-theme"

Which will result in this :

(The GitHub icon is automatically added to GitHub links in the left sidebar)

To add a menu entry through a page's front matter, see this page from the Hugo documentation

Removing the trailing slash in URLs (Experimental)

Hugo currently does not support natively removing the trailing slash from URLs. However, Go's templates are powerful enough to be able to do it ourselves!

To try it out, add

[params]
removeTrailingSlash = true

to your config.toml.

Take note that this will also affect external links and canonical url meta tags. However it won't touch the ref and relref shortcodes, you'll have to make your own. (Example)

Adding a logo

Put an image called logo.png in {SITE_ROOT}/static/assets/. Royal will automatically use it for the header instead of writing the website name

Adding a favicon

Like for the logo, Royal checks if a file called favicon.png exists in {SITE_ROOT}/static/assets/. Royal currently does not support having multiple formats and sizes for favicon

"Edit this page" link

The Edit this page link (both in the sidebar and in the shortcode) requires editURL to be set in the params section of your config.toml file. Like so :

[params]
editURL = "https://github.com/rpgmakeralliance/wiki/edit/master/content"

The current page link will be appended to this link, so make sure it point to your content folder without a trailling slash!

SEO

OpenGraph Icon

Unless a page-specific OpenGraph icon is specified (see Specify an OpenGraph icon), Royal will automatically use a file called default_opengraph.png located in {SITE_ROOT}/static/assets/ if it exist.

Currently, for Twitter Cards, the summary type of card is hardcoded in baseof.html

Twitter Handler

In your site config.toml file, simply add

[social]
twitter = "YOUR_TWITTER_HANDLE"

Don't add the at (@) sign, Royal will add it automatically

Page Parameters

A few parameters are supported to disable certain features or change the opengraph icon on a per page basis

Disable the "Edit this Page" link

Add editthispage: false to your page's front matter

Disable the right sidebar

Add onthispage: false to your page's front matter

Specify an OpenGraph icon

Add og_image: "{IMAGE_URL}" to your page's front matter

Limit Table of Content depth

Add tocmaxdepth: {DEPTH} to your page's front matter. Only values from 1 to 5 are currently supported

Unfortunately it's not yet possible in Hugo to limit the Table of Content depth natively so we had to do it through CSS (which is why it's limited to specific values)

Licenses

This theme is distributed under the MIT license. You can see the details here

External Resources

• Normalize.css by Nicolas Gallagher under the MIT license
• Dark Mode Icon by Rami McMin under the CC 3.0 BY license
• Source Sans Pro font by Adobe under the Open Font License
• Various icons (menu, permalinks, external links etc) from Font-Awesome built into a custom bundle using Fontello