README.rst :include: directive doesn't work

[jaredly]

The :include: restructuredtext directive (http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment) looks like it's disabled at the moment. https://github.com/github/markup/blob/master/lib/github/commands/rest2html#L24

Could you enable it, so that I could, for example, put

.. include:: requirements.txt
   :literal:

And it would put the contents of the requirements.txt file into the rendered readme page.

[jm]

I doubt this will ever be re-enabled for security reasons, but I will let someone else make that final call. :)

[jaredly]

hmmm so would there need to be a change to docutils to allow restrictions? for example -- only include documents in the current directory or lower?

[TimidRobot]

It would be very helpful to be able to include LICENSE, requirements.txt, etc.

[hit9]

I also meet the same problem to include codes from sample/codes to my readme.rst. I think this feature will be very helpful

[thomas-scrace]

I also think this would be a very useful feature. For example, it is convenient to store a DESCRIPTION.rst file in repositories that use python's distutils so that it can be read into setup.py as the long_description argument. But of course, the description also wants to be in README.rst, so at the moment one is forced to duplicate the same material in two places, which is annoying.

[ncalexan]

Seconding what @jabapyth suggested: include only files in the current directory or lower. I just reworked my project's documentation to include the relevant pieces, only to find it doesn't show up at all. Thanks for that, @github. Some indication such as links to included files or even just a mention that pieces are missing would go a long way.

[gvangool]

Enabling it for other .rst files would also help (in my case)

[itsjohncs]

I would also like to see this implemented. I'd like to include code examples in my README without having to copy and paste them or include my README in my build system.

[mojavelinux]

We have the same limitation in AsciiDoc files. I'd like to see a unified way to provide an include hook in markup so that GitHub can handle the intent to include the file as they see fit. Surely it's okay to combine files, they would just like to be able to load them in dedicated code for reasons of security, caching and other such reasons. Can we discuss this possibility?

[kaystrobach]

any news on that?

[Seraf]

Hello, same problem here. I would like to use include to avoid duplicating information (and forget to update it somewhere)

[artob]

Just encountered this problem myself. It seems that for the time being content just has to be duplicated verbatim into the README file, which is pretty unfortunate and not very maintainable in the long run.

[kaystrobach]

but you can link documents :D -> this way you can store the docs in documentation and link to the rst from the readme :D

[fgmacedo]

any news on that? +1

[peterjc]

Here's the matching issue on BitBucket https://bitbucket.org/site/master/issue/5411/restructuredtext-include-directive which is clearly marked as WONTFIX due to security concerns.

I would like to be able to use this for embedding sample scripts (and perhaps their output) within documentation. The ideas above about restricting this to only include files in the current or sub-directories sound like a reasonable compromise.

[mojavelinux]

Given that the set from which includes are drawn is well known, the git
repository, I can't see how this is a security issue. Assuming there is a
hook to resolve the directive, you don't even have to involve raw
filesystem access. I think it's a great opportunity to demonstrate a usage
of git on GitHub itself.

[kaystrobach]

i think using include inside one repo should be possible, this way documentation can be easily structured, and this would IMHO make github even more useable.

Think f.e. of TYPO3 CMS and NEOS, both require to have an file calles Documentation/Index.rst, but github needs an Readme.rst, so i would not need to duplicate content if i simply could use an include here 😄

[bkeepers]

For now, we're not going to allow any includes in any of our markup formats. There's just too much overhead to making sure that there are no security vulnerabilities in each of the markup formats we support.

Personally, I would love to be able to use them, but the idea of supporting it scares the bejesus out of me.

[jaredly]

:( Is there no way to just roll your own include directive that, for example, can only reference files in the same directory? Even that would be a huge leap forward.

[bkeepers]

That's probably an option that is more likely to happen than supporting the native includes for each format. I can't promise anything, but I'll look into it sometime.

[jaredly]

awesome thanks!

On 1/24/14, Brandon Keepers notifications@github.com wrote:

That's probably an option that is more likely to happen than supporting the
native includes for each format. I can't promise anything, but I'll look
into it sometime.

---

Reply to this email directly or view it on GitHub:
#172 (comment)

[ramnes]

That would be definitely awesome.

[simleo]

Any news on this? Duplication is the root of all evil :(

[bkeepers]

Sorry, no news. Our first priority is sandboxing markup rendering so even if there is a security vulnerability in one of these libraries, we don't have to worry about it having access to everything under the sun. I know our security team has been making some progress on it, but it's not their highest priority at the moment.

[ramnes]

Thanks for the heads up @bkeepers.

[simleo]

OK, thanks for the update

[eddiejaoude]

Almost 6months on, any news? I am keen to have markdown files include other markdown files.

👍

[yvaucher]

👍 to have at least include from same directory

[peralmq]

👍

[samuelgoto]

+1

[svetlyak40wt]

:(

[cdgriffith]

+1

[mralexgray]

+1

[imhoffd]

I don't personally see the security vulnerability of including another file of the same markup language.

+1