Display #+INCLUDE File Contents in Github README.org?

Github and Gitlab both use org-ruby to convert org syntax to markdown.

The #+INCLUDE: syntax is available in org-ruby but requires two environmental variables to be set at run time by the server administrators to to enable this functionality. See parser.rb#L102

  #
  # Include file feature disabled by default since 
  # it would be dangerous in some environments
  #
  # http://orgmode.org/manual/Include-files.html
  #
  # It will be activated by one of the following:
  #
  # - setting an ORG_RUBY_ENABLE_INCLUDE_FILES env variable to 'true'
  # - setting an ORG_RUBY_INCLUDE_ROOT env variable with the root path
  # - explicitly enabling it by passing it as an option:
  #   e.g. Orgmode::Parser.new(org_text, { :allow_include_files => true })
  #
  # IMPORTANT: To avoid the feature altogether, it can be _explicitly disabled_ as follows:
  #   e.g. Orgmode::Parser.new(org_text, { :allow_include_files => false })
  #

As a workaround, I also recommend exporting your original org file as a separate org file just as Michaël recommended. I use org to org exports everyday. I use the first org file as template to manage my projects. As an added benefit this allows me fine grained control over multiple documents, source code files and other file types as needed.

For some real life examples in order of increasing complexity, look at Literate DevOps common-project-files.org file, Literate Devops How to Migrate LaTeX Template into org-mode and the Atom editor org-mode package.

Thanks for asking your question!

Hope that helped!

I believe the best solution is to export to Org (export to MD can be faulty, or deficient). This can be done using the function org-org-export-to-org. You can then store your regular readme in, say, doc/README.org, and have it automagically export to ./README.org upon changes. That's the approach I followed for this repo.