はじめに
READMEについて全くの初心者がREADMEとは何かというのと基本的な記法についてまとめてみました。
READMEとは
READMEとはソフトウェアプログラミングにおいてプロジェクトの概要や、ツールの使い方など主にソフトウェアの関する情報が書かれた説明書のようなものである。READMEがあることによりプロジェクトへの理解が容易になるメリットが得られるので誰でもスムーズにプロジェクトへ参画することが可能である。
しかし、READMEはプロジェクトの第一印象を決めるものと言っても過言ではないので記述が不十分であると、プロジェクトの目的、仕様の理解が不十分になってしまい誤った情報を共有する恐れがある。その結果、重大なバグにつながる可能性があるので誰が読んでも理解できるREADMEを書くことを意識することが大事である。
READMEに書かれる項目として主に以下のような項目が含まれる。
- タイトル
- 機能概要
- 開発環境
- 運用方針
- 環境の構築方法・インストール方法
- ライセンス
- ディレクトリ構成
など...
READMEの記述方法
READMEはMarkdown（マークダウン記法）（.md拡張子）で記述する。
マークダウン記法とは
マークダウン記法とは文章を記述するための言語（計量マークアップ言語）の一種であり誰でも簡単に文章を明示でき、装飾されたHTML文章などに変換できる。
- マークダウン記法のメリット
- 誰でも簡単に学習することが可能
- 文章を簡単に見やすくまとめることが可能
- マークダウン記法のデメリット
- 慣れるまでは書き方を調べながらしなくてはいけない
- シンプルな文書を作成することは可能だが、逆に言うと画像、複雑な図を用いた表現、また、アニメーション用いた表現には不向きである
Markdown記法の実際の書き方
実際にMarkdown記法でどのように表現できるのか基本的な書き方をいくつかあげる。
１.見出し
- 行の先頭に
#(シャープ記号)で見出しを表すことができる - #の先頭の数によって見出しの大きさを変えられることできる(H1からH6まで)
# 見出し
## 見出し
### 見出し
#### 見出し
##### 見出し
###### 見出し
結果
見出し
見出し
見出し
見出し
見出し
見出し
２.リスト
- 行の先頭に
-(ハイフン)+(プラス)*(アスタリスク)＋半角スペースでリストを表すことができる - リストの中に入れ子（ネスト）を挿入したい場合はtabキーを利用してネストすることが可能
- 数字付きのリストを作成したい場合は先頭部分に半角数字. をつけるとことで作成することができる
- リスト
+ リスト
* リスト
- リスト
- ネスト1
- ネスト2
1. リスト1
1. ネストされたリスト1
1. ネストされたリスト2
1. リスト2
1. リスト3
結果
- リスト
- リスト
- リスト
- リスト
- ネスト1
- ネスト2
- リスト1
- ネストされたリスト1
- ネストされたリスト2
- リスト2
- リスト3
3.強調
- 文書の中で強調したい部分を
*(アスタリスク)2つを囲むことで強調することができる
囲まれたところが**強調**される。
結果
囲まれたところが強調される。
4.斜体
- 文書の中で斜体にしたい部分を
*(アスタリスク)または_(アンダーバー)1つをで文字列を囲むことで斜体にすることが可能 - 強調＋斜体を利用したい場合は
アスタリスクまたはアンダーバーを3つを文字列で囲むことで、強調かつ斜体の文字を作成することが可能
囲まれたところが *斜めに* 表示される
囲まれたところが _斜めに_ 表示される
***強調と斜体*** の文字を作成
___強調と斜体___ の文字を作成
結果
囲まれたところが 斜めに 表示される
囲まれたところが 斜めに 表示される
強調と斜体 の文字を作成
強調と斜体 の文字を作成
5.リンク
- リンクの書き方は
[タイトル](URL)でURLに記載されているリンクに飛ぶことが可能となる
[トップページに戻る](https://qiita.com/)
結果
6.コードの挿入
-
(バッククォート記号)を3つ記載することでコードの挿入が可能となる - 3つのバッククォート記号の後に言語を指定するとその言語に対応した表示がされる
```php:web.php
Route::get('test/index', [TestControlle::class, 'index'])->name('index');
```
結果
Route::get('test/index', [TestControlle::class, 'index'])->name('index');
- コードのインラインを表示したい場合はバッククォート記号を1つで囲む
`all()`を使えば対象のテーブル内の全ての情報を取得することが可能です。
結果
all()を使えば対象のテーブル内の全ての情報を取得することが可能です。
7.アラートの挿入
- アラートを挿入をする場合は
:(コロン)を３つ入力した後にnote infoと記述してアラートの最後を:::で囲むことでアラートの作成が可能となる
:::note info
一般
これは一般的な情報を示しています。
:::
:::note warn
注意
これは注意が必要な情報を示しています。
:::
:::note alert
警告
これはwarnよりも緊急性の高い警告を示しています。
:::
結果
一般
これは一般的な情報を示しています。
注意
これは注意が必要な情報を示しています。
警告
これはwarnよりも緊急性の高い警告を示しています。
8.テーブルの作成
- テーブルの作成方法はまず1行目に|(パイプ記号) テーブルのヘッダー名 |で区切ることによりテーブルのヘッダーを作成することができる
- 次に2行目に文字の表示位置を指定することができる
- 左寄せ： --- または :---
- 右寄せ： ---:
- 中央寄せ： :---:
| No | 名前 | 社員番号 |
| :--- | :-----------: | -------: |
| 1 | ユーザー1 | **101** |
| 2 | ユーザー2 | *102* |
| 3 | ユーザー3 | ***103*** |
| No | 名前 | 得意言語 |
|---|---|---|
| 1 | ユーザー1 | 101 |
| 2 | ユーザー2 | 102 |
| 3 | ユーザー3 | 103 |
9.画像の挿入
- 画像の挿入方法は
を記述する
結果
終わりに
簡単ではありますがREADMEの基本的な記法についてまとめてみました。まずはこれらを扱えるようにしたいと思います。