Geekblog

Getting Started

2020-07-15T20:00:00+02:00

Geekblog is a simple Hugo theme for personal blogs. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. This post helps you to get started with the Geekblog theme, including initial setup and basic configuration.

Features

Clean and simple design
Light and mobile-friendly
Easy customization
Zero initial configuration
Handy shortcodes
Simple sticky posts
Content tags
Multiple authors
Supports Atom and JSON feeds

Setup requirements

You need a recent version of Hugo for local builds and previews of sites that use Geekblog. As we are using webpack as pre-processor, the normal version of Hugo is sufficient. If you prefer the extended version of Hugo anyway this will work as well. For comprehensive Hugo documentation, see gohugo.io.

If you want to use the theme from a cloned branch instead of a release tarball you’ll need to install webpack locally and run the build script once to create all required assets.

# install required packages from package.json
npm install

# run the build script to build required assets
npm run build

# build release tarball
npm run pack

Using the theme

To prepare your new site environment just a few steps are required:

Create a new empty Hugo site.
```
hugo new site demosite
```
Switch to the root of the new site.
```
cd demosite
```
Install the Geekblog theme from a release bundle (recommended) or from Git branch.

Create the minimal required Hugo configuration hugo.toml. For all configuration options take a look at the configuration page.

baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"

pluralizeListTitles = false

# Geekblog required configuration
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true

# Needed for mermaid shortcodes
[markup]
  [markup.goldmark.renderer]
    unsafe = true
  [markup.tableOfContents]
    startLevel = 1
    endLevel = 9

[taxonomies]
  author = "authors"
  tag = "tags"

[mediaTypes]
  [mediaTypes."application/atom+xml"]
    suffixes = ["xml"]

[outputFormats]
  [outputFormats.Atom]
    name = "Atom"
    mediaType = "application/atom+xml"
    baseName = "feed"
    isPlainText = false
    rel = "alternate"
    isHTML = false
    noUgly = true
    permalinkable = false

[outputs]
  home = ["HTML", "ATOM"]
  page = ["HTML"]
  section = ["HTML"]
  taxonomy = ["HTML"]
  term = ["HTML", "ATOM"]

Test your site.
```
hugo server -D
```
The -D or --buildDrafts option is used to include content marked as draft during the build. It is used because content pages created with the hugo new content command have the draft flag set by default and this can lead to build errors in newly created projects. For projects with a production-ready content structure, this flag is not required in most cases and can be omitted.

If you want to add some demo data you could use the content from the Hugo basic example:
```
curl -L https://github.com/gohugoio/hugoBasicExample/archive/master.tar.gz | tar -xz --exclude "config*" --exclude "LICENSE" --exclude "README*" --strip-components=1
```

Option 1: Download pre-build release bundle

Download and extract the latest release bundle into the theme directory.

mkdir -p themes/hugo-geekblog/
curl -L https://github.com/thegeeklab/hugo-geekblog/releases/latest/download/hugo-geekblog.tar.gz | tar -xz -C themes/hugo-geekblog/ --strip-components=1

Option 2: Clone the GitHub repository

Note

Keep in mind this method is not recommended and needs some extra steps to get it working. If you want to use the Theme as submodule keep in mind that your build process need to run the described steps as well.

Clone the Geekblog git repository.

git clone https://github.com/thegeeklab/hugo-geekblog.git themes/hugo-geekblog

Build required theme assets e.g. CSS files and SVG sprites.

npm install
npm run build

Deployments

Netlify

There are several ways to deploy your site with this theme on Netlify. Regardless of which solution you choose, the main goal is to ensure that the prebuilt theme release tarball is used or to run the required commands to prepare the theme assets before running the Hugo build command.

Here are some possible solutions:

Use a Makefile

Add a Makefile to your repository to bundle the required steps.

Important

The Makefile is only an example. Depending on your project structure, BASEDIR or THEMEDIR may need to be adapted.

# Please change the theme version to the latest release version.
THEME_VERSION := v0.26.1
THEME := hugo-geekblog
BASEDIR := docs
THEMEDIR := $(BASEDIR)/themes

.PHONY: doc
doc: doc-assets doc-build

.PHONY: doc-assets
doc-assets:
	mkdir -p $(THEMEDIR)/$(THEME)/ ; \
	curl -sSL "https://github.com/thegeeklab/$(THEME)/releases/download/${THEME_VERSION}/$(THEME).tar.gz" | tar -xz -C $(THEMEDIR)/$(THEME)/ --strip-components=1

.PHONY: doc-build
doc-build:
	cd $(BASEDIR); hugo

.PHONY: clean
clean:
	rm -rf $(THEMEDIR) && \
	rm -rf $(BASEDIR)/public

This Makefile can be used in your netlify.toml, take a look at the Netlify example for more information:

[build]
publish = "docs/public"
command = "make doc"

Chain required commands

Chain all required commands to prepare the theme and build your site on the command option in your netlify.toml like this:

[build]
publish = "docs/public"
command = "command1 && command 2 && command3 && hugo"

Subdirectories

Important

As deploying Hugo sites on subdirectories is not as robust as on subdomains, we do not recommend this. If you have a choice, using a domain/subdomain should always be the preferred solution!

If you want to deploy your site to a subdirectory of your domain, some extra steps are required:

Configure your Hugo base URL e.g. baseURL = http://localhost/demo/.
Don’t use relativeURLs: false nor canonifyURLs: true as is can cause unwanted side effects!

There are two ways to get Markdown links or images working:

Use the absolute path including your subdirectory e.g. [testlink](/demo/example-site)
Overwrite the HTML base in your site configuration with geekblogOverwriteHTMLBase = true and use the relative path e.g. [testlink](example-site)

But there is another special case if you use geekblogOverwriteHTMLBase = true. If you use anchors in your Markdown links you have to ensure to always include the page path. As an example [testlink](#some-anchor) will resolve to http://localhost/demo/#some-anchor and not automatically include the current page!

Known Limitations

Minify HTML results in spacing issues

Using hugo --minify without further configuration or using other minify tools that also minify HTML files might result in spacing issues in the theme and is not supported.

After some testing we decided to not spend effort to fix this issue for now as the benefit is very low. There are some parts of the theme where spaces between HTML elements matters but were stripped by minify tools. Some of these issues are related to gohugoio/hugo#6892. While recommendation like “don’t depend on whitespace in your layout” sounds reasonable, it seems to be not that straight forward especially for something like embedded icons into the text flow.

If you still want to use Hugo’s minify flag you should at least exclude HTML file in your site configuration:

[minify]
  disableHTML = true

Whats next?

There are a lot more things to discover. To get the most out of the Theme we have collected interesting posts covering more advanced topics:

Configuration
Menus
Features
- Code Blocks
- Dark Mode
- Icon Sets
- Theming
- Authors
- Sticky Posts
Shortcodes
Asciidoc
- Admonitions
- Admonition Icons

Simple sticky posts

2020-06-13T00:06:00+02:00

Sticky (or pinned) posts can be used to permanently pin important posts to the top of the post list. The implementation is pretty simple and handled by weight: 1 in a post front matter. As there is no other logic to identify sticky posts you should not use negative values for weight as this will result in posts listed earlier.

Example:

---
title: Simple sticky posts
weight: 1
date: 2020-06-13T00:06:00+02:00
authors:
  - john-doe
---

Markdown syntax

2020-07-13T20:00:00+02:00

This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

Headings

The following HTML <h1>—<h6> elements represent six levels of section headings. <h1> is the highest section level while <h6> is the lowest.

H1

H2

H3

H4

H5

H6

Paragraph

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

Blockquote

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Tables

Tables aren’t part of the core Markdown spec, but Hugo supports supports them out-of-the-box.

Name	Age
Bob	27
Alice	23

Inline Markdown within tables

Italics	Bold	Code
italics	bold	`code`

Code Blocks

Code block with backticks

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example HTML5 Document</title>
  </head>
  <body>
    <p>Test</p>
  </body>
</html>

Code block indented with four spaces

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block with Hugo’s internal highlight Shortcode

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

List Types

Ordered List

First item
Second item
Third item

Unordered List

List item
Another item
And another item

Nested list

Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese

Other Elements — abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL+ALT+Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎

Short post

2020-06-22T20:00:00+02:00

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo.

Audio

2026-02-01T12:00:00+02:00

The audio shortcode allows you to embed audio files.

Usage

Define your resources in the page front matter, custom parameter params.credits is optional.

---
resources:
  - name: diamonds-trap
    src: "diamonds-trap.mp3"
    title: Diamonds Trap
    params:
      credits: "[Jakob Eglmeier on openmusic.academy CC0-1.0](https://openmusic.academy/media-library/b9do2E2ZwVCfppyBf2yuej)"
---

{{< audio name="diamonds-trap" >}}

Attributes

name required string: Name of the audio resource defined in page front matter.

Default: none

Example

Diamonds Trap (Jakob Eglmeier on openmusic.academy CC0-1.0)

Avatar Images

2024-04-27T21:00:00+02:00

The avatar shortcode is another custom image shortcode.

Usage

Define a resource in the page front matter.

---
resources:
  - name: avatar
    src: "images/avatar.jpg"
    title: "Avatar"
---

{{< avatar name="avatar" >}}

Attributes

alt optional string: Description text for the image.

Default: none
anchor optional string: Anchor to determine the placement of the crop box.

Default: none
name required string: Name of the image resource defined in page front matter.

Default: none
size optional string: Thumbnail size. Supported values are origin|tiny|small|medium|large.

Default: none

Example

Code Blocks

2021-11-21T15:00:00+01:00

There are several ways to add code blocks. Most of them work out of the box, only the Hugo short code <highlight> needs to be configured to work properly. The theme also provides some additional features like a copy button and an option to set the maximum length of code blocks. Both of these functions and the dependent formatting rely on the .highlight CSS class. You must ensure that you always assign a language to your code blocks if you want to use these functions. If you do not want to apply syntax highlighting, you can also specify plain or text as the language.

Inline code

To display an inline shortcode use single quotes:

`some code`

Example: some code with a link

Code blocks

Code blocks can be uses without language specification:

```plain
some code
```

Example:

some code

… or if you need language specific syntax highlighting:

```shell
# some code
echo "Hello world"
```

Example:

# some code
echo "Hello World"

Highlight shortcode

Hugo has a build-in shortcode for syntax highlighting. To work properly with this theme, you have to set following options in your site configuration:

TOML

pygmentsUseClasses=true
pygmentsCodeFences=true

YAML

pygmentsUseClasses: true
pygmentsCodeFences: true

You can use it like every other shortcode:

{{< highlight Shell "linenos=table" >}}
# some code
echo "Hello World"
{{< /highlight >}}

Example:

1
2

# some code
echo "Hello World"

Dark Mode

2021-11-21T15:00:00+01:00

Say hello to the dark mode of the Geekblog theme!

The dark mode can be used in two different ways. If you have JavaScript disabled in your browser, the dark mode automatically detects the preferred system settings via the prefers-color-scheme parameter. Depending on the value, the theme will automatically switch between dark and light mode if this feature is supported by your operating system and browser.

The second mode requires JavaScript and is controlled by a dark mode switch in the upper right corner. You can switch between three modes: Auto, Dark and Light. Auto mode works the same as the first method mentioned above and automatically detects the system setting. Dark and Light modes allow you to force one of them for your Geekblog page only, regardless of the system setting. This works even if your browser or operating system does not support the system setting. The current selection is stored locally via the Web Storage API.

To avoid very bright spots often caused by images while using the dark mode we have added an optional auto-dim feature that can be enabled with the site parameter geekblogDarkModeDim (see Configuration). As this may have an impact on the quality of the images it is disabled by default.

Authors

2021-05-23T20:00:00+01:00

The theme supports multiple authors. The required information for each author need to be stored in a single Hugo data template per author.These files need to be stored in the data/authors/ directory in your projects root.

data/
└── authors
   ├── john-doe.yml
   ├── richard-roe.yml
   └── Special User.yml

The name of the file will be used as the reference later, so if you prefer some kind of naming convention this need to covered by the file names. Example authors file:

name: John Doe
email: john@example.com

With the defined files, you can add as many authors as you want to the front matter of your posts:

---
title: Demo Posts
authors:
  - john-doe
  - Special User
---

My first demo post.

Configuration

2021-05-23T20:00:00+01:00

Overview of all available site and page configuration options provided by the theme.

Configuration

Site configuration

TOML

baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"

[pagination]
pagerSize = 5

pluralizeListTitles = false

# Required to get well formatted code blocks
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
enableGitInfo = true

# Required if you want to render robots.txt template
enableRobotsTXT = true

[markup]
  [markup.goldmark.renderer]
      unsafe = true
  [markup.tableOfContents]
    startLevel = 1
    endLevel = 9

[taxonomies]
  author = "authors"
  tag = "tags"

[mediaTypes]
  [mediaTypes."application/atom+xml"]
    suffixes = ["xml"]

[outputFormats]
  [outputFormats.Atom]
    # https://validator.w3.org/feed/docs/atom.html#whatIsAtom
    name = "Atom"
    mediaType = "application/atom+xml"
    # generated file = <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
    baseName = "feed"
    isPlainText = false
    rel = "alternate"
    isHTML = false
    noUgly = true
    permalinkable = false

[outputs]
  home = ["HTML", "ATOM"]
  page = ["HTML"]
  section = ["HTML"]
  taxonomy = ["HTML"]
  term = ["HTML", "ATOM"]

[params]
  subtitle = "Blog about my favorite topics"
  description = "This is my personal blog about tech."
  keywords = []
  images = []

  # (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
  # relative to your 'static/' folder.
  logo = "logo.png"

  # (Optional, default 6) Set how many table of contents levels to be showed on page.
  # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
  # You can also specify this parameter per page in front matter.
  geekblogToC = 3

  # (Optional, default none) Add a link to your Legal Notice page to the site footer.
  # It can be either a remote url or a local file path relative to your content directory.
  geekblogLegalNotice = "https://blog.example.com/legal"

  # (Optional, default none) Add a link to your Privacy Policy page to the site footer.
  # It can be either a remote url or a local file path relative to your content directory.
  geekblogPrivacyPolicy = "/privacy"

  # (Optional, default true) Add an anchor link to headlines.
  geekblogAnchor = true

  # (Optional, default none) Sites main author.
  geekblogAuthor = "john-doe"

  # (Optional, default posts) Set the name of the default content section.
  geekblogContentSection = "my-pages"

  # (Optional, default true) Enable or disable image lazy loading for images rendered
  # by the 'img' shortcode.
  geekblogImageLazyLoading = true

  # (Optional, default false) Set HTMl <base> to .Site.Home.Permalink if enabled. It might be required
  # if a subdirectory is used within Hugo's BaseURL.
  # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
  geekblogOverwriteHTMLBase = false

  # (Optional, default true) Enable or disable the JavaScript based color theme toggle switch. The CSS based
  # user preference mode still works.
  geekblogDarkModeToggle = false

  # (Optional, default true) Enable or disable adding tags automatically to the main menu.
  geekblogTagsToMenu = true

  # (Optional, default false) Auto-decrease brightness of images and add a slightly grayscale to avoid
  # bright spots while using the dark mode.
  geekblogDarkModeDim = false

  # (Optional, default false) Enforce code blocks to always use the dark color theme.
  geekblogDarkModeCode = false

  # (Optional, default true) Display a "Back to top" link in the site footer.
  geekblogBackToTop = true

  # (Optional, default ["taxonomy", "section", "term", "404"])
  # Page types to exclude from the sitemap and set to noindex,nofollow.
  geekblogSeoIgnore = ["taxonomy", "section"]

  # (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
  # Could be used if you want to give credits to your hosting provider.
  [params.geekblogHostedOn]
    name = "Uberspace"
    link = "https://uberspace.de/en/"

  # (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
  # Could be used if you want to define a default license for your content.
  [params.geekblogContentLicense]
    name = "CC BY-SA 4.0"
    link = "https://creativecommons.org/licenses/by-sa/4.0/"

YAML

---
baseURL: "http://localhost"
title: "Geekblog"
theme: "hugo-geekblog"

pagination:
  pagerSize: 5

pluralizeListTitles: false

# Required to get well formatted code blocks
pygmentsUseClasses: true
pygmentsCodeFences: true
disablePathToLower: true
enableGitInfo: true

# Required if you want to render robots.txt template
enableRobotsTXT: true

markup:
  goldmark:
    renderer:
      unsafe: true
  tableOfContents:
    startLevel: 1
    endLevel: 9

taxonomies:
  author: authors
  tag: tags

mediaTypes:
  "application/atom+xml":
    suffixes:
      - "xml"

outputFormats:
  Atom:
    # https://validator.w3.org/feed/docs/atom.html#whatIsAtom
    name: "Atom"
    mediaType: "application/atom+xml"
    # generated file: <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
    baseName: "feed"
    isPlainText: false
    rel: "alternate"
    isHTML: false
    noUgly: true
    permalinkable: false

outputs:
  home:
    - HTML
    - ATOM
  page:
    - HTML
  section:
    - HTML
  taxonomy:
    - HTML
  term:
    - HTML
    - ATOM

params:
  subtitle: "Blog about my favorite topics"
  description: "This is my personal blog about tech."
  keywords: []
  images: []

  # (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
  # relative to your 'static/' folder.
  logo: logo.png

  # (Optional, default 6) Set how many table of contents levels to be showed on page.
  # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
  # You can also specify this parameter per page in front matter.
  geekblogToC: 3

  # (Optional, default none) Add a link to your Legal Notice page to the site footer.
  # It can be either a remote url or a local file path relative to your content directory.
  geekblogLegalNotice: https://blog.example.com/legal

  # (Optional, default none) Add a link to your Privacy Policy page to the site footer.
  # It can be either a remote url or a local file path relative to your content directory.
  geekblogPrivacyPolicy: /privacy

  # (Optional, default true) Add an anchor link to headlines.
  geekblogAnchor: true

  # (Optional, default none) Sites main author.
  geekblogAuthor: john-doe

  # (Optional, default posts) Set the name of the default content section.
  geekblogContentSection: "my-pages"

  # (Optional, default true) Enable or disable image lazy loading for images rendered
  # by the 'img' shortcode.
  geekblogImageLazyLoading: true

  # (Optional, default false) Set HTMl <base> to .Site.Home.Permalink if enabled. It might be required
  # if a subdirectory is used within Hugo's BaseURL.
  # See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
  geekblogOverwriteHTMLBase: false

  # (Optional, default true) Enable or disable the JavaScript based color theme toggle switch. The CSS based
  # user preference mode still works.
  geekblogDarkModeToggle: false

  # (Optional, default true) Enable or disable adding tags automatically to the main menu.
  geekblogTagsToMenu: true

  # (Optional, default false) Auto-decrease brightness of images and add a slightly grayscale to avoid
  # bright spots while using the dark mode.
  geekblogDarkModeDim: false

  # (Optional, default false) Enforce code blocks to always use the dark color theme.
  geekblogDarkModeCode:
    false

    # (Optional, default true) Display a "Back to top" link in the site footer.
  geekblogBackToTop: true

  # (Optional, default ["taxonomy", "section", "term", "404"])
  # Page types to exclude from the sitemap and set to noindex,nofollow.
  geekblogSeoIgnore:
    - "taxonomy"
    - "section"

  # (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
  # Could be used if you want to give credits to your hosting provider.
  geekblogHostedOn:
    name: Uberspace
    link: https://uberspace.de/en/

  # (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
  # Could be used if you want to define a default license for your content.
  geekblogContentLicense:
    name: CC BY-SA 4.0
    link: https://creativecommons.org/licenses/by-sa/4.0/

Page configuration

TOML

# Title of your post. If not set, filename will be used.
title = My first post

# Hugo predefined front matter variable, to re-arrange items in file-tree menu.
# See weights section of https://gohugo.io/content-management/front-matter/#predefined
# Set weight to 1 to mark this post as sticky post.
weight = 1

# List of authors of the post.
authors = ["john-doe"]

# Tags for this post.
tags = ["Open Source"]

# Set how many table of contents levels to be showed on page.
geekblogToC = 3

# Add an anchor link to headlines.
geekblogAnchor = true

YAML

# Title of your post. If not set, filename will be used.
title: My first post

# Set weight to 1 to mark this post as sticky post.
weight: 1

# List of authors of the post.
authors:
  - john-doe

# Tags for this post.
tags:
  - Open Source

# Set how many table of contents levels to be showed on page.
geekblogToC: 3

# Add an anchor link to headlines.
geekblogAnchor: true

Icon Sets

2021-05-23T20:00:00+01:00

Learn how about build-in icons and how to extend it.

Custom icons

The only supported source for custom icons are SVG sprites. Some icon frameworks provides ready to use sprites e.g. FontAwesome. If the framework don’t provide sprites, you can create your own from raw SVG icons. There are a lot of tools available to create sprites, please choose one that fits your need. One solution could be svgsprit.es.

Regardless of which tool (or existing sprite) you choose, there are a few requirements that must be met:

The sprite must be a valid SVG file.
You have to ensure to hide the sprite. Apply the predefined class svg-sprite or hidden to the root element of your sprite or add a small piece of inline CSS e.g. style="display: none;".
Save the sprite to the folder assets/sprites right beside your content folder.

The result of a valid minimal SVG sprite file could look like this:

<svg class="svg-sprite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <symbol viewBox="-2.29 -2.29 28.57 28.57" id="arrow_back" xmlns="http://www.w3.org/2000/svg">
        <path d="M24 10.526v2.947H5.755l8.351 8.421-2.105 2.105-12-12 12-12 2.105 2.105-8.351 8.421H24z"/>
    </symbol>
</svg>

Example:

FontAwesome provides three pre-build sprites included in the regular Web download pack, sprites/brands.svg, sprites/regular.svg and sprites/solid.svg. Choose your sprite to use and copy it to your projects root directory into assets/sprites, right beside your content folder. The result should look like this:

my_project/
├── assets
│   └── sprites
│       └── regular.svg
├── hugo.yaml
├── content
│   ├── _index.md
│   ├── ...

That’s it! The theme will auto-load all available SVG sprites provided in the assets folder. To use the icons, you need to lookup the id of the icon. An example would be thumbs-up . There is also a shortcode available

Build-in icons

The theme bundles just a small set of hand crafted icons.

#gblog_arrow_back

#gblog_arrow_left

#gblog_arrow_right

#gblog_bitbucket

#gblog_bookmark

#gblog_brightness_auto

#gblog_brightness_dark

#gblog_brightness_light

#gblog_check

#gblog_check_circle_outline

#gblog_clear

#gblog_cloud_off

#gblog_code

#gblog_contacts

#gblog_copy

#gblog_create

#gblog_dangerous

#gblog_date

#gblog_download

#gblog_email

#gblog_error_outline

#gblog_fire

#gblog_git

#gblog_gitea

#gblog_github

#gblog_gitlab

#gblog_heart

#gblog_info_outline

#gblog_keyboard_arrow_down

#gblog_keyboard_arrow_left

#gblog_keyboard_arrow_right

#gblog_keyboard_arrow_up

#gblog_link

#gblog_mastodon

#gblog_matrix

#gblog_menu

#gblog_notifications

#gblog_person

#gblog_pin

#gblog_rss_feed

#gblog_search

#gblog_security

#gblog_star

#gblog_tag

#gblog_timer

#gblog_tree

#gblog_xmpp

Includes

2021-05-23T20:00:00+01:00

Include shortcode can include files of different types. By specifying a language, the included file will have syntax highlighting.

Usage

{{< include file="relative/path/from/hugo/root" language="go" >}}

Attributes

file required string: Path of the file (relative to the Hugo root) to include.

Default: none
language optional string: Language for syntax highlighting.

Default: none
options optional bool: highlighting options.

Default: linenos=table
type optional string: Special include type. Supported values are html|page. If not set the included file is rendered as markdown.

Default: none

Examples

Markdown files (default)

If no other options are specified, files will be rendered as Markdown using the RenderString function.

Important

Location of markdown files
If you include markdown files that should not get a menu entry, place them outside the content folder or exclude them otherwise.

{{< include file="/static/_includes/example.md.part" >}}

Example Markdown include

File including a simple Markdown table.

Head 1	Head 2	Head 3
1	2	3

Language files

This method can be used to include source code files and keep them automatically up to date.

{{< include file="hugo.yaml" language="yaml" options="linenos=table,hl_lines=5-6,linenostart=100" >}}

Result:

---
baseURL: https://hugo-geekblog.geekdocs.de/
title: Geekblog
theme: hugo-geekblog
pygmentsUseClasses: true
pygmentsCodeFences: true
enableGitInfo: true
timeout: "180000s"
pluralizeListTitles: false

pagination:
  pagerSize: 5

markup:
  goldmark:
    renderer:
      unsafe: true
  tableOfContents:
    startLevel: 1
    endLevel: 9

taxonomies:
  author: authors
  tag: tags

mediaTypes:
  "application/atom+xml":
    suffixes:
      - "xml"

outputFormats:
  Atom:
    # https://validator.w3.org/feed/docs/atom.html#whatIsAtom
    name: "Atom"
    mediaType: "application/atom+xml"
    # generated file: <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
    baseName: "feed"
    isPlainText: false
    rel: "alternate"
    isHTML: false
    noUgly: true
    permalinkable: false
  Json:
    # https://www.jsonfeed.org/2020/08/07/json-feed-version.html
    name: "Json"
    mediaType: "application/json"
    # generated file: <baseName>.<mediaType."application/feed+json".suffixes[0]> = feed.json
    baseName: "feed"
    isPlainText: false
    rel: "alternate"
    isHTML: false
    noUgly: true
    permalinkable: false

outputs:
  home:
    - HTML
    - ATOM
    - JSON
  page:
    - HTML
  section:
    - HTML
  taxonomy:
    - HTML
  term:
    - HTML
    - ATOM
    - JSON

enableRobotsTXT: true

security:
  exec:
    allow:
      - "^git$"
      - "^asciidoctor$"

Special include types

HTML

HTML content will be filtered by the safeHTML filter and added to the rendered page output.

{{< include file="/static/_includes/example.html.part" type="html" >}}

Example HTML include

This is heading 4

This is heading 5

This is heading 6

Pages

In some situations, it can be helpful to include Markdown files that also contain shortcodes. While the default method works fine to render plain Markdown, shortcodes are not parsed. The only way to get this to work is to use Hugo pages. There are several ways to structure these include pages, so whatever you do, keep in mind that Hugo needs to be able to render and serve these files as regular pages! How it works:

First you need to create a directory within your content directory. For this example site _includes is used.
Place your Markdown files within the _includes folder e.g. /_includes/include-page.md. Make sure to name it *.md.
Include the page using {{< include file="/_includes/include-page.md" type="page" >}}.

Resulting structure should look like this:

_includes/
 ├── include-page.md
 └── _index.md

Example page include

Note

Example Shortcode
Shortcode used in an include page.

Head 1	Head 2	Head 3
1	2	3

Menus

2021-05-23T20:00:00+01:00

The theme supports different kinds of menus.

If you want to customize the menus (header and footer), this can be achieved by a data file. This file needs to be written in YAML and placed at data/menu/extra.yml.

Example:

---
header:
  - name: Github Profile
    icon: gblog_github
    ref: "https://github.com/xoxys"
    external: true

footer:
  - name: About
    icon: gblog_email
    ref: "/about"

Shortcodes

2021-05-23T20:00:00+01:00

The theme bundles some handy shortcodes that tries to cover common situations.

Buttons

Buttons are styled links that can lead to local page or external link.

Usage

{{< button relref="/" [class="...", size="large|regular"] >}}Get Home{{< /button >}}
{{< button href="https://github.com/thegeeklab/hugo-geekblog" >}}Contribute{{< /button >}}

Attributes

class optional list: List of space-separated CSS class names to apply.

Default: none
href optional string: The URL to use as target of the button.

Default: none
relref optional string: Executes the relref Hugo function to resolve the relative permalink of the specified page. The result is set as the target of the button.

Default: none
size optional string: Preset of different button sizes. Supported values are regular|large.

Default: regular

Example

Get Home Contribute

Columns

The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability.

Usage

{{< columns [size="small|regular|large"] >}} <!-- begin columns block -->
# Left Content
Dolor sit, sumo unique argument um no ...

<---> <!-- magic separator, between columns -->

# Mid Content
Dolor sit, sumo unique argument um no ...

<---> <!-- magic separator, between columns -->

# Right Content
Dolor sit, sumo unique argument um no ...
{{< /columns >}}

Attributes

size optional string: Preset of different sizes for the first column. Supported values are small|regular|large.

Default: regular

Example

Left

Mid Content

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Right Content

Emojify

Emoji can be enabled in a Hugo project in a number of ways.

The emojify function can be called directly in templates or Inline Shortcodes. To enable emoji globally, set enableEmoji to true in your site’s configuration and then you can type emoji shorthand codes directly in content files.

Example

Output	Inline	Shortcode
🙈	`:see_no_evil:`	`{{< emojify ":see_no_evil:" >}}`
🙉	`:hear_no_evil:`	`{{< emojify ":hear_no_evil:" >}}`
🙊	`:speak_no_evil:`	`{{< emojify ":speak_no_evil:" >}}`

The Emoji cheat sheet is a useful reference for emoji shorthand codes.

Note

The above steps enable Unicode Standard emoji characters and sequences in Hugo, however the rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack.

1
2
3

.emoji {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}

Expand

Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.

Usage

{{< expand >}}
### Markdown content
Dolor sit, sumo unique ...
{{< /expand >}}

It is also possible to use a custom label and symbol.

{{< expand "Custom Label" "..." >}}
### More markdown
Dolor sit, sumo unique ...
{{< /expand >}}

Example

Expand ↕

Markdown content

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Custom Label ...

More markdown

Hint

Hint shortcode can be used as hint/alerts/notification block.

Usage

{{< hint type=[note|tip|important|caution|warning] (icon=gblog_github) (title=GitHub) >}}
**Markdown content**\
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
 Ornateness bland it ex enc, est yeti am bongo detract re.
{{< /hint >}}

Attributes

icon optional string: Icon to use. The value need to be an icon from an SVG sprite.

Default: none
title optional string: Title text of the hint.

Default: none
type optional string: Type of the hint. Supported values are note|tip|important|caution|warning.

Default: note

Example

Note

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Tip

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Important

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Caution

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Warning

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Romanesque acclimates investiture.

Example with a custom icon and title:

GitHub

Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Icon

Simple shortcode to include icons from SVG sprites outside of menus.

Usage

{{< icon "thumbs-up" >}}

Example

Output	Code
	`{{< icon "thumbs-up" >}}`
	`{{< icon "thumbs-down" >}}`
	`{{< icon "laugh" >}}`
	`{{< icon "lemon" >}}`
	`{{< icon "moon" >}}`

Tabs

Tabs let you organize content by context, for example installation instructions for each supported platform.

Usage

{{< tabs "uniqueid" >}}
{{< tab "macOS" >}} # macOS Content {{< /tab >}}
{{< tab "Linux" >}} # Linux Content {{< /tab >}}
{{< tab "Windows" >}} # Windows Content {{< /tab >}}
{{< /tabs >}}

Example

macOS

This is tab macOS content.

Linux

This is tab Linux content.

Windows

This is tab Windows content.

Boxes

Boxes can be used to create a simple grid.

Usage

{{< boxes "contact" >}}
{{< box size=large [title=E-Mail icon=gblog_email] >}}mail@example.com{{< /box >}}
{{< box size=large title=Matrix icon=gblog_matrix >}}@john:example.com{{< /box >}}
{{< box size=large title=XMPP icon=gblog_xmpp >}}john@example.com{{< /box >}}
{{< box size=large title=Others >}}You can also find us on the Fediverse.{{< /box >}}
{{< /boxes >}}

Attributes

icon optional string: Icon to use. The value need to be an icon from an SVG sprite.

Default: none
size optional string: Size of each box. Supported values are regular|large.

Default: regular
title optional string: Title text of the hint.

Default: none

Example

E-Mail

mail@example.com

Matrix

@john:example.com

XMPP

john@example.com

Others

You can also find us on the Fediverse.

Mermaid

Mermaid is library for generating SVG charts and diagrams from text.

Usage

{{< mermaid class="text-center" >}}
sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    alt is sick
        Bob->>Alice: Not so good :(
    else is well
        Bob->>Alice: Feeling fresh like a daisy
    end
    opt Extra response
        Bob->>Alice: Thanks for asking
    end
{{< /mermaid >}}

Attributes

class optional list: List of space-separated CSS class names to apply.

Default: none

Example

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    alt is sick
        Bob->>Alice: Not so good :(
    else is well
        Bob->>Alice: Feeling fresh like a daisy
    end
    opt Extra response
        Bob->>Alice: Thanks for asking
    end

As an alternative to shortcodes, code blocks can be used for markdown as well.

```mermaid
flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

KaTeX

KaTeX shortcode let you render math typesetting in markdown document.

Usage

{{< katex [display] [class="text-center"] >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}

Attributes

class optional list: List of space-separated CSS class names to apply.

Default: none

Example

f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi

KaTeX can be used inline, for example $\pi(x)$ or used with the display parameter as above.

Progress

Usage

{{< progress title=Eating value=65 icon=gblog_heart >}}

Attributes

icon optional string: Icon to use. The value need to be an icon from an SVG sprite.

Default: none
label optional string: Value to display.

Default: `value`
title optional string: Title text of the progress bar.

Default: none
type optional string: Color type of the progress bar. Supported values are main|note|tip|important|caution|warning.

Default: main
value optional integer: Progress value.

Default: 0

Example

Eating

65 %

Type: note

10 %

Type: tip

70 %

Type: important

30 %

Type: caution

90 %

Type: warning

80 %

Properties

The property list shortcode creates a custom HTML description list that can be used to display properties or variables and general dependent information. The shortcode requires a data file in data/properties/, e.g. data/properties/demo.yaml.

Usage

{{< propertylist name=demo (sort=name) (order=[asc|desc]) >}}

The supported attributes can be taken from the following example:

---
properties:
  - name: prop1
    type: string
    description: Dummy description of the prop1 string property.
    required: true

  - name: prop2
    type: int
    defaultValue: 10
    description: Another description for the integer property called prop2.
    required: false
    tags:
      - tag1
      - tag2

  - name: prop3
    type: bool
    defaultValue: false
    description: |
      A `bool` property with a complex multiline description and embedded Markdown:

      - List item 1
      - List item 2

      More description how to use this property.
    required: false

  - name: a-prop
    type: string
    description: Property to demonstrate sorting.
    required: true

Attributes

name required string: Name of the file from the data/properties/ directory.

Default: none
order optional string: Sort order, only applied if sort is set. Supported values are asc|desc.

Default: asc
sort optional string: Field name to use for sorting.

Default: none

Example

a-prop required string

Property to demonstrate sorting.

Default: none

prop1 required string

Dummy description of the prop1 string property.

Default: none

prop2 optional int tag1 tag2

Another description for the integer property called prop2.

Default: 10

prop3 optional bool

A bool property with a complex multiline description and embedded Markdown:

List item 1
List item 2

More description how to use this property.

Default: false

Table of Content

2021-05-23T20:00:00+01:00

Simple wrapper to generate a page Table of Content from a shortcode.

{{< toc >}}

Level 1

Level 2

Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.

Level 2.1

Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.

Level 2.1.1

Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim.

Level 2.1.1.1

In pro quints consequent, denim fastidious copious quo ad.

Level 2.1.1.1.1

In pro quints consequent, denim fastidious copious quo ad.

Level 2.2

Amalia id per in minimum facility, quid facet modifier ea ma. Ill um select ma ad, en ferric patine sentient vim. Per expendable foreordained interpretations cu, maxim sole pertinacity in ram.

Theming

2021-05-23T20:00:00+01:00

Color Scheme

If you want to customize the theme’s color scheme to give it your individual touch, you are only a few lines of CSS away. Generally, you need to override the default settings. The easiest way to do this is to create a file named static/custom.css right at the root of your site.

All the necessary CSS customization properties are listed below. If you want to customize elements that don’t use these properties, you can always look up the class name and override it directly. For inspiration, you can also take a look at https://www.color-hex.com. In this simple example, we’ll use the Beach color palette.

Custom CSS:

/* Global customization */

:root {
  --code-max-height: 60rem;


  --header-font-family: "DancingScript";
  --body-font-family: "DancingScript";
  --code-font-family: "DancingScript";
}

/* Light mode theming */
:root,
:root[color-theme="light"] {
  --header-background: #4ec58a;
  --header-font-color: #ffffff;

  --body-background: #ffffff;
  --body-font-color: #343a40;

  --mark-color: #ffab00;

  --button-background: #62cb97;
  --button-border-color: #4ec58a;

  --link-color: #518169;
  --link-color-visited: #c54e8a;

  --code-background: #f5f6f8;
  --code-accent-color: #e3e7eb;
  --code-accent-color-lite: #eff1f3;
  --code-font-color: #5f5f5f;

  --code-copy-background: #f8f9fa;
  --code-copy-font-color: #6b7784;
  --code-copy-border-color: #adb4bc;
  --code-copy-success-color: #00c853;

  --accent-color-dark: #868e96;
  --accent-color: #e9ecef;
  --accent-color-lite: #f8f9fa;

  --control-icons: #b2bac1;

  --footer-background: #112b3c;
  --footer-font-color: #ffffff;
  --footer-link-color: #ffcc5c;
  --footer-link-color-visited: #ffcc5c;
}
@media (prefers-color-scheme: light) {
  :root {
    --header-background: #4ec58a;
    --header-font-color: #ffffff;

    --body-background: #ffffff;
    --body-font-color: #343a40;

    --mark-color: #ffab00;

    --button-background: #62cb97;
    --button-border-color: #4ec58a;

    --link-color: #518169;
    --link-color-visited: #c54e8a;

    --code-background: #f5f6f8;
    --code-accent-color: #e3e7eb;
    --code-accent-color-lite: #eff1f3;
    --code-font-color: #5f5f5f;

    --code-copy-background: #f8f9fa;
    --code-copy-font-color: #6b7784;
    --code-copy-border-color: #adb4bc;
    --code-copy-success-color: #00c853;

    --accent-color-dark: #868e96;
    --accent-color: #e9ecef;
    --accent-color-lite: #f8f9fa;

    --control-icons: #b2bac1;

    --footer-background: #112b3c;
    --footer-font-color: #ffffff;
    --footer-link-color: #ffcc5c;
    --footer-link-color-visited: #ffcc5c;
  }
}

/* Dark mode theming */
:root[color-theme="dark"] {
  --header-background: #4ec58a;
  --header-font-color: #ffffff;

  --body-background: #343a40;
  --body-font-color: #ced3d8;

  --mark-color: #ffab00;

  --button-background: #62cb97;
  --button-border-color: #4ec58a;

  --link-color: #7ac29e;
  --link-color-visited: #c27a9e;

  --code-background: #f5f6f8;
  --code-accent-color: #262b2f;
  --code-accent-color-lite: #2b3035;
  --code-font-color: #b9b9b9;

  --code-copy-background: #343a40;
  --code-copy-font-color: #6b7784;
  --code-copy-border-color: #6b7784;
  --code-copy-success-color: #37905c;

  --accent-color-dark: #222629;
  --accent-color: #2b3035;
  --accent-color-lite: #2f353a;

  --control-icons: #b2bac1;

  --footer-background: #112b3c;
  --footer-font-color: #ffffff;
  --footer-link-color: #ffcc5c;
  --footer-link-color-visited: #ffcc5c;
}
@media (prefers-color-scheme: dark) {
  :root {
    --header-background: #4ec58a;
    --header-font-color: #ffffff;

    --body-background: #343a40;
    --body-font-color: #ced3d8;

    --mark-color: #ffab00;

    --button-background: #62cb97;
    --button-border-color: #4ec58a;

    --link-color: #7ac29e;
    --link-color-visited: #c27a9e;

    --code-background: #f5f6f8;
    --code-accent-color: #262b2f;
    --code-accent-color-lite: #2b3035;
    --code-font-color: #b9b9b9;

    --code-copy-background: #343a40;
    --code-copy-font-color: #6b7784;
    --code-copy-border-color: #6b7784;
    --code-copy-success-color: #37905c;

    --accent-color-dark: #222629;
    --accent-color: #2b3035;
    --accent-color-lite: #2f353a;

    --control-icons: #b2bac1;

    --footer-background: #112b3c;
    --footer-font-color: #ffffff;
    --footer-link-color: #ffcc5c;
    --footer-link-color-visited: #ffcc5c;
  }
}


@font-face {
  font-family: "DancingScript";
  src:
    url("fonts/DancingScript.woff2") format("woff2"),
    url("fonts/DancingScript.woff") format("woff");
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

Favicons

The Theme is shipped with a set of default Favicons in various formats generated by the Favicon Generator. All files can be found in the static/favicon folder of the release tarball. To make the replacement of the default Favicons as simple as possible, the theme loads only a very small subset of the Favicon formats.

<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">

Simple replacement

The minimal steps to load a custom Favicon is to overwrite the three default Favicon files. Therefore place these files into your projects root folder:

static/favicon/favicon.svg
static/favicon/favicon-32x32.png
static/favicon/favicon-16x16.png

Full replacement

If you want to add more Favicon formats you have to overwrite the default partial that is used to load the files. In the next step you have to place the required files in the static folder of your project as well.

Example:

<!-- layouts/partials/head/favicons.html -->
<link rel="icon" type="image/svg+xml" href="{{ "favicon/favicon.svg" | relURL }}">
<link rel="apple-touch-icon" sizes="180x180" href="{{ "favicon/apple-touch-icon.png" | relURL }}">
<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon/favicon-32x32.png" | relURL }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon/favicon-16x16.png" | relURL }}">
<link rel="manifest" href="{{ "favicon/site.webmanifest" | relURL }}">
<link rel="mask-icon" href="{{ "favicon/safari-pinned-tab.svg" | relURL }}" color="#efefef">
<meta name="msapplication-TileColor" content="#efefef">
<meta name="theme-color" content="#efefef">

Fonts

To use a custom font, it needs to be specified first. While there are many ways to do this, we recommend to use @font-face as it supports local as well as remote fonts. If you want to serve the fonts from your own server, you have to place them in the static/fonts folder of your project.

The font registration is done in the custom.css file. There are also a few custom CSS properties available to simplify the usage of custom fonts.

Example:

@font-face {
  font-family: "DancingScript";
  src:
    url("fonts/DancingScript.woff2") format("woff2"),
    url("fonts/DancingScript.woff") format("woff");
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

:root {
  --code-max-height: 60rem;

  --header-font-family: "DancingScript";
  --body-font-family: "DancingScript";
  --code-font-family: "DancingScript";
}

Happy customizing!

Admonition Icons

2020-06-22T20:00:00+02:00

By default, the admonition is rendered with a plain text label. To enable font icons the document attribute :icons: font need to be set.

Example

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Admonitions

2020-06-22T20:00:00+02:00

AsciiDoc admonitions are special callout blocks that highlight important information in documentation using distinct visual styles and icons.

Admonition types

There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions.

[NOTE|TIP|IMPORTANT|CAUTION|WARNING]
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
Ornateness bland it ex enc, est yeti am bongo detract re.

Example

Note	Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Tip	Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Important

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Caution

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Warning

Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.

Romanesque acclimates investiture.

Admonition icons

Icons can be added by setting a unicode glyph or a character reference to the tip-caption attribute:

:tip-caption: 💡

[TIP]
It's possible to use Unicode glyphs as admonition icons.

:tip-caption: pass:[&#128293;]

[TIP]
It's possible to use Unicode glyphs as admonition icons.

Example

💡	It’s possible to use Unicode glyphs as admonition icons.

🔥	It’s possible to use Unicode glyphs as admonition icons.

Advanced Images

2020-06-22T20:00:00+02:00

If you need more flexibility for your embedded images, you could use the img shortcode. It is using Hugo’s page resources and supports lazy loading of your images.

Usage

Define your resources in the page front matter, custom parameter params.credits is optional.

---
resources:
  - name: forest-1
    src: "images/forest-1.jpg"
    title: Forest (1)
    params:
      credits: "[Jay Mantri](https://unsplash.com/@jaymantri) on [Unsplash](https://unsplash.com/s/photos/forest)"
---

{{< img name="forest-1" lazy=false >}}

Attributes

alt optional string: Description text for the image.

Default: none
lazy optional bool: Enable/disable lazy loading for the image.

Default: true
name required string: Name of the image resource defined in page front matter.

Default: none
size optional string: Thumbnail size. Supported values are origin|tiny|small|medium|large.

Default: none

Example

Forest (1) (Jay Mantri on Unsplash)

Forest (2) (Jay Mantri on Unsplash)

Forest (3) (Jay Mantri on Unsplash)

Forest (4) (Jay Mantri on Unsplash)

Forest (5) (Jay Mantri on Unsplash)

Forest (6) (Asher Ward on Unsplash)

Forest (7) (Asher Ward on Unsplash)

Forest (8) (SVG Repo)

Geekblog

Getting Started

Features

Setup requirements

Using the theme

Option 1: Download pre-build release bundle

Option 2: Clone the GitHub repository

Deployments

Netlify

Use a Makefile

Chain required commands

Subdirectories

Known Limitations

Minify HTML results in spacing issues

Whats next?

Simple sticky posts

Markdown syntax

Headings

H1

H2

H3

H4

H5

H6

Paragraph

Blockquote

Blockquote without attribution

Blockquote with attribution

Tables

Inline Markdown within tables

Code Blocks

Code block with backticks

Code block indented with four spaces

Code block with Hugo’s internal highlight Shortcode

List Types

Ordered List

Unordered List

Nested list

Other Elements — abbr, sub, sup, kbd, mark

Short post

Audio

Usage

Attributes

Example

Avatar Images

Usage

Attributes

Example

Code Blocks

Inline code

Code blocks

Highlight shortcode

Dark Mode

Authors

Configuration

Configuration

Site configuration

Page configuration

Icon Sets

Custom icons

Build-in icons

Includes

Usage

Attributes

Examples

Markdown files (default)

Language files

Special include types

HTML

This is heading 4

This is heading 5

This is heading 6

Pages

Menus

Extra menu

Shortcodes

Buttons

Usage

Attributes

Example