How to list key/value pairs in a markdown

Question

There is a way to write a key/value pairs list?

I've tried this:

+ key1: value1
+ key2: value2
+ key3: value3

But the result is not very clean to me..

I've also tried tables:

|    |      |
|----|------|
|key1|value1|
|key2|value2|
|key3|value3|

But tables are not meant for key/value listing (I've for example to leave the heading row blank, that sounds ugly to me..)

Answer 1

GitHub Flavored Markdown does not apparently provide for definition lists. It indicates to do it in raw HTML:

<dl>
    <dt>Definition list</dt>
    <dd>Is something people use sometimes.</dd>

    <dt>Markdown in HTML</dt>
    <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>

Answer 2

The answer will depend heavily on the Markdown flavour and processor you are using. Regular Markdown doesn't support tables or definition lists, though it does support inline HTML.

Pandoc and PHP Markdown Extra both support definition lists:

key1
: value 1

key2
: value 2

If you are not working with a version of Markdown that supports definition lists you could add HTML <dl>, <dt>, and <dd> tags manually. Of course, the stylesheet being used will affect their display. Stack Overflow shows them as essentially an unordered list without bullets, which isn't very useful.

Alternatively you could use regular lists and re-indent your values with four spaces, e.g.

* key1
    * value1
* key2
    * value2

You could use inline bold or italics to visually separate the key from the value, e.g.

* **key1**: value1
* **key2**: value2

Finally, as you suggested in your question, you could use a table if your version of Markdown supports it.

Answer 3

Github will render a block of key value pairs as table with a header row if you fence it with three dashes ---

For example:

---
layout: classic-docs
title: "Caching in CircleCI"
short-title: "Caching"
description: "Caching strategies to increase build speeds"
categories: [configuring-jobs]
order: 20
---

renders as: