irasin/github_document_demo

• これはGitHubでドキュメントを公開するにはどうしたらいいか、というブログ記事用のデモリポジトリです。
  • ゆめみスタッフブログ
  • Qiita

---

GitHubは、プログラムのソースを公開するだけでなく、テキストドキュメントを置くことができます。 プログラマの方でなくても手順やガイドラインなどを公開したり、またドキュメントを複数人で書いたりバージョン管理するのに活用できます。

必要なもの

• GitHubのアカウント
  • https://github.com で取得
• Gitのクライアント環境
  • ここが分かりやすいです。
    • http://www.backlog.jp/git-guide/

リポジトリ内のファイルの構成

とくに決まりはないのですが、こういう構成がいいんじゃないかというものです。 （ボリュームがなければ README.md ひとつだけでもいいと思います。）

リポジトリTOP
│
├ README.md .. 目次を書く
│
├ ○○.md
├ ○○.md
├ ○○.md
│
├ 第１章 .. フォルダを作成
│　├ ○○.md
│　├ ○○.md
│　└ ○○.md
│
├ 第２章 .. フォルダを作成

　　～

└ 画像用フォルダ .. 細分化してもよい
　　├ ○○.jpg
　　├ ○○.png
　　└ ○○.xxx

ドキュメントの記法

• マークダウン形式で書きます。
  • https://guides.github.com/features/mastering-markdown/
• ただ色々おぼえなくても、基本は次のようなものだけ覚えておけばとりあえずは十分かと。

① 見出し

• 記法

   # 大タイトル
   ## 中タイトル
   ### 小タイトル
  

• 結果

  ---

  大タイトル

  中タイトル

  小タイトル

  ---

② 箇条書き

• 記法

   - 箇条書き
   	- タブでインテント
   		-  さらにタブでインテント
   - 箇条書き
   - 箇条書き
  

• 結果

  ---

  • 箇条書き
    • タブでインテント
      • さらにタブでインテント
  • 箇条書き
  • 箇条書き

  ---

③ コード

• 記法

  • 文中で利用する場合

    文文文[半角スペース]`コード`[半角スペース]文文文

  • 複数行の場合

     [空行]
     `を3つ
     コード
       ～
     コード
     `を3つ
     [空行]
    

• 結果

  ---

  文文文 コード 文文文

   コード
     ～
   コード
  

  ---

④ 引用

• 記法

   [空行]		
   > 引用したい文
   [空行]		
  

• 結果

  ---

  引用したい文

  ---

ページを作ってリンクを張る

• 適当にファイルを ○○.md として作成してコミット＆プッシュします。
• リンクを張りたい場合は
  • [リンク名](○○.md) と記載します。
  • こんな感じ → リンクテスト
• フォルダ作って階層を分けてもＯＫです。
  • [リンク名](△△/○○.md) と記載します。
  • こんな感じ → リンクテスト
• 日本語のフォルダ名、ファイル名も使えます。

画像を張る

• まず利用する画像もこのリポジトリにコミット＆プッシュしておきます。
  • 仮に images フォルダに格納するとします。
• こういう風にリンクを張ります。

  • ![alt内容（マウスカーソルが当たったときの表示テキスト）](images/○○.jpg)

  • こんな感じ↓

    

ほか

• リンクや画像は http(s)://～ で書けばリポジトリ外のものでもＯＫです。
• 絵文字も使えます。
  • 使える絵文字はこちら
    • http://www.emoji-cheat-sheet.com/
  • 例えばこういう風に書けばＯＫです。
    • :smile: → 😄
• 個人的に参考になるGitHub上のドキュメント
  • cookpadさんのコーディングガイドライン
  • mixiさんのトレーニング資料
    • いろいろありますが、これはiOSのもの
    • こちらは目次だけリポジトリで管理して、各ページはそのリポジトリのWikiで管理するタイプです。

おわりに

最近はGitHubで小説を書いたりする人もいるようですね。本記事がGitHubの導入の参考になれば幸いです^^