I was looking at Hugo to create a documentation site for a package that I wrote. However, one thing I was wondering about was the subject of documentation tests. So basically in the documentation I have some code snippets. And I would like to test that these code snippets run successfully, each time I rebuild the documentation.
Now is there a way to pull out the code snippets from Hugo generated content, so that these can be tested? I checked but did not see anyone posting on this question. It would really help if anyone knew of examples of someone doing this.
Note that I am writing code snippets in python.
Hi, I don’t think there is anything out of the box, but I believe with some scripting/shortcoding it can be done.
- Idea one: write a script that processes your markdown files (or if you prefer to test the output, the generated html files), finds the code snippets, and runs whatever tests you want on them. For markdown, for example you can search for the lines between
python and lines (or the highglight shortcode), depending what you use. In the HTML output you can probably easily find the relevant code/pre tags using BeautifulSoup.
- Idea two: you can write a shortcode that includes a code snippets from a file, and use that, so your snippets would already be in separate files, and you could run tests/linter/whatever on them.
HTH
1 Like
Idea 2 from @fekete-robert is good! It saves you from doing some uncomfortable parsing to try and get out the code to highlight, even with beautifulsoup.
If you’re looking for some sample code for the shortcode, I do something very similar here: https://github.com/pypyr/pypyr-docs/blob/master/layouts/shortcodes/app-window.html
It’s a shortcode that takes a path and renders the file with highlight code formatting. This one does it in a styled application/terminal style window via another partial, so it’s not exactly what you’re after, but you can just invoke the highlight shortcode instead:
{{ highlight .content .lang "" }}