Newbie : Using Hugo, Asciidoc, and the Techdoc Theme

support
1

Hi,

I am reviewing static site generators. I am new to Hugo. I have been using asciidoc (python) for many years so I thought I would try Hugo and its’ support for asciidoctor. All my documents are technical with source inclusions, code snippets, and reference tables. I am still considering whether to stay with asciidoc or convert to markdown. The features I like about asciidoc are the = titles, .subtitles, delimited blocks (listing, literal, sidebar, comment, pass-through, quote, example, admonition) lists, [ ] attributes, and |= tables that support formatting and spanning.

So far I have gone through the Hugo Quick-Start, brought over 1 asciidoc document for testing and changed the theme to Techdoc.

I added the following to the .toml file to use asciidoc.

# To use asciidoctor
[security.exec]
allow = ["^asciidoctor$"]

I have a few questions and would like to confirm that I’m heading in the right direction. At this time, I’d like to keep things local.

  1. Does indentation mean anything in a .toml file or is it just for human-readability?

  2. The Quick Start created a hugo.toml file. I have seen the name config.toml. What are the rules for naming the .toml file? Can I name it anything and as long as it ends with .toml Hugo will find it?

  3. The Quick Start added a document under the directory “posts” for a blog. When I started using the Hugo theme Techdoc, it wanted documents under “doc”. I thing I found that out when my asciidoc document (still under posts) didn’t appear in the html, so I viewed the source html. Is this a hugo thing or a theme thing, and what should I be reading to understand where things go?

  4. As I scrolled down the page for the Hugo theme Techdoc, it showed features for “Theme Color”, “Menu Style” but I could not find any additional documentation on how to use/configure them. How do I change the theme color and where is that documented?

  5. What am I suppose to do to get the theme’s nice menus — open menu, side menu, top-horizontal menu?

  6. Syntax highlighting is working. I am using ruby-rouge (it was the only package in the distribution’s official repository). I ran the command below in the quickstart directory. I also added some css for the admonitions. How do I get Hugo to add this additional css to my static web site? When I viewed the html source, I didn’t see it.

[params]
  custom_css = ["static/css/github.css", "static/css/adoc.css"]

rougify style github > static/css/github.cs

  1. Can an asciidoc document use Hugo’s Chroma highlighting? If so, how?

  2. When I ran hugo --verbose, I got a message saying it was deprecated and use --logLevel. All the options (debug, info) didn’t say much. Is there something else I’m suppose to do to get more details?

First impressions are very positive.

Thank you.

2
  1. No indentation in Toml, see TOML: Tom's Obvious Minimal Language
  2. Naming the conf file “hugo." is new, "config.” is still supported.
  3. You can have any dir structure you like in your content folder acording to Hugo. The theme commonly add specific templates for different sections however. E.g. templates for blog posts for the “posts” section. The naming is completely up to the theme author.
  4. Theme question are best asked to the theme author(s).
  5. Theme question are best asked to the theme author(s).
  6. Theme question are best asked to the theme author(s).
  7. I leve this to someone who have used asciidoc.
  8. See hugo | Hugo.

As you see Hugo leaves a lot up to the theme.

3

It is just for readability.

NO! It was named config.toml previously, but became hugo.toml since version 0.110.0. Stick with that.

Content organization is your decision (or your themes). See content organization, sections and template lookup order.

You should ask the theme author in their git repo. But most documentations for themes are in a wiki, the config file (sometimes inside exampleSite folder) or the readme file.

Again, ask the theme author.

Your theme author should direct you on how to do this.

@jmooring can answer 7 and 8 (I only use markdown).

4

You cannot configure asciidoctor to use the Chroma syntax highlighter, but you can use Hugo’s highlight shortcode instead of a code block:

content/posts/post-1.adoc

{{< highlight "go" >}}
for {
  fmt.Println("Hello world.")
}
{{< /highlight >}}

I’m not sure what that means.

5

Thank you for the helpful replies.

I can see that the Quick Start was just the very tip of the iceberg…

I chose the TechDoc theme after viewing the gohugo themes. I see they have a exampleSite with a config.toml (I’ll change that to hugo.toml :wink: ), with lots of comments (i.e., how to change the color).

The Book theme looked nice too. Both look very close to sphinx+myst furo theme. Are there themes that are more supported or more hugo official than others?

As I mentioned, I’m coming from asciidoc (python) and I picked it up pretty quickly. I liked that the documentation was one page with an organized table of contents. It reduces link-fatigue. There was no tutorial, but a user could view the Page Source and even download it and use it in their learning process.

Should I just start at the top of the Hugo’s Docs and plow my way through each chapter to learn the hugo way of doing things (Content Mgmt, Templates, Functions, Methods, Quick reference, Variables, Modules, Pipes). I know this hugo discourse forum’s header recommends “Read the docs”. I’ve got a couple of youtube video’s lined up that go beyond Hugo’s Quick Start and I put the site makewithhugo.com on my list.

Any other recommendations for tutorials or other resources that helped you advance in your Hugo knowledge?

Happy New Year!

6

https://gohugo.io/getting-started/external-learning-resources/

7

Hugo Tutorial by Giraffe Academy has been most helpful. I see it is referenced in the Hugo documentation. It is on the old side (6 years), but it is well done and gets into advanced topics. I appreciated the short, to the point, videos. I could skip install videos. Yeah! I feel it gave me the foundation I needed to read and comprehend the Hugo documentation better. Nothing stood out to me at this time as being too out-of-date where a newbie :wave: learns bad habits or deprecated syntax.

The one thing that keeps popping up is the use of toml vs yaml. In the above video, the site configuration file was config.toml but when they created files in the content directory the front matter was yaml. I now know the default name for the site configuration file is hugo.toml and the front-matter defaults to toml. Being new to both, I’ll stick with the defaults.

How to Deploy a Static Site using Hugo was also helpful because it was the first tutorial that I ran across that used a theme, jane, that had a fully functional example site that a user could explore. The theme used config.toml, so when I copied over the example, config.toml and hugo.toml both existed and the site compile failed. I chose to delete the hugo.toml and it worked :slight_smile:

I don’t recall which video but there has been some mention that the server must be stopped and restarted to pick up some content changes. I use options --noHTTPCache --disableFastRender and updates seem to be recognized.

Two questions,

  1. I know Hugo News shows changes in chunks, but is there a way to see a consolidated list? For example, like bash.

  2. Are Hugo’s plans to continue to use asciidoctor for parsing asciidoc or something else?

Thank you.

8

Clone source and run git log. Other than that, no.

Yes. There’s a Go implementation, but it is incomplete. See Add support for native Go implementation of AsciiDoc · Issue #1435 · gohugoio/hugo · GitHub.

9

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.