Update Docsy

[christianbraeunlich]

Hello there,
wanted to add new content to AL Guidelines. Unfortunately it seems to be a bit outdated, as it used the Docsy theme from 2 -3 years ago, but with the latest hugo version, which causes some errors in a GitHub Codespace:

• $ hugo version
  hugo v0.133.1-47d00202e7e61769ce4d14691e43b27852c9cce4+extended linux/amd64 BuildDate=2024-08-26T13:58:46Z VendorInfo=gohugoio
• docsy: 0.2.0-dev (package.json) (the version was changed with commit = google/docsy@4a7c5c6)

1. created a Codespace
2. executed hugo serve
3. Errors pop up

Todos:

• ERROR deprecated: config: languages.en.description: custom params on the language top level was deprecated in Hugo v0.112.0 and will be removed in Hugo 0.134.0
• executing "home.html" at <partial "head.html" .>: error calling partial
• With v0.109.0 and earlier the basename of the site configuration file was config instead of hugo. You can use either, but should transition to the new naming convention when practical (https://gohugo.io/getting-started/configuration/#configuration-file)
• Migrate to Hugo Modules (https://www.docsy.dev/docs/updating/convert-site-to-module/) (not a requirement as we can still use Git submodule. I read https://www.docsy.dev/docs/get-started/#installation-options and decided to use Hugo Modules in favor of Git submodule to update to the latest Docsy Theme)
  • needs Go to be installed: update .devcontainers (replaces node entirely, removed package.json files Node needed for hugo building step)
  • hugo mod init github.com/microsoft/alguidelines
  • update hugo.toml theme
  • hugo mod graph
  • Removed docsy git submodule
• update GitHub workflows/actions (remove submodules from checkout and uptake to hugo v0.133.1 and node v20)
• verify the hugo.yaml workflow runs successfully
• WARN Config parameter '.params.ui.footer_about_disable' is DEPRECATED, use '.params.ui.footer_about_enable' instead.
• update the Contributing / Install Hugo section

Noticed only 1 big change in design so far, see the header in the following picture:

Feel free to edit this PR.

Detailed error information:

ERROR deprecated: config: languages.en.description: custom params on the language top level was deprecated in Hugo v0.112.0 and will be removed in Hugo 0.134.0

ERROR deprecated: config: languages.en.description: custom params on the language top level was deprecated in Hugo v0.112.0 and will be removed in Hugo 0.134.0. Put the value below [languages.en.params]. See https://gohugo.io/content-management/multilingual/#changes-in-hugo-01120
Watching for changes in /workspaces/alguidelines/{archetypes,assets,content,layouts,package.json,static,themes}
Watching for config changes in /workspaces/alguidelines/config.toml, /workspaces/alguidelines/themes/docsy/config.toml
Start building sites … 
hugo v0.133.1-47d00202e7e61769ce4d14691e43b27852c9cce4+extended linux/amd64 BuildDate=2024-08-26T13:58:46Z VendorInfo=gohugoio

executing "home.html" at : error calling partial

ERROR render of "home" failed: "/workspaces/alguidelines/themes/docsy/layouts/_default/baseof.html:4:7": execute of template failed: template: home.html:4:7: executing "home.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:52:16: no such template "_internal/google_analytics_async.html"
ERROR render of "taxonomy" failed: "/workspaces/alguidelines/themes/docsy/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/terms.html:4:7: executing "_default/terms.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:52:16: no such template "_internal/google_analytics_async.html"
ERROR render of "section" failed: "/workspaces/alguidelines/themes/docsy/layouts/blog/baseof.html:4:7": execute of template failed: template: blog/list.html:4:7: executing "blog/list.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:52:16: no such template "_internal/google_analytics_async.html"
Built in 586 ms
Error: error building site: render: failed to render pages: render of "404" failed: "/workspaces/alguidelines/themes/docsy/layouts/_default/baseof.html:4:7": execute of template failed: template: 404.html:4:7: executing "404.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:52:16: no such template "_internal/google_analytics_async.html"

[TheDoubleH]

The sample file, has more content: (See https://github.com/google/docsy-example/blob/main/go.sum)

github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
github.com/google/docsy v0.10.0 h1:6tMDacPwAyRWNCfvsn/9qGOZDQ8b0aRzjRZvnZPY5dg=
github.com/google/docsy v0.10.0/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc=
github.com/google/docsy v0.10.1-0.20240516225026-36746913371a h1:Fmx4SmmyWZf4q3rq9jhVWr6/h2MKEi4+61irjQO2ylI=
github.com/google/docsy v0.10.1-0.20240516225026-36746913371a/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc=
github.com/google/docsy v0.10.1-0.20240528200232-6549143cf323 h1:T4UiGpcrIgiuyQj0tc7BtJwv6u736J8Jnl4QZno0fk4=
github.com/google/docsy v0.10.1-0.20240528200232-6549143cf323/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc=
github.com/google/docsy v0.10.1-0.20240529105443-333c2f8d4172 h1:1gAAuOfHRok/hJqfF+wpjOYqlH0d76dwUsskLEnOzxo=
github.com/google/docsy v0.10.1-0.20240529105443-333c2f8d4172/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc=
github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

[christianbraeunlich]

I've followed the steps in https://www.docsy.dev/docs/updating/convert-site-to-module/#import-the-docsy-theme-module-as-a-dependency-of-your-site, which automatically generated the go.sum and go.mod files.

Based on the commit history of the file, I assume they've added the additional docsy version dependencies to test the new RTL feature.

Would leave the content on it's initial, auto-generated state.

[TheDoubleH]

The sample does not specify a theme, but has the following content to use Docsy as a module (See https://www.docsy.dev/docs/get-started/docsy-as-module/)

Sample config file:

https://github.com/google/docsy-example/blob/604f8183399ebc25e53dfd08f5607817e21a2871/hugo.yaml#L212:L220

module:
  # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace:
  # workspace: docsy.work
  hugoVersion:
    extended: true
    min: 0.110.0
  imports:
    - path: github.com/google/docsy
      disable: false

[christianbraeunlich]

In the migration guide, it was mentioned that the value can be changed from theme = ["docsy"] to theme = ["github.com/google/docsy"] (https://www.docsy.dev/docs/updating/convert-site-to-module/#update-your-config-file).

Alternatively, we could add the example you've provided. Should I adapt these changes?

[TheDoubleH]

We can do that in a separate PR later. But I do think we should get the update "all the way"

[TheDoubleH]

There are no 'Content" changes - This is a technical update of the Theme.