Including external files in Markdown source prior to converting to HTML

[wilkinsona]

I'm the lead of the Spring REST Docs project. It uses an application's tests to generate snippets (curl requests, HTTP responses, etc) that are then included in documentation written in Asciidoctor or Markdown. These snippets are exactly like the code blocks that can be found in introduction.md.

Spring REST Docs includes a sample showing how it can be used with Slate and I'd like to do the same for Docbox. To that end, I'd like to explore the possibility of Docbox supporting external files being inlined into the Markdown. With Slate, this can be done fairly easily using ERB:

<%= ERB.new(File.read("../build/generated-snippets/index-example/curl-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-request.md")).result(binding) %>
<%= ERB.new(File.read("../build/generated-snippets/index-example/http-response.md")).result(binding) %>

I'm relatively inexperienced when it comes to Node, so perhaps this is something that can already be done with Docbox? My apologies if that's the case. If it's not, is this a use case that you are interested in supporting? I would be happy to contribute something, although I would almost certainly require a little guidance to be able to do so.

[tmcw]

I've written an FAQ entry and made an example branch that demonstrates how you can template data. The gist is that this should happen ahead of time, in a prestart command or build. It's encapsulated by an 11-line node.js method that templates the content ahead of time. I think this is the right approach because it saves the application itself from being concerned about template logic and it keeps the guarantee that the content in ./content is real and final.

[wilkinsona]

Thanks, @tmcw. That's exactly the sort of thing I was looking for.