Support org-mode rendering (BB-7757)

Issue #6569 open
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 (97)

  1. Erik van Zijst

    I've raised an internal issue for this (in all honesty an despite the competition, I'm not sure this will get top priority).

  2. Dylan Etkin

    We rely on pygments. We update pygments fairly often so if they add support for this we should get it.

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

  4. 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".

  5. Erik Post

    Me too! It would even help if BB just recognised files named 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."

  6. Victor Oliveira Nascimento

    Yes! This would help a lot!

    If you have at least one Emacs user in the company, there is a 150% probability he uses org-mode.

  7. Rusi Mody

    I gather that whats holding this up is something to do with pygments. Can someone enlighten what exactly?

  8. Mateusz

    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.

  9. 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!

  10. 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?

  11. Jules Tamagnan

    I know a few other people who would love this feature! At least one person I know has moved to gitlab because of this.

  12. 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. :(

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

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

  15. Christian Ridderström

    I sent in a support request (as we're paying customers) explaining in some details how I'd tried (extensively) to use markdown + bitbucket for documents that were non-trivial. This ended up in them creating a new ticket here: Perhaps these issues should be linked, or people should add comments there.

  16. Zachary Davis Account Deactivated

    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

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

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

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

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

  21. 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: 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:

  22. Christian Romney

    Wow, that's great. I was completely unaware of this capability. I'll have a closer look. Thanks for the response.

  23. Peter Schmiedeskamp

    At the very least, could you display the raw text of a 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 😀

  24. Former user Account Deleted


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

  25. Nyameko Lisa


    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 to

    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.

  26. César García Sáez

    I moved to Gitlab a few months ago and it's refreshing to see it works out of the box.

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

  28. honmaple

    I write a package named org-python to convert org-mode to html, it's not perfect but I think it's enough to parse there any considering to add org-mode support?

  29. Malcolm Cook

    hello fellow org-mode aficionados....

    Lacking the feature we are requesting here, I currently use emacs to export to html, and then use Pages for Bitbucket Server to serve the page statically from BitBucket.


    • It works pretty well
    • You get the exact html as exported by org, respecting any configuration options you may prefer (code high-lighting, pygments, etc)


    • I have found and reported a few bugs already.

    FWIW: I have myself configure an Apache web-server to render .org documents on the fly (using a pandoc filter) and am generally dis-satisfied. I expect if we get what we're asking for in this issue, you will find that you really want to control all the .org-mode bells & whistles anyway.

    I earlier +1ed this item, but am having 2nd thoughts about the true value.

  30. Alejandro Barocio

    +1 to org-mode support.

    README files should be as flexible as possible.

    Org-mode files are quite readable per se, so the option to simply add .org extension to be rendered as plain text files will be acceptable.

    Yet a limitation on the format selected for such a simple thing as a README file (for over 4 years now), sounds more like the developers not only don't like org-mode, but actually had something against it. (Is it the case?)

    Org-mode is a text based system, not only a format. Yet it has a format that is quite simple and structurated. And the system part of its implementation is not needed for rendering. If we (the users) had to make our own rendering by ourselves to something that machine-side thing (that, again, the competition already has), it is a productivity down-side to use this product.

    Yet, since most of us use org-mode in a daily baisis, we might be content to the use of plain text rendering. But since many developers use this README file to comunicate ideas to other people, such file should render in a more reader-friendly than just an outline full of asterisks.

    Here is my resumee:

    • Many developers already use it.
    • Generating a supported rendering (thinking on Markdown as a rendering is weird) is a down side to productivity.
    • Most of the REDAME readers will rather a more human-friendly render.
    • The rendering is possible and implemented by other systems.
    • In four years there has not be any implementation.

    My question would be: Wy not, Bitbucket?

  31. James Miller

    Yeah, it's a shame this isn't a thing. It couldn't take more than like, an hour of BB dev time to implement. Lots of libraries out there rendering org files. Github sure can do it. Gitlab too. Even Gitea and Gogs do it.

    PLEASE implement this. PLEASE PLEASE PLEASE.

  32. lunk djedi

    Content Please fix this. I like to review docs while in transit to the office, it would be nice if it was rendered and human readable. The implementation you have causes huge blocks of orange text anywhere there is a single apostrophe.

    Pattern After four years, the pattern of flippancy towards this request is comical. This pattern of inaction has caused to fall behind your competitors.

    Relationship Org mode is a way of life supported by all of your competitors. Syntaxes highlighting should be a simple library update. However, the pattern of inaction is starting to make me question why I stay in this relationship. I'm a VM and some cloud storage away from moving to your Lab competitor for private and your Hub competitor for public. Just because you can't render notes.

  33. Michael Kreikenbaum

    Relationship Org mode is a way of life supported by all of your competitors. Syntaxes highlighting should be a simple library update. However, the pattern of inaction is starting to make me question why I stay in this relationship. I'm a VM and some cloud storage away from moving to your Lab competitor for private and your Hub competitor for public. Just because you can't render notes.

    This might be the reason why people adopt gitlab instead of bitbucket.

  34. Alejandro Barocio

    OK. It's official.

    I'm moving to gitlab over this issue.

    Most of my work flow is based upon org-mode, and not having a decent rendering is not just an issue any more, precisely because there are options to that provide for my needs.

    Right now it has become embarrassing to trust my code to people who can't (or won't) make their code to work correctly over this issue for over five years. Not even an official comment on this, or a promise that it will work on the future. Shame on you,, and so long.

  35. Brian Carlson

    I've been watching this issue for a while. I write almost exclusively in Org-mode

    If you're moving from github because of the recent acquisition by Microsoft, I think it's worth pointing out that Atlassian is no more responsive than Microsoft. If org-mode is paramount to you then I recommend you move back to GitHub or GitLab.

    It's pretty obvious that Atlassian does not consider this to be anywhere close to important. It's marked as "low priority enhancment" .

    The most recent change was to remove an engineer from being assigned to the defect and to remove this bug from being associated with any component. So if you are "thinking of moving, but maybe I'll stay if Atlassian fixes this" -- then you should move onwards and upwards.

  36. Danny Freeman

    I'd love to see some action on this. Even some basic syntax highlighting for ORG mode would be nice.

  37. Nicolas Cavigneaux

    To all of you. I think it will never happen. I’m following this issue for years (litteraly) and nothing, NOTHING. They are ignoring this issue that is damn simple to solve. I’m losing faith. Too bad since bitbucket is such a great code hosting platform

  38. Former user Account Deleted

    As a steady org-mode user, I would love to see this happen too.

    And I really hope, there are no reservations against org-mode at atlassian: While the system org-mode (a major-mode in emacs) can be viewed as a single-user alternative to Jira, nothing similar can be said about the markup-language ! (Which is the point beeing discussed here.) So adding support for the markup would give users more options without endangering the jira-business in any way.

  39. Samuel Franklin

    +1 for this, if Atlassian will pay any attention to 90+ comments. I'm stuck with Bitbucket due to work, but if and when I have control over picking repository options, that Bitbucket lacks a simple functionality provided by other services will be a deal breaker. I'd change to a repository allowing .org file markup in a heartbeat.

  40. Dušan Maliarik

    In 6 years you weren't able to add this, with this many comments. Speaks of where Atlassian is going... I wish my company would use github or gitlab.

  41. Kent Johnson

    It seems the greatest argument in favor of scheduling this issue in is capturing the market share of all the dedicated, likely above-average in programming skill and evangelism attributes, engineers who will no doubt drive adoption of Bitbucket with their friends if the platform properly supports Org mode.

    I hope to see this feature added soon, especially since GitHub has added free private repositories, which is the main reason I switched to Bitbucket in the first place. I have had a very good experience with Bitbucket so far and would love for that to continue.

  42. Log in to comment