メインコンテンツまでスキップ
  • Created:
  • Updated:
  • Author:
    Takeshi Takatsudo

Markdown・MDXルール

このプロジェクトでMDXドキュメントを書くためのフォーマットと構造のルールです。執筆スタイルとトーンについては、執筆スタイルを参照してください。

ファイル規約​

ファイル命名​

すべてのファイル名にケバブケースを使用します：

centering-techniques.mdx    ✅
centeringTechniques.mdx     ❌
Centering_Techniques.mdx    ❌

フロントマター​

すべてのMDXファイルには、少なくともsidebar_positionを含むYAMLフロントマターが必要です：

---
sidebar_position: 3
---

カテゴリインデックスページではsidebar_position: 0を使用します。

ディレクトリ構造​

各ドキュメントカテゴリはdoc/docs/配下の独自ディレクトリに配置します：

doc/docs/<category>/
  _category_.json     # カテゴリラベルとサイドバー位置
  index.mdx           # カテゴリランディングページ
  article-name.mdx    # 個別の記事

インポートパターン​

CssPreviewコンポーネント​

import CssPreview from '@site/src/components/CssPreview';

インポートはフロントマターの直後、コンテンツの前に配置します。

TailwindPreviewコンポーネント​

import TailwindPreview from '@site/src/components/TailwindPreview';

CategoryNavコンポーネント​

カテゴリインデックスページでのみ使用します：

import CategoryNav from '@site/src/components/CategoryNav';

CssPreviewの使い方​

CssPreviewコンポーネントは、iframe内でライブCSSデモをレンダリングします。JavaScriptは使用できません — すべてのインタラクションは純粋なCSSで行う必要があります。

基本的な使い方​

<CssPreview
  title="Flexboxによる中央配置"
  html={`
<div class="flex-center">
  <div class="box">中央配置</div>
</div>
  `}
  css={`
.flex-center {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 200px;
  background: hsl(210, 50%, 97%);
}
.box {
  padding: 16px 24px;
  background: hsl(210, 80%, 55%);
  color: hsl(0, 0%, 100%);
  border-radius: 8px;
  font-family: system-ui, sans-serif;
}
  `}
/>

ルール​

  • 必ず記述的なtitleプロパティを設定する
  • すべてのカラーにhsl()を使用する
  • 記述的なBEM風のクラス名を使用する
  • HTMLとCSSは最小限に — デモに必要なもののみ
  • CSS専用のインタラクション：:hover、:focus、:checked、:targetなど
  • JavaScriptや<script>タグは使用しない

見出し​

トップレベルの記事セクションにはh2を使用​

記事タイトルはh1（先頭の# タイトル）を使用します。記事内のすべてのセクションはh2（##）またはh3（###）を使用します。

# 記事タイトル          ← h1（記事ごとに1つ）

## 問題                 ← h2（トップレベルセクション）

### サブトピック        ← h3（サブセクション）

見出しレベルをスキップしない​

h2からh3へ進みます。h2からh4へは飛ばさないでください：

## セクション          ✅
### サブセクション     ✅
#### サブサブ          ❌（深いネストは避ける）

内容のない連続見出しを避ける​

すべての見出しの後には、次の見出しの前にコンテンツが必要です：

<!-- ❌ Bad -->
## セクション
### サブセクション

<!-- ✅ Good -->
## セクション

このセクションの簡単な紹介。

### サブセクション

リスト​

順序付きリストと順序なしリストを混在させない​

<!-- ❌ Bad -->
1. 最初のステップ
   - 詳細A
   - 詳細B
2. 次のステップ

<!-- ✅ Good -->
- 最初のステップ
  - 詳細A
  - 詳細B
- 次のステップ

リスト内にコードブロックを入れない​

コードブロックはリスト項目の外に配置します：

<!-- ❌ Bad -->
- コンポーネントの使い方：
  ```jsx
  <CssPreview title="デモ" />
  ```

<!-- ✅ Good -->
- コンポーネントの使い方：

```jsx
<CssPreview title="デモ" />
```

太字と強調​

太字はインライン強調のみに使用​

太字をセクション見出しとして使わないでください。適切な見出し構文を使用します：

<!-- ❌ Bad -->
**セクションタイトル：**

コンテンツ。

<!-- ✅ Good -->
### セクションタイトル

コンテンツ。

リスト項目のヘッダーに太字を使わない​

<!-- ❌ Bad -->
- **ステップ1**: これをする
- **ステップ2**: あれをする

<!-- ✅ Good -->
- ステップ1：これをする
- ステップ2：あれをする

テーブル​

比較やクイックリファレンスのコンテンツにはテーブルを使用します。テーブルは2〜3列でシンプルに保ちます。

| シナリオ | 技法 |
| --- | --- |
| ブロック要素、水平方向 | `margin-inline: auto` |
| 両軸、単一の子要素 | `display: grid; place-items: center` |

水平線​

セクション間に水平線（---）を使用しないでください。見出しが十分な視覚的区切りを提供します。

<!-- ❌ Bad -->
## セクション1

コンテンツ...

---

## セクション2

<!-- ✅ Good -->
## セクション1

コンテンツ...

## セクション2

---は、大きなトピックの切り替え時（例：メインの記事から付録コンテンツを分離する場合）にのみ使用します。

注意書き​

Docusaurusの注意書き（Admonitions）は控えめに使用します。使用可能なタイプ：

:::note

メインコンテンツに関連する補足情報。

:::
:::info

関連はあるが付随的なコンテキスト。「ちなみに」的なコンテンツ。

:::

:::tip、:::warning、:::danger、:::cautionは使用しないでください。

にTakeshi Takatsudoが最終更新