Skip to content


Subversion checkout URL

You can clone with
Download ZIP


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

jaredly opened this Issue · 34 comments

The :include: restructuredtext directive ( looks like it's disabled at the moment.

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

.. include:: requirements.txt

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

jm commented

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


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?


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


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


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 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.


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.


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


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.


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?


any news on that?


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


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.


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


any news on that? +1


Here's the matching issue on BitBucket 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.


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 :smile:


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

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


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.


That would be definitely awesome.


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

@simleo simleo referenced this issue from a commit in galaxyproject/bioblend
@afgane afgane Add Travis CI and the pypi download count icons to the README f50df31

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.


Thanks for the heads up @bkeepers.


OK, thanks for the update


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

Initial stage of Definition of Done #5


:+1: to have at least include from same directory

@jsalva jsalva referenced this issue in binarybottle/mindboggle

uses .rst format for README #51


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


@dwieeb dwieeb referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
@bkeepers bkeepers locked and limited conversation to collaborators
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Something went wrong with that request. Please try again.