Working with Tables in GitHub Markdown

Markdown is a great tool for documentation on Github because documentation is only as useful as it is readable. Among other things, Github's flavor of markdown allows for the creation of tables to display data in rows and columns.

• A table in markdown consists of two parts.
  • The header
  • The rows of data in the table
• Individual columns in a table are separated by a pipe character: |.
• Rows in the table are separated by line breaks.
• HTML tags can be used for additional formatting inside individual cells.

The header of a markdown table consists of two rows. The first row is the column headers for the table. To specify the headers, simply separate each header with spaces and pipes. Make sure to include a pipe at the beginning and end of the line as well.

The second row is just metadata for the table that determines how the text will be vertically aligned. Each column can be aligned left, right, or center. The alignment is set by using a pattern of dashes and a colon separated by spaces and pipes.

• To left-align a column, put a colon to the left of two dashes :--.
  • Three dashes --- can also be used.
• To right-align, put a colon to the right of two dashes --:.
• To center-align, surround a dash with two colons :-:.

Surround any of the above with pipes to create the second row of the header.

For better readability of the raw markdown, the number of dashes can be increased.

Spaces can also be used.

The number of spaces or dashes is not important as long as there are at least three dashes or colons.

The body of the table consists of any number of rows separated by line breaks. Like the header, every cell is separated by a pipe character |. Putting this together with a header creates a full table:

When rendered, it will look something like this:

Whitespace before and after the text in a cell does not matter. It will be added or truncated automatically to create columns.

The following tables will both render identically. The only thing to consider here is the readability of the raw markdown file.

The header is the source of truth for the number of columns in the table. If a row in the body contains fewer cells than the header, it will be rendered with empty cells at the end.

Here the first row of the body will be populated with 2 empty cells at the end.

If a row in the body contains more cells than the header, the extra cells will be ignored

Here the first row of the body will have 2 cells trimmed from the end.

To add an empty cell in the middle of a row, just leave it empty.

Here the second cell of the first row will be empty.

This can be done by using whitespace, as above, or without it, as below. They will render identically.

Within table cells, most markdown formatting syntax—italics, bold, URLs, inline code blocks—can still be used. A literal pipe character can be used by escaping the pipe with a slash as seen below:

More advanced formatting can be done using HTML tags. Which tags are supported is beyond the scope of this guide, but I will say that the one I use commonly is <br /> to force cells to span multiple lines.

Note: Markdown tables will automatically wrap for cells that contain a lot of text. <br /> is only necessary when you need to force a line break in a specific place.

Github's flavor of markdown allows you to create some complex tables, but in many cases, it's best to keep it simple and easy to read. Markdown native syntax, such as bold or inline code blocks, is easy to add to tables, and HTML tags can be used as well. For more information on how Github generates tables refer to Github's Markdown Documentation. You should now be ready to start creating tables to improve your documentation in Github!

Explore these Github and Markdown courses from Pluralsight to continue learning:

• Build or Contribute with Github
• Github Course
• Writing Content with Markdown