Hugo Details

Hugo version

jhDocs currently supports version 0.120.4 of Hugo. Please ensure that you are using that exact version.

Hugo Folders

Below is a partial listing showing the most important folders in a typical jhDocs Hugo site. Any areas that you need to pay attention to are indicated with a star emoji (⭐).

• assets
  • Many sites won’t use this folder, but it can be used to store some assets as resources that your site can access at run time.
• ⭐ content
  • This is where you place the markdown files for your site content. This is the folder you will use the most, by far.
  • You can nest your content within subfolders in the content folder.
  • Each subfolder should have exactly one markdown file named _index.md. Hugo calls this the list page for the folder. The term comes from blogging sites, where a list page lists all content in a folder (think blog posts).
  • Each subfolder can also contain markdown files with any other name. Hugo calls these single pages because they stand on their own topic-wise, while a list page introduces the content within the subfolder.
  • ⭐ The /content/_index.md markdown file contains the markdown for your site’s home page.
• layouts
  • This folder includes:
    • Page templates
      • layouts/index.html is the HTML-based page template for your site’s home page.
        • The jhDocs theme provides this file, so do not modify the contents of this file.
        • This file renders the markdown content from the /content/_index.md file, which contains the markdown for your site’s home page.
      • layouts/404.html is the “file not found” page for your site.
        • The jhDocs theme provides this file, so you don’t need to create this.
      • layouts/_default/baseof.html is the page template for all pages other than the site’s home page.
        • This page template sets up the site’s layout: header, nav, content, table of contents, and footer.
        • It projects your markdown-based content for each page into this page template to create each final page.
        • The jhDocs theme provides this file, so you don’t need to create this. If you need to inject additional content into all pages, it’s probably cleaner to add that to the list.html and single.html templates, both of which are described below.
      • layouts/_default/list.html is the content template for list pages, i.e. markdown files named _index.md.
        • You will typically use the default version of this file provided by the theme, but you can override it if needed.
      • layouts/_default/single.html is the content template for single pages, i.e. markdown files not named _index.md.
        • You will typically use the default version of this file provided by the theme, but you can override it if needed.
    • Partials
      • Partials are Hugo components embedded in HTML.
      • Partials are used in HTML-based Hugo files like page templates and other partials.
      • There are several partials included with the theme, all of which begin with “jhdocs-”. Do not modify these partials.
      • ⭐ One partial that you should override is layouts/partials/local-head.html. This lists items to place in your site’s head other than the items added by the jhdocs-head-start.html, including your favicons and any special CSS files that you load in the head. Place your override for this file in the layout/partials folder in your site.
        • Consider using cache busting techniques for any resources you link into the page head.
        • If you define Open Graph meta tags in local-head.html, users will see a professional looking image and description when sharing links to your doc site.
          • Here’s an example of the Open Graph card for the jhDocs starter template site:
            
    • Shortcodes
      • Shortcodes are Hugo components embedded in markdown.
      • Shortcodes are used in your content markdown files.
      • There are several shortcodes included with the theme, all of which begin with “jhdocs-”. Do not modify these shortcodes.
      • You can optionally write your own shortcodes as needed that capture recurring patterns within your own documentation site.
• public
  • This is the folder that Hugo generates with your static site content. Do not modify this content and do not check it into source control as it is generated by Hugo.
  • This is the content that you will deploy to your website host.
  • This starter template deploys its contents to GitHub Pages, where it is hosted, although you can host your site on any server accessible by the public.
• ⭐ static
  • This is where you place all static assets, including your CSS, images, and favicon assets.
  • ⭐ In particular, the /static/images/hero-main.jpg file is the hero image displayed in your site’s home page. You can and should change this to an image that reflects your site’s content.
    • Sites like Pexels and Unsplash offer great royalty-free image options.
    • For the hero image, use an image that works well in that short and wide slot.
  • Note that Hugo moves all subfolders beneath the static folder to the top directory level of your site when it generates your site. The static folder itself is not included in the final site structure.
    • For example, if you added a css folder beneath the static folder and placed a file called local.css within that folder, the css folder will be available as a top-level folder within the site generated by Hugo and you can reference that CSS file from a Hugo partial as "{{ .Site.BaseURL }}css/local.css".
• themes
  • This folder includes all Hugo themes used by your site.
  • Your site will typically only use the jhDocs theme, so you’ll see the jhDocs theme assets in /themes/jhdocs.
  • Do not modify any of the assets in the themes folder; any changes are overwritten whenever you refresh the theme.
  • This folder should get checked into source control since your server build process will need access to the theme files.

How theme assets get merged with your content

Hugo stores files in several different folders:

• Your site provides content and configuration within some of these folders.
• The jhDocs theme provides assets in its own copy of some of these same folders, beneath the themes/jhdocs folder.
• Hugo combines (a) the assets from the jhDocs theme with (b) your content in order to produce the final website.
• Whenever Hugo builds your site, it looks first for theme assets within your site’s folders (assets, layouts, and static), then it looks for those same files in the theme’s subfolder if they’re not found in your site.
  • This means that you can either default to using the theme’s version of any of these files, or you can override any of them by placing a copy of that file with the same filename and within the same location in your site’s folders.
  • For example, the jhDocs theme provides a page template for all pages in your site other than the home page.
    • The theme’s version of this file is found in themes/jhdocs/layouts/_default/baseof.html.
    • If you needed to override this page template, you would copy the file from the themes/jhdocs/layouts/_default/ folder and place it into the layouts/_default/ folder in your site, then modify it there.
    • Since Hugo looks for all files first in your site, then in the theme, this allows you to override theme files.
  • You only need to override a small number of files provided by the theme. For the most part, you can just install the theme’s assets into your site as-is and things should just work.
  • You should only override theme assets when absolutely needed. This is because any assets that you override in your site will no longer receive the ongoing enhancements that the theme assets get over time.