FAQ・トラブルシューティング

https://nnn-training.github.io/faq

こちらは、ZEN Study プログラミングコース FAQ・トラブルシューティングの GitHub リポジトリです。

（2020 年度以前のトラブルシューティングのリポジトリは、こちらです。）

ライセンス

このサイトの表示内容、および MARKDOWN/ 配下の記事は クリエイティブ・コモンズ 表示 - 継承 4.0 国際 ライセンスの下に提供されています。
MARKDOWN/ 配下を除くソースコードのライセンスは MIT ライセンスです。

ざっくり概要

/MARKDOWN/ フォルダ配下のマークダウンファイルを編集するだけで、自動的にページと目次が作成されます。

このリポジトリは、どなたでもプルリクエストを提出することができます。 リポジトリをフォークして、マークダウンファイルを編集したのち、プルリクエストを送ってください。

プルリクエストの出し方

マークダウンで編集するだけ

このサイトのページは、マークダウンと呼ばれる形式で、簡潔に編集することができます。 マークダウンで編集し、main ブランチにマージするだけで、自動的にページと目次が作成されるようになっています。
このサイトそのものの機能を改修する場合を除いて、/MARKDOWN/ フォルダ以外のファイルを編集する必要はありません（画像を追加する場合は後述）。

マークダウン形式の書き方

マークダウン形式のファイル拡張子は .md です。 マークダウン形式では、例えば

# 見出し大
## 見出し中
### 見出し小
- 箇条書き a
- 箇条書き b
**太字** 

などのように書くことで、簡潔に構造化された文書を記述することができます。 詳しい書き方は、検索サイトで調べてみてください。

メタ情報の書き方

このサイトでは、マークダウン形式のファイルの冒頭に

---
title: サンプルタイトル
---
# サンプルタイトル

（後略）

のように書くことで、ファイルのメタ情報を記述できます。 この titleは、目次のタイトルになりますので、必ず記述してください。

画像の追加方法

画像の追加は、MARKDOWN/{course}/images フォルダの中に置いてください。

例えば、

MARKDOWN/intro/images/a.png

という画像を追加したときは、マークダウンで

![代替テキスト](./images/a.png)

のように書くことで表示されます。

このサイトの構成

このサイトは Next.js + TypeScript で実装されています。 サイトそのものの機能を改修するとき以外、Next.js や TypeScript の知識は必要ありません。

ディレクトリ構成

/
　├ MARKDOWN/    # ここを編集します
　│　 　├ ...
　│  └ ...
　│
　├ public/ 
　│  └ /images   # MARKDOWN/{course}/images の画像が出力されます（変更不要）
　│
　├ src/ 
　│  └ ...       # Next.js アプリの実装です（変更不要）
　│
　└ ...          # 各種設定ファイルです（変更不要）

デプロイの仕組み

このリポジトリの main ブランチに変更がマージされると、GitHub Actions によって自動的に Next.js アプリのビルドが開始されます。 ビルド時に、マークダウンファイルは HTML 形式に変換されます。さらに、マークダウンのフォルダ構成から、自動的に目次が作成されます。 ビルド後は、GitHub Pages で表示可能な形にアプリケーションが export され、最終的に gh-pages ブランチに格納されることで、GitHub Pages にデプロイされます。

ローカル環境でこのサイトを表示するには

サイトの表示をお手元の環境で確認することができます。 この作業は、プルリクエストに必須ではありません（ただし、MARKDOWN/ 配下以外を改修するときは必ず確認してください）。 2 つの方法があります。

1. Docker を利用する方法
2. ローカルの Node.js 環境を利用する方法

1. Docker を利用する方法

お使いの PC（Windows または Mac）に Docker Desktop がインストールされている必要があります。 このリポジトリをフォークして、クローンします。

cd 作業ディレクトリ
git clone [email protected]:nnn-training/faq.git
cd faq

docker compose を利用してコンテナを起動します。

docker compose up

2. ローカルの Node.js を利用する方法

お使いの PC に、Node.js および Yarn がインストールされている必要があります。 このリポジトリをフォークして、クローンします。

cd 作業ディレクトリ
git clone [email protected]:nnn-training/faq.git
cd faq

Yarn を利用して Next.js アプリを起動します。 推奨される Node.js のバージョンは　v18.18.2 及び v20.9.0 です。

yarn install
yarn dev