Introduction

This page provides a comprehensive reference for org-mode syntax and how it renders in Org-Press. Org-mode is a markup language similar to Markdown but with more powerful features for literate programming, task management, and document structuring.

Why Org-Mode?

• Hierarchical structure with unlimited heading levels
• Literate programming support with :tangle and code execution
• Rich metadata support via properties and drawers
• Powerful linking system for internal and external references
• Table support with calculations and formulas
• Extensible with custom block types and exporters

Document Structure

Document Metadata

Org files begin with metadata keywords:

#+TITLE: Document Title
#+AUTHOR: Author Name
#+DATE: 2025-12-09
#+DESCRIPTION: Brief description
#+KEYWORDS: keyword1, keyword2
#+LANGUAGE: en
#+LAYOUT: default

Headings Hierarchy

Headings are created with asterisks:

#+begin_export html <pre><code>* Level 1 Heading

Level 2 Heading

Level 3 Heading

Level 4 Heading

Level 5 Heading

Level 6 Heading

</code></pre> #+end_export

Each heading can have:

• TODO states (TODO, DONE, HOLD, etc.)
• Tags (:tag1:tag2:)
• Properties (in a :PROPERTIES: drawer)
• Priority ([#A], [#B], [#C])

Heading with All Features

** TODO [#A] Important Task :work:urgent:
SCHEDULED: <2025-12-10>
:PROPERTIES:
:ID: unique-task-id
:CUSTOM_ID: my-task
:END:

Task description goes here.

Text Markup

Inline Formatting

Special Symbols

Line Breaks and Paragraphs

• Single newline: Continues same paragraph
• Double newline: Creates new paragraph
• \\ at end of line: Forces line break

This is one paragraph.
Still same paragraph.

This is a new paragraph.\\
This is a new line in same paragraph.

Lists

Unordered Lists

Bullet lists use -, +, or * at line start:

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

Ordered Lists

Numbered lists use 1., 1), a., or a):

1. First item
2. Second item
   1. Sub-item A
   2. Sub-item B
3. Third item

Checkbox Lists

Task lists with checkboxes:

- [ ] Unchecked item
- [-] Partially checked (indeterminate)
- [X] Checked item

Description Lists

Definition lists use :: separator:

- Term :: Definition of the term
- Another term :: Its definition
                  can span multiple lines

Links

Link Syntax

General link format: [[target][description]]

Internal Links

[[*Heading Name][Link to Heading]]
[[#custom-id][Link to Custom ID]]
[[file:other-file.org][Link to Other File]]
[[file:other-file.org::*Heading][Link to Heading in Other File]]

External Links

[[https://example.com][Website Link]]
[[mailto:user@example.com][Email Link]]
[[file:/path/to/file.pdf][PDF Link]]

Bare URLs

Plain URLs are auto-linked:

• https://example.com
• user@example.com

Image Links

[[file:image.png]]
[[https://example.com/image.jpg][Image Description]]

Tables

Basic Table Syntax

Tables use | for columns and |- for separator rows:

| Header 1 | Header 2 | Header 3 |
|----------+----------+----------|
| Cell 1.1 | Cell 1.2 | Cell 1.3 |
| Cell 2.1 | Cell 2.2 | Cell 2.3 |

Table Alignment

Use <c>, <l>, or <r> for column alignment:

|        |        |        |
| Centered  | Left      |     Right |
|-----------+-----------+-----------|
| Data      | Data      | Data      |

Table Formulas

Org tables support spreadsheet-like formulas:

| Item   | Quantity | Price | Total |
|--------+----------+-------+-------|
| Apples |        3 |  1.50 |  4.50 |
| Oranges|        2 |  2.00 |  4.00 |
|--------+----------+-------+-------|
| Total  |          |       |  8.50 |
#+TBLFM: $4=$2*$3::@>$4=vsum(@2..@-1)

Source Code Blocks

Basic Syntax

#+begin_src language
code goes here
#+end_src

Block Parameters

Common parameters:

Named Blocks

Blocks can have names for referencing:

#+NAME: block-name
#+begin_src javascript
// code here
#+end_src

Block Import

Import named blocks from other files:

#+begin_src javascript
import func from "file.org?name=block-name";
#+end_src

Special Blocks

Quote Blocks

#+begin_quote
This is a quoted passage.
It can span multiple lines.
#+end_quote

Example Blocks

Verbatim text without formatting:

#+begin_example
Plain text here
No formatting applied
#+end_example

Verse Blocks

For poetry with line breaks preserved:

#+begin_verse
Roses are red,
Violets are blue,
Org-mode is great,
And so are you!
#+end_verse

Center Blocks

Centered content:

#+begin_center
Centered text
#+end_center

Custom Blocks

You can define custom blocks:

#+begin_custom_block_name
Content inside custom block
#+end_custom_block_name

Drawers

Syntax

Drawers store metadata and collapsible content:

:DRAWER_NAME:
Content inside drawer
:END:

Properties Drawer

Special drawer for metadata:

:PROPERTIES:
:ID: unique-id
:CUSTOM_ID: custom-id
:CREATED: [2025-12-09]
:CATEGORY: category-name
:END:

AI Conversation Drawer

In Org-Press, :AI: drawers render with 🤖 emoji:

:AI:
User: Question here
Assistant: Answer here
:END:

Important: Drawers must be under a heading, not at document root level.

Comments

Line Comments

Lines starting with # are comments:

# This is a comment
# It won't be exported

Block Comments

Multi-line comments:

#+begin_comment
Everything in here
is a comment
#+end_comment

Inline Comments

Inline comments (not exported):

Some text @@comment:hidden comment@@ more text

Macros and Includes

Define Macros

#+MACRO: name replacement text $1 $2

Use macro:

{{{name(arg1, arg2)}}}

Include Files

Include content from other files:

#+INCLUDE: "file.org"
#+INCLUDE: "file.org" src javascript
#+INCLUDE: "file.org" :lines "1-10"
#+INCLUDE: "file.org" :only-contents t

Export Settings

Global Export Options

#+OPTIONS: toc:nil num:nil
#+OPTIONS: timestamp:nil author:nil
#+OPTIONS: ^:nil  (disable subscript/superscript)

Per-Heading Export

Tags affect export:

#+begin_export html <pre><code>** This heading will not be exported :noexport:

This and all children exported to separate file   export_file_name

</code></pre> #+end_export

Advanced Org-Press Features

Layout Selection

Choose page layout via #+LAYOUT keyword:

#+LAYOUT: default
#+LAYOUT: kanban
#+LAYOUT: custom-layout-name

Block Plugins

Org-Press supports plugins for specialized rendering:

JSCad (3D CAD)

#+begin_src javascript :use jscad
import { cube } from "@jscad/modeling/primitives";
export default [cube({ size: 10 })];
#+end_src

Excalidraw (Diagrams)

#+begin_src json :use excalidraw
{"elements": [...]}
#+end_src

Rendering Modes

Customize code/result presentation:

#+begin_src javascript :use dom | withSourceCode
// Show both code and results
#+end_src

#+begin_src javascript :use sourceOnly
// Show code only, no execution
#+end_src

Server-Side Execution

Execute code during build:

#+begin_src javascript :use server
// This runs on server during build
const fs = require('fs');
return fs.readdirSync('./content').join(', ');
#+end_src

Code Tangling

Extract code to external files:

#+begin_src javascript :tangle src/generated.js
// This code will be written to src/generated.js
export function hello() {
  return "Hello from tangled code!";
}
#+end_src

Tips and Best Practices

Organization

• Use hierarchical headings for clear structure
• Add IDs to headings for stable links
• Use tags to categorize content
• Store metadata in PROPERTIES drawers

Literate Programming

• Name reusable code blocks with #+NAME:
• Use :tangle to generate source files from documentation
• Use :use server for dynamic content generated at build time
• Use :use dom | withSourceCode for interactive examples

Performance

• Use :use sourceOnly for display-only blocks (no execution)
• Server execution runs once at build time (faster than browser)
• Cache expensive computations in named blocks

Maintainability

• Keep each org file focused on one topic
• Use #+INCLUDE: to reuse content
• Define commonly-used text as macros
• Add comments to explain complex structures

Reference

Complete Example File

See Also

• Comprehensive Rendering Examples
• Block Plugins Reference
• Configuration Guide
• Official Org-Mode Manual