Best way to "include" code snippets?

support
1

I am documenting my company’s software. We have sample C# code we want to scrape from a source file (e.g. unit tests) to drop into markdown. (It is embarrassing to provide sample code that does not compile.) I don’t want the code to run or anything, I just want it to show up on our documentation pages. Since we’ll be thinking of other things during the release cycle, I want this to be an automated process. Is this a stupid thing to want? Or has someone already made this happen in a fashion I haven’t read about yet.

Thanks in advance,

steve

1 Like
2

But then…

So are you asking how to add code snippets into markdown files on the fly, or are you talking about taking a bunch of existing code files and somehow automating to dump into markdown files?

3

I guess I’m asking for the latter. (I’ll want something else if this sounds stupid.)

Suppose we’ve got code that has a lot of distracting setup/teardown. In the middle is a unit test that runs as part of each build. It illustrates something awesome. If I copy/paste it to the markdown file, Murphy will move to change something that’ll cause the snippet to quit working. And I want to be DRY. So, I envision juicing the source code file with something magic before/after the awesome snippet to mark it to go into a markdown file. Obviously, I can write a little filter to look for the start/stop magic in my sources and write what it finds into a markdown. This can get called just before each release so the documentation stays up to date.

But if someone has already done something smarter, I want to learn from youze guyz.

4

Hey Steve,

In your case I would go with the following approach:

  • Create a shortcode that include the content of a certain file in a <pre><code>-HTML-Markdown.
  • recommended readings: Shortcodes and readFile

In practice this could look like this:

Create a shortcode file called snippet.html in your /layouts/shortcodes/ directory with a content like:

<pre><code>
{{ readFile (.Get 0) }}
</code></pre>

then use it in your markdown like:

{{< snippet "wherever/your/snippet/lays/snippet.c" >}}

If you do this in an automated build, make sure the C#-files are available in the same repository, otherwise there the CI system has no chance to reach the files.

Hope this helped.

1 Like
5

@rwi to @StevePoling…

To piggyback on the shortcode idea…

  1. I’m assuming you want some sort of syntax highlighting.
  2. If you’re going to manually drop chunks of code into, for example, body copy, I would bear in mind that markdown allows you to declare your language syntax…so you have a few different ways to do this
  3. Definitely look at Hugo’s built-in highlight shortcode, which is in a less-than-obvious location in the documentation.

I use the following because I prefer to have the syntax highlighting done on the client via highlight.js, which has a module for C#.

So, in your layouts/shortcodes/readfile.html…

You could put the following:

{{- if eq .Get "md" "true" -}}
{{- readFile (.Get "file") | markdownify -}}
{{- else -}}
{{ readFile (.Get "file") }}
{{- end -}}

Here is how you could call it in your *.md content files:

~~~html

{{ readfile file="filedir/your-file.md" }}

~~~

Note that you can use triple back ticks or triple tildes to represent code blocks in markdown, so I had to use the latter because Discuss is giving me grief. Also filedir in this case is always going to be relative to your root project directory…

Anyways, the above would convert the contents of your-file.md to a string and then wrap it in code blocks with class="language-html" for some nice client-side highlighting.

That said, if your-file.md already includes the triple back ticks (I’m not sure how you’re going to script this and output it from source to these individual content files), you could then just pass the md value as true so that Hugo a) converts the file’s text to string and then b) runs that string through the Blackfriday markdown parser.

I like the idea of creating a readfile shortcode like this because you have a single shortcode that can be applied across the board.

Now, if you want to pass more arguments into the shortcode, you might want to look at the split function or even replaceRe depending on your desired output. LOTS. O. OPTIONS.

HTH.

3 Likes
6

Everyone, I thought I owe y’all a status report. First, I apologize for asking an ill-posed question. What I wanted was a way to guarantee that someone using my documentation could copy-paste code snippets into his IDE and encounter no syntax errors. This proved to be impossible, because often code examples will omit stuff unrelated to the functionality being described, but vital to syntactical completeness. includes and declarations for instance.

I wrote a simple program to scan all .md files for ``` patterns, and noticed the majority of these were XML, not C# source code. Instead of dropping the project then and there, I extended this program to read the XSD files matching the XML and validate that instead.

I wrote this in C# leveraging the MSTest framework, but I think a Hugo-righteous solution will require me to port it to golang and invoke it whenever Hugo builds my site. As recommended to me earlier in this thread, now is a good time for me to read the fine manual.

Thank you to everyone who helped me. If ever in Grand Rapids, MI, let me buy you a round of your favorite beverage.

1 Like
7

LOL. You’re among friends here. :wink: