dotland icon indicating copy to clipboard operation
dotland copied to clipboard

Add support for org-mode readmes

Open GuiltyDolphin opened this issue 4 years ago • 4 comments

Currently there appears to only be support for markdown readmes. If you try to use any other readme (e.g., Org), then no readme file will be detected, and documentation will not be displayed.

I propose that the website support Org readmes. I know this is much less common than markdown, but I tend to write my readmes in Org and was caught out when I found that the readmes weren't being detected.

Relevant files:

  • https://github.com/denoland/deno_website2/blob/main/components/Markdown.tsx - this deals with most of the conversion to HTMl, and uses =marked= (https://marked.js.org/) to do the parsing.\
  • https://github.com/denoland/deno_website2/blob/0b3b183ba44fdf7555edafe958b93f84fd7671c3/util/registry_utils.ts - this contains functions such as findRootReadme and isReadme that will need updating

I think the main thing to decide upon is which org-mode parser to use. For example:

  • https://github.com/daitangio/org-mode-parser
  • https://github.com/mooz/org-js
  • https://github.com/glmxndr/orgjs (probably not this one)

etc.

I'm happy to have a shot at implementing this, but considering there are some choices to be had re: which parser to use, I would greatly appreciate input on which parser would be good to go with. Has anyone used any of these (or other) parsers in your own projects? How have you found them in terms of speed and ease of use? Any rules and regs on what sorts of packages Deno can import?

GuiltyDolphin avatar Jun 03 '21 08:06 GuiltyDolphin

mooz/org-js looks better to me. Bundle size is smaller (7kb) and it has no external dependencies. org-mode-parse depends on node.js native modules like fs and util. I think this isn't suitable for frontend usage.

ref: https://www.npmtrends.com/org-mode-parser-vs-org

kt3k avatar Jun 07 '21 05:06 kt3k

@kt3k Yep, mooz/org-js looks pretty good from a dependency standpoint. I do worry though that it hasn't been updated since 2015, so it might not keep up-to-date with new features in org.

We could potentially fork that and try and maintain it with new features of Org, but I don't know how much work this would be. I suspect it probably supports most features that would be wanted, but it would be ideal if there was a more up-to-date package.

GuiltyDolphin avatar Jun 07 '21 12:06 GuiltyDolphin

This one looks more maintained (and linked from the official website), https://github.com/orgapp/orgajs, the usage looks more complex than mooz/org-js though.

kt3k avatar Jun 07 '21 23:06 kt3k

That looks pretty good. I've got quite a bit of experience working with ASTs, so it shouldn't be an issue in terms of complexity. I think the main difficulty will be in rendering/styling, but I'm hoping I can (for the most part) make use of the markdown styling for that.

GuiltyDolphin avatar Jun 09 '21 10:06 GuiltyDolphin

Closing as due to system changes this is not possible anymore

crowlKats avatar Aug 25 '22 12:08 crowlKats