vscode ➜ /workspaces/omis_docs_07_23/docs (master) $ hugo -v --cacheDir ~/.local/hugo/
WARN --verbose is deprecated and will be removed in a future release. use --logLevel info
hugo: downloading modules …
hugo: collected modules in 52376 ms
Start building sites …
hugo v0.115.1-857374e69358f788bd31ddc55255c5c8e3dcfd80+extended linux/amd64 BuildDate=2023-07-03T17:28:25Z VendorInfo=gohugoio
INFO Translation func for language de not found, use default.
INFO copy static: syncing static files to /
INFO build: running step process duration 13.242084768s
INFO build: running step assemble duration 1.89347537s
Total in 71086 ms
Error: error building site: assemble: "/workspaces/omis_docs_07_23/docs/content/de/_index.md:9:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
This is a weird error message because the resolution for fixing it has just been done and the file cover.html is definitely in the /blocks/ directory.
Another resolution had a comment that before the command git submodule update, npm install should be run. OK! Testing now…
and no change…
Perhaps try first to use your theme as a real folder and not as a submodule, and with another version of Hugo. Your workflow seems quite complex, so it would be useful to decompose your workflow to identify the error(s).
baseURL = "docs/"
title = "omis documentation"
theme = ["docsy", "hugo-shortcode-roneo-collection"]
# https://www.docsy.dev/docs/adding-content/navigation/#adding-icons-to-the-top-level-menu
# As well as the completely expanded and compact menu options,
# you can also create a foldable menu by setting the site parameter
ui.sidebar_menu_foldable = true
# Language settings
contentDir = "content/en"
# defaultContentLanguage = "en"
defaultContentLanguageInSubdir = true
# Useful when translating.
enableMissingTranslationPlaceholders = true
enableRobotsTXT = false
# Will give values to .Lastmod etc.
enableGitInfo = true
# Comment out to enable taxonomies in Docsy
# disableKinds = ["taxonomy", "taxonomyTerm"]
# You can add your own taxonomies
[taxonomies]
tag = "tags"
category = "categories"
[params.taxonomy]
# set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloud = ["tags", "categories"]
# If used, must have same length as taxonomyCloud
taxonomyCloudTitle = ["Tag Cloud", "Categories"]
# set taxonomyPageHeader = [] to hide taxonomies on the page headers
taxonomyPageHeader = ["tags", "categories"]
# Highlighting config
pygmentsCodeFences = true
pygmentsUseClasses = false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic = false
#pygmentsOptions = "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle = "tango"
# Configure how URLs look like per section.
[permalinks]
blog = "/:section/:year/:month/:day/:slug/"
# Image processing configuration.
[imaging]
resampleFilter = "CatmullRom"
quality = 75
anchor = "smart"
[services]
[services.googleAnalytics]
# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
# id = "UA-00000000-0"
# Language configuration
[languages]
[languages.en]
languageName ="English"
# Weight used for sorting.
weight = 1
[languages.en.params]
title = "omis docs"
description = "omis Documentation"
[languages.de]
languageName ="Deutsch"
contentDir = "content/de"
[languages.de.params]
title = "omis doks"
description = "omis Dokumentation"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"
[markup]
[markup.goldmark]
[markup.goldmark.parser.attribute]
block = true
[markup.goldmark.renderer]
unsafe = true
[markup.highlight]
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
style = "rainbow_dash"
# Uncomment if you want your chosen highlight style used for code blocks without a specified language
guessSyntax = "true"
# Everything below this are Site Params
# Comment out if you don't want the "print entire section" link enabled.
# [outputs]
# section = ["HTML", "print", "RSS"]
[params]
copyright = "omis GmbH"
privacy_policy = "https://www.omis.at/en/Privacy_policy_en.html"
# First one is picked as the Twitter card image if not set on page.
# images = ["images/project-illustration.png"]
# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"
# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version = false
# The version number for the version of the docs represented in this doc set.
# Used in the "version-banner" partial to display a version number for the
# current doc set.
version = "4.0"
# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = "https://pages.omis.at/docs"
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
# github_repo = "https://support.omis.at/"
# An optional link to a related project repo. For example, the sibling repository where your product code lives.
# github_project_repo = "https://github.com/google/docsy"
# Specify a value here if your content directory is not in your repo's root directory
# github_subdir = "omis_docs_07_23"
# Uncomment this if your GitHub repo does not have "main" as the default branch,
# or specify a new value if you want to reference another branch in your GitHub links
github_branch= "main"
# Google Custom Search Engine ID. Remove or comment out to disable search.
# gcs_engine_id = "d72aa9b2712488cc3"
# Enable Algolia DocSearch
algolia_docsearch = false
# Enable Lunr.js offline search
offlineSearch = true
offlineSearchSummaryLength = 200
# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting = false
# User interface configuration
[params.ui]
# Set to true to disable breadcrumb navigation.
breadcrumb_disable = false
# Set to true to disable the About link in the site footer
footer_about_disable = false
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
navbar_logo = true
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
navbar_translucent_over_cover_disable = false
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = true
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable = false
# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
# add "hide_feedback: true" to the page's front matter.
[params.ui.feedback]
enable = false
# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
yes = 'Glad to hear it! Please <a href="mailto:office@omis.at?subject=Positive%20Feedback%20from%20doc%20omis">let us know how we are doing!</a>.'
no = 'Sorry to hear that. Please <a href="mailto:office@omis.at?subject=Constructive%20Feedback%20from%20doc%20omis">tell us how we can improve</a>.'
# Adds a reading time to the top of each doc.
# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
[params.ui.readingtime]
enable = true
[params.timeout]
timeout = "10m"
[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
[[params.links.user]]
name = "Contact us!"
url = "https://www.omis.at/en/Contact-en.html"
icon = "fa fa-envelope"
desc = "Discussion and help from your fellow users"
[[params.links.user]]
name ="Instagram"
url = "https://www.instagram.com/omis4.0/"
icon = "fab fa-instagram"
desc = "Follow us on Instagram to get the latest news!"
[[params.links.user]]
name = "Linkedin"
url = "https://at.linkedin.com/company/omis-gmbh"
icon = "fab fa-linkedin-in"
desc = "Practical questions and curated answers"
version_menu = "Releases"
[[params.versions]]
version = "master"
url = "http://localhost:1313/"
[[params.versions]]
version = "v1.23.7"
url = "https://pages.omis.at/docs"
[[params.versions]]
version = "v1.23.6"
url = "https://doc.omis.at/"
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
# [[params.links.developer]]
# name = "Gitlab"
# url = "https://github.com/google/docsy"
# icon = "fab fa-github"
# desc = "Development takes place here!"
#[[params.links.developer]]
# name = "Slack"
# url = "https://example.org/slack"
# icon = "fab fa-slack"
# desc = "Chat with other project developers"
#[[params.links.developer]]
# name = "Developer mailing list"
# url = "https://example.org/mail"
# icon = "fa fa-envelope"
# desc = "Discuss development issues around the project"
# hugo module configuration
[module]
# uncomment line below for temporary local development of module
# replacements = "github.com/google/docsy -> ../../docsy"
[module.hugoVersion]
extended = true
min = "0.115.1"
[[module.imports]]
path = "github.com/google/docsy"
disable = false
min = "0.7.1"
[[module.imports]]
path = "github.com/google/docsy/dependencies"
disable = false
#[[module.imports]]
#path = "github.com/RoneoOrg/hugo-shortcode-roneo-collection"
#disable = false
hugo mod graph shows my project is the same as the standard docsy project.
And in the project I do have /themes/docsy and /themes/hugo-shortcode-roneo-collection
I do see some syntax errors using the VS Code extension “Even Better TOML” but they don’t make sense to me:
[{"extended":true,"min":"0.115.1"}] is not of type "object"
Additional properties are not allowed ('min' was unexpected)
Additional properties are not allowed ('min' was unexpected)
One thing that is missing from this example is that vscode on github is not an option, rather Visual Studio, so you cannot launch VS Code into a devcontainer directly from the browser, instead you have to clone the repo into a container, which launches VS Code devcontainer automatically into Alpine, which isn’t as useful as launching into a golang image as happens in the .gitlab-ci.yml pipeline. How to directy VS Code to use a golang image?
As a result I seem to have to install golang and npm globally as a postCreate task in the devcontainer.json and this is sloow.
18Error: error building site: POSTCSS: failed to transform “scss/main.css” (text/css). Check your PostCSS installation; install with “npm install postcss-cli”. See https://gohugo.io/hugo-pipes/postcss/: this feature is not available in your current Hugo version, see Frequently asked questions | Hugo for more information
turns out I have a huge number of hugos installed for some weird reason.
One of those reasons is I had to manually install hugo using apt-get in the github codespace which is weird because that was supposed to be github’s job. But they won’t listen tot he hugo.toml file and use hugo extended 0.115.1.
Hugo 1: /usr/bin/hugo
Hugo 2: /usr/local/bin/hugo
Hugo 3: /usr/local/bin/hugo/bin/hugo
$PATH variable managed to go DEEP: /usr/local/bin/hugo/bin/hugo.
Removed all but /usr/local/bin/hugo.
Can now build hugo and the server works in the sense that it is a running process on github. It’s unreachable, but its running.
Github actions also fails to build and pretends it just installed hugo and not hugo_extended but it TOTALLY installed hugo extended (See github actions build debug log):
Start building sites …
hugo v0.115.1-857374e69358f788bd31ddc55255c5c8e3dcfd80+extended linux/amd64 BuildDate=2023-07-03T17:28:25Z VendorInfo=gohugoio
Total in 16872 ms
Error: error building site: POSTCSS: failed to transform "scss/main.css" (text/css). Check your PostCSS installation; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/: this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information
Error: Process completed with exit code 1.
##[debug]Finishing: Build with Hugo
I interpret this message as being a very very general “something went wrong” message for a laundry list of potential failures such as the software stack forgetting the software stacks stack order (again, and again). I am unaware of an obvious method for telling the github action to run (again) npm install.
Adding incarnations of npm install xxxxxxx to the .github/workflows/hugo.yml until it works…
stay tuned.
However this file doesn’t make hugo run version 115.4 and it doesn’t appear to mean you will get the dependencies installed either. What is frustrating here is the ability to tell the software to install hugo 115.1 and it installs and/or uses 113.x in github actions and has a package.json that dictates 115.4.
There are of course reasons for this behavior but they aren’t apparent and should be subservient to the hugo.toml file in any case.
The devcontainertool CAN or COULD work for some people some of the time.
The hugo project definitely does work as long as you don’t use github actions or visit locallhost:1313
Under the right conditions somewhere deep within github’s network this project is hosting some content successfully.
What is the point of hugo.toml if it can’t actually dictate a hugo version as a moduel a-la:
[module]
# uncomment line below for temporary local development of module
# replacements = "github.com/google/docsy -> ../../docsy"
[module.hugoVersion]
extended = true
min = "0.115.1"
– What is the reason for building hugo not hugo extended when I am unable to find any code that says anything other than install hugo extended?
This is why we can’t have nice things.
@mattomis ➜ ~/omisdocs-0 (main) $ sudo apt-get remove hugo
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Package 'hugo' is not installed, so not removed
0 upgraded, 0 newly installed, 0 to remove and 16 not upgraded.
@mattomis ➜ ~/omisdocs-0 (main) $ which hugo
/usr/bin/hugo
`npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
@antoinentl I uploaded my hugo.toml to github after forking the docsy example and successfully got it to build but it required installing npm again or rather messing about with package-lock.json, package.json, npm install and npm ci and my overall impression is that this software is very brittle and the relationship between the hosting and the code repo is difficult to simplify. It doesn’t “just work” and I am not sure how much simpler I can make my project. I am unclear why using github’s own actions and hugo.yml file I can’t get hugo extended to just work, if my hugo.toml file says use hugo extended 115.1 and the docsy example I forked ALSO says that as do the package.json dependencies and the package-lock.json dependencies.
of course! My process is I start with something that works and then break it and then fix it. But with this stuff you can break it and then it lies to you and you try to fix it and break it some more. This means you can’t work backwards and start again. Instead you have to start over from scratch and just avoid doing what you did before and can’t readily learn from the mistake beyond just not doing it like that.
I haven’t had to work with npm before and it looks horrible. The propensity for confusion when you have node, nodejs, node.js, npm, nvm, npx and package.json and package-lock.json and the local vs. global absurdity without a consistent management solution is a big part of that.
But right now I just want to know why using a devcontainer with golang doesn’t mean I have access to go once the devcontainer build completes. It looks like I am installing a container that doesn’t work on top of a container which does work. So I end up with hugo installed but no go and end up installing golang all over again in the final step. What happend to the golang when hugo got installed?
Anyway, I have learned a lot and have tried to employ as much as I can to get a better quality product. Our documentation needs updating big time. We need full text search , versioning, multilingual support and maintainability and I think hugo markdown docs as a git repo will provide that.
Maybe you could start with a simpler setup, like running a Hugo executabledirectly on your machine. No container, no Go, just the absolutely necessary stuff.
So I split my problems into two separate repos (a devcontainer environment for VS Code and the Hugo Project itself and tested first the devcontainer.
I used a base GO devcontainer and a base Hugo devcontainer and they worked.
The issue with the devcontainer repo is the dockerfile. Specifically in that dockerfile Go is not removed from the golang:1.13 image. Instead, it’s used in the build stage to compile and prepare the version and variant of Hugo. The final image (mcr.microsoft.com/vscode/devcontainers/base ) does not include Go, but it includes the hugo binary that was built during the build stage. So by the time I need go in my vs code environment, I can run ‘hugo version’ but ‘hugo mod graph’ will fail as there is no go installed. If I want to keep Go in the final image, I should perform the Hugo installation and other setup steps in the same stage of the Dockerfile as the golang:1.13 base image. This way, Go will be present in the final image, and I don’t need to switch to another base image.
Then with respect to npm there is an ongoing issue with a debian mirror being flaky and so sometimes builds would fail to update packages at the point in time the build hit the flaky mirror:
This mirror is excised thusly in the Dockerfile:
RUN sed -i 's/debian.map.fastlydns.net/deb.debian.org/' /etc/apt/sources.list &&
These two changes mean I can reliably get to a devcontainer and can focus on issues with the 2nd repo and the hugo project itself.
Launching a codespace on github and using the test repo, I then can successfully run
hugo mod graph
npm install
npm ci
hugo
hugo server
hugo mod graph returns:
hugo: downloading modules …
hugo: collected modules in 20032 ms
github.com/google/docsy-example github.com/google/docsy@v0.7.1
github.com/google/docsy-example github.com/google/docsy/dependencies@v0.7.1
github.com/google/docsy/dependencies@v0.7.1 github.com/twbs/bootstrap@v5.2.3+incompatible
github.com/google/docsy/dependencies@v0.7.1 github.com/FortAwesome/Font-Awesome@v0.0.0-20230327165841-0698449d50f2
github.com/google/docsy-example github.com/RoneoOrg/hugo-shortcode-roneo-collection@v0.0.0-20230702180628-c61064e895fd
I consider any issues with using github pages or github actions as not relevant as the environment was only for testing and we use gitlab which is working fine to serve the Hugo project as a Pages site.