<!--
date: 2024-12-11
title: 在 markdown 中使用描述清單
comment: true
-->

目前本站文章皆是使用 markdown 語法撰寫，並由 discount[^1] 套件提供的 `markdown` 指令來產製網頁。
最近在閱讀相關文件時，才發現它支援了不少擴充功能（相對於 John Gruber 最初使用的 [Perl 實現]）。
其中支援 HTML 描述清單(`<dl>`)的語法就很實用。

## `<dl>` 語法

HTML 元素 [`<dl>`] 即是 Description List 的縮寫，用來針對特定字詞深入描述。
內部使用[`<dt>`](abbr:Description Term)和[`<dd>`](abbr:Description Detail)分別來包含字詞本身和其描述。

通常會是這樣的節構：
```html
<dl>
  <dt>Beast of Bodmin</dt>
  <dd>A large feline inhabiting Bodmin Moor.</dd>

  <dt>Morgawr</dt>
  <dd>A sea serpent.</dd>

  <dt>Owlman</dt>
  <dd>A giant owl-like creature.</dd>
</dl>
```

其實 Unix Command 的網頁版文件（也包含 discount）就大量使用 `<dl>` 來描述可用選項。
依照 discount 定義的[語法]，我們可以使用 `=` 框住 `<dt>` 的內容，用四格空白來定義 `<dd>`，寫成下面這樣：

```markdown
=Beast of Bodmin=
    A large feline inhabiting Bodmin Moor.

=Morgawr=
    A sea serpent.

=Owlman=
    A giant owl-like creature.
```

接著使用相關的 Flag 即可：

```bash
markdown -f definitionlist input.md
```

## CSS

瀏覽器預設的樣式下，渲染出來的樣子比較像上面 markdown 的寫法。標題在上，內容緊跟在下:

<style>
  dl {
    padding: 1em;
    border: 1px solid gray;
  }
  .initial * {
    margin: initial;
    padding: initial;
    float: initial;
    text-align: initial;
    width: initial;
  }
</style>
<dl class='initial'>
  <dt>Beast of Bodmin</dt>
  <dd>A large feline inhabiting Bodmin Moor.</dd>

  <dt>Morgawr</dt>
  <dd>A sea serpent.</dd>

  <dt>Owlman</dt>
  <dd>A giant owl-like creature.</dd>
</dl>


不過既然本站有關程式開發的內容比較多，自然會想要做到像[說明文件]的樣子，把標題和內容齊平，並向中間靠攏。
因此則可以使用以下的 CSS 樣式：

```CSS
dt {
  width: 10em;
  float: left;
  clear: left;
  text-align: right;
}

dd {
  margin: 0 0 .5em 11em;
}
```

<br>
這樣就可以做出以下的成果，是不是順眼多了呢?

=Beast of Bodmin=
    A large feline inhabiting Bodmin Moor.

=Morgawr=
    A sea serpent.

=Owlman=
    A giant owl-like creature.


<br>
表格語法在 markdown 中難以編輯，若是要承載的資訊用兩個 column 就足夠，不妨考慮使用描述清單吧！


[^1]: discount 可說是最快速的 markdown processor 之一，由資深開發者 David Parsons 維護。
      可以輕易由 Arch Linux 的套件管理功能取得。詳見：https://www.pell.portland.or.us/~orc/Code/discount

[`<dl>`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[discount]: https://www.pell.portland.or.us/~orc/Code/discount/#:~:text=Language%20extensions
[Perl 實現]: https://daringfireball.net/projects/markdown/
[說明文件]: https://www.pell.portland.or.us/~orc/Code/discount/#:~:text=The%20program
[語法]: https://www.pell.portland.or.us/~orc/Code/discount/#:~:text=To%20mark%20up%20a%20definition%20list
