Gokarna is an opinionated theme with a focus on minimalism and simplicity.

Installation

Follow these steps to initialize your new website.

If you are new to Hugo, we suggest following this great documentation for beginners.

a. Create Your Project

Hugo provides a new subcommand to create a new website:

hugo new site my-website
cd my-website

b. Install the Theme

The theme’s repository is: https://github.com/gokarna-theme/gokarna-hugo.

Make this repository a submodule of your Git project:

git init
git submodule add https://github.com/gokarna-theme/gokarna-hugo.git themes/gokarna

c. Basic Configuration

A simple Hugo configuration file with menu items.

Gokarna supports adding Feather icons to the header.

baseURL = "https://example.org/"
defaultContentLanguage = "en"
# Automatically generate robots.txt
enableRobotsTXT = true
languageCode = "en"
theme = "gokarna"
title = "My New Hugo Site"

[menu]
  [[menu.main]]
    # Display name
    name = "Posts"

    # Relative URL slug (appended to baseURL)
    url = "/posts/"

    # Lower weights are listed first in the menu (leftmost); higher weights are
    # listed last in the menu (rightmost)
    weight = 1

  [[menu.main]]
    name = "Tags"
    url = "/tags/"
    weight = 2
    
  [[menu.main]]
    # Unique identifiers are required for menu entries without a name property,
    # or for menu entries which re-use a name
    identifier = "github"

    # Absolute URL to external resource
    url = "https://github.com"
    weight = 3
    
    # Surround the menu entry (or name) with HTML content, such as Feather
    # icons: https://feathericons.com
    pre = "<span data-feather='github'></span>"
    post = ""

d. Create Your First Post

Use the new subcommand to create a post (in the content/ directory):

hugo new posts/'My First Post'.md

Two content types are supported in Gokarna:

  1. type: "post"

    A blog post consisting of a page title, meta description, creation/last modified dates, SEO keywords (tags), and Markdown content.

    Read more about Posts in the advanced documentation.

  2. type: "page"

    A standalone page which only renders Markdown. Best used for custom pages (e.g. your portfolio) which should not feature in your Posts timeline.

    Read more about Pages in the advanced documentation.

Using archetypes

hugo new will automatically use an appropriate archetype (see archetypes/) and insert front matter depending on the location of your content:

  • hugo new posts/$post-name.md automatically sets type: "post"
  • hugo new $page-name.md automatically sets type: "page"

Gokarna employs custom front matter, which is included in the archetypes:

  • The creation date of the file is automatically set (e.g. date: 2023-12-25)
  • The file name is used as the default title (e.g. title: "My First Post")

e. Launching the Website Locally

Use the server subcommand to view your site.

hugo server

Go to http://localhost:1313 (if no other Hugo servers are running; Hugo will use an ephemeral port if one or more servers are running concurrently on the host).

f. Build the Website

Use the hugo command to build your site.

hugo

A public folder will be generated, containing all static content and assets for your website. It can be hosted on any web server.

The website can be automatically published and hosted with Netlify, AWS Amplify, GitHub Pages, Render, and more…

Configuration

In addition to Hugo global configuration and menu configuration, Gokarna lets you define the following parameters in your site configuration.

See this sample config.toml, which uses Gokarna’s default values, and exampleSite’s config.toml:

[params]
  # Choose the color shown when hyperlinks are hovered over
  accentColor = "#FF4D4D"

  # Resource URL for the site avatar (home page and header)
  avatarURL = "/images/avatar.webp"

  # Describe the avatar for screen readers
  avatarAltText = "avatar"

  # Set the avatar's size: size-xs, size-s, size-m, size-l & size-xl
  avatarSize = "size-m"

  # Inject arbitrary HTML via the <head> tag
  # Best used for importing custom JavaScript, CSS, or analytics
  customHeadHTML = ""

  # Configure how post dates are displayed
  # dateFormat must be set if lastmod is declared in front matter, or
  # enableGitInfo is true
  dateFormat = "January 2, 2006"
  
  # Home page meta description
  description = "Sky above, sand below & peace within"

  # Footer text (i.e. author/project name)
  footer = "The Marauders"

  # Define SEO keywords
  metaKeywords = ["blog", "gokarna", "hugo"]

  # Define how many posts are displayed on the home page
  # showPostsOnHomePage must be "popular" or "recent"
  numberPostsOnHomePage = 4

  # Display a "back to top" button on posts and pages: true, false
  # May not render on smaller screen sizes
  showBackToTopButton = true

  # Display posts on the home page:
  # "popular" (order posts by weight)
  # "recent" (order posts by date)
  # "", unset (do not display)
  showPostsOnHomePage = ""

  # Show the previous and next post in your timeline: "true", "false"
  # Incompatible with Weight
  togglePreviousAndNextButtons = "false"

Accent color

The color displayed when a user hovers over hyperlinks (<a> tags), expressed as a hexadecimal.

[params]
  accentColor = "#FF4D4D"

Avatar URL

The avatar’s resource URL, displayed on the home page and header (top-left).

Images are typically placed into the assets/ or static/ directories (which are copied to the top-level directory at build time).

[params]
  avatarURL = "/images/avatar.webp"

Avatar size

Set the avatar’s size as: size-xs, size-s, size-m, size-l, or size-xl.

[params]
  avatarSize = "size-m"

Custom Head HTML

Add arbitrary HTML code to the <head> element.

[params]
  customHeadHTML = "<script>console.log('Any HTML')</script>"

Examples are available in the advanced documentation.

Date format

Configure how posts date are displayed, using date strings.

dateFormat must be set if enableGitInfo is true, or .Lastmod is present in any front matter.

[params]
  dateFormat = "2 January, 2006"

Description

Meta description to display on the home page, below the title and avatar.

[params]
  description = "Sky above, sand below & peace within"

Display content on the home page

Markdown content in content/index-about.md will be rendered on the home page, below the social icons.

Display posts on the home page

Recent and popular posts can be shown on the home page:

  • popular: Sort posts in ascending order of their Weight

    If any post on your site defines weight, you cannot enable Previous and Next buttons.

  • recent: Sort posts in ascending order of Date

  • Do not show anything if the variable is:

    • unset
    • an empty string ("")

The number of posts displayed on the home page can be changed by setting numberPostsOnHomePage. If numberPostsOnHomePage is equal to "" or 0, the default value (4) is used.

[params]
  showPostsOnHomePage = ""
  numberPostsOnHomePage = 4

Favicons

Place favicons into the static/ directory. The following files are supported:

  • apple-touch-icon.png (180x180)
  • favicon-32x32.png (32x32)
  • favicon-16x16.png (16x16)
  • mstile-150x150.png (150x150)
  • android-chrome-192x192.png (192x192)
  • android-chrome-512x512.png (512x512)

Favicons can be generated using services such as favicon.io, or realfavicongenerator.net.

Text to display in the footer section, typically the name of the author or project.

[params]
  footer = "The Marauders"

footer can include Markdown syntax - best used for including hyperlinks, emoji, or text formatting.

Previous and Next buttons

At the bottom of a post, show the previous and next post chronologically.

Warning: Not compatible with the .Weight parameter.

If any post front matter contains weight, the posts will not appear by Date. See Hugo’s default sort.

[params]
  togglePreviousAndNextButtons = "false"

robots.txt

Automatically generate a robots.txt file, used to ‘manage crawler traffic to your site’.

enableRobotsTXT = true