Using org-mode instead of markdown

[seanfarley]

Since we're discussing writing documentation, would it be possible to use org-mode instead of markdown? I suggest this because the current use of markdown is almost the same syntax as org-mode BUT org-mode allows so much more power (not to mention org-mode is a better fit for emacsen 😄)?

[cxxxr]

Yes, it seems to be supported by github and may be a motivation to support org-mode to lem 👍

[vindarel]

I would warn about this move. Org-mode is poorly supported by Github (for example, we can't inline html, so we can't have images with custom size and height, and it limits the overall possible shapes of the README) (and it is not yet supported by Lem). In many cases, for projects hosted on Github, I have in the past preferred to convert org-mode documents to markdown. They look better, it is less hassle.

[seanfarley]

for example, we can't inline html

That's not really true and can be achieved with #+html: lines. You can see my conversion of Doom Emacs' README.md to README.org which, in my opinion, has very fancy formatting and looks great.

In general, I really, really don't like choosing a document's format based on GitHub's ability. All the deficiencies of GitHub's org-mode support can be worked around (at least in all the times I've needed to do such a thing) plus org-mode enables so many wonderful things that we could do with generating documentation within lem!

[vindarel]

ah, you make a point, thanks for sharing.