spike-leung / org-to-markdown

org mode to markdown/mdx

org-to-markdown

An org-mode to markdown/mdx converter. Uses orgajs for all the heavy lifting.

Has the following features not found in other converters;

1. MDX support. You can use jsx, import, and export statements!
2. code blocks with info strings and parameters, e.g js repl
3. Compatible with the unified ecosystem (because of orgajs). Want to combine this with remark plugins or mdx plugins? No problem!
4. JS ecosystem support. Currently a webpack loader and next plugin is available.

Installation/Usage

There is a cli, a library, a webpack loader, and next plugin available.

Syntax

To write jsx use begin_export blocks. These blocks become jsx, import, export and elements. Here is an example:

#+begin_export import
import { ReactComponent } from "unicorns-are-awesome";
#+end_export

** An org doc

#+begin_export jsx
<ReactComponent />
#+end_export

A code block with info strings

#+begin_src javascript repl
// gets a repl 
const unicorns = "are awesome!";
#+end_src

CLI

You can install and use the cli using npx. The tool takes org via stdin and outputs to stdout:

$ npx org-to-markdown < Unicorns.org > Unicorns.md

The mdxast and the mdast are compatible so if you want to use mdx you just need to use only need to change the file ext:

$ npx org-to-markdown < Unicorns.org > Unicorns.mdx

Library

The library exports a convert function, you can use it like this:

const orgToMarkdown = require("org-to-markdown");
const orgString = `
* Org file 

- List of stuff
- unicorns
`;

(async () => {
  const md = await orgToMarkdown(orgString);
  console.log(md);
}); 

Using in Unified

Things are built on two unified compatible libraries; orga-remark and mdx-stringify. You can use the orga-remark plugin to convert the orga ast (oast) to mdxast and mdx-stringify to stringify the mdxast. Here is an example:

const unified = require("unified");
const parse = require("orga-unified");
const getStdin = require("get-stdin");
const orgaToRemark = require("orga-remark");
const stringify = require("mdx-stringify");

(async () => {
  const s = await getStdin();
  const md = await unified()
    .use(parse)
    .use(orgaToRemark)
    .use(stringify)
    .process(s);

  console.log(md.contents);
})();

Webpack

You can install the webpack loader like this:

$ npm i @mdx-js/loader orga-loader

And use it like this

module: {
  rules: [
    { test: /\.org?$/,
      use: [
        'babel-loader',
        '@mdx-js/loader',
        'orga-loader'
      ]
    },

    // ...
  ]
}

Then you can import your org file:

import React, { Component } from 'react'
import Document, { frontMatter, tableOfContents } from './document.org'

export default class Something extends Component {
  render() {
    return (
      <div>
        <h1>{frontMatter.title}</h1>
        <Document />
      </div>
    )
  }
}

Next

There is a next plugin next-orga for usage instructions see its docs

Planned Features

• Gatsby support
• Parcel support
• Drawer support. (maybe some sort of conversion to html attributes)

Is this useless?

It is mostly useless :)

License

Licensed under ISC. © K-2052