1. Bitbucket
  2. Public Issue Tracker
  3. master
  4. Issues


Issue #6569 open

Support org-mode rendering (BB-7757)

William Stevenson
created an issue

Org-mode is "an Emacs Mode for Notes, Planning, and Authoring", it's pretty popular in the emacs and hence programmer community. Another git hosting provider also supports this format for readme files.

This should be supported when both browsing files and anywhere a README can be displayed.

Comments (69)

  1. Calvin Beck

    I would really like this feature as well. Github makes .org files extremely readable, which is quite nice... It makes me sad that it doesn't get correct syntax highlighting on Bitbucket :(. Random sections in the middle are made orange (from apostrophes, so if I type "it's" everything gets messed up). It makes me wish it didn't try to do syntax highlighting at all :P. Ah well, hopefully it gets better.

  2. Priyadarshan

    All of our documentation is in org-mode. Unfortunately, we are compelled to use the "other git hosting provider" for those repos where a clear display of such files is indispensable. It is a pity that a useful feature is not satisfied only becasue "a component of the toolchain (pygments) does not support it".

  3. Erik Post

    Me too! It would even help if BB just recognised files named README.org as plaintext readmes, instead of showing a rather forbidding page saying "There isn't a README yet. Create one and tell people where to start and how to contribute."

  4. Mateusz Kaduk

    Would be nice to have at least one reasonable document format supported by bitbucket and org-mode would be best of all (Not this horrible implementation of Markdown with spaces). Shame that github not only has better Markdown but also org-mode is supported. If I wouldn’t care about private repository I would use github for all my stuff.

  5. Albert Huang

    Recently I am happy to find that github directly supports orgmode, and I almost switch there because of this. But I already have a lot of code/text in BB, and I need the private repo as well. I strongly suggest BB to raise the priority of this task. Thank you very much!

  6. Tom Roche

    @Rusi Mody: "I gather that [what's preventing Bitbucket wikis from rendering org-mode has] something to do with pygments."

    I'm not sure about that, and would also appreciate enlightenment. Please correct me where wrong, or add what I'm missing:

    1. GitHub wikis render with Gollum.
    2. Gollum does highlighting with Pygments if that's installed.
    3. Gollum supports org-mode.

    So if Pygments (which appears to be hosted on BB!) prevents BB's wikis from rendering org-mode, then why doesn't Pygments prevent GH's wikis from rendering org-mode?

  7. alphapapa

    Three years, still no org? Even GitLab has it. I'd like to try hosting some of my repos on Bitbucket, but it's not worth giving up Org-mode support. :(

  8. Rolando Abarca

    As a workaround, you can turn orgmode for text-only readme, if you add something like this at the top:

    README -*- mode: org -*-
    * My Project
    ... etc

    That way at least bitbucket won't complain that there is no readme in the repo.

  9. Andrew Davis

    I agree with alphapapa that this is pretty pathetic. I am migrating everything away from Bitbucket now predominately because of this issue. It is unfortunate as this has been my primary repo of choice. It's been fun.

  10. Zachary Davis

    Thanks Christian. I don't think it makes sense to have both tickets open, so I've marked #13193 as a duplicate of this one. The description for that issue states:

    Problem Definition

    It is hard to write simple documents (formatted a little better than just plain text) which content can be version controlled and rendered in the bitbucket repo browser.

    Below are the feedback based on customer's experience:

    • Markdown is not good enough, e.g. to easy to make mistakes that do not render properly. (E.g. that an empty white line is needed between a paragraph and a bullet item).
    • It's fragile to maintain user's local render system and to make it render the same way the bitbucket repo browser renders things.

    Suggested Solution

    Emacs' has had the "org-mode" for quite some time and works beatifully. It will be great that Bitbucket Cloud will support it

  11. Christian Ridderström

    Zachary, please be adviced that 13193 contains a justification/rationale, which serve as reminder that there is more details I have provide in my original support ticket. By marking 13193 as duplicate you will in practice lose this.

    Further, the use case underlying 13193 can be solved without implementing support for org-mode. The issues are thus different. Christian

  12. Kaleb Elwert

    Christian, it sounds like #13193 may be missing some of the important information from your support request because as it currently stands, it seems to request the same thing as this ticket.

    I've updated this ticket a bit to be a little more general so it's clearer that "org-mode support" would include both readme and file browsing support.

  13. Christian Romney

    I would like to make a suggestion. Given that BitBucket is a proprietary system which feeds families, it makes sense to close the source. The only real downside to this is that people who would like to request features have to do so in threads like this one and use whatever verbal leverage they think might get the company to reconsider the low prioritization of the request. This leads to whining, hurt feelings, thinly (and not so thinly) veiled threats to adopt a competitor's product instead. In short, it brings out the worst in everyone and does zero to address the issue. I would respectfully submit for your consideration the following idea. Consider releasing an API specification and allow the community to contribute the org-mode syntax support. The code would have to be licensed in such a way as to allow you to use it without infecting the rest of your proprietary codebase. It would have to pass your internal review before consideration for inclusion. You could add any other stipulation you like. The benefits include providing an avenue for developers that really care about this feature, and that are inclined to contribute a solution, to get the feature they want at a very low cost to Atlassian. Of course, there is some cost to considering this issue and perhaps releasing an API spec and maybe performing a code review down the line (if this ever gets that far). This would also provide you with a fantastic PR opportunity, leveraged correctly...

  14. Andreas Tjärnberg

    I was under the impression that bitbucket used the pigments python library for formating code and Readmes. This is not a closed source product but the issue posted there about supporting org a while back has not been addressed yet.

  15. Kaleb Elwert

    Thanks for the comments!

    Andreas, we do use Pygments for source code highlighting, but not for READMEs.

    Supporting rendering of org-mode files is a bit of a larger challenge. Last I checked, I didn't see any good python libraries dealing with rendering org-mode. I'm not even sure if that's a good idea. org-mode is a very good elisp library, and it would make sense to use the built in export feature, however this is probably not something that will be worked on by the Bitbucket any time soon, outside a hackathon. This is something that would be nice to support, but it's not a very high priority.

    All this being said, believe it or not, there's already a way to build custom file views as connect addons. There have been amazing examples, like the ones seen here: https://blog.bitbucket.org/2015/12/29/file-viewer-for-bitbucket/ and building one for org files would definitely be possible by anyone with the time and resources to do so.

    For a good resource to get started with fileview addons, checkout "Run Bucket Run" here: https://developer.atlassian.com/blog/2015/10/bitbucket-fileview-addon/

  16. Peter Schmiedeskamp

    At the very least, could you display the raw text of a README.org file instead of making me feel bad every time I view a bitbucket repository? The subtle signaling of the frowning "no readme" just makes me feel bad about Bitbucket, and does not in any way deter me from using my beloved Emacs which is my closest friend and confidant 😀

  17. Richard Gomes


    Seems like this thread is becoming popular enough. I'm voting +1 just 7 hours after the previous vote.

    IMHO, the main selling point for org-mode is that a README.org file is not only documentation, but also a TODO list of things you haven't documented enough, or things you still don't understand enough, etc. So, you document not only things you know, but also things you don't know, in a very organized fashion. And you can assign priorities and deadlines to these items. And you can display these things you don't know as part of a consolidated agenda of all things you have to do.

  18. drliny


    Issue is over 4 years now, and still left open... Sigh.

    Not the end of the world however, just add

    (require 'ox-md nil t)

    to you init-file and then remember to export your README.org to README.md:

    C-c C-e m m


    M-x org-md-export-as-markdown

    This can be automated using a hook-script each time you save the file, but since its only needed for BitBucket repos, I do it manually.

  19. Fred Mitchell

    org-mode now, please. That other place is using a Ruby gem to render theirs, from what I understand. I am getting grief at my current place of employ over translating org-mode to markdown, because the conversion inserts HTML which you also don't support! Not to mention handling tables..... I can work around this, but I would rather need not to.

    If I were setting up a new startup, we'd be using that other guy you love so well. Sorry, guys, but this is a deal breaker for me in what is an otherwise excellent product.

  20. Log in to comment