hugo-geekblog/exampleSite/content/posts/getting-started.md

title	date	authors	tags	weight
Getting Started	2020-07-15T20:00:00+02:00	john-doe	Documentation	1

This post tells you how to get started with the Geekblog theme, including installation and basic configuration.

{{< toc >}}

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

Install requirements

You need a recent version of Hugo for local builds and previews of sites that use Geekblog. As we are using gulp 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 gulp locally and run the default pipeline once to create all required assets.

# install required packages from package.json
npm install

# run gulp pipeline to build required assets
gulp default

Using the theme

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

1. Create a new empty Hugo site.

   hugo new site demosite
   

2. Switch to the root of the new site.

   cd demosite
   

3. Install the Geekblog theme from a release bundle (recommended) or form Git branch.

4. Create the minimal required Hugo configuration config.toml. For all configuration options see here.

   baseURL = "http://localhost"
   title = "Geekblog"
   theme = "hugo-geekblog"
   
   # Geekblog required configuration
   pygmentsUseClasses = true
   pygmentsCodeFences = true
   
   disablePathToLower = true
   enableGitInfo=true
   
   # Needed for mermaid shortcodes
   [markup]
     [markup.goldmark.renderer]
       # Needed for mermaid shortcode
       unsafe = true
     [markup.tableOfContents]
       startLevel = 1
       endLevel = 9
   

5. Test your site.

   hugo server --theme geekblog -D
   

Option 1: Download pre-build release bundle

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

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

Option 2: Clone the GitHub repository

{{< hint info >}} Info
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. {{< /hint >}}

Clone the Geekblog git repository.

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

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

gulp default

Configuration

Site configuration

{{< tabs "site-config" >}} {{< tab "TOML" >}}

# ...

theme = "hugo-geekblog"

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

disablePathToLower = true
enableGitInfo = 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 = "atom"
    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 =
  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 true) Copy anchor url to clipboard on click.
  geekblogAnchorCopy = true

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

  # (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/"

{{< /tab >}} {{< tab "YAML" >}}

---
# ...

theme: hugo-geekblog

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

disablePathToLower: true
enableGitInfo: 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: "atom"
    isPlainText: false
    rel: "alternate"
    isHTML: false
    noUgly: true
    permalinkable: false

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

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

params:
  subtitle:
  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 true) Copy anchor url to clipboard on click.
  geekblogAnchorCopy: true

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

  # (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/

{{< /tab >}} {{< /tabs >}}

Page configuration

{{< tabs "page-config" >}} {{< tab "TOML" >}}

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

# Set weigth 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

# Set true to hide page or section from side menu (file-tree menu only).
geekblogHidden = true

# Add an anchor link to headlines.
geekblogAnchor = true

{{< /tab >}} {{< tab "YAML" >}}

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

# Set weigth 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

# Set true to hide page or section from side menu (file-tree menu only).
geekblogHidden: true

# Add an anchor link to headlines.
geekblogAnchor: true

{{< /tab >}} {{< /tabs >}}