はじめに
今回は私が記事を書くために使用している記法やツールについて使い方等を備忘録としてまとめます。ここでまとめるツールについては基本的に無料で使えるものに限ります。
またここで言うリッチな記事とは「視覚的に分かりやすいよう工夫されている記事」を定義としています。視覚的に分かりやすいということは情報量が多いということです。少しの工夫でもより多くの人々の役に立つ記事にすることができると考えています。
参考までに私が自分で書いてリッチだと思っている記事を下記にリンクします。
| リッチ度 | 記事 |
|---|---|
| ⭐️☆☆ | PGroonga で検索の幅を広げる！複数のカラムを合わせた全文検索のテクニック |
| ⭐️⭐️☆ | dialog の背景色が変わらないときに読んで下さい (React サンプルコード付き) |
| ⭐️⭐️⭐️ | [Unity] ハイパフォーマンスな Tween ライブラリ LitMotion を OpenUPM からインストールする |
記法編
注意
Markdown の基本的な記法については扱いません。
不安のある方はまず Markdown記法 チートシート を参照して下さい。
色付き文字
文字に色をつけて強調することが可能です。注意点として多用すると少しくどいです。「強調したいが Note ではないなー」というときに使えます。
色名指定
一部だけ <font color="red">赤色</font> に表示されます。
表示
一部だけ 赤色 に表示されます。
カラーコード指定
カラーコードも <font color="#0086AD">このように</font> 使えます。
表示
カラーコードも このように 使えます。
コードブロック
基本的な記法ですが、いくつか Qiita 独自に工夫できる点があるので記載します。
基本 (シンタックスハイライト + 名前)
始めの ``` の後にファイルの拡張子を入れるとシンタックスハイライトが適用されます。
さらに ```(ファイル拡張子):(文字列) のようにするとコードブロックに名前をつけることができます。
```c:hello.c
#include <stdio.h>
int main(void)
{
printf("Hello, world!\n");
return 0;
}
```
表示
#include <stdio.h>
int main(void)
{
printf("Hello, world!\n");
return 0;
}
発展編： 差分表示
```(ファイル拡張子):(文字列) のファイル拡張子の前に diff_ を入れます。そうして変更前の行の先頭に - を、変更後を表現する行の先頭に + を入れると差分が分かりやすく表示されます。
```diff_c:hello.c
#include <stdio.h>
int main(void)
{
- printf("Hello, world!\n");
+ printf("Hello, Qiita!\n");
return 0;
}
```
表示
#include <stdio.h>
int main(void)
{
- printf("Hello, world!\n");
+ printf("Hello, Qiita!\n");
return 0;
}
Note
Qiita のチートシートでは補足説明となっていますが、要件や必ず確認して欲しい事項などの強調表示として使用することが多いです。
補足説明
:::note info
補足情報てすと
:::
表示
補足情報てすと
警告表示
:::note warn
警告てすと
:::
表示
警告てすと
より強い警告表示
:::note alert
より強い警告てすと
:::
表示
より強い警告てすと
発展編: エラーについての補足表示
上手くいかずにエラーが出た人に向けた内容を 「警告 + 折りたたみ」 で行う表現が個人的に気に入っています。
エラーが起こらなかった人は読み飛ばしやすく、エラーに困っている人には目につきやすいという点で優れていると感じます。
:::note warn
<details>
<summary>
<b>エラーが出る！</b>
</summary>
大文字と小文字をしっかりと区別して入力したか確認してみましょう。
</details>
:::
表示
エラーが出る！
大文字と小文字をしっかりと区別して入力したか確認してみましょう。
ツール編
スクリーンショット
言わずもがなスクリーンショットあった方がリッチです。
次のショットカットキーで範囲を指定してスクリーンショットが撮れます。
-
Mac
⌘ command + ⇧ shift + 4
-
Windwos
Win + ⇧ Shift + S
tree: ディレクトリ構造を簡単に出力する
インストール方法
Mac ユーザーの場合は HomeBrew からインストールできます。
brew install tree
Windows ユーザーの場合はインストール不要ですが、コマンドが異なるため下記のリンクを参照して下さい。
カレントディレクトリ配下のディレクトリを全て表示
tree
.
├── README.md
├── src
│ ├── main.c
│ └── utils.c
└── test
└── test_main.c
階層を指定して表示
-L (数字) で階層を指定してディレクトリを表示できます。
次のコマンドはカレントディレクトリを含む 2 階層目までを表示するものです。
tree -L 2
よく使うオプション
| オプション | 概要 |
|---|---|
| --dirsfirst | ファイルの前にディレクトリをリストする |
| --gitignore | .gitignore ファイルを使って表示を除外する |
| -I | ディレクトリ・ファイルを個別に除外して表示 |
| -a | 隠しファイルを表示 |
| -d | ディレクトリのみを表示 |
FFmpeg: gif を使用する
細かな操作や動作の説明などを行う場面においてスクリーンショットでは情報量が不足しがちです。動画を使用できれば解決するのですが、Qiita では動画ファイルを使用できないので代わりに gif を使用したいと思います。
手順としては画面をキャプチャーした動画を gif に変換して貼り付けます。
今回変換に使用する FFmpeg は動画エンコード等を行えるフリーソフトウェアです。
インストールしなければいけないのが若干面倒ですが、記事を書くこと以外にも使い道があるためインストールしておいて損はないでしょう。
インストール方法
Mac ユーザーの場合は HomeBrew からインストールできます。
brew install ffmpeg
Windows ユーザーの場合は下記リンクからダウンロードを行い、システム環境変数を設定する必要があります。
動画を gif に変換する
.mp4 でも .mov でも問題なく変換可能です。
ffmpeg -i sample.mp4 output.gif
ffmpeg -i sample.mp4 -vf scale=960:-1 output.gif
オプション -vf scale=960:-1 のように指定することでアスペクト比を崩さず横幅 960px にリサイズすることが可能です。
意味としては scale=(横ピクセル数):(縦ピクセル数) で、-1 は片方の比率に合わせて出力するという意味になります。
まとめ
今回は Notion にしたためていた「少しだけリッチな技術記事を書くためのハウツー」を記事にしました！今後もメモとともに拡充する予定です！
紹介したような記法やツールを使うことでよりリッチな記事がかけると思います！ぜひともこの記事を有効活用していただけると嬉しいです！
質問やフィードバックがあれば、ぜひコメントでお知らせください。