Installation: Configuration

General considerations#


To configure a Hugo website using the theme, there are three types of configuration:

TypeConfiguration file
Standard Hugo configuration./config.toml
Specific configuration using site variables./config.toml
Default theme configuration.themes/shadocs/data/themeParams.toml

Specific configuration#


config.toml ([params] section)
[params]
  # Website logo file paths
  logo                    = "images/logo.png"
  logoTouch               = "images/logoTouch.png"
  # Image file path displayed during a 404 error
  image404                = "images/404.gif"
  # Favicon website file path
  favicon                 = "images/favicon.png"
  # Default layout used for the homepage
  homeLayout              = "onboarding"
  # Site content order (https://gohugo.io/templates/lists/#order-content)
  siteContentOrder        = "weight"
  # Activate/Deactivate the table of contents globally (sitewide)
  toc                     = true
  # Activate a global banner on all website pages
  globalBanner            = true
  # Curent version of the website
  currentVersion          = "latest"
  # Url of the latest version of the website
  latestVersionUrl        = "https://jgazeau.github.io/shadocs/"
  # Enforce Link resolution using relref function (https://gohugo.io/content-management/cross-references/)
  enforceRefrelLinks      = true
  # Disable "Print" button in navbar
  navbarPrintEntry        = false
  # Disable "QR code" button in navbar
  navbarQRCodeEntry       = false
  # Disable "Shortcuts" button in navbar
  navbarSchortcutsEntry   = false
  # Disable "About" button in navbar
  navbarInfo              = false
  # Keyboard shortcuts list
  # For each shortcut following keys must be sets:
  # - keys     = [Keyboard shortcuts table](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)
  # - function = "Javascript function name to call by the shortcut"
  [params.navbar.shortcuts]
    # Example shortcut definition
    [params.navbar.shortcuts.example]
      keys     = ["Shift","1"]
      function = "scExample"
  # Taxonomies list
  # For each taxonomy following keys can be sets:
  # - icon = "Fontawesome classes associated to the taxonomy"
  [params.taxonomies]
    [params.taxonomies.categories]
      icon = "fa-solid fa-table-cells"
  # Assets list (https://gohugo.io/hugo-pipes/resource-from-template/) to include
  # Managed assets:
  # - sass                  = [List of SASS files]
  # - css                   = [List of CSS files]
  # - js                    = [List of javascript files]
  # - jsModules             = [List of javascript modules]
  # - shortcodes.css        = [List of CSS files to includes when the associated shortcode exist in the page content]
  # - shortcodes.js         = [List of javascript files to includes when the associated shortcode exist in the page content]
  # - shortcodes.jsModules  = [List of javascript module files to includes when the associated shortcode exist in the page content]
  # - fencedcodes.css       = [List of CSS files to includes when the associated language of fenced code exist in the page content]
  # - fencedcodes.js        = [List of javascript files to includes when the associated language of fenced code exist in the page content]
  # - fencedcodes.jsModules = [List of javascript module files to includes when the associated language of fenced code exist in the page content]
  #
  [params.includes]
    sass = [
      "sass/file1.sass",
      "sass/fileX.sass"
    ]
    css = [
      "css/file1.css",
      "css/fileX.css"
    ]
    js = [
      "js/file1.js",
      "js/fileX.js"
    ]
    jsModules = [
      "js/modules/file1.js",
      "js/modules/fileX.js"
    ]
  [params.includes.shortcodes.sass]
    shortcode1 = [
        "sass/shortcodes/shortcode1.sass"
      ]
    shortcodeX = [
        "sass/shortcodes/shortcodeX.sass"
      ]
  [params.includes.shortcodes.css]
    shortcode1 = [
        "css/shortcodes/shortcode1.css"
      ]
    shortcodeX = [
        "css/shortcodes/shortcodeX.css"
      ]
  [params.includes.shortcodes.js]
    shortcode1 = [
        "js/shortcodes/shortcode1.js"
      ]
    shortcodeX = [
        "js/shortcodes/shortcodeX.js"
      ]
  [params.includes.shortcodes.jsModules]
    shortcode1 = [
        "js/shortcodes/modules/shortcode1.js"
      ]
    shortcodeX = [
        "js/shortcodes/modules/shortcodeX.js"
      ]
  [params.includes.fencedcodes.css]
    shortcode1 = [
        "css/fencedcodes/shortcode1.css"
      ]
    shortcodeX = [
        "css/fencedcodes/shortcodeX.css"
      ]
  [params.includes.fencedcodes.js]
    shortcode1 = [
        "js/fencedcodes/shortcode1.js"
      ]
    shortcodeX = [
        "js/fencedcodes/shortcodeX.js"
      ]
  [params.includes.fencedcodes.jsModules]
    shortcode1 = [
        "js/fencedcodes/modules/shortcode1.js"
      ]
    shortcodeX = [
        "js/fencedcodes/modules/shortcodeX.js"
      ]

Default theme configuration#


themeParams.toml
#
# GitHub links displayed in the information modal
#
[github]
  main = "https://github.com/jgazeau/shadocs"
  download = "https://github.com/jgazeau/shadocs/archive/main.zip"
  issue = "https://github.com/jgazeau/shadocs/issues"
  fork = "https://github.com/jgazeau/shadocs/fork"
#
# Miscellaneous sidebar parameters
#
[sidebar]
  homeSectionIconDefault = "fa-solid fa-house-chimney"
  firstSectionIconDefault = "fa-solid fa-ban"
  nestedSectionIconDefault = "fa-solid fa-turn-up fa-rotate-90 fa-xs"
#
# List of theme keyboard shortcuts
# For every shortcut the following keys are sets:
# - keys     = [Table of keyboard shortcut keys] (https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)
# - function = "Name of the javascript function to call for the shortcut"
#
[navbar]
  [navbar.shortcuts.1_info]
    keys = ["Shift","i"]
    function = "scShowInfo"
  [navbar.shortcuts.2_shortcuts]
    keys = ["Shift","k"]
    function = "scShowShortcuts"
  [navbar.shortcuts.3_home]
    keys = ["Shift","h"]
    function = "scGoHome"
  [navbar.shortcuts.4_search]
    keys = ["Shift","f"]
    function = "scGoSearch"
  [navbar.shortcuts.5_togglesidebar]
    keys = ["Shift","m"]
    function = "scToggleSidebar"
  [navbar.shortcuts.6_toggletoc]
    keys = ["Shift","t"]
    function = "scToggleToc"
  [navbar.shortcuts.7_backtotop]
    keys = ["Shift","ArrowUp"]
    function = "scBackToTop"
  [navbar.shortcuts.8_gotobottom]
    keys = ["Shift","ArrowDown"]
    function = "scGoToBottom"
  [navbar.shortcuts.9_print]
    keys = ["Shift","p"]
    function = "scPrint"
  [navbar.shortcuts.10_qrcode]
    keys = ["Shift","q"]
    function = "scQrCode"
  [navbar.shortcuts.11_closemodals]
    keys = ["Escape"]
    function = "scCloseModals"
#
# Assets list (https://gohugo.io/hugo-pipes/resource-from-template/) to include
# Managed assets:
# - sass                  = [List of SASS files]
# - css                   = [List of CSS files]
# - js                    = [List of javascript files]
# - jsModules             = [List of javascript modules]
# - shortcodes.sass       = [List of SASS files to includes when the associated shortcode exist in the page content]
# - shortcodes.css        = [List of CSS files to includes when the associated shortcode exist in the page content]
# - shortcodes.js         = [List of javascript files to includes when the associated shortcode exist in the page content]
# - shortcodes.jsModules  = [List of javascript module files to includes when the associated shortcode exist in the page content]
#
[includes]
  sass = [
    "sass/theme/main.sass"
  ]
  css = [
    "css/external/fontawesome.all.min.css",
    "css/external/overlay-scrollbars/overlayscrollbars.min.css"
  ]
  js = [
    "js/theme/browserCompatibility.js",
    "js/external/flexsearch/flexsearch.bundle.min.js",
    "js/external/qrious/qrious.min.js",
    "js/external/overlay-scrollbars/overlayscrollbars.min.js"
  ]
  jsModules = [
    "js/theme/modules/const.js",
    "js/theme/modules/helpers.js",
    "js/theme/modules/helpersGlobal.js",
    "js/theme/init.js",
    "js/theme/navbar.js",
    "js/theme/print.js",
    "js/theme/qrcode.js",
    "js/theme/search.js",
    "js/theme/shortcuts.js",
    "js/theme/sidebar.js",
    "js/theme/toc.js"
  ]
  [includes.shortcodes.jsModules]
    asyncapi = [
      "js/shortcodes/asyncapi.js",
      "js/external/asyncapi/asyncapi-web-component.min.js"
    ]
    collapsible = [
      "js/shortcodes/collapsible.js"
    ]
    highcharts = [
      "js/shortcodes/highcharts.js",
    ]
    intro = [
      "js/external/intro/intro.min.js",
      "js/shortcodes/intro.js"
    ]
    jsoneditor = [
      "js/external/bulma-toast/bulma-toast.min.js",
      "js/external/json-editor/jsoneditor.min.js",
      "js/shortcodes/jsoneditor.js"
    ]
    openapi = [
      "js/shortcodes/openapi.js",
    ]
    treeview = [
      "js/shortcodes/treeview.js"
    ]
  [includes.shortcodes.js]
    openapi = [
      "js/external/swagger-ui/swagger-ui-bundle.min.js",
      "js/external/swagger-ui/swagger-ui-standalone-preset.min.js"
    ]
  [includes.shortcodes.css]
    asyncapi = [
      "css/external/asyncapi/default.min.css"
    ]
    openapi = [
      "css/external/swagger-ui/swagger-ui.min.css"
    ]
  [includes.fencedcodes.js]
    mermaid = [
      "js/external/mermaid/mermaid.min.js"
    ]
  [includes.fencedcodes.jsModules]
    mermaid = [
      "js/fencedcodes/mermaid.js"
    ]
#
# Miscellaneous shortcodes parameters
#
[shortcodes]
  [shortcodes.treeview]
    [shortcodes.treeview.kinds]
      default     = "fa-solid fa-circle-question"
      dir         = "fa-solid fa-folder"
      file        = "fa-solid fa-file"
      home        = "fa-solid fa-house-chimney"
      page        = "fa-solid fa-file-lines"
      section     = "fa-solid fa-folder-tree"
      taxonomy    = "fa-solid fa-tags"
      term        = "fa-solid fa-tag"
      archive     = "fa-solid fa-file-zipper"
      image       = "fa-solid fa-file-image"
      video       = "fa-solid fa-file-video"
      script      = "fa-solid fa-file-code"
      dockerfile  = "fa-brands fa-docker"
      pdf         = "fa-solid fa-file-pdf"
      powerpoint  = "fa-solid fa-file-powerpoint"
      excel       = "fa-solid fa-file-excel"
      csv         = "fa-solid fa-file-csv"
      word        = "fa-solid fa-file-word"