README.rst :include: directive doesn't work #172
Description
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.
Activity
jm commentedon 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 commentedon 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?
TimidRobot commentedon Feb 7, 2013
It would be very helpful to be able to include LICENSE, requirements.txt, etc.
hit9 commentedon 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 commentedon Feb 23, 2013
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 commentedon Mar 14, 2013
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 commentedon Apr 11, 2013
Enabling it for other
.rstfiles would also help (in my case)itsjohncs commentedon May 7, 2013
I would also like to see this implemented. I'd like to include code examples in my
READMEwithout having to copy and paste them or include myREADMEin my build system.mojavelinux commentedon May 10, 2013
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 commentedon Jun 13, 2013
any news on that?
Seraf commentedon Jun 16, 2013
Hello, same problem here. I would like to use include to avoid duplicating information (and forget to update it somewhere)
artob commentedon Aug 10, 2013
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 commentedon Aug 12, 2013
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 commentedon Aug 17, 2013
any news on that? +1
peterjc commentedon 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.
8 remaining items
ramnes commentedon Feb 8, 2014
That would be definitely awesome.
simleo commentedon Jul 24, 2014
Any news on this? Duplication is the root of all evil :(
Add Travis CI and the pypi download count icons to the README
bkeepers commentedon Jul 24, 2014
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 commentedon Jul 24, 2014
Thanks for the heads up @bkeepers.
simleo commentedon Jul 25, 2014
OK, thanks for the update
eddiejaoude commentedon Dec 19, 2014
Almost 6months on, any news? I am keen to have markdown files include other markdown files.
👍
yvaucher commentedon Jan 16, 2015
👍 to have at least include from same directory
peralmq commentedon Feb 24, 2015
👍
samuelgoto commentedon Mar 17, 2015
+1
svetlyak40wt commentedon Mar 29, 2015
:(
cdgriffith commentedon Apr 13, 2015
+1
mralexgray commentedon Apr 21, 2015
+1
imhoffd commentedon Apr 23, 2015
I don't personally see the security vulnerability of including another file of the same markup language.
+1