執筆の流れ

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

編集環境のセットアップ

リポジトリを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の自動整形をさせたくないコードブロックにはをつけます。

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の結果を確認の上、問題なければ自分でマージして構いません。

編集環境のセットアップ​

ブランチを作る​

コンテンツを作る​

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

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

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