メインコンテンツまでスキップ

執筆の流れ

環境構築から執筆、公開までの流れと手順を説明します。

編集環境のセットアップ

リポジトリをGitHub上でフォークし、フォークしたリポジトリをチェックアウトします。(当リポジトリにコミット権限がある方はフォークする必要はありません。)

shell
# 一般の方
git clone git@github.com:自分のアカウント/フォーク先のリポジトリ名.git
# 当プロジェクトにコミット権限がある方
git clone git@github.com:yytypescript/book.git
shell
# 一般の方
git clone git@github.com:自分のアカウント/フォーク先のリポジトリ名.git
# 当プロジェクトにコミット権限がある方
git clone git@github.com:yytypescript/book.git

必要なツールをインストールします。

shell
yarn
shell
yarn

開発サーバーを起動します。

shell
yarn start
shell
yarn start

開発サーバーが起動したら、ブラウザでhttp://localhost:3000を開きます。

ブランチを作る

ブランチを作成します。

bash
git checkout -b ブランチ名
bash
git checkout -b ブランチ名

masterブランチには直接pushできません。そのため変更はブランチで行う必要があります。

コンテンツを作る

新規ページを追加する場合

docsディレクトリに新規ページのMarkdownファイルを追加します。

shell
mkdir -p docs/カテゴリ名/サブカテゴリ名
touch docs/カテゴリ名/サブカテゴリ名/new-page.md
shell
mkdir -p docs/カテゴリ名/サブカテゴリ名
touch docs/カテゴリ名/サブカテゴリ名/new-page.md

sidebars.jsに新規ページへのパスを追加します。パスには拡張子.mdを含めません。

sidebars.js
js
module.exports = {
// ...
tutorialSidebar: [
{
type: "category",
label: "カテゴリ名",
items: [
{
type: "category",
label: "サブカテゴリ名",
items: [
// highlight-next-line
"カテゴリ名/サブカテゴリ名/new-page",
],
},
],
},
],
};
sidebars.js
js
module.exports = {
// ...
tutorialSidebar: [
{
type: "category",
label: "カテゴリ名",
items: [
{
type: "category",
label: "サブカテゴリ名",
items: [
// highlight-next-line
"カテゴリ名/サブカテゴリ名/new-page",
],
},
],
},
],
};

ここまで完了したら、作成したファイルを編集していきます。

既存ページを変更する場合

既存ページを変更する場合は、docsディレクトリから当該ファイルを探して編集してください。

コンテンツ編集時に知っておくとよいこと

📄️ VS Codeで編集する

Markdownファイルを編集するエディターはVS Codeがお勧めです。

📄️ Markdown

Markdownは標準的な記法に加えて、本プロジェクトで独自拡張した仕様があります。

📄️ ファイル構成

どこにどのようなファイルがあるかを説明します。

コミットする

作成したファイルを編集したらコミットします。

shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit -m "「新しいページ」を追加しました。"
shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit -m "「新しいページ」を追加しました。"
tip

このプロジェクトは日本語話者向けなので、コミットメッセージは日本語で構いません。

コミットメッセージの例:

  • 「型注釈」を追加しました。
  • 「関数」にサンプルコードを追加しました。
  • 誤字「使用」を「仕様」に修正しました。

コンテンツを校正する

コードスタイルの校正

Prettierとmarkdownlintで、Markdownの記法スタイルやコードブロック内のTypeScriptコードスタイルを修正します。

shell
yarn markdownlint:fix
yarn prettier:fix
shell
yarn markdownlint:fix
yarn prettier:fix
tip

Prettierの自動整形をさせたくないコードブロックには<!--prettier-ignore-->をつけます。

markdown
<!--prettier-ignore-->
```ts
type Code =
| 1
| 2
| 3;
```
markdown
<!--prettier-ignore-->
```ts
type Code =
| 1
| 2
| 3;
```
tip

markdownlintで指摘されたエラーの詳細はmarkdownlintのドキュメントをご覧ください。

日本語の校正

textlintで日本語に問題がないかチェックします。

shell
yarn textlint
shell
yarn textlint

textlintで問題が指摘された箇所で、変更すべきところを変更します。

tip

textlint指摘箇所をすべて直していい場合はyarn textlint:fixで一括修正できます。

textlintを部分的に無効化する

textlintのエラーが出ない書き方が望ましいです。場合によって、textlintを無効にしたいことがあるかもしれません。無効化したい部分はコメントで囲みます。

markdown
...
<!--textlint-disable prh-->
textlintのprhルールが無効になるエリア
<!--textlint-enable prh-->
...
markdown
...
<!--textlint-disable prh-->
textlintのprhルールが無効になるエリア
<!--textlint-enable prh-->
...

注意点として、コメントの前後には空行が必要です。

NG
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
NG
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
OK
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->
OK
markdown
<!--textlint-disable-->
無効化したいテキスト
<!--textlint-enable-->

校正結果をコミットする

自動修正の結果は差分で確認します。

shell
git diff
shell
git diff
tip

自動修正による変更をもとに戻すには、git checkoutを使います。

自動修正の内容に問題がなければコミットします。

shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit --amend # 直前のコミットに含めて、コミットを1つにする方法です
shell
git add docs/カテゴリ名/サブカテゴリ名/new-page.md
git commit --amend # 直前のコミットに含めて、コミットを1つにする方法です

プルリクエストを送る

caution

プルリクエストを送る前にできるだけコミットが1つになっているか確認してください。

変更内容をpushします。

shell
git push -u origin ブランチ名
shell
git push -u origin ブランチ名

GitHub上でプルリクエストを作成します。プルリクエストが作成されると、CIが走りコードスタイルなどのチェックが行われます。CIに問題がなければメンテナーによってマージされます。マージ権限がある方は、CIの結果を確認の上、問題なければ自分でマージして構いません。

  • 質問する ─ 読んでも分からなかったこと、TypeScriptで分からないこと、お気軽にGitHubまで🙂
  • 問題を報告する ─ 文章やサンプルコードなどの誤植はお知らせください。