GitHubのMarkdown小技

2024.05.29

概要

GitHubでMarkdownでいろいろドキュメントを書いているのですが、使える機能が制限されているので気がついたことをまとめていきたいと思います。

表組みについて

Markdownで書く

| SWCLK | SWDIO | TX1 | RX1  | TX2 | RX2 | TX3  | RX3  |
|-------|-------|-----|------|-----|-----|------|------|
| PA14  | PA13  | PA9 | PA10 | PA2 | PA3 | PB10 | PB11 |

たとえば上記にような表記で表組みが可能です。手で書くのは面倒なので基本はエクセルで下書きをしています。

上記のようにエクセルで書いたものをフォーマット変換サイトを使ってMarkdownにします。

SWCLK	SWDIO	TX1	RX1	TX2	RX2	TX3	RX3
PA14	PA13	PA9	PA10	PA2	PA3	PB10	PB11

エクセルをコピーすると上記のようにタブ区切りのデータになります。

https://www.tablesgenerator.com/markdown_tables
www.tablesgenerator.com

これを上記のページでMarkdownに変換します。

Fileの中にあるPaste table dataにコピーしたセルを貼り付けると上記のようにMarkdownにしてくれます。非常に便利なサイトなのでおすすめです。

HTML

基本的にはMarkdownで良いのですが、ケーブルの結合をしている場合にはHTMLのtableタグを利用する必要があります。

上記の表はGitHubのMarkdownでは表現できません。

https://www.tablesgenerator.com/html_tables
www.tablesgenerator.com

同じサイトですが、HTMLモードにすると変換可能です。

一番上のタブをHTMLにしてペーストすると結合した状態のtableタグが出力されます。GitHubで利用するときにはCSSを使わないプレーンなモードが好ましいです。

改行の制御

通常の改行 <br>

<br>

通常のbrタグが使えますので問題ありません。

ソフトハイフン(横幅が厳しいときは-を入れて改行) &shy;

上記のところで使っていますが、単語が長くて横幅が厳しいときにハイフンをいれて改行することができる記号です。

<th>I/O struc&shy;ture</th>

&shy;がソフトハイフンの特殊文字で、横幅が厳しくないときにはstructureと表示されて、厳しいときにはstruc-tureとハイフンを入れて改行をしてくれます。GitHubは横幅を広げても一定以上大きくならないので大きな表の場合には手動で改行位置を調整する必要があります。

改行可能要素 ​​​​&#8203;

ソフトハイフンは-を入れて改行をしますが、入れてほしくない場合があります。通常はwbrタグを使うのですがGitHubでは許可されていません。そこで特殊文字で&#8203;と入力することで無理やり再現することが可能です。

上記のような横幅が厳しい表で、とりあえず改行をしたいときに利用します。

<th>F6&#8203;(&#8203;TSSOP&#8203;20)</th>
<th>F8&#8203;(&#8203;TSSOP&#8203;20)</th>
<th>F8&#8203;(&#8203;QFN&#8203;20)</th>
<th>G6&#8203;(&#8203;QFN&#8203;28)</th>
<th>G8&#8203;(&#8203;QSOP&#8203;28)</th>
<th>K6/K8&#8203;(&#8203;LQFP&#8203;32)</th>
<th>C6&#8203;(&#8203;LQFP&#8203;48)</th>
<th>C8&#8203;(&#8203;QFN&#8203;48)</th>
<th>RB&#8203;(&#8203;LQFP&#8203;64M)</th>

上記のようにひたすら見にくくなるので多用するとあとで辛くなります。見た目的にはbrタグで調整しても問題がないのですが、テキストを選択したときに違いがでます。brタグだと改行コードがコピーされますが、wbr(&#8203;)だと元のテキストがコピー可能です。

F6​(
​TSSOP
​20)

つまりbrタグだとテキストを選択すると上記のコピーになります。

F6​(​TSSOP​20)

wbr(&#8203;)だと見た目の改行はコピーされないのできれいなテキストのままになります。

画像の貼り付け

Markdown

![](image/system_CH32V003.png)

ファイルはあらかじめリポジトリにアップしておきます。本来は[]の中に画像の概要を書いておきますが上記では省略しています。

HTML

<img src="image/system_CH32V003.png" />

imgタグでもかけます。こちらは好みなので好きな方を使って問題ないと思います。

PDFの貼り付け

GitHubへの直リンク

GitHubにはPDFビュアーがあるので、直接リンクでも開くことができます。ただし内部的に画像に変換しているのでテキストコピーはできないですし、開くのが非常に重いです。やっと開いたところでダウンロードして別のアプリで見る人も多いのではないでしょうか？

GitHubへのダウンロードリンク

rawから始まるURLにすることで直接ダウンロードが可能です。ただこの状態だとダウンロードフォルダに大量のPDFが保存されて、(2)とか同じファイルもなんどもダウンロードしてしまいます。

GitHub Pagesへのリンク

GitHub Pagesを有効化して、Pages側のリンクの場合にはファイルをダウンロードせずにブラウザ上で開くことも可能です。こちらだとブラウザ側のキャッシュも使えるのでハッピーです。

まとめ

表形式で横スクロールが出るのが嫌なので、がんばって調整する方法を探していました。wbrタグが使えればよかったんですけれどね。

あとはPDFをGitHubで開くのが大嫌いだったのですがPagesを使えばよいのがわかったのが収穫でした。

コメント