Upgrade Hugo and Docsy to latest versions (#731)

.github/workflows/ci.yml

@@ -14,17 +14,16 @@ jobs:
     timeout-minutes: 15
     steps:
 
-      - name: All Branches - Git checkout, including recursive call for Docsy theme
+      - name: All Branches - Git checkout
         uses: actions/checkout@v2
         with:
           ref: ${{ github.ref }}
-          submodules: recursive  # Fetch the Docsy theme
           fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
 
-      - name: All Branches - Install hugo extended v0.71.1
+      - name: All Branches - Install hugo extended v0.101.0
         uses: peaceiris/actions-hugo@v2
         with:
-          hugo-version: "0.71.1"
+          hugo-version: "0.101.0"
           extended: true
 
       - name: All Branches - Install Node 12.x

.github/workflows/daily.yml

@@ -20,16 +20,15 @@ jobs:
     timeout-minutes: 15
     steps:
 
-      - name: All Branches - Git checkout, including recursive call for Docsy theme
+      - name: All Branches - Git checkout
         uses: actions/checkout@v2
         with:
-          submodules: recursive  # Fetch the Docsy theme
           fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
 
-      - name: All Branches - Install hugo extended v0.71.1
+      - name: All Branches - Install hugo extended v0.101.0
         uses: peaceiris/actions-hugo@v2
         with:
-          hugo-version: "0.71.1"
+          hugo-version: "0.101.0"
           extended: true
 
       - name: All Branches - Install Node 12.x

.gitignore

@@ -2,6 +2,8 @@
 public/
 resources/
 node_modules/
+# Ignore old theme submodule folder
+themes/
 tech-doc-hugo
 
 .DS_Store

README.md

@@ -10,14 +10,12 @@ The documentation is built using Markdown pages, which can be converted into a n
 
 ## Installing Hugo
 
-The documentation site uses [Hugo](https://gohugo.io/), and specifically uses features found in the extended version of Hugo, v0.53 and later.
+The documentation site uses [Hugo](https://gohugo.io/), and specifically uses features found in the extended version of Hugo, v0.76.0 and later.
 
 To install, follow the [installation instructions for your Operating System](https://gohugo.io/getting-started/installing/), and be sure to get the extended version.
 
 ## Building the Documentation
 
-1. Get local copies of the project submodules so you can build and run your site locally:
-   - `git submodule update --init --recursive`
 1. Build your site:
    - `hugo server`
    - If there are any errors, check that you have the latest version of Hugo, and are using the extended version.
@@ -42,3 +40,19 @@ _Note_: The `muffet.sh` script here is the identical script we run on GitHub. If
 ## Continuous Deployment
 
 All changes to `main` branch run a [GitHub action](.github/workflows/ci.yml) to first check for any broken links ([per above](#link-checking-optional)) and then deploy to the documentation site: [docs.communityhealthtoolkit.org](https://docs.communityhealthtoolkit.org)
+
+## Upgrading dependencies
+
+### Hugo
+
+The version of Hugo used to deploy the site is specified in the [GitHub workflows config](./.github/workflows). To upgrade to a new version of Hugo, simply update the `hugo-version` property in the workflows to the desired version (after confirming the site functions properly on the new version of Hugo). 
+
+_(Note there is also a minimum version of Hugo required to deploy the site specified via `module.hugoVersion` in the [`config.toml`](./config.toml) file.)_
+
+See the [Hugo Release Notes](https://github.com/gohugoio/hugo/releases) for documentation regarding what has changed in the new versions.
+
+### Docsy
+
+The current version of Docsy is pinned in the [`go.mod`](./go.mod) file. To upgrade to a new version of Docsy, use the `hugo mod get` command as described [in the Docsy documentation](https://www.docsy.dev/docs/updating/updating-hugo-module/).
+
+See the [Docsy CHANGELOG](https://github.com/google/docsy/blob/main/CHANGELOG.md) for documentation regarding what has changed in the new versions.

assets/scss/_variables_project.scss

@@ -53,21 +53,21 @@ h2, h3 {
   clear: both;
 }
 
+#td-sidebar-menu {
+  .td-search-input {
+    max-width: none;
+  }
+}
+
+// https://github.com/medic/cht-docs/issues/212
 #td-section-nav {
   .td-sidebar-nav {
     &__section {
-      .show {
-        padding-left: .5rem;
+      label {
+        padding-left: 0.7rem;
       }
-      ul {
-        padding-left: 0;
-      }
-    }
-
-    &__section-title {
-      i {
-        display: inline;  // prevent widowed icon
-        opacity: 0.5;
+      .without-child, .with-child {
+        padding-left: 0.5rem;
       }
     }
   }
@@ -122,4 +122,4 @@ h2, h3 {
 
 .fa-rotate-45 {
   transform: rotate(45deg);
-}
+}

config.toml

@@ -5,9 +5,6 @@ refLinksErrorLevel = "ERROR"
 
 enableRobotsTXT = false
 
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
-theme = ["docsy"]
-
 # Will give values to .Lastmod etc.
 enableGitInfo = true
 
@@ -68,6 +65,20 @@ weight = 1
 time_format_default = "02.01.2006"
 time_format_blog = "02.01.2006"
 
+[module]
+  proxy = "direct"
+  # uncomment line below for temporary local development of module
+  # replacements = "github.com/google/docsy -> ../../docsy"
+  [module.hugoVersion]
+    extended = true
+    min = "0.76.0"
+  [[module.imports]]
+    path = "github.com/google/docsy"
+    disable = false
+  [[module.imports]]
+    path = "github.com/google/docsy/dependencies"
+    disable = false
+
 [markup]
   [markup.tableOfContents]
     endLevel = 4
@@ -125,6 +136,8 @@ offlineSearch = false
 [params.ui]
 # Enable to show the side bar menu in its compact state.
 sidebar_menu_compact = true
+# Enable folding sections of the sidebar
+sidebar_menu_foldable = true
 #  Set to true to disable breadcrumb navigation.
 breadcrumb_disable = false
 #  Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)

content/en/_index.md

@@ -3,9 +3,19 @@ title: "Welcome to the Community Health Toolkit Docs Site!"
 linkTitle: "Documentation"
 identifier: "docs"
 weight: 1
-menu:
-main:
-weight: 1
+cascade:
+- _target:
+  path: "/**"
+  kind: "page"
+  type: "docs"
+- _target:
+  path: "/**"
+  kind: "section"
+  type: "docs"
+- _target:
+  path: "/**"
+  kind: "section"
+  type: "home"
 ---
 
 {{% pageinfo %}}

go.mod

@@ -0,0 +1,5 @@
+module github.com/medic/cht-docs
+
+go 1.13
+
+require github.com/google/docsy v0.4.0 // indirect

go.sum

@@ -0,0 +1,5 @@
+github.com/FortAwesome/Font-Awesome v0.0.0-20210804190922-7d3d774145ac/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
+github.com/google/docsy v0.4.0 h1:Eyt2aiDC1fnw/Qq/9xnIqUU5n5Yyk4c8gX3nBDdTv/4=
+github.com/google/docsy v0.4.0/go.mod h1:vJjGkHNaw9bO42gpFTWwAUzHZWZEVlK46Kx7ikY5c7Y=
+github.com/google/docsy/dependencies v0.4.0/go.mod h1:2zZxHF+2qvkyXhLZtsbnqMotxMukJXLaf8fAZER48oo=
+github.com/twbs/bootstrap v4.6.1+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

layouts/_default/content.html

@@ -1,19 +1,24 @@
-{{/* Layout from docsy theme's /docs */}}
+<!-- Modified from docsy theme to show related content -->
+<!-- https://github.com/google/docsy/blob/c65715725ee992cd4e59aeefe0f66df80b2eb4ea/layouts/_default/content.html -->
 <div class="td-content">
 	<h1>{{ .Title }}</h1>
-    {{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
-	{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
-        {{ partial "reading-time.html" . }}
-    {{ end }}       
+	{{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
+	<header class="article-meta">
+		{{ partial "taxonomy_terms_article_wrapper.html" . }}
+		{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
+		{{ partial "reading-time.html" . }}
+		{{ end }}
+	</header>
 	{{ .Content }}
-	{{ partial "related.html" . }}{{/* This line is the only addition to theme's file, moved from /docs */}}
+<!-- Show related content - https://github.com/medic/cht-docs/commit/7daf27fe8e58c225759276a0284043dfcafde550 -->
+	{{ partial "related.html" . }}
 	{{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable) (.Site.GoogleAnalytics)) }}
-		{{ partial "feedback.html" .Site.Params.ui.feedback }}
-		<br />
+	{{ partial "feedback.html" .Site.Params.ui.feedback }}
+	<br />
 	{{ end }}
-	{{ if (.Site.DisqusShortname) }}
-		<br />
-		{{ partial "disqus-comment.html" . }}
+	{{ if (.Site.Params.DisqusShortname) }}
+	<br />
+	{{ partial "disqus-comment.html" . }}
 	{{ end }}
-	<div class="text-muted mt-5 pt-3 border-top">{{ partial "page-meta-lastmod.html" . }}</div>
+	{{ partial "page-meta-lastmod.html" . }}
 </div>

layouts/_default/list.html

@@ -1,22 +1,27 @@
-{{/* Layout from docsy theme's /docs */}}
+<!-- Modified from docsy theme to show related content -->
+<!-- https://github.com/google/docsy/blob/c65715725ee992cd4e59aeefe0f66df80b2eb4ea/layouts/docs/list.html -->
 {{ define "main" }}
 <div class="td-content">
 	<h1>{{ .Title }}</h1>
-        {{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
-	{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
-            {{ partial "reading-time.html" . }}
-        {{ end }}
+	{{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
+	<header class="article-meta">
+		{{ partial "taxonomy_terms_article_wrapper.html" . }}
+		{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
+		{{ partial "reading-time.html" . }}
+		{{ end }}
+	</header>
 	{{ .Content }}
-				{{ partial "section-index.html" . }}
-	{{ partial "related.html" . }}{{/* This line is the only addition to theme's file, moved from /docs */}}
+	{{ partial "section-index.html" . }}
+<!-- Show related content - https://github.com/medic/cht-docs/commit/7daf27fe8e58c225759276a0284043dfcafde550 -->
+	{{ partial "related.html" . }}
 	{{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable) (.Site.GoogleAnalytics)) }}
-		{{ partial "feedback.html" .Site.Params.ui.feedback }}
-		<br />
+	{{ partial "feedback.html" .Site.Params.ui.feedback }}
+	<br />
 	{{ end }}
 	{{ if (.Site.DisqusShortname) }}
-		<br />
-		{{ partial "disqus-comment.html" . }}
+	<br />
+	{{ partial "disqus-comment.html" . }}
 	{{ end }}
-	<div class="text-muted mt-5 pt-3 border-top">{{ partial "page-meta-lastmod.html" . }}</div>
+	{{ partial "page-meta-lastmod.html" . }}
 </div>
 {{ end }}

layouts/partials/page-meta-lastmod.html

@@ -1,2 +1,14 @@
-{{ T "post_last_mod"}} {{ .Lastmod.Format .Site.Params.time_format_default }}{{ with .GitInfo }}: <a  href="{{ $.Site.Params.github_repo }}/commit/{{ .Hash }}">{{ .Subject }} ({{ .AbbreviatedHash }})</a>{{end }}
+<!-- Modified from docsy theme to show meta links -->
+<!-- https://github.com/google/docsy/blob/c65715725ee992cd4e59aeefe0f66df80b2eb4ea/layouts/partials/page-meta-lastmod.html -->
+{{ if and (.GitInfo) (.Site.Params.github_repo) -}}
+<div class="text-muted mt-5 pt-3 border-top">
+    {{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}}
+    {{ with .GitInfo }}: {{/* Trim WS */ -}}
+    <a href="{{ $.Site.Params.github_repo }}/commit/{{ .Hash }}">
+        {{- .Subject }} ({{ .AbbreviatedHash }}) {{- /* Trim WS */ -}}
+    </a>
+    {{- end }}
+</div>
+{{ end -}}
+<!-- Show meta links when not displayed in right pane - https://github.com/medic/cht-docs/commit/05d9fffe77fa4dadd55ddc83b72c32fda569b40e -->
 <div class="d-xl-none d-print-none meta-links">{{ partial "page-meta-links" . }}</div>