Markdownとは? 軽量マークアップの解説

Markdownは、シンプルな記号を使ってテキストをheading、リスト、link、コードブロックにフォーマットする、軽量なプレーンテキストのマークアップ言語です。

Markdownを使うと、ひと握りの直感的な記号を使ってプレーンテキストでフォーマットされた文書を書けます。READMEファイル、GitHubのissueやpull requestの説明、そして多くのドキュメントのフォーマットです。単なるテキストなので、バージョン管理に置くことができ、どこでもきれいにレンダリングされます - CIのjobサマリーも含めて。

Markdownとは

Markdownはプレーンテキストの慣例を使ってフォーマットを暗示します: headingにはハッシュ、強調にはアスタリスク、リスト項目にはダッシュ、インラインコードにはbacktick。レンダラーがそのテキストをHTMLに変換します。要点は、レンダリングされる前でも生のソースが読みやすいままであることです。

flavorと拡張

いくつかの方言があります。CommonMarkは厳格で標準化されたコアであり、GitHub Flavored Markdownはテーブル、task list、取り消し線、syntax highlighting付きのfenced code blockを追加します。CIで出会うほとんどのツールはGitHub Flavored Markdownをレンダリングします。

Markdownがバージョン管理に合う理由

Markdownはプレーンテキストなので、diffが意味を持ち、mergeが機能し、独自エディタに縛られません。これにより、コードの隣に置かれ、他の変更と同様にpull requestでレビューされるドキュメントにとって、自然なフォーマットになります。

CIのjobサマリーにおけるMarkdown

GitHub Actionsでは、jobが特別なサマリーファイルにMarkdownを書き込むことができ、それが実行ページ上でリッチなレポートとしてレンダリングされます - テスト結果のテーブル、link、あるいはdeployのサマリー。そのファイルに書き込むことが、実行から離れずに生のjob出力を読みやすいレポートに変える方法です。

A Markdown step summary

# Write a Markdown job summary in GitHub Actions
steps:
  - run: |
      echo "## Build report" >> $GITHUB_STEP_SUMMARY
      echo "- Status: passing" >> $GITHUB_STEP_SUMMARY

Latchkeyについての注記

GITHUB_STEP_SUMMARYの仕組みは標準runnerの一部なので、MarkdownのjobサマリーはLatchkeyのマネージドrunnerでも同一にレンダリングされます - buildやdeployのレポートを実行ページ上で直接表示するのに便利です。

重要なポイント

Markdownはシンプルな記号を使ってheading、リスト、link、コードをフォーマットするプレーンテキストのマークアップです。
GitHub Flavored Markdownは、CommonMarkの上にテーブル、task list、fenced code blockを追加します。
CIではjobサマリーファイルにMarkdownを書き込むことで、リッチで読みやすい実行レポートを作成できます。