Asciidoc and TOC shortcode

support
1

I’m also running into this issue. Note that my content is in Asciidoc.

If I leave the TOC on top of my post, the post excerpts on the home page (.Summary) appear messed up (well - showing the TOC, which I don’t want).

If I move the TOC below the initial excerpt (to a place after <!--more-->) the excerpts appear fine, but the TOC stops rendering inside the page.

Trivia: I think I once wrote the word excerpts with the consonants in the correct order, at the first try, but it wasn’t today.

Can somebody point me to a working example of getting a nice excerpt from a post that should start with a TOC?

Or if it helps, I can point you to my non-working example here. I’d like that first post to have an excerpt that excludes the TOC, but I can’t just move the TOC lower in the content, because it disappears.

Thanks!

2

I wonder if it could be an issue with the new shortcode syntax. If you start your shortcode with {{% then the shortcode will be parsed as content and added to the content >> appears in your summary. Using {{< should take it out of the summary.

But that’s just an idea, untested.

3

I write :toc: to make a TOC appear…

(The title mentions “shortcode” bit I didn’t write that title, it was written by a moderator that split my post from an old thread)

4

Have your tried using :toc: macro instead of :toc: and then putting this on a line by itself in the content where you want the TOC:

toc::[]

Details about this are here:

https://asciidoctor.org/docs/user-manual/#manual-placement

Let us know if that works!

-N, a fellow AsciiDoc user

2 Likes
5

Oh the beauty!

That worked perfectly, thanks!

1 Like
6

Great :clap:. Your question inspired me to start using AsciiDoc’s :toc: macro and I’ve now got the “Goals” section of my Themeless & Gitless Introduction to Hugo before the TOC. UX (or any) opinions welcome!

7

I just read your entire loooooong page and I quite enjoyed it. I do know something of Hugo already, so I skipped a few parts. What I most valued, compared to other stuff I’d read before, was the “bare bones” approach, teaching the basics with detail.

In fact, my experience with this site I built was that I had to learn so many technologies all at once (toml, asciidoc, go templates, hugo, the theme, git, and possibly others I forget now), that I was often left feeling quite lost.

I have a challenge for you, if you feel this would be something that could motivate you: a page giving the overall logic that Hugo follows when handling your site.

  • what is the basic high-level pseudo-code of the Hugo build process?
  • what happens first, Go templates,the Hugo lookup order, the markdownify rendering?

This could be inferred from experiments, but would likely be easier to see by just following Hugo with a Go debugger, and seeing how it does its job…

This would be quite useful, especially for people who think like a developer, like me.

What do you think?

1 Like
8

It’s from 2017, so not sure how accurate, but it’s a fun read: https://www.liwen.id.au/hugo-order/

1 Like
9

Thanks, that was an interesting read. Nice work he did there.

That is one more piece of the puzzle.

I would love to find the top-level piece described somewhere. What does Hugo do when it starts looking at a directory? Does it start with content, go one by one, inspect front-matter, decide on a layout to use, then run that process described in that post you linked?

10

#MeToo! When I first started with Hugo, I thought OK, now I will learn git… hahahaha months later, nope. My TGIH: Themeless & Gitless Introduction to Hugo is what I wish I had had when I started with Hugo. I also would like to know the answers to your two questions and, unfortunately, am not knowledgeable enough to accept your challenge :slightly_frowning_face:. It would be great if someone did.