Blog

Start Here: Configuration and Content

Jul 25, 2020 | 5 minutes read

Series: quickstart

Tags: code, features

Here are some helpful tips for setting up this theme.

Most of what you’ll want to configure is demonstrated in the exampleSite config.toml. This is Hugo’s configuration file. You can copy the config.toml in the exampleSite/ to your site root get started.

Here are all the options included in the (live!) configuration file for this example site!

baseURL                          = "http://christophermerchant.com/"   # Your domain name. Must end with "/"
theme                            = "introduction"
DefaultContentLanguage           = "en"                    # Default language for multilingual sites
# disqusshortname                 = ""                     # https://gohugo.io/content-management/comments
googleAnalytics                 = "G-QWTWMTEV1K"                     # https://gohugo.io/templates/internal/#google-analytics

[params]
    themeStyle                   = "dark"                  # Choose "light" or "dark" or "auto"
    favicon                      = "/img/fav.ico"          # Path to favicon file
    showMenu                     = true                    # Show navigation menu
    showRSSButton                = false                   # Show rss button in navigation
    fadeIn                       = false                    # Turn on/off the fade-in effect
    fadeInIndex                  = true                   # Turn on/off the fade-in effect on the index page even if fade-in was otherwise turned off
    dateFormat                   = "Jan 2, 2006"
    email                        = "[email protected]"   # E-mail address for contact section
    # customCSS                  = ["foo.css"]             # Include custom css files placed under assets/
    # customJS                   = ["foo.js"]              # Include custom JavaScript files placed under assets/
    # plausible                  = true                    # Use Plausible analytics (requires an account at Plausible.io)

    # Configure the home page
    [params.home]
        introHeight              = "fullheight"            # Input either "medium" or "large" or "fullheight"
        showLatest               = true                    # Show latest blog post summary
        showAllPosts             = false                   # Set true to list all posts on home page, or set false to link to separate blog list page
        allPostsArchiveFormat    = true                    # show all posts in an archive format
        # numberOfProjectsToShow   = 3                       # Maximum number of projects to show on home page. Unset or comment out to show all projects
        localTime                = true                    # Show your current local time in contact section
        timeZone                 = "America/New_York"   # Your timezone as in the TZ* column of this list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
        timeFormat               = "en-US"                 # Language specific format to use
    [params.projects]
        useTwoColumns            = false                   # Use a layout with two columns instead of three

    # Share buttons on blog post pages
    [params.share]
        twitter                  = true
        facebook                 = true
        pinterest                = false

    # To enable giscus, the GitHub-discussions-based comment section,
    # input the repository for the discussions below. For more details, see
    # https://www.joelnitta.com/posts/2021-11-24_using-giscus/
    # and https://github.com/giscus/giscus
    [params.giscus]
        # repo = "github-user/github-repo" # Entering repo will enable giscus
        repo-id = "enter-repo-id"
        category = "Comments"
        category-id = "enter-category-id"
        mapping = "pathname"
        reactions-enabled = "1"
        emit-metadata = "0"
        theme = "light"
        lang = "en"

    # Social icons appear in introduction and contact section. Add as many more as you like.
    # Icon pack "fab" includes social network icons, see: https://fontawesome.com/icons?d=gallery&s=brands&m=free
    # Icon pack "fas" includes solid style icons, see: https://fontawesome.com/icons?d=gallery&s=solid&m=free
    [[params.social]]
        url   = "https://twitter.com/cdmerchant"
        icon  = "twitter" # icon name without the 'fa-'
        icon_pack = "fab"
  #  [[params.social]]
#        url   = "https://facebook.com/"
  #      icon  = "facebook-f" # icon name without the 'fa-'
    #    icon_pack = "fab"
    [[params.social]]
        url   = "https://www.linkedin.com/in/cdmerchant/"
        icon  = "linkedin-in" # icon name without the 'fa-'
        icon_pack = "fab"
    [[params.social]]
        url = "mailto:[email protected]"  # For a direct email link, use "mailto:[email protected]".
        icon = "paper-plane" # icon name without the 'fa-'
        icon_pack = "fas"
#    [[params.social]]
 #       url   = "https://mastodon.social/"
  #      icon  = "mastodon" # icon name without the 'fa-'
   #     icon_pack = "fab"
    #    html_attributes = "rel=\"me\"" # Add rel attribute for Mastodon profile link verification


# If you don't want to use the default menu, you can define one by yourself
# [[menu.main]]
#     name    = "Home"
#     url     = "/"
#     weight  = 0
# [[menu.main]]
#     name    = "Blog"
#     url     = "/blog/"
#     weight  = 1

# We only use tag as a taxonomies
# You can add more by yourself
[taxonomies]
  tag = "tags"
  series = "series"

[markup]
  defaultMarkdownHandler = "goldmark"
  [markup.goldmark]
  [markup.goldmark.renderer]
    unsafe = true
  [markup.highlight]
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    # noClasses = true
    # For styles, see https://xyproto.github.io/splash/docs/longer/all.html
    style = "solarized-dark"
    tabWidth = 4

[languages]
    [languages.en]
        languageName     = "English"
        languageCode     = "en-us"
        contentDir       = "content/en"
        weight           = 0
        title            = "Christopher Merchant"
        [languages.en.params]
            description  = "Program Manager"   # Max 160 characters show in search results
             footerText   = "© Christopher Merchant 2022"                      # Text to override default footer text (markdown allowed)

 #   [languages.es]
  #      languageName     = "Español"
   #     languageCode     = "es"
    #    contentDir       = "content/es"
     #   weight           = 1
      #  title            = "Introducción"
       # [languages.es.params]
        #    description  = "Descripcion del sitio web"
            # footerText   = ""

#    [languages.de]
 #       languageName     = "Deutsch"
  #      languageCode     = "de"
   #     contentDir       = "content/de"
    #    weight           = 2
     #   title            = "Vorstellung"
      #  [languages.de.params]
       #     dateFormat   = "2. January 2006"
        #    description  = "Beschreibung der Webseite"
            # footerText   = ""

Below are some specific things you might like to configure right away.

Introduction allows the use of Hugo’s rich built-in syntax highlighting capabilities. See Syntax Highlighting in the Hugo docs.

Below is an example configuration for Highlight. See Highlight in the Hugo docs for more.

[markup]
  [markup.highlight]
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    # For styles, see https://xyproto.github.io/splash/docs/longer/all.html
    style = "friendly"
    tabWidth = 4

Custom shortcodes can be added to a layouts/shortcodes/ directory in your site root. For example, I used a shortcode above to display the current configuration file for this site! You can see the shortcodes in the raw Markdown for this page to understand how they work.

To ensure Hugo renders any HTML that your shortcode or other additions like Font Awesome uses in posts, make sure these lines for the Goldmark renderer are in your config.toml:

[markup]
defaultMarkdownHandler = "goldmark"

[markup.goldmark]

[markup.goldmark.renderer]
unsafe = true

The easiest way to start adding content to your site is to copy the exampleSite folder to your site’s root directory.

You can change the existing posts to see how it all works. Add new pages using the hugo new command.

To understand how different pages are rendered by Hugo, read Content Organization in the Hugo docs.