Current: https://halogenica.net/beautifulhugo.
Older: https://hugo-theme-beautifulhugo.netlify.app.
Install Hugo and create a new site. See the Hugo documentation for details.
Add Beautifulhugo as git submodule:
$ git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo
Initialize your site as hugo module:
$ hugo mod init github.com/USERNAME/SITENAME
Add Beautifulhugo module as a dependency of your site:
$ hugo mod get github.com/halogenica/beautifulhugo
You can stay up to date with:
$ hugo mod get
Copy the content of exampleSite at the root of your project:
cp -riv themes/beautifulhugo/exampleSite/* .
If you installed Beautifulhugo as hugo module, set your theme in your config file (hugo.toml):
[[module.imports]]
path = "github.com/halogenica/beautifulhugo"
Start Hugo:
hugo serve
This theme is designed to look great on both large-screen and small-screen (mobile) devices.
This theme has support for either Hugo's lightning fast Chroma, or both server side and client side highlighting. See the Hugo docs for more.
Chroma is built into Hugo and enabled by default. If you want it to guess syntax, you can (though it has much more limited language support for guessing compared to Highlight.js):
[markup.highlight]
guessSyntax = trueAlternatively, you can enable client-side highlighting with Highlight.js. This bypasses Chroma and uses highlight.min.css instead of syntax.css.
[Params]
useHLJS = true
[markup.highlight]
codeFences = falseThis has better language autodetection support.
To use this feature add your disqus shortname to the hugo.toml file like this:
[services]
[services.disqus]
shortname = ''For further reference see hugo config
Add Staticman configuration section in hugo.toml or hugo.yaml
Sample hugo.toml configuration
[Params.staticman]
api = "https://<API-ENDPOINT>/v3/entry/{GIT-HOST}/<USERNAME>/<REPOSITORY-BLOGNAME>/master/comments"
[Params.staticman.recaptcha]
sitekey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v"
secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic="
Note: The public API-ENDPOINT https://staticman.net is currently hitting its API limit, so one may use other API instances to provide Staticman comment service.
The section [Params.staticman.recaptcha] is optional. To add reCAPTCHA to your site, you have to replace the default values with your own ones (to be obtained from Google.) The site secret has to be encrypted with
https://<API-ENDPOINT>/v3/encrypt/<SITE-SECRET>
You must also configure the staticman.yml in you blog website.
comments:
allowedFields: ["name", "email", "website", "comment"]
branch : "master"
commitMessage : "New comment in {options.slug}"
path: "data/comments/{options.slug}"
filename : "comment-{@timestamp}"
format : "yaml"
moderation : true
requiredFields : ['name', 'email', 'comment']
transforms:
email : md5
generatedFields:
date:
type : "date"
options:
format : "iso8601"
reCaptcha:
enabled: true
siteKey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v"
secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic="
If you don't have the section [Params.staticman] in hugo.toml, you won't need the section reCaptcha in staticman.yml
Add this section in hugo.toml:
[Params.utterances]
repo = "owner/repo"
issueTerm = "pathname" # pathname, url, title, og:title
theme = "preferred-color-scheme"
# label = "comment"Add this section in hugo.toml:
[Params.giscus]
repo = "owner/repo"
repoId = "R_kgDO..."
category = "Announcements"
categoryId = "DIC_kwDO..."
mapping = "pathname"
reactionsEnabled = "1"
emitMetadata = "0"
inputPosition = "top"
theme = "preferred_color_scheme"
lang = "en"
lazyLoading = trueIf you need to put a Disclaimer on your website (e.g. "My views are my own and not my employer's"), you can do so via the following:
- Uncomment and edit the
disclaimerTextparameter inhugo.toml. - If you need to adjust the disclaimer's styling, modify the declarations within the
footer div.disclaimerselector instatic/css/main.css.
The code for the disclaimer text is in
layouts/partials/footer.html. Moving this code block to another partial file (or relocating it withinfooter.html) will require changes to the css selector inmain.cssas well.
Sign up to Google Analytics to obtain your Google Tracking ID.
To use this feature add your Google Analytics ID to the hugo.toml file like this:
[services]
[services.googleAnalytics]
id = ''
Note that the Google Analytics tracking code will only be inserted into the page when the site isn't served on Hugo's built-in server, to prevent tracking from local testing environments.
If the source of your site is in a Git repo, the SHA corresponding to the commit the site is built from can be shown on the footer. To do so, two site parameters commit has to be defined in the config file hugo.toml:
enableGitInfo = true
[Params]
commit = "https://github.com/<username>/<siterepo>/tree/"
See at vincenttam/vincenttam.gitlab.io for an example of how to add it to a continuous integration system.
To allow Beautiful Hugo to go multilingual, you need to define the languages
you want to use inside the languages parameter on hugo.toml file, also
redefining the content dir for each one. Check the i18n/ folder to see all
languages available.
[languages]
[languages.en]
contentDir = "content/en" # English
[languages.ja]
contentDir = "content/ja" # Japanese
[languages.br]
contentDir = "content/br" # Brazilian PortugueseNow you just need to create a subdir within the content/ folder for each
language and just put stuff inside page/ and post/ regular directories.
content/ content/ content/
└── en/ └── br/ └── ja/
├── page/ ├── page/ ├── page/
└── post/ └── post/ └── post/
With default settings, visiting to a website using Beautifulhugo connects also to remote services like google fonts or jsdelivr to embed fonts, js and other assets.
To avoid this, set the following param in hugo.toml:
[Params]
selfHosted = true
[params]
showPageDates = false # disables the dates below pages, can be controlled in page frontmatter, too<<<<<<< HEAD
Hidden posts
Set hidden: true in a page's front matter to remove it from the homepage and list pages while still building the page (so it remains accessible by direct URL).
Beautiful Hugo overrides Hugo's built-in figure shortcode with beautifulfigure, which adds PhotoSwipe gallery support.
You can restore the original Hugo behaviour by setting disableFigureOverride = true in your hugo.toml;
the beautifulfigure shortcode will still be available for PhotoSwipe figures.
[params]
disableFigureOverride = true # use Hugo's native <figure> for {{< figure >}} shortcodesThere are three extra shortcodes provided (along with the customized beautifulfigure shortcode which remains backwards compatible with figure):
This simply adds the html5 detail attribute, supported on all modern browsers. Use it like this:
{{< details "This is the details title (click to expand)" >}}
This is the content (hidden until clicked).
{{< /details >}}
This adds a two column side-by-side environment (will turn into 1 col for narrow devices):
{{< columns >}}
This is column 1.
{{< column >}}
This is column 2.
{{< endcolumns >}}
In order to show social media icons in the footer, add a section like this to your hugo.yaml or hugo.toml. You can see the full list of supported social media sites in data/beautifulhugo/social.toml.
author:
name: "Author Name"
website: "https://example.com"
github: halogenica/beautifulhugo
twitter: username
discord: 96VAXXvjCB
...[Params.author]
name = "Author Name"
website = "https://example.com"
github = "halogenica/beautifulhugo"
twitter = "username"
discord = "96VAXXvjCB"
...This is an adaptation of the Jekyll theme Beautiful Jekyll by Dean Attali. It supports most of the features of the original theme, and many new features. It has diverged from the Jekyll theme over time, with years of community updates.
MIT Licensed, see LICENSE.