Reopen issue 346 - Include file-content as part of markdown

[mcarans]

Please reopen #346 - just look at the comments to see the support for this feature

[pgallir]

+1

[eavalenzuela]

+1

[user1095108]

+1

[Artistan]

Subscribe works better than +1 !!!
+1

[brry]

+1

[BenjaBobs]

+1

[briankfitzwater]

+1

[lucasrodes]

+1

[BurdetteLamar]

I have been working (in a private repo) on a Ruby class, MarkdownHelper, whose first method is include(template_file_path, markdown_file_path). I had intended to make this public, and to put it onto Rubygems.org.

I've seen in (much) earlier issues that GitHub has security concerns. Should I share their concern, and not go public?

[BurdetteLamar]

Fwiw, I have made public my GitHub repository MarkdownHelper.

The first feature is file inclusion for GitHub markdown, supporting included text as:

• Highlighted code block.
• Plain code block.
• Verbatim text.

[0Grit]

I wouldn't even mind if it were as simple as including an entire file inline.
My use case is to be able to display a mermaid diagram tracked in its own .md document across multiple documents.

[BurdetteLamar]

Then the verbatim inclusion might be helpful to you?

[baukeposthuma]

+1

[baukeposthuma]

Would be awesome to include .js files in markdown documentation

[BurdetteLamar]

I've put up a markdown helper with file inclusion on RubyGems:

https://rubygems.org/gems/markdown_helper

[mcarans]

@BurdetteLamar I am not clear what your markdown helper does exactly. What do I add to my README.md or README.rst on Github to use your markdown helper to include a file within it?

[BurdetteLamar]

Specify each file inclusion via an include pragma, which has the form:

• @[format](relative_file_path)

where:

• format (in square brackets) is one of the following:
  • Highlighting mode such as [ruby], to include a highlighted code block. This can be any Ace mode mentioned in GitHub Languages.
  • [:code_block], to include a plain code block.
  • [:verbatim], to include text verbatim (to be rendered as markdown).
• relative_file_path (in parentheses) points to the file to be included.

[The formatting of my doc is correct on GitHub, but gets mangled on RubyDoc.info. In answering you, I may have discovered a fix.! Will work on it.]

[mcarans]

@BurdetteLamar Do I need to add markdown_helper-0.1.5.gem in the root of my Github repo for it to work? If not, where should it go?

[BurdetteLamar]

@mcarans First, thanks for the earlier nudge. Got my doc fixed so it's right both on GitHub and RubyGems.

Second, let's take this offline, say, to email at burdettelamar@yahoo.com. Or Skype at burdette.lamar.

[BurdetteLamar]

I've seen over at GH that @mcarans often(?) codes in Python.

My method MarkdownHelper#include is not all that much code, so it wouldn't be hard to port it from Ruby to Python.

But that idea brings me back to something I'd thought before: Maybe we should have an agreed-upon specification for include files (i.e., specify the format for the include pragma). Then implementations that honor that spec would be able to process anyone's input.

Alternatively, there could be just two "universal" implementations, one (say, sh) that works on Linux, and one (say, Powershell) that works on Windows.

Thoughts?

[I know this is a bit off-topic for GH, but I don't know where else to go with this idea. Suggestions welcome.]

[mcarans]

Just in case anyone else was confused, @BurdetteLamar kindly explained to me that his markdown helper requires running before pushing to GitHub ie. it takes a template and generates the README.md from that template with any include files incorporated. You then check in the generated README.md. Combined with a Git hook, it could be a helpful automated workaround.

The proper solution is for GitHub to add this functionality directly so we do not need any workarounds.

[BurdetteLamar]

"Proper solution" indeed. A main difference is that at GH, the inclusion could be done at render time. This would mean that the project's README.md would be the template, instead of being manufactured from the template and uploaded separately. :(

[DDBdrift]

+1

[mikessoldier]

+1

[BurdetteLamar]

As I said earlier, I've put up gem markdown_helper, which does file inclusion and a couple of other things.
It's written in Ruby, of course. Would some here be more comfortable with similar functionality offered in a different language? If so, which language(s)? Possibly one for Windows and one for Linux?

[SamuelMarks]

+1

[progral]

I have same docs in different languages. The reason why I need such a feature is, that the code will be equal in every language file. But if the code changes I had to change it in every language.

[novafire99]

+1

Would be great to be able to do this. In both the wiki and repo. Have a standard copyright, help, quick jump links back and forth, company policy information, etc... Edit one file and change it everywhere.

[vnenkpet]

+1

[ttben]

+1

[ghost]

+1 It makes it easier to keep an organization's github-pages site in sync with the main repo's markdown. Ideally, one could store the common content in a separate file and have it included by other markdown documents.

Currently, If you have content which should be seen (not linked) on a README.md but also seen on a github-pages site then you must duplicate the content or include the whole README.md on the site. I don't think this is preferred for most use cases.

It would be even better if we could include a particular section of a separate markdown document.

What I'm advocating for is not including source files or external content but rather just other markdown from the same repository which shouldn't pose a security problem.

[Essenceia]

+1

[mrutkows]

+1

[basilhariri]

+1

[kloczek]

+1

[LittleGreenViper]

+1

[fabiojwalter]

+1

[JoshuaWise]

+1

[FireyFly]

It would be an idea to use the 👍 reaction to the issue to tally support, rather than flood the issue tracker with "+1" comments, now that Github actually does support that.

[SandroLuck]

+1

[phd]

+1

[BurdetteLamar]

Don't forget: you can do markdown file inclusion with Ruby gem markdown_helper. Works via both CLI and API.

The documentation is over at GitHub.

[pvcraven]

+1

[NikolayXHD]

+1

After refactoring my Wiki I need to maintain moved pages available in old locations as there are links in some forums pointing there.

Without content inclusion I have to duplicate moved content in maintained old version of the page,
and later repeat any change I make in new pages.

[kkroening]

+10

[WolfgangFahl]

4 years - no assignee, no milestone ... a lot of people have the need and not much of a reaction yet ...

[maximdanilchenko]

+1

[djonasdev]

+1

[jchapuis]

+1

[Muldec]

+1

[jesse-l]

+1

[kivikakk]

This repository is for the github-markup gem, a library which GitHub.com uses to choose a markup processor based on the type of the input data. All questions not related specifically to this gem should go to our support team. (Put another way: if a PR to this repo can't fix it, it doesn't belong here.)

I understand this is something that people want, but opening an issue here won't make that happen. People who work on the code that pertains to your query do not, in general, watch this repository. (I do because I maintain this gem.) To get it in front of their eyes, you'll need to go contact support so they can triage and prioritise it along with other requests.

Just to be super clear: another "+1" comment will not make this feature request known to the support team, who are responsible for triaging feature requests. You'll need to contact them to do so. We currently have no plan to implement this feature.

Thanks for your understanding. I'll be locking this issue now to prevent further pile-ons, as this is the third issue in github/markup for a feature that does not relate to the github-markup gem.