Better config file default when creating new site

[imsus]

Problem

When starting out a new site, we sometimes find the config does not explain directly. Instead we go to the docs and find out there. Even in the docs, some of the config keys are not documented yet. Leading to confusion.

In this issue, I propose a new format for default config file with Categorization and Explanation for each key.

Current config.toml file:

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

Solution

In this case, I'm using yaml.

Proposed default config file. If there is no comment on some key, then it means it's not documented on the docs.

#-------------------------------------------------------------------------------
# CONFIG & DIRECTORY PATH
#-------------------------------------------------------------------------------

# Configuration file path.
config: config.yaml

# Archetype directory. Contains schema for content.
archetypeDir: archetypes

# Content directory. Contains all content created.
contentDir: content

# Layout directory. Contains all website view.
layoutDir: layouts

# Data directory. Contains all kinds of data-format content.
dataDir: data

# Static directory. Will be copied directly to destination.
staticDir: static

# Theme directory. Contains all theme installed on website.
themesDir: themes

# Filesystem path to read files relative from
source: ''

# Destination directory.
publishDir: public

#-------------------------------------------------------------------------------
# DEFAULT SETTINGS
#-------------------------------------------------------------------------------

# Default Theme
theme: ''

# Default Post Extension
defaultExtension: html

# Default Layout
defaultLayout: post

# Default metadata format for newly created frontmatter using
# hugo new command. "toml", "yaml", or "json"
metaDataFormat: yaml

#-------------------------------------------------------------------------------
# BUILD CONFIG
#-------------------------------------------------------------------------------

# Include content marked as draft
buildDrafts: false

# Include content with publishdate in the future
buildFuture: false

# Include content already expired
buildExpired: false

#-------------------------------------------------------------------------------
# ENABLE / DISABLE
#-------------------------------------------------------------------------------

# Enable GitInfo feature
enableGitInfo: false

# Build robots.txt file
enableRobotsTXT: false

# Enable Emoji emoticons support for page content;
# see emoji-cheat-sheet.com
enableEmoji: false

# Show a placeholder instead of the default value or an empty
# string if a translation is missing
enableMissingTranslationPlaceholders: false

# Disable Live Reload on Hugo Serve
disableLiveReload: false

# Do not inject generator meta tag on homepage
disableHugoGeneratorInject: false

# Do not build RSS files [DEPRECATED] see disableKinds
# disableRSS: false

# Do not build Sitemap file [DEPRECATED] see disableKinds
# disableSitemap: false

# Do not render 404 page [DEPRECATED] see disableKinds
# disable404: false

# Allows you to disable all page types and will render nothing
# related to 'kind';
#
# values = "page", "home", "section", "taxonomy",
#          "taxonomyTerm", "RSS", "sitemap",
#          "robotsTXT", "404"
disableKinds: ['taxonomy']

# Do not make the url/path to lowercase
disablePathToLower: false

# Don't sync permission mode of files
noChmod: false

# Don't sync modification time of files
noTimes: false

#-------------------------------------------------------------------------------
# URL RELATED SETTINGS
#-------------------------------------------------------------------------------

# Hostname (and path) to the root, e.g. http://spf13.com/
baseURL: 'localhost'

# Enable this to make all relative URLs relative to content
# root. Note that this does not affect absolute URLs. See
# https://gohugo.io/content-management/urls
relativeURLs: false

# If true all relative URLs would instead be canonicalized
# using baseURL.
canonifyURLs: false

# If true, use /filename.html instead of /filename/
uglyURLs: false

# Preserve special characters in taxonomy names
# ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames: false

# Default pagination every X items
paginate: 10

# Additional path appended for pagination
paginatePath: page

# See "content-management/permalinks"
permalinks: null

footnoteAnchorPrefix: ''

footnoteReturnLinkContents: ''

#-------------------------------------------------------------------------------
# LOCALE & LANGUAGE
#-------------------------------------------------------------------------------

languageCode: ''

# Missing translations will default to this content language
defaultContentLanguage: en

# Renders the default content language in subdir, e.g. /en/.
# The root directory / will redirect to /en/
defaultContentLanguageInSubdir: false

# if true, auto-detect Chinese/Japanese/Korean Languages in
# the content. (.Summary and .WordCount can work properly in
# CJKLanguage)
hasCJKLanguage: false

#-------------------------------------------------------------------------------
# CONTENT RELATED
#-------------------------------------------------------------------------------

title: ''

# Title Case style guide for the title func and other
# automatic title casing in Hugo.
#
# Valid values are "AP" (default), "Chicago" and "Go"
# (which was what you had in Hugo <= 0.25.1).
#
# See https://www.apstylebook.com/ and
# http://www.chicagomanualofstyle.org/home.html
titleCaseStyle: AP

# Enables syntax guessing for code fences without
# specified language
pygmentsCodeFencesGuessSyntax: false

# Color-codes for highlighting derived from this style
pygmentsStyle: monokai

# true use pygments-css or false will color code directly
pygmentsUseClasses: false

# Pluralize titles in lists using inflect
pluralizeListTitles: true

# Maximum number of items in the RSS feed
rssLimit: 15

# See "Section Menu for Lazy Bloggers",
# /templates/menu-templates for more info
SectionPagesMenu: ''

# The length of text to show in a .Summary
summaryLength: 70

newContentEditor: ''

#-------------------------------------------------------------------------------
# DEVELOPMENT & DEBUGGING
#-------------------------------------------------------------------------------

# Enable Logging
log: false

# Log File path (if set, logging enabled automatically)
logFile: ''

# Display memory and timing of different steps of the program
stepAnalysis: false

# Display metrics about template executions
templateMetrics: false

# Verbose output
verbose: false

# Verbose logging
verboseLog: false

# Watch filesystem for changes and recreate as needed
watch: true

#-------------------------------------------------------------------------------
# TAXONOMIES MAPPING
#-------------------------------------------------------------------------------

# Taxonomies
taxonomies:
  - category: categories
  - tag: tags

#-------------------------------------------------------------------------------
# OUTPUT FORMAT
#-------------------------------------------------------------------------------

# Possible output based on Kinds
#
# keys = "page", "home", "section", "taxonomy",
#        "taxonomyTerm", "RSS", "sitemap",
#        "robotsTXT", "404"
outputs:
  home: ['HTML', 'JSONFeed', 'RSS', 'InstantArticles']
  page: ['HTML', 'JSON']

# Custom Output format configuration
#
# For default Output format, see
outputFormats:

  # Output format name
  RSS:

    # Base name file
    baseName: rss

  JSONFeed:

    # Mime Type
    mediaType: application/json
    baseName: feed

    # Determine if it is plaintext or html
    isPlainText: true

  InstantArticles:
    mediaType: application/rss
    baseName: instant-article
    isPlainText: true

#-------------------------------------------------------------------------------
# CUSTOM MENU
#-------------------------------------------------------------------------------

# Menu key configuration
menu:

  # Menu area
  docs:

      # Item name
    - Name: "about hugo"

      # Item prefix
      Pre: "<i class='fa fa-heart'></i>"

      # Item allocated weight
      Weight: -110

      # Item identifier
      Identifier: "about"

      # Path for destination
      URL: "/about/"

#-------------------------------------------------------------------------------
# RELATED CONTENT
#-------------------------------------------------------------------------------

# Related key configuration
related:

  # Only include matches with rank >= threshold. This is a
  # normalized rank between 0 and 100.
  threshold: 80

  # To get stable "See also" sections we, by default, exclude
  # newer related pages.
  includeNewer: false

  # Will lower case keywords in both queries and in
  # the indexes.
  toLower: false

  # Indices list
  indices:

      # Indices name
    - name: author

      # Amount weight allocated
      weight: 150

      # Normalize to lowercase first
      toLower: true

    - name: date
      weight: 10

      # Format date
      pattern: "2006"

#-------------------------------------------------------------------------------
# CUSTOM GLOBAL PARAMETERS
#-------------------------------------------------------------------------------

# Usage {{ .Site.Params.[PARAMETER_NAME] }}
params:
  Subtitle: Another Blog

[bep]

There is a couple of problems with this approach:

1) Keeping it up-to-date and correct (it is not correct as presented, source isn't a config option). Which requires some kind of test harness. Not sure what. 2) Getting the defaults correct (watch = true doesn't make sense) 3) Hugo is all about sensible defaults. Me, personally, want as small a config as possible, so I don't set hasCJKLanguage: false because 1) It's not relevant and 2) The default is correct.

We should improve in this area, but I'm not sure this is it. If I, as a new Hugoer, got this config in my face, I would have thought that Hugo was some really complex thing for developers only. And that is not the common case.

[imsus]

I agree with you with that.

Some Idea from me:

• Show all possible keys from configuration
• Comment out all of the keys that can be customized. So that it just leave the normal defaults.
• Add simple explanation for the keys. If it is too long to be explained, just point out to the respected docs that explain the concept about the keys.

I just really like the way that Laravel handle their config. If you have time please take a look. https://github.com/laravel/laravel/blob/master/config/app.php

[bep]

Here is my take on it:

• This is about maintainance/correctness and making the life easier for the end user.
• Whatever we do, it should not make any of the above worse.

We already have some "test helper generator" from code. And we have one place in the code where we set all the defaults.

So what we can do is to add some metadata there which can be used when

1) Generating the JSON for the documentation. 2) Generating the TOML config when doing hugo new site.

The metadata should be:

• A description
• Is this a core config setting (i.e. something most people might want to fiddle with)

The config created with hugo new site should then have:

1) All the core config settings with default values + a comment with the description (if the config format supports it) 2) A comment section with all the other settings with a note that "this section can be safely deleted" or something.

That file should also be part of a automatic integration test.

[dudil]

Hi Sorry for jumping in (Let me know if you feel opening a new issue about it will serve better).

When trying to use different themes I found out that most of them will utilise just part of the settings (and will add of their own).

I think that while generating this config.toml it will make sense to have a different secondary theme-config.toml

This will allow to use different themes on the same website (not realy possible today) for A/B testing for example...

What do you think?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help. If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open. If this is a feature request, and you feel that it is still relevant and valuable, please tell us why. This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[godalming123]

1. I don't think that we should litter the hugo config with irrelevant parameters, but I defiantly think that their should be a few relevant things added, for example:

   [params]
   description = "add your sites description here"

2. Linked to this, I feel like you should add a default index.html file before you add all of this in the config file, as most paramaters aren't useful unless you know how to use them
3. A test to make sure that the default config would be correct could also be ran when you use the hugo server and just hugo commands, if this is done well then #10024 can be fixed as well, this is an alternative idea to https://github.com/gohugoio/hugo/issues/4165#issuecomment-351984978
4. I feel like hugo should not have as much functionality in the default config, for example everything to handle RSS feeds, as this will confuse the user when they are starting out, although it is great that hugo has such vast built-in functionality

[saikadaramakaisosjupita]

My proposal is either to create a new file with hugo new site that shows all the default (and/or most used) configuration options with comments for each entry or to create a command that the user can run to see these options.