Chapter 3: Document Structure - The Art of the Outline

We’ve established that asterisks create headings:

#+begin_example

This is the heading body. Everything until the next heading belongs to this section. #+end_example

Let’s break this down:

• * - The level indicator
• TODO - A state keyword (we’ll cover this deeply in Chapter 6)
• Write documentation - The heading text itself
• :work:urgent: - Tags (Chapter 7)
• SCHEDULED: - A planning keyword with timestamp
• :PROPERTIES: - A property drawer with metadata
• The body content below

Each component is optional. A heading can be just * Simple or a metadata-rich container. The choice is yours.

Org-Mode supports rich text formatting using simple markup:

*bold text*
/italic text/
_underlined text_
=verbatim text= (displayed in monospace)
~code~ (also monospace)
+strikethrough text+

When Org-Mode displays these, they render beautifully, but open the file in any text editor and it’s still human-readable. This is the plain-text philosophy in action.

Org-Mode has sophisticated list support. Simple to start, powerful when you need it.

• Milk
• Eggs
  • Free range if possible
  • Brown eggs preferred
• Coffee
  • Dark roast
• Bread

#+end_example

Start a line with -, +, or * (if not at the start of the line) to create a list item. Press M-RET on a list item to create another at the same level.

1. Preheat oven to 350°F
2. Mix dry ingredients
   1. Flour
   2. Sugar
   3. Baking powder
3. Add wet ingredients
4. Bake for 25 minutes

#+end_example

Org-Mode automatically renumbers lists when you add or remove items. Move an item with M-up/down and the numbers update automatically. It’s the little things.

git add

Stage changes for commit

git commit

Save staged changes to history

git push

Send commits to remote repository

git pull

Fetch and merge remote changes

#+end_example

The :: separator creates description lists—perfect for glossaries, definitions, or any term/description pairs.

• [ ] Design mockups
• [ ] Get client approval
• [X] Set up development environment
• [ ] Write tests
• [ ] Implement features
  • [X] User authentication
  • [ ] Dashboard
  • [ ] Reports
• [ ] Deploy to staging

#+end_example

[ ] creates an unchecked box, [X] is checked. Press C-c C-c (Control-c twice) on a checkbox to toggle it.

The magic: parent items show completion statistics:

#+begin_example

• [ ] Task 1
• [X] Task 2
• [ ] Task 3
• [ ] Task 4
• [ ] Task 5

#+end_example

Or as a percentage:

#+begin_example

#+end_example

Add [/] or [%] after the heading text, and Org-Mode calculates it automatically when you toggle child checkboxes. This is phenomenal for tracking progress in nested task lists.

You’ve learned the basic movement commands. Let’s expand your toolkit.

Drawers are collapsible sections for metadata that you don’t need to see all the time:

#+begin_example

The actual meeting notes go here. #+end_example

The :PROPERTIES: drawer stores key-value pairs. The :LOGBOOK: drawer (auto-created) stores notes and state changes. Press TAB on a drawer to collapse/expand it.

You can create custom drawers too:

#+begin_example

• https://docs.example.com
• https://github.com/example/repo

#+end_example

Blocks are regions with special formatting or behavior:

Sometimes you need notes that don’t export:

#+begin_example

This exports.

This also exports. #+end_example

You can also comment entire subtrees:

#+begin_example

Org-Mode has first-class footnote support:

#+begin_example The Org-Mode manual¹ is comprehensive but dense. Some prefer community guides² for learning.

Sometimes you need a visual separator:

#+begin_example

Content here.

More content. #+end_example

Five or more dashes on a line creates a horizontal rule.

Documents grow. Eventually you’ll want to move completed or outdated items without deleting them:

#+begin_example

Here’s a killer feature: sparse trees let you filter your document to show only matching items.

• C-c / r - Show headings matching a regexp
• C-c / t - Show TODO items
• C-c / p - Show items with specific properties
• C-c / T - Show items with specific tags

The document folds to show only matches and their context. Everything else disappears. When you’re done, C-c C-c clears the sparse tree.

Working on a specific tag across a 5000-line document? Sparse tree it. Need to see all TODO items? Sparse tree. This feature alone justifies the plain-text approach.

Here’s the thing about outlines: there’s no “correct” structure. Some people organize by project. Others by time (daily/weekly notes). Some by area of responsibility. Many combine approaches.

Org-Mode doesn’t care. It provides the tools; you provide the structure. Experiment. Reorganize. Your .org files should evolve as you do.

Create a document that uses:

1. At least three levels of headings
2. Both ordered and unordered lists
3. A checkbox list with nested items
4. A few formatted text elements (bold, italic, code)
5. At least one block (quote, example, or code)
6. A comment that won’t export
7. Practice using sparse trees to filter your content

Play with structural editing. Move things around. Feel the outline become an extension of your thought process.

You’ve mastered document structure. In the next chapter, we’ll tackle one of Org-Mode’s most surprisingly powerful features: tables that act like spreadsheets, all in plain text. You’re going to love it.