Configuring jhDocs

After the jhDocs theme is installed in your Hugo site, follow the steps below to get it fully set up.

config.yaml

Edit the Hugo configuration in the config.yaml file.

• Set baseURL to your site’s production base URL.
  • IMPORTANT: The baseURL must end with a forward slash character (/).
  • If you’re hosting your site in GitHub Pages without a custom URL, then your baseURL in the Hugo configuration will include your repo name.
  • For example, if your product repo name is fraud-detection and it’s part of the jkhy organization and is hosted using GitHub Pages, your baseURL would be https://jkhy.github.io/fraud-detection/. The forward slash on the end is required.
  • If you examine your site and it looks like a jumbled mess on the screen, it’s very likely that you have an incorrect baseURL defined for your site.
• Set title to the title for your documentation site.
• enableGitInfo controls where jhDocs looks to get the last modified date that displays at the bottom of every page:
  • If you explicitly define the last modified date within each page using the lastmod front matter variable, then omit the enableGitInfo setting or set it to a value of false. jhDocs will use the front matter variable value as the last modified date for each page.
  • Otherwise set enableGitInfo to a value of true and jhDocs will use the date of the last git commit that updated the page as the last modified date for each page.
• Ensure that module is defined as follows in order to link in the jhDocs theme:

  module:
    imports:
      - path: "github.com/jkhy/jhdocs-hugo-theme"
  

• If your site uses Google Analytics, set the googleAnalytics parameter to your Google Analytics measurement ID, which typically starts with “G-”. Doing this will tell Hugo to inject the proper Google Analytics JavaScript for your measurement ID into your documentation site.
• If your site should allow the user to include search results from other jackhenry.dev documentation sites, add a params entry with an dotDevSite parameter that’s set to a value of 'true';
  • Otherwise you can either omit the params > dotDevSite parameter or set it to a value of 'false'
• The params section is for custom variables:
  • searchIndexUrl
    • This setting is required in order for site search and AI Assist to work.
    • Set this to the same values as the baseURL param described above, tacking _pagefind/pagefind.js onto the end of that.
    • For example, the baseURL param for this site is https://jkhy.github.io/jhdocs/, so the searchIndexUrl param is set to a value of https://jkhy.github.io/jhdocs/_pagefind/pagefind.js.
  • aiAssistAgentId
    • If you have set up an AskJack AI Assist agent for the content in this repo, specify the agent ID for the AI Assist agent in this value.
    • You can find this value within the AskJack admin UI itself.
    • Both aiAssistAgentId and aiAssistKbId must be filled in in order for the AI Assist feature to work.
    • See Configuring AI Assist for details on configuring AI Assist.
  • aiAssistKbId
    • If you have set up a knowledge base for an AskJack AI Assist agent for the content in this repo, specify the knowledge base ID for the AI Assist agent in this value.
    • You can find this value within the AskJack admin UI itself.
    • Both aiAssistAgentId and aiAssistKbId must be filled in in order for the AI Assist feature to work.
    • See Configuring AI Assist for details on configuring AI Assist.
  • swaggerSupport
    • If your site uses the jhdocs-swagger-ui shortcode to display Swagger UI specs using our standard Swagger UI support, then the swaggerSupport value under params should use a value of standard.
    • If your site uses a custom shortcode to display Swagger UI specs using our a custom version of Swagger UI, then the swaggerSupport value under params should use a value of custom.
    • Otherwise the swaggerSupport value under params should use a value of none. You can also just omit this parameter.
  • There are several parameter values that begin with banner that define an optional eye-catching banner for displaying important updates at the top of every page in your documentation site.
• You should be able to leave the other items at their default values.

A sample config.yaml file is shown below, with the items you should pay attention to highlighted.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

baseURL: https://jkhy.github.io/jhdocs/
languageCode: en-us
title: jhDocs Hugo Theme
sectionPagesMenu: main
pygmentsUseClasses: true
enableGitInfo: true
disableKinds:
  - RSS
  - sitemap
  - taxonomy
  - taxonomyTerm
markup:
  tableOfContents:
    endLevel: 6
    ordered: false
    startLevel: 1
module:
  imports:
    - path: "github.com/jkhy/jhdocs-hugo-theme"
params:
  swaggerSupport: none
  pageFeedbackEmails: jhoneycutt@jackhenry.com
  bannerText: 
  bannerStyle: information
  bannerLinkText: More info
  bannerLinkUrl: 
  bannerStartDate:
  bannerEndDate:
  searchIndexUrl: https://jkhy.github.io/jhdocs/_pagefind/pagefind.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

baseURL: https://jkhy.github.io/jhdocs/ ⭐
languageCode: en-us
title: jhDocs Hugo Theme ⭐
sectionPagesMenu: main
pygmentsUseClasses: true
enableGitInfo: true ⭐
disableKinds:
  - RSS
  - sitemap
  - taxonomy
  - taxonomyTerm
markup:
  tableOfContents:
    endLevel: 6
    ordered: false
    startLevel: 1
module: ⭐
  imports:
    - path: "github.com/jkhy/jhdocs-hugo-theme"
params:
    dotDevSite: 'false'

local-head.html

You can define elements for your site’s HTML head by editing the layouts/partials/local-head.html file.

What the theme adds to the head

The contents of your copy of this file are added to the head after the jhDocs theme adds its own elements to the head, including:

• The charset (UTF-8) definition
• The viewport definition
• The page title, which is calculated from your markdown and your site’s title
• A link to the pagefind site search CSS
• A link to the jhDocs CSS

So your local-head.html file should not redefine any of the items listed above.

What you should add to the head

Here’s what you should define in your copy of local-head.html:

• Links to your favicon file(s)
• A link to any local CSS that you’re using in your site (beyond the jhDocs and Pagefind CSS)
  • Consider using cache busting techniques for any resources you link into the page head. The local.css import in the example below adds a ?v=1 suffix for this purpose. Increment that version number whenever you update local.css; this tells browsers to download the new copy instead of using an older cached copy of the file.
• Any other meta tags you need to define in your 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 this site:
  

<!-- Description -->
<meta name="description" content="Create technical documentation that engages and delights your users.">
<meta property="og:title" content="jhDocs Hugo Theme | Jack Henry Docs" />
<meta property="og:image" content="https://jkhy.github.io/jhdocs/images/jhdocs-hugo-theme-hero.jpg">
<meta property="og:description" content="Create technical documentation that engages and delights your users.">
<meta property="og:url" content="{{ .Site.BaseURL }}"/>

<!-- Favicon -->
<link rel="apple-touch-icon" sizes="180x180" href="{{ .Site.BaseURL }}favicon/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="{{ .Site.BaseURL }}favicon/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="{{ .Site.BaseURL }}favicon/favicon-16x16.png">
<link rel="mask-icon" href="{{ .Site.BaseURL }}favicon/safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">

<!-- Local styles -->
<link rel="stylesheet" href="{{ .Site.BaseURL }}css/local.css?v=1">

static

The static folder is where you place all static assets that your markdown will need access to, including your CSS, images, and favicon assets. You’ll typically partition this static content into subfolders like css, favicon, images, etc.

All folders beneath the static folder are moved to the top level of your site when Hugo 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 as "{{ .Site.BaseURL }}css/local.css".

Home page content

Edit your site’s home page content in the content/_index.md file, using markdown.

Mobile search page

You must have a mobile search page named search.md at the top level of your content folder.

Site content

Add your markdown-based content into the content folder.