Markdown Bullets and Sub-Bullets: A Comprehensive Guide

Markdown is commonly used by writers, bloggers, note-takers, and developers to add lightweight formatting for web content. One of its most popular features is simple syntax for creating bulleted and nested outlines.

As a full-stack developer and technical writer, I utilize Markdown-powered outlines daily to structure documentation, tutorials, meeting notes, and more. The ability to quickly build nested bullet points helps rapidly map out content relationships.

In this comprehensive guide, we will dig deep into best practices for getting the most from Markdown lists and sub-lists.

Bulleted Lists vs Other Outliners

Outlining is the practice of organizing information into hierarchical groups to map conceptual relationships. Outliners simplify creating structure by providing easy ways to nest parent-child relationships.

Common types of outlining tools include:

• Word Processor Outlining – Office apps like Word, Google Docs, and Pages have built-in outline modes that use collapsible headings and preset hierarchy levels. These integrate outlining directly with document creation.

• Tree Diagram Software – Some tools are dedicated specifically to building tree charts and diagrams for visualization. OmniGraffle and MindNode are two examples that focus solely on flexible outlines.

• Markdown Lists – As we discuss here, Markdown uses simple text-based conventions like bullets, indentation, and blanks lines to denote hierarchy levels. This outlining is integrated directly into the writing flow.

The main advantage of Markdown list-based outlining compared to traditional workflow tools is tight integration with writing without added UI complexity. The simple syntax interleaves naturally with long-form writing content production.

Now let‘s explore how Markdown lists work under the hood.

Markdown List Syntax Fundamentals

To understand how to best utilize Markdown lists, it helps to know a little bit about the HTML markup that gets generated from the plain text source.

Unordered bulleted lists in Markdown get translated to HTML <ul> (unordered list) elements containing <li> (list item) children:

* First item
* Second item 

Becomes:

<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>  

Likewise, ordered numbered lists generate structured <ol> (ordered list) containers housing the list items:

1. First item
2. Second item

Converts to:

<ol>
  <li>First item</li>
  <li>Second item</li>  
</ol>

This simple mapping of Markdown conventions to HTML tags enables seamless rendering across websites, ebook readers, and HTML-based applications.

Now let‘s explore some common list use cases.

Use Cases for Markdown Lists

Thanks to flexible HTML representations, Markdown lists shine for organizing:

• Outlines – Bullets naturally denote hierarchies for outlines, reports, stories, etc. Nested indentations visualize conceptual relationships.

• Articles and Posts – Numbered steps work perfectly for tutorials, documentation, recipes. Streamlined syntax is easy to write.

• Meeting Notes – Quickly capturing notes and action items in bulleted lists captures information on the fly. Easy to scan later.

• Todo Lists – Task tracker extensions let you markup interactive checklists. Great for workflow management.

• Questionnaires – Definition lists allow pairing questions and answers. Ideal for self-serve interviews.

• Glossaries – Definition lists also work well for defining terminology. Useful in documentation.

For any concept involving words, lists provide generic containers to map linguistic relationships. Markdown simplifies authoring nested tree hierarchies as part of your core content.

Next let‘s dig deeper into techniques and best practices.

Constructing Nested List Hierarchies

Properly structuring list hierarchies is key for creating clear, scannable outlines in Markdown. Here are some techniques and principles for crafting semantic nested content.

Order Matters

With up to 6 levels of possible indentations, determining what order to present information comes first. Outline the topic children before diving into details – set the stage at higher levels before elaborating lower down.

I structure my outlines into groupings like:

1. Main topics
2. Supporting topics
3. Details on #2
4. More details on #3

Starting broad and progressively focusing each level creates strong information flows.

Scannability First

We read outlines by scanning for salient words and phrases instead of reading every word. Make skimmability easy through:

• Short 1-3 word nested list item titles
• Consistent parallel grammar constructions
• Brevity over verbosity

Review ensuring each line is easy to visually jump to and digest. Use copious white space between levels to guide the eyes.

Active Voice Lists

Outlines serve as writing scaffolds, so compose list items in active voice:

• Transform the verbs
• Streamline the flows
• Tighten the language

Doing so transfers cleanly when expanding into paragraphs for drafts.

Parallelism Consistency

Readers comprehend lists easiest when all items follow consistent parallel grammatical structure.

Bad example:

My car maintenance checklist

- Change oil 
- Checking tire pressure
- Clean interior thoroughly  
- Fill up the tank

The mixed verb forms (change vs checking vs clean vs fill up) make this scan oddly.

Better example with parallel structure:

My car maintenance checklist

- Change the oil
- Check tire pressure  
- Clean interior thoroughly
- Fill up the gas tank

Now the consistency flows smoothly to the eye.

Best Practices for Markdown Nesting

Beyond overall organization and content tips, utilizing consistent Markdown syntax helps reinforce information hierarchies:

Dedicate a Line Per Item

Give each distinct thought its own line:

Bad nested example:

* Clean sink
    * Scrub inside basin - scour outer surfaces

Here two related but distinct actions get squashed together losing visual clarity.

Better line separation:

* Clean sink
    * Scrub inside basin
    * Scour outer surfaces

Now each step exists independently.

Separate Levels with Blank Lines

Blank lines are significant in Markdown to delimit block-level elements. Apply them wisely:

• Add blank line after lowest nested items
• But not between upper nested levels

For example:

Good nesting practice  

* Top level
    * Nested item 1

    * Nested item 2

* Next top level thought 

Blank line only after the complete nested thought.

Indent Consistently With 4 Spaces

Align all list nesting relationships through consistent spacing. Deviating whitespace leads to broken layouts:

Bad random indentation:

    * Step 1
        * Sub-step A
             * Sub-sub-step i

  * Step 2

The alignment is broken visually here.

Use 4 consistent spaces for all indentation:

* Step 1
    * Sub-step A
        * Sub-sub step i

* Step 2  

Now the left spacing reinforces the hierarchy.

Limit Depth With 3 Levels Max

Readers can typically track only 3-5 levels of nesting effectively. Complexity grows exponentially deeper.

Stick to 3 indentations max in most outlining cases:

* Level 1  
    * Level 2
        * Level 3

Allowing quick visual scanning with just shallow enough nesting to establish detailed relationships.

HTML List Styling

As Markdown maps to HTML lists, CSS styling can customize rendered presentation details:

Bullet Styles

The list-style-type CSS property adjusts bullet marker style, like:

ul {
  list-style-type: square;
}

Renders with solid square bullets instead of default discs.

Other list-style-type options:

• circle – hollow circles
• decimal – numeral bullets
• none – no bullets

Indentation & Spacing

padding-left indents nested levels. line-height separates vertical space:

ul ul {
   padding-left: 1.5em;
   line-height: 1.5;  
}

Sets tighter nested indent spacing.

Multi-Column Lists

Using CSS columns and column-count, we can flow list items horizontally:

ul {
  columns: 2; 
  column-gap: 2rem;
}

Will render list items in 2 columns with spacing. Great for glossaries.

Advanced Nested List Techniques

Markdown‘s simplicity contains additional advanced possibilities when crafting complex outlines.

Mixed Nesting Structures

When extra hierarchy clarity is needed, combine numbered and bulleted nesting together:

1. Step one  
    * Sub-step 1.a 
    * Sub-step 1.b

2. Step two

Allows seeing high-level steps but detailed sub-steps.

Headings Within Lists

Treat headers just like list items by adding consistent indentation:

* Main bullet
    ### Sub-heading

    Paragraph text...  

    ### Another sub-heading

Works great for long articles/chapters!

Nested Reference Links

Reference links also adapt well for links within lists without cluttering flow:

* Main item [see details below][nestref]
    * Child item

### More details on the main item <a id="nestref"></a>

Then link to that in-page ID from within the list item.

Common Markdown List Gotchas

While Markdown lists generally "just work" well, a few non-obvious edge cases frequently trip folks up:

Spacing After Markers

Must have 1 space between all list item markers (*, 1.) and the subsequent line text. No space = broken formatting.

Intermediate Blank Lines

A single intermediate blank line in a list breaks flow causing formatting issues. Delete stray empties.

Inconsistent Indentation

Mixing tabs, 2 spaces, 3 spaces quickly ruins rendering by mismatching levels visually. Stick to 4 consistent spaces.

Nested Paragraphs != Sub-Lists

Unlike HTML, in Markdown inserting a blank line inside a list item does NOT create a sub-list. It just makes a nested paragraph.

Summary on Markdown Lists

In this comprehensive guide, we explored how Markdown bullets and sub-lists enable flexible outlining integrated with long-form writing:

• Basic Markdown syntax quickly structures unordered and ordered lists through indentation, markers, and blank lines

• Map Markdown lists to <ul>/<ol> HTML for ubiquitous rendering

• Best practices maximize nesting readability and maintainability

• Advanced techniques involve mixing structures and elements for complex outlines

• Common gotchas should be avoided through consistency and planning

As a writer, I utilize deeply nested Markdown outlines daily to organize book chapters, documentation, tutorials, notes, and more. The simplicity and flexibility of composing bullet point hierarchies interwoven with prose content accelerates my writing productivity.

I encourage you to explore ways of incorporating Markdown lists more deeply into your own writing workflows to simplify outlining.