✨📚 Pretty theme for pretty documentations
MIT License
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
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.
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
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
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)
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
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
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!
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
In your site config.toml
file, simply add
[social]
twitter = "YOUR_TWITTER_HANDLE"
Don't add the at (@) sign, Royal will add it automatically
A few parameters are supported to disable certain features or change the opengraph icon on a per page basis
Add editthispage: false
to your page's front matter
Add onthispage: false
to your page's front matter
Add og_image: "{IMAGE_URL}"
to your page's front matter
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)
This theme is distributed under the MIT license. You can see the details here