search

amyreese / markdown-pp

Preprocessor for Markdown files to generate a table of contents and other documentation needs
MIT License
309 stars 68 forks source link

Feature Request: Module for constructing code tutorials. Include code blocks (diff files) #40

Open tswast opened 7 years ago

tswast commented 7 years ago

I'd love to be able to run a diff command as part of the pre-processor for making tutorials / codelabs.

Would such a module be in scope for this project? I guess it wouldn't necessarily be cross-platform to be able run commands from the environment.

amyreese commented 7 years ago

The biggest concern would be around the security implications of allowing arbitrary shell commands to be run when ostensibly building documentation, especially in combination with the ability to include content from remote URLs. If there are specific features that you'd like to have, then I'd rather see those implemented as custom modules instead.

tswast commented 7 years ago

Makes sense to me. Yeah, it could get nasty with things like !INCLUDEURL where commands could get run without the user expecting it.

I think what I want is something like embedmd where I can include a code block from another file. I'd really like if I could define the code blocks by diffing two files, but I'm having trouble visualizing what the output of that would look like (other than just plain diff/patch syntax, which isn't great for copy-paste).

amyreese commented 7 years ago

It might make sense to add support for a generic syntax highlighter, like Pygments, though it would make more sense to do that as a post processor, after the real Markdown has been formatted. At that point, anything in a <code> tag could be safely run through the syntax highlighter to generate the final HTML. Alternatively, you could run files through Pygments as a separate step before running MarkdownPP, so that they're already marked up before being included into the markdown document.