search

FransBouma / DocNet

Your friendly static documentation generator, using markdown files to build the content.
http://fransbouma.github.io/DocNet/
248 stars 36 forks source link

Added support for @@include tag which will allow embedding html files from the '_partial' folder #27

Closed seemantr closed 8 years ago

seemantr commented 8 years ago

Include tag allows embedding file into the generated document. This is very useful if you want to embed the same text more than once across different pages. This is a very simplistic implementation which does not require changes to the underlying Markdown parser and uses regex expression.

FransBouma commented 8 years ago

Ah I was under the impression it included markdown snippets :) (so it would parse the markdown file first for includes, parse those for includes using a set of already includes to avoid cycles etc. till no includes are found, merge included markdown in-place, then return that as the markdown to use). (which would require markdown parser adjustments)

Having @@include include literal fragments would make that of course not possible anymore. Hmm... Not sure what the best option is. @@include-html or @@includeliteral or @@includefragment all sound verbose.

It also might be done on-the-fly though: @@include("bla.md") is included into the markdown as-is, but so is @@include("bla.htm"). So before parsing/handling markdown. The markdown parser can deal with html, so that's not a problem (although I haven't tested that in full, e.g. a markdown pre block whether that's still converted or not I don't know). IF the markdown parser can deal with it without a problem, a recursive include is best, before parsing.

What are your thoughts on this?

seemantr commented 8 years ago

I feel @@include on the fly is the best option as it is very simple to implement without touching the markdown parser. I really like the idea of embedding the source content before handing things over to markdown parser, that way the same include block can support both html and markdown.

Should be a very simple change. I will make it and submit a new pr. I can use the same approach for adding support for @@render tags also.

FransBouma commented 8 years ago

Sounds good! Your regexp version does a 1 level include I think? (the included markdown isn't parsed for include statements again). That's fine though, it can always be extended to be a recursive include :)