Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

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

Closed
jaredly opened this Issue · 34 comments
@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
jm commented

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?

@TimZehta

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)

@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

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

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

@bkeepers
Owner

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
@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
Owner

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
@ramnes

That would be definitely awesome.

@simleo

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
@bkeepers
Owner

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.

:+1:

@eddiejaoude eddiejaoude referenced this issue in TransformCore/CSR-Fast-Stream-frontend
Merged

Initial stage of Definition of Done #5

@yvaucher

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

@jsalva jsalva referenced this issue in binarybottle/mindboggle
Closed

uses .rst format for README #51

@dwieeb

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

+1

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