README.rst :include: directive doesn't work #172

Closed
jaredly opened this Issue Dec 13, 2012 · 34 comments

Projects

None yet
@jaredly
jaredly commented Dec 13, 2012

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
jm commented Dec 13, 2012

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

@jaredly
jaredly commented Dec 13, 2012

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?

@TimZehta
TimZehta commented Feb 7, 2013

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

@hit9
hit9 commented Feb 9, 2013

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)

@brownhead

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
Collaborator

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
Seraf commented Jun 16, 2013

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

@bendiken

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
peterjc commented Jan 22, 2014

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
Collaborator

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
Member

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.

@bkeepers bkeepers closed this Jan 24, 2014
@jaredly
jaredly commented Jan 24, 2014

:( 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
Member

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
jaredly commented Jan 24, 2014

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
ramnes commented Feb 8, 2014

That would be definitely awesome.

@simleo
simleo commented Jul 24, 2014

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

@bkeepers
Member

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
ramnes commented Jul 24, 2014

Thanks for the heads up @bkeepers.

@simleo
simleo commented Jul 25, 2014

OK, thanks for the update

@eddiejaoude

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

👍

@eddiejaoude eddiejaoude referenced this issue in TransformCore/CSR-Fast-Stream-frontend Dec 19, 2014
Merged

Initial stage of Definition of Done #5

@yvaucher

👍 to have at least include from same directory

@jsalva jsalva referenced this issue in nipy/mindboggle Jan 28, 2015
Closed

uses .rst format for README #51

@peralmq
peralmq commented Feb 24, 2015

👍

@samuelgoto

+1

@svetlyak40wt

:(

@cdgriffith

+1

@mralexgray

+1

@dwieeb
dwieeb commented Apr 23, 2015

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

+1

@bkeepers bkeepers locked and limited conversation to collaborators Apr 23, 2015
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.