I learned from How to embed external file contents in org file? about including contents from another file into the org file. I tried that for my README.org. My code in org file looked like this:

#+INCLUDE: "~/.emacs.d/init.el" src emacs-lisp :lines "2-20"

This indeed worked when I export the org file into html, looked very neat and even have syntax highlighting. However, when I upload the README into Github and try to view it in my Github project homepage's README area, the entire section of code disappeared.

I wish to be able to function like BEGIN_SRC emacs-lisp, so that I am able to view the chunk of code within README. How can I do this?

  • This is a question about Github, not Emacs. I don't think Github supports includes, but you should check their help pages to find out for sure. – db48x Mar 13 '19 at 19:45
  • Nothing useful here. help.github.com/en/articles/about-readmes – Matthew Zeng Mar 13 '19 at 19:56
  • Github supports org file for README, supports BEGIN_SRC and END_SRC but doesn't support INCLUDE, this sounds kinda absurd – Matthew Zeng Mar 13 '19 at 19:59
  • I'm not going to make any promises about the quality or thoroughness of GitHub's help files. – db48x Mar 13 '19 at 20:01
  • I had exactly the same thought - just referencing a feature request I've made on the underlying Ruby library GitHub uses: github.com/wallyqs/org-ruby/issues/75 – Phil Mar 28 '20 at 17:34

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.


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!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.