【Github】Github ~ README.md の書き方 ~

■ はじめに

 Github の README.md の作成があったので、
チートリストとか気を付けることとか環境に関してメモする

https://dk521123.hatenablog.com/entry/2019/08/01/000000

で扱ったMarkdown記法で記述する。

https://gist.github.com/mignonstyle/083c9e1651d7734f84c99b8cf49d57fa

を見れば一通りいいのだが、自分に必要な記述をピックアップ。

目次

【1】リンク
 1)絶対パス
 2)相対パス
 3)内部リンク
【2】表
 1)表内に改行を入れる場合
【3】使用上の注意
 1)README.md の置き場に注意
 2)記号の一部をエスケープする必要がある
【4】その他事項
 1)VS Codeによる README.md の編集環境
 2)おまけ:シーケンス図を書くことを考える

【1】リンク

# Targetってリンクができる
[Target](URL)

1)絶対パス

[MSN](https://www.msn.com/ja-jp)

2)相対パス

[Cheat Sheet](/cheatsheet.md)

3)内部リンク

See also [here](#appendix-A)

# <span id="appendix-A">Appendix-A: Set-up docker/docker compose</span>

【2】表

| 左寄せ | 中央寄せ | 右寄せ |
| :---- | :---: | ---: |
| 値1 | 値2 | 値3 |

1)表内に改行を入れる場合

* <br> を入れればいい

https://qiita.com/onigra/items/b43481ea46b809d3a2f1

|name            |
|---------------|
|Hello <br> World |

【3】使用上の注意

1)README.md の置き場に注意

以下「フォルダ構成」のように、README.md を置いたら
.github 直下に README.md がリポジトリルートに表示される
 => 詳細は、以下の関連記事に記載しているが、この動きは仕様

https://dk521123.hatenablog.com/entry/2024/03/20/000000

フォルダ構成

+ README.md
+ .github
  + README.md << こっちが表示

2)記号の一部をエスケープする必要がある

* 「_」とかは、「\_」とかでエスケープする必要がある
  + 「__XXX___」で「XXX」が太文字になってまう
   (「**XXX** 」も同じ)

* &マークなどは「&amp;」に変換
  + (まだ、理由がよくわかっていないが)
  「xxx.sh」になるとリンクになってしまうので、
  「xxx&#46;sh」でリンクを解除できる
 => 「xxx\.sh」でもリンクになってしまう
 => ちなみに、「xxx.py」だとリンクにならない

エスケープ一覧

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

特殊文字の変換

以下のサイトを参照。

http://www.shurey.com/js/labo/character.html

【4】その他事項

1)VS Codeによる README.md の編集環境

* README.md を修正するのに、プレビューがないと面倒くさいのでメモ。
* プレビューの表示だけなら、プラグイン不要

VS Codeの操作:プレビュー表示

Ctrl + Shift + V

https://www.atmarkit.co.jp/ait/articles/1804/20/news030.html

2)おまけ:シーケンス図を書くことを考える

* 以下のサイトのような方法を取らないといけないらしい

https://qiita.com/takke/items/86a5ddf145cf9693b6e9

* Github では、Mermaid記法(※)は、サポートしていないらしい

https://hpcmemo.hatenablog.com/entry/2018/04/05/221339
※ Mermaid記法(マーメイド) について

以下のサイトなどを参照。

https://note.com/ss_kasagi/n/nefb9875d7a72

関連記事

Github ~ 入門編 ~
https://dk521123.hatenablog.com/entry/2019/07/18/234652
.github 直下に README.md を置いたらリポジトリルートに表示
https://dk521123.hatenablog.com/entry/2024/03/20/000000
Markdownモードについて
https://dk521123.hatenablog.com/entry/2019/08/01/000000
Github ~ AsciiDoc ~
https://dk521123.hatenablog.com/entry/2023/11/06/235823