Skip to content

Instantly share code, notes, and snippets.

@MarcoEidinger
Last active June 12, 2024 05:14
Show Gist options
  • Save MarcoEidinger/c0f0583f19baca0a8f33bcded644be41 to your computer and use it in GitHub Desktop.
Save MarcoEidinger/c0f0583f19baca0a8f33bcded644be41 to your computer and use it in GitHub Desktop.
Master GitHub markdown tables with code blocks

Master GitHub markdown tables with code blocks

  1. Use HTML tags to define the table to get the best layout result
  2. Use either backticks (```) or the HTML pre element with attribute lang
  3. Keep a blank line before and after a code block for correct formatting and syntax highlighting

Good

Example: nice looking table to show HTTP Responses

Status Response
200
{
  "id": 10,
  "username": "marcoeidinger",
  "created_at": "2021-02-097T20:45:26.433Z",
  "updated_at": "2015-02-10T19:27:16.540Z"
}
400

Error, what the hell is going on?!?

500 Internal Server Error

Example: nice looking table to compare code changes

Before After
struct Hello {
   public var test: String = "World" // original
}
struct Hello {
   public var test: String = "Universe" // changed
}

Bad

Markdown defined table

Some markdown editors show correct layout and syntax highlighting if you use <br> tags in your code block. But this is very cumbersome and akward. And finally GitHub itself will show the code block on a single line :(

Status Response
200
{  "id": 10,  "username": "alanpartridge",  "email": "alan@alan.com",  "password_hash": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.CPCWCZsyqqa8./whhfzBZydX7yvahHS",  "password_salt": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.",  "created_at": "2015-02-14T20:45:26.433Z",  "updated_at": "2015-02-14T20:45:26.540Z"}
400 Error, what the hell is going on?!?

Using HTML code element to wrap code

You won't get syntax highlighting :(

Status Response
200 { "id": 10, "username": "marcoeidinger", "email": "alan@alan.com", "created_at": "2021-02-097T20:45:26.433Z", "updated_at": "2015-02-10T19:27:16.540Z" }
400

Error, what the hell is going on?!?

No blank line before/after a code block

You just lost line breaks AND syntax highlighting :((

Status Response
200 ```json { "id": 10, "username": "marcoeidinger", "email": "alan@alan.com", "created_at": "2021-02-097T20:45:26.433Z", "updated_at": "2015-02-10T19:27:16.540Z" } ```
400

Error, what the hell is going on?!?

@ricaun
Copy link

ricaun commented Jul 21, 2023

Just to mention, if you add the pre without the attribute lang kinda works, in multiple lines at least.

Status Response
200
{
"id": 10,
"username": "alanpartridge",
"email": "alan@alan.com",
"password_hash": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.CPCWCZsyqqa8./whhfzBZydX7yvahHS",
"password_salt": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.",
"created_at": "2015-02-14T20:45:26.433Z",
"updated_at": "2015-02-14T20:45:26.540Z"
}
400 Error, the lang is missing.

@akhanalcs
Copy link

@borama
Copy link

borama commented Jun 12, 2024

The Markdown defined table does seem to support new lines in the code block if you replace the <br> tags with &#13; HTML entities:

Status Response
200
{
  "id": 10,
  "username": "alanpartridge",
  "email": "alan@alan.com",
  "password_hash": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.CPCWCZsyqqa8./whhfzBZydX7yvahHS",
  "password_salt": "$2a$10$uhUIUmVWVnrBWx9rrDWhS.",
  "created_at": "2015-02-14T20:45:26.433Z",
  "updated_at": "2015-02-14T20:45:26.540Z"
}
400 Error, what the hell is going on?!?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment