Q&A
総合スコア1
投稿2026/04/19 14:18
各種ドキュメントの作成に際し、AI は（もちろん設定できますが初期状態では）下記の様に「絵文字」と「---」と「セクション番号」を入れてきますよね。
markdown
1# あああ 2 3--- 4 5## 1. 🚀タイトル1 6 7あああ 8 9--- 10 11## 2. 📦タイトル2 12 13あああ
みなさんこれってどうしていますか？
私は Github もマークダウンも書いたことないので、AI に「Github のマークダウンの慣習だとどうなの？」と聞いても毎回答えが違ってわからず…
なるべく一般論に従って作りたいと思っています。
「個人的にわたしはこう」という感想や「うちのチームはこう」という慣習を知りたいです。
よろしくお願い致します。
回答5件
0
一般論として確立したものはないと思います。
私はセクション番号を Markdown の文中には入れません。 ドキュメントのセクション番号が必要なのは「そのドキュメントのセクション番号〇〇番を読んで」と言うため、参照しやすさの便宜のためなわけですがソフトウェアのドキュメントは更新されるものですし章構造が変わることもあるので番号に一意性がなく混乱の元です。
長期的に運用される版管理がしっかりした仕様書などではセクション番号が有用なこともありますが、その場合でもなるべくスタイルシートの側の記述で入れるようにします。 Markdown 側に書いていると改定のときに連番に振りなおすのが面倒ですし、何かの拍子に重複したり抜けたりするミスが起こりそうだからです。 私は一貫性のある基準に従って記述する自信がないので書かずに済むものなら書きたくないです。
絵文字に関しては、絵文字が何らかの意味のある分類を表しているなら入れれば良いと思いますが一貫性のあるルールがない装飾であれば無いほうが良いです。
水平線については、一般的には大きく内容が切り替わるような場合はセクションを分けるので水平線で区切りを付けることが必要な場合というのがそもそも想像できないです。 セクションの間に装飾的に水平線を入れたいのであればセクション番号と同様にスタイルシートで設定したいです。
ただ、ツールやサービスの都合でスタイルシートをいじれないときなどもあるでしょうから、そういうときは必要性によって個別に判断するしかないでしょう。
Markdown の大元の思想ではプレーンテキストで使われていた見出しや強調などの記法を HTML に変換することを意図していたのでその思想に則るのであればプレーンテキストとして読んでも見やすいことが望ましく、私が考えるスタイルシートを前提とする考え方は妥当ではないです。 つまり運用方法とセットで考えないと Markdown としてどうこうとは言えません。
投稿2026/04/20 03:16
総合スコア5896
0
https://qiita.com/YushiYamamoto/items/6383fb102420003b07d2
Qiitaの記事ですが、絵文字は意味を持たせて使うことはあります！
ただ、自分（自分のチーム）はあまり使いません。
チーム内のドキュメントやプルリクのルールで指定しているのはあるかもなので、指定されてれば使うかなぐらいです。
個人の見解としては、自分も含め質問者さんと同様に調べないと意味理解できなく、そういう人も少なからずいると思うと、重要性少ないしつかわないかなという感じです。
水平線などは場合によって使います。
この例だと、1, 2で大きく分野が違うことを記載していれば入れてあげても良いかなと。
同じ内容をセクションに分けただけならいらないかなという印象です。
こちらもルールとかなく、他者が見たときに理解しやすくするためのを考えてご検討されるのが良いと思います！
投稿2026/04/20 02:25
総合スコア272
0
(Markdownは単なるマークアップ言語なので、質問の意図がよくわかりませんが...)
そのドキュメントの目的や読者層を想定した場合、絵文字/水平線/セクション番号を使うのが適切なら使います。不適切なら使いません。
別にGitHubだからMarkdownだからといった一般論は無いと思います。
それは、AIが書いても自分で書いても同じですし、Word/Excel/PowerPointでも同じです。
実際は、判断に迷うのは絵文字くらいで、水平線/セクション番号を書いて怒られる状況は考えづらいです。
投稿2026/04/19 23:10
総合スコア1810
0
一般論ではなくて慣習を知りたいからみなさんどうしてますか、と問われているのですよね。
慣習ではありませんが例えば
https://handbook.gitlab.com/
これはGithubではなくGitlabの方ですが、Markdownで業務の文書を全て社内共有そして可能なものは一般公開というすごいものです。
ドキュメントかしていつでもどこでも誰が来ても一定の水準の仕事をしようぜというような哲学で書かれているので、ここの書き方に倣うのが1つ見本になると思います。
投稿2026/04/26 02:17
総合スコア2339
0
「markdown だから→どうこう」ということではなくて，「何を書いているのか」次第では．
「Github 用に書いているのであって，且つ，Github という場にはそれなりの慣習というものがある」という話なのであれば，その慣習に従っておけば良いのでは？ …としか．
あるいは
「論文を書いているんです！」とかであれば，それなりのフォーマットというものがあるでしょうから，それに合わせるだけでしょうし．
そういうのじゃなくて｛単なるメモ書き，その場限りの文書，etc｝とかであれば，好きにやれば良いんじゃないかな，と．
以下は，単なる個人的なメモ書きの場合の話ですが……
投稿2026/04/23 02:00
総合スコア12398
あなたの回答
tips
プレビュー
2026/04/22 21:17