Convert ORG to Markdown

Why Convert ORG to Markdown?

Converting Org-mode files to Markdown is essential when you need to share your content beyond the Emacs ecosystem. While Org-mode is an incredibly powerful format for personal productivity, project management, and literate programming within Emacs, Markdown is the universal standard for plain-text content on the web. GitHub, GitLab, Stack Overflow, and virtually every documentation platform render Markdown natively, making it the ideal format for published content.

Org-mode, created by Carsten Dominik in 2003, uses asterisk-based headings, slash-delimited emphasis, and a rich set of keywords for TODO items, timestamps, and properties. Markdown, created by John Gruber in 2004, takes a simpler approach with hash-based headings, asterisk emphasis, and minimal syntax. The conversion maps Org headings (* Heading) to Markdown headings (# Heading), Org emphasis (*bold*, /italic/) to Markdown emphasis (**bold**, *italic*), and Org links ([[url][text]]) to Markdown links ([text](url)).

Some Org-mode features, such as TODO states, scheduling timestamps, property drawers, and executable code blocks (Babel), do not have direct Markdown equivalents. During conversion, TODO keywords are typically preserved as text labels, timestamps may be included inline, and code blocks are converted to fenced code blocks. Tables are translated from Org pipe-based syntax to Markdown pipe-based syntax, though Org's formula support is not carried over.

The conversion is particularly valuable for publishing Org-mode notes as documentation, sharing project README files on GitHub, migrating content to static site generators like Hugo or Jekyll, or collaborating with team members who do not use Emacs. Markdown's widespread adoption ensures your content reaches the broadest possible audience.

Key Benefits of Converting ORG to Markdown:

• Universal Compatibility: Markdown is rendered natively on GitHub, GitLab, Bitbucket, and countless platforms
• Wider Audience: Share content with people who don't use Emacs or know Org syntax
• Static Site Generators: Use your Org notes as content for Hugo, Jekyll, Gatsby, or Eleventy sites
• Documentation Publishing: Publish clean technical docs in the industry-standard format
• Tool Ecosystem: Access hundreds of Markdown editors, previewers, and processing tools
• Collaboration: Work with teams that standardize on Markdown for their workflows
• Version Control: Markdown diffs are clean and readable in Git pull requests

Practical Examples

Example 1: Project README Conversion

Input ORG file (README.org):

* MyProject
A lightweight HTTP server written in Python.

** Features
- Fast and asynchronous
- Zero external dependencies
- Built-in logging

** Installation
#+BEGIN_SRC bash
pip install myproject
#+END_SRC

** Usage
#+BEGIN_SRC python
from myproject import Server

app = Server(port=8080)
app.run()
#+END_SRC

** License
This project is licensed under the MIT License.

Output Markdown file (README.md):

# MyProject
A lightweight HTTP server written in Python.

## Features
- Fast and asynchronous
- Zero external dependencies
- Built-in logging

## Installation
```bash
pip install myproject
```

## Usage
```python
from myproject import Server

app = Server(port=8080)
app.run()
```

## License
This project is licensed under the MIT License.

Example 2: Technical Notes with Tables and Links

Input ORG file (notes.org):

* API Endpoints Reference
Documentation for the REST API.

** Status Codes
| Code | Meaning               | Action         |
|------+-----------------------+----------------|
|  200 | Success               | Process result |
|  401 | Unauthorized          | Re-authenticate|
|  404 | Not Found             | Check URL      |
|  500 | Internal Server Error | Retry later    |

** Authentication
All requests require a bearer token.
See [[https://docs.example.com/auth][Authentication Guide]] for details.

*** Example Request
#+BEGIN_SRC bash
curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/v1/users
#+END_SRC

Output Markdown file (notes.md):

# API Endpoints Reference
Documentation for the REST API.

## Status Codes
| Code | Meaning               | Action         |
|------|----------------------|----------------|
| 200  | Success               | Process result |
| 401  | Unauthorized          | Re-authenticate|
| 404  | Not Found             | Check URL      |
| 500  | Internal Server Error | Retry later    |

## Authentication
All requests require a bearer token.
See [Authentication Guide](https://docs.example.com/auth) for details.

### Example Request
```bash
curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/v1/users
```

Example 3: Task List and Structured Content

Input ORG file (tasks.org):

* Sprint 12 Planning
** TODO Refactor database layer
   DEADLINE: <2026-03-15 Sun>
   - [ ] Migrate to PostgreSQL
   - [X] Write migration scripts
   - [ ] Update connection pooling

** DONE Implement user authentication
   CLOSED: [2026-03-01 Sun 14:30]
   - [X] JWT token generation
   - [X] Login endpoint
   - [X] Password hashing

** Notes
   #+BEGIN_QUOTE
   Performance target: all API responses
   must complete within 200ms.
   #+END_QUOTE

   /Italic note/: see *bold reference* in =config.yaml=.

Output Markdown file (tasks.md):

# Sprint 12 Planning
## TODO Refactor database layer
DEADLINE: 2026-03-15

- [ ] Migrate to PostgreSQL
- [x] Write migration scripts
- [ ] Update connection pooling

## DONE Implement user authentication
CLOSED: 2026-03-01

- [x] JWT token generation
- [x] Login endpoint
- [x] Password hashing

## Notes
> Performance target: all API responses
> must complete within 200ms.

*Italic note*: see **bold reference** in `config.yaml`.

Frequently Asked Questions (FAQ)

Q: What is Org-mode format?

A: Org-mode is a plain-text markup format and a major mode for the GNU Emacs text editor. Created by Carsten Dominik in 2003, it uses a simple yet powerful syntax for outlining, note-taking, task management, time tracking, literate programming, and document authoring. Files use the .org extension and are structured with asterisk-based headings that form a collapsible outline hierarchy.

Q: Will my Org headings convert correctly to Markdown?

A: Yes. Org headings use asterisks (* Heading, ** Sub-heading) while Markdown uses hash symbols (# Heading, ## Sub-heading). The converter maps heading levels directly: one asterisk becomes one hash, two asterisks become two hashes, and so on. Both formats support up to six heading levels, so all your document structure is preserved.

Q: What happens to Org TODO items during conversion?

A: TODO keywords (TODO, DONE, IN-PROGRESS, etc.) are preserved as text labels in the Markdown output. For example, ** TODO Fix bug becomes ## TODO Fix bug. Org checkbox lists (- [ ] and - [X]) convert directly to GitHub Flavored Markdown task lists, which render as interactive checkboxes on platforms like GitHub and GitLab.

Q: Are Org code blocks converted to Markdown fenced code blocks?

A: Yes. Org source blocks (#+BEGIN_SRC language ... #+END_SRC) are converted to Markdown fenced code blocks with triple backticks and language identifiers (```language ... ```). The language tag is preserved so syntax highlighting works correctly on platforms like GitHub. Inline code marked with =code= or ~code~ in Org is converted to backtick-delimited `code` in Markdown.

Q: How are Org tables handled in the conversion?

A: Org tables and Markdown tables both use pipe-based syntax, so the structure translates naturally. The main difference is that Org uses |---+---| separator rows while Markdown uses |---|---|. Org's column alignment and formula features (using #+TBLFM) are not supported in Markdown, so formulas are dropped during conversion. The table data and alignment are preserved.

Q: What Org features are lost in Markdown conversion?

A: Some Org-specific features have no Markdown equivalent. These include: property drawers (:PROPERTIES: ... :END:), scheduled and deadline timestamps, clock entries, tags on headings (e.g., :tag1:tag2:), table formulas, column view, agenda integration, and Babel code execution results. The converter preserves as much content as possible, but interactive and Emacs-specific features are simplified or omitted.

Q: Can I convert Markdown back to Org format?

A: Yes, you can convert Markdown to Org using our converter or tools like Pandoc. However, converting ORG to Markdown and back may not produce an identical result because Org-specific features (TODO states, properties, timestamps) that were lost during the initial conversion cannot be restored. For round-trip workflows, consider keeping a master copy in Org format and exporting to Markdown as needed.

Q: Which Markdown flavor does the converter output?

A: The converter outputs GitHub Flavored Markdown (GFM), which is the most widely supported Markdown variant. GFM extends CommonMark with features like task lists, tables, strikethrough text, and fenced code blocks. This output works on GitHub, GitLab, Bitbucket, VS Code previews, most static site generators (Hugo, Jekyll, Gatsby), and virtually any platform that supports Markdown rendering.