/ How to

How To Build and Format Tables in Markdown Documents

As a technical writer with over 5 years of experience creating Markdown documents, I often need to include tables to organize complex information. Properly formatting tables requires learning some key Markdown syntax. In this comprehensive guide, I will teach you step-by-step how to build and format tables for your Markdown documents to make them easy to read and understand.

Why Use Tables

Tables allow you to arrange information in rows and columns. This makes complex data:

  • Easier to scan
    -Simpler to compare
  • More organized and readable

For technical documents like software documentation, tables help readers:

  • Quickly lookup configuration options
  • Compare features
  • Get details about commands, APIs, etc.

With some simple Markdown formatting, you can create and style tables to communicate complex technical details to users more effectively.

Basic Table Syntax

To add a table, you’ll first write the column headers, separate them with pipes |, then add a separator row below. For example:

| Column 1 Header | Column 2 Header | Column 3 Header |
| --------------- | --------------- | --------------- |

Then you would add rows of data below, separating values with pipes:

| Column 1 Header | Column 2 Header | Column 3 Header | 
| --------------- | --------------- | --------------- |
| Row 1 Column 1 | Row 1 Column 2 | Row 1 Column 3 |
| Row 2 Column 1 | Row 2 Column 2 | Row 2 Column 3 |

The pipes separate the cells, while the dashes separate the headers from the data rows.

Formatting Rules

To properly format Markdown tables:

  • The pipes | are required to divide columns
  • The header rows should use three or more dashes --- under each column
  • There must be pipes at the start and end of each line
  • Columns should align properly

Adding Styling

You can make tables easier to read by adding formatting:

Text Alignment

Use colons : within the header separator row to set alignment:

  • Add :--- to left align
  • :--: to center
  • ---: to right align

For example:

| Left Aligned | Center Aligned | Right Aligned |
| :---         |     :---:      |          ---: |

Formatting Text

Use standard Markdown formatting within cells:

  • **Bold**
  • _Italics_
  • ~~Strikethrough~~

For example:

| **Product** | **Price** | **In Stock** |
| ----------- | --------- | ------------ |
| _IPhone_    | $800      | False        |

Formats the text in each cell.

Cell Background Color

Add a {bg-color} attribute inside a cell to set the background color:

| Orange Background | Green Background | Blue Background |
| --------------- | ------------- | ------------- |
| {bg-orange}Cell 1| {bg-green}Cell 2| {bg-blue}Cell 3|

Produces:

Orange BackgroundGreen BackgroundBlue Background
{bg-orange}Cell 1{bg-green}Cell 2{bg-blue}Cell 3

Cell Width and Heights

Use {width} and {height} attributes to set cell dimensions:

| Tall Cell | Wide Cell |
| ------ | ------- | 
| {height=4em}Tall height| {width=6em}Wide width|
Tall CellWide Cell
{height=4em}Tall height{width=6em}Wide width

Spanning Cells

You can combine cells using >{cols} syntax:

  • >{2} spans 2 columns
  • >{3} spans 3 columns, etc

For example:

| Day | Breakfast | Lunch | Dinner |
| ------------- | ------------- | ------------- | ------------- |
| Monday | Pancakes | Sandwich | Chicken |
| Tuesday | >{3} 2 dozen donuts |
DayBreakfastLunchDinner
MondayPancakesSandwichChicken
Tuesday>{3} 2 dozen donuts

This is useful for creating headings that span multiple columns.

Escaping Pipes

If you need to display a pipe | within a cell, escape it with a backslash \:

| Column 1 | Column 2 | 
| -------- | -------- |
| \| escaped pipe | Normal pipe |
Column 1Column 2
| escaped pipeNormal pipe

Tables Within Tables

You can nest tables inside table cells by adding the Markdown table syntax within a cell:

| Main Table Cell | 
| --------------- |
|  | Nested Table Header 1 | Nested Table Header 2 |
|  | ---------------------- | --------------------- |
|  | Nested Table Cell 1 | Nested Table Cell 2 |
Main Table Cell

This allows creating more complex, structured data.

Common Issues

Here are some common table formatting issues:

Misaligned Columns

Make sure pipes separate every cell and header dashes match the length of the column:

❌ Misaligned

| Column 1 | Column 2 | Column 3 |
| -------- | ---- | --------- |

✅ Aligned

| Column 1 | Column 2 | Column 3 |   
| -------- | -------- | -------- |

Missing Pipes

Every line must start and end with a pipe, including the first and last line:

❌ Missing corner pipes

Column 1 | Column 2
-------- | --------
Cell 1 | Cell 2

✅ Pipes on every line

| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1 | Cell 2 |

Improper Header Separators

Use three or more dashes separated by pipes to divide headers from data rows:

❌ Wrong header format

| Column 1 | Column 2 | 
- | -
| Cell 1 | Cell 2 |

✅ Proper header separator 

| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1 | Cell 2 |

Conclusion

By following these Markdown table syntax rules and formatting options, you can insert tables to make complex technical information easier to visualize.

The key is to:

  • Properly divide columns with pipes
  • Separate headers from bodies with dashes
  • Align columns
  • Use formatting to highlight cells
  • Span cells and nest tables as needed

With the power of Markdown tables, you can improve the organization and readability of all types of long and complex technical documents.

Over years of writing documentation, I’ve found well-formatted tables to be invaluable for communicating complex technical details to users in an easy-to-digest way.

Let me know if you have any other questions!

Related Posts