To keep Markdown table source readable, pad cells with spaces and realign each column after longer edits. On a Mac using Obsidian, edit through the native table editor, then inspect Source mode. Source padding and rendered text alignment need separate checks.

This workflow is for someone maintaining a small Markdown table in a desktop note: a reading list, a stationery inventory, or a project checklist. The goal is to keep the actual text easy to scan as entries change, while preserving a working table in the intended renderer.

What makes Markdown table source readable?

A readable source table has recognizable column boundaries, consistent spacing, and one complete row per line. Its pipes line up vertically when viewed in a fixed-width font. GitHub’s documentation explicitly says cells need not have matching widths or perfectly aligned source columns, so this alignment is an editing convenience rather than a requirement for a valid table. Organizing information with tables.

For example, this synthetic table is compact but becomes harder to scan after a longer item name is entered:

| Item | Finish | Count |
| --- | --- | ---: |
| Pencil | Matte | 4 |
| Large sketchbook | Linen | 12 |

Adding spaces makes the same content easier to inspect as plain text:

| Item             | Finish | Count |
| ---------------- | ------ | ----: |
| Pencil           | Matte  |     4 |
| Large sketchbook | Linen  |    12 |

In GFM, spaces between the pipe boundaries and cell content are trimmed. Padding therefore does not establish a rendered column width. The colon in ----: controls right alignment of the rendered column; the spaces before 4 simply make this source example easier to scan. GitHub Flavored Markdown Spec, Tables.

Treat these as two separate decisions: choose padding for reading the source, and choose delimiter-row colons for aligning rendered text. If your only problem is uneven pipes in the editor, changing colons will not solve it.

Which renderer will read the table?

Pipe tables are an extension, not a feature of core CommonMark. The current CommonMark specification resolves to version 0.31.2, while GitHub’s published GFM specification explicitly defines tables as an extension to CommonMark. A renderer described only as CommonMark-compatible does not thereby promise pipe-table support. Check whether it also supports a table extension. CommonMark Spec, GitHub Flavored Markdown Spec.

The following distinctions matter when moving a note between applications:

Destination Documented behavior Practical choice
Core CommonMark No pipe-table syntax in the core specification Confirm a table extension is available
GitHub Its table guide requires at least three hyphens per delimiter cell Use --- or longer
Obsidian Its table guide accepts a minimum of two hyphens and does not require aligned source cells Use three or more when also targeting GitHub

The hyphen requirements above come from the respective product guides. Using at least three is a convenient shared convention for these two destinations; it does not make every Markdown renderer equivalent. GitHub table documentation, Obsidian advanced formatting syntax.

For a table intended for both Obsidian and GitHub, use leading and trailing pipes, ordinary spaces for padding, and a blank line before and after the table. GitHub’s guide calls for a preceding blank line; the GFM specification documents that an empty line ends a table. Keeping both boundaries explicit also makes the source easier to identify. GitHub table documentation, GFM table boundaries.

How to maintain the table in Obsidian on a Mac

Obsidian provides a useful route for people who want convenient cell editing and readable Markdown afterward. Its desktop 1.5.8 release notes introduced automatic table formatting while typing, specifically describing cleaner columns when viewed in Source mode. This is documented editor behavior, rather than a Markdown syntax feature. Obsidian 1.5.8 Desktop release notes.

Use this sequence for an ordinary note:

  1. Open the note in Live Preview. If necessary, select that mode through the editor’s status icon.
  2. Insert a table using the Insert Table command, or right-click and choose Insert → Table.
  3. Enter or revise the cell contents in the table editor. Right-click the table when you need to add, delete, move, or sort rows and columns.
  4. Select Source mode through the status icon and inspect the resulting Markdown.
  5. Switch to Reading view to check the displayed table.

The mode controls are documented in Views and editing mode; table insertion and context-menu operations are documented in Advanced formatting syntax.

For repeated switching, assign a hotkey to Toggle Live Preview/Source mode. On macOS, Cmd+E toggles reading and editing views; use the dedicated mode command when your aim is specifically to move between the two editing modes. Obsidian views and editing mode.

If typing directly in Source mode leaves uneven padding, return to the native table editor for further edits and inspect the source afterward. The cited documentation supports automatic table formatting and precise source inspection, but does not establish a universal promise that every arbitrary source edit is immediately repadded. For a small table that remains uneven, the manual method below gives you direct control.

How to realign source columns after a longer edit

Use a simple rule: make each source column wide enough for its longest current entry, including its heading. Add padding to the other cells in that column. Recalculate when an entry becomes longer than the existing space.

Here is a worked example using only plain ASCII text. Start with this table:

| Item   | Finish | Count |
| ------ | ------ | ----: |
| Pencil | Matte  |     4 |
| Folder | Linen  |    12 |

Now replace Folder with Large sketchbook. The new item has 16 characters, so the first column needs a 16-character content area. Leave one space immediately inside each boundary pipe, then add enough trailing spaces to fill that area:

  • Item has 4 characters, so add 12 padding spaces after it, followed by the boundary space.
  • Pencil has 6 characters, so add 10 padding spaces after it, followed by the boundary space.
  • Large sketchbook fills the 16-character area, so it needs only the boundary space afterward.
  • Extend the first delimiter cell to 16 hyphens for a matching visual guide.

The result is the padded table shown earlier. Only the first column needed widening. The other columns retain their spacing and alignment markers.

This is a manual formatting recipe for the stated ASCII example, not a general character-width algorithm. For everyday editing, inspect the result in a fixed-width source display. If cells contain substantial inline formatting, judge source width using the characters actually written, including punctuation such as backticks and asterisks.

After a batch of edits, align the table once rather than adjusting every row after every keystroke. If entries frequently become paragraphs, consider keeping only a short label in the table and moving the explanation into ordinary prose below it. That reduces the amount of whitespace maintenance without shortening the underlying information.

What should you check when a table breaks?

Begin with structure before adjusting spaces. Under GFM, the header and delimiter rows must have matching cell counts. Body rows with too few cells receive empty cells; excess cells are ignored. A table can therefore look plausible while omitting content from the rendered result. GFM table parsing rules.

Use this diagnostic sequence after a substantial edit:

  1. Compare the header and delimiter rows. Give each heading a corresponding delimiter cell.
  2. Inspect every body row. Keep the intended number of cells even where a value is empty.
  3. Look for literal pipes in content. An unescaped pipe may be interpreted as another boundary.
  4. Inspect row boundaries. Keep each table row on one source line and avoid blank lines inside the table.
  5. Preview the destination. Check the displayed values as well as the table’s appearance.

For literal pipes, GitHub documents placing a backslash before the character. This complete example keeps Blue | Green inside one cell:

| Item   | Options       |
| ------ | ------------- |
| Folder | Blue \| Green |

The escape is structural; adding more spaces around an unescaped pipe will not fix it. GitHub’s literal-pipe example.

Obsidian also documents escaping the pipe used in an internal-link alias inside a table. That is an Obsidian-specific syntax consideration, so an escaped alias does not by itself establish equivalent link behavior on GitHub. Obsidian table formatting guidance.

Do not press Enter midway through a long cell to make its source look narrower. GFM tables accept inline content and exclude block-level elements; they do not provide a general multiline source-cell format. Move lengthy explanations outside the table when one-line rows become impractical. GFM table content rules.

Keep the maintenance routine small: finish the content changes, inspect cell boundaries, repad the affected columns, and review the rendered table. In Obsidian, the native table editor followed by Source mode is the practical starting point. Manual padding remains useful when you want a particular plain-text layout.

Sources