Summaries not being reliably generated

I’m using the docdock theme to generate an internal documentation site. It works well, except for the fact that summaries of child documents seem to not be generated reliably.

I’ve come up with a small sample repository that reproduces the issue consistently on my machine. The scripted steps to reproduce are currently geared towards Windows users, but if need be I can try to add a script to reproduce the problem on Linux (although I haven’t reproduced the issue on Linux yet).

I suspect it’s some kind of race condition or ordering problem, because if I delete some unrelated content from the site, the summaries generate correctly.

I haven’t seen anyone else reporting this “bug”, so there may be something that I’m doing wrong.

I think you need to be more specific about what your expected outcome is. Your Windows script points to a section with a content file without any summary, so that does not make any sense. I run your site on my PC and all looks as expected to me – and I would suspect other people shouting if summaries didn’t work.

Sure. I was angling for the script being a fully-automated test that unambiguously demos the problem, but I’ll try to describe the scenario here in English… which may be a bit less precise, so bear with me.

My expectation is that when _index.markdown renders, the children shortcode will list the licence.markdown as child content. The summary will be rendered below the title.


I’m using the following version of Hugo (the Windows version is committed to the repository for reproducibility):

Hugo Static Site Generator v0.31.1 windows/amd64 BuildDate: 2017-12-08T12:39:01+13:00

The test script runs this particular version of Hugo to build the site to static HTML and then loads the test/index.html file to see whether the summary of the child was pulled in or not.

If you do manage to work out what the cause is, I’d also be interested in how you did so, so that I can resolve future issues myself. I couldn’t get enough information using the --debug flag to diagnose the problem.

If you need any more information, please let me know.

OK, now I get it.

Using page content (and this includes summary) in shortcodes is not supported and has undefined behaviour. This has been discussed before. We may improve on this, but you will eventually end up in a chicken and egg situation.

Thanks, @bep.

I’ll remove the summaries and just list the titles. Is there any other way to achieve what I want to achieve without copying and pasting code into each page?

What do you want?