Directly inserting a file into Markdown

support
1

I really tried to figure this out, please point me to relevant docs / or posts that I may have missed!

Trying to document a project and would like to keep bash scripts next to my Markdown, and use Hugo to insert the contents of the bash into my final output. Here’s my idea:

description.md

`FancyScript` processes things.  Here's how it works:

{<insert contents of FancyScript.sh here>}

FancyScript.sh

cp /dev/random /tmp/fills_the_disk

In my final output, I’d like the contents of FancyScript.sh to be inserted into the {{.Content}} generated from description.md.

Any hints on how to do this (or even if it’s possible)?

Thanks,
-dan

2

Currently not possible. This kind of relates to this discussion:

But that discussion may go on for a while, so we might as well implement a cross-platform cat template function that would do this.

Thoughts, @spf13 ?

3

@blezek I’m going to go on a limb and say that I’m misunderstanding your use case, but wouldn’t one of Hugo’s built-in short codes for gists work (assuming you are hosting the gists on GH):

{{< gist yourghusername 3496402 >}}

Or partials?

If you’re talking about importing another file from outside your directory, or executing a file (I think this is what you’re aiming at), that strikes me as a bit of a security nightmare, no?

4

I think I understand his use case – I have had this need myself.

A gist would work — but that would be an extra level of duplication and work …

Say you have this software project you want to document. The source code is in /home/bep/myproject/src.

It would be nice if I would just pull in and highlight source files from that directory (reading, not executing), maybe even parts of it (lines 10-20) – and having it update itself whenever the code changes.

There may be security considerations having a cat function read files outside the project directory, maybe (cat /etc/passwd from a theme template …), but it would be very, very useful for software documentation.

5

@rdwatters No, a gist is not helpful, these are internal projects that can’t be hosted on Github at this moment. I had thought of a partial, but I’d also like the script to be right next to the markdown, so it would link correctly when rendered by a simple Markdown engine.

@bep hit the nail on the head. Specifically, my use case is documenting a cron shell script. Typically, crontabs live outside of source code control but dearly need to be documented and checked in somewhere.

Springboarding off his thoughts… The config file could list “approved” include directories, and would be able to search for the source code, directly including it in the output, and recursively applying shortcodes. Would give you the ability to do something like this:

{{<highlight python>}}
  {{<insert "path/to/approved/file" [startline]:[endline]>}}
{{</highlight>}}

Would grab lines [startline] through [endline] from the file (Hugo enforcing that it is approved), and processing via pygmentize.

This would be fantastic and simple. No exec needed.

6

I think any safe function we can expose in a cross platform way is goodness. I think cat is safe enough. It would only have access to read files that the application already has access to (and could consequently access another way).

7

Would putting the source in /data/ be too much? I mean limit ‘cat’ to read only for the /data/ path.