Docusaurus Site Scaffold

SKILL.md

Docusaurus Site Scaffold

Complete scaffold for Docusaurus v3 sites targeting Korean users, deployed to GitHub Pages. Two established structures to choose from based on the project type.

Reference Files

| File | Purpose | |------|---------| | references/docusaurus-config.ts | Config template | | references/sidebars.ts | Sidebar template | | references/deploy.yml | GitHub Actions workflow |

Choosing a Structure

| Pattern | Use when | Example repo | |---------|----------|-------------| | A: English Learning | Flat topic sections, 5-8 categories | jeonck/us-work-english | | B: Knowledge Base | Many topics (10+), grouped navigation, stub-first authoring | jeonck/fw-thinking, jeonck/info-security |

Common Setup Steps

Step 1 — Gather required info

Confirm before writing any files:

• GITHUB_USERNAME — verify with gh auth status (do not guess)
• REPO_NAME — target repository name
• SITE_TITLE — displayed in navbar
• SITE_TAGLINE — subtitle

Step 2 — Bootstrap Docusaurus

npx create-docusaurus@latest . classic --typescript --skip-install
npm install

Step 3 — GitHub Actions workflow

mkdir -p .github/workflows

Read references/deploy.yml → write to .github/workflows/deploy.yml.

Step 4 — Build verification

npm run build

Fix any broken link or MDX errors before continuing.

Step 5 — Git init, create repo, push

git init
git add .
git commit -m "초기 Docusaurus 사이트 설정 - SITE_TITLE"
gh repo create REPO_NAME --public --description "..."
git remote add origin https://github.com/GITHUB_USERNAME/REPO_NAME.git
git push -u origin main

Step 6 — Enable GitHub Pages

Trigger the Actions workflow first (creates gh-pages branch), then enable Pages:

gh workflow run deploy.yml --repo GITHUB_USERNAME/REPO_NAME
# wait ~60s for workflow to complete
gh api repos/GITHUB_USERNAME/REPO_NAME/pages \
  --method POST \
  --input - <<'EOF'
{"source":{"branch":"gh-pages","path":"/"}}
EOF

Site goes live at https://GITHUB_USERNAME.github.io/REPO_NAME/.

Structure A: English Learning Site

Based on jeonck/us-work-english. Best for 5–8 flat topic sections.

Sidebar pattern

Each section gets one named sidebar with collapsed: false:

// sidebars.ts
const sidebars: SidebarsConfig = {
  jobSearchSidebar: [{
    type: 'category', label: '취업 영어', collapsed: false,
    items: ['job-search/intro', 'job-search/resume', ...]
  }],
  workplaceSidebar: [{
    type: 'category', label: '직장 소통', collapsed: false,
    items: ['workplace/intro', 'workplace/email', ...]
  }],
};

Navbar pattern

items: [
  {type: 'docSidebar', sidebarId: 'jobSearchSidebar', label: '취업 영어', position: 'left'},
  {type: 'docSidebar', sidebarId: 'workplaceSidebar', label: '직장 소통', position: 'left'},
]

Docs folder structure

docs/
├── job-search/
│   ├── intro.md        ← sidebar_position: 1
│   ├── resume.md
│   └── interview.md
└── workplace/
    ├── intro.md
    └── email.md

No _category_.json needed — labels are defined directly in sidebars.ts.

Structure B: Knowledge Base Site

Based on jeonck/fw-thinking / jeonck/info-security. Best for 10+ topics with grouped navigation.

Folder naming

Use numeric prefix for auto-ordering:

docs/
├── 01-topic-one/
├── 02-topic-two/
└── 03-topic-three/

Docusaurus strips the numeric prefix from URLs:

• 01-topic-one/intro.md → /docs/topic-one/intro

_category_.json

Keep minimal — label only:

{"label": "01. 주제 이름"}

No link, no collapsed, no position needed.

Sidebar pattern — one sidebar per topic

Each of the 11 topics gets its own autogenerated sidebar. This ensures clicking a topic in the navbar shows ONLY that topic's items:

// sidebars.ts
const sidebars: SidebarsConfig = {
  itGovernanceSidebar:    [{type: 'autogenerated', dirName: '01-it-governance'}],
  enterpriseArchSidebar:  [{type: 'autogenerated', dirName: '02-enterprise-architecture'}],
  legalSidebar:           [{type: 'autogenerated', dirName: '03-legal-compliance'}],
  // ... one per topic
};

Navbar pattern — grouped dropdowns

Group topics into 3–4 dropdown menus in the navbar. Each dropdown item links to the first doc in that topic:

items: [
  {
    type: 'dropdown', label: '거버넌스 & 전략', position: 'left',
    items: [
      {label: '01. IT 거버넌스 및 전략 경영', to: '/docs/it-governance/intro'},
      {label: '02. 엔터프라이즈 아키텍처', to: '/docs/enterprise-architecture/intro'},
      {label: '03. 법규 및 컴플라이언스', to: '/docs/legal-compliance/intro'},
    ],
  },
  // ... more groups
]

When the user navigates to a doc, Docusaurus renders only the sidebar that doc belongs to.

Stub placeholder files

Create placeholder docs for all topics upfront. Users fill them in later:

---
sidebar_position: 2
title: 프레임워크 이름
---

# 프레임워크 이름
**Full English Name**

:::info 작성 예정
이 문서는 작성 중입니다.
:::

sidebarItemsGenerator (docs before categories)

Add to the docs plugin config in docusaurus.config.ts:

docs: {
  sidebarPath: './sidebars.ts',
  async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
    const items = await defaultSidebarItemsGenerator(args);
    function reorder(list: any[]): any[] {
      const docs = list.filter(i => i.type === 'doc');
      const cats = list.filter(i => i.type === 'category').map(c => ({
        ...c, items: reorder(c.items ?? []),
      }));
      const rest = list.filter(i => i.type !== 'doc' && i.type !== 'category');
      return [...docs, ...cats, ...rest];
    }
    return reorder(items);
  },
},

Mermaid Diagrams

Installation

npm install @docusaurus/theme-mermaid

Add to docusaurus.config.ts:

const config: Config = {
  themes: ['@docusaurus/theme-mermaid'],
  markdown: { mermaid: true },
  // ...
  themeConfig: {
    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
  }
};

Rendering rules (from CONTENT_GUIDE.md)

1. Use <br/> for line breaks — never \n

❌ EDM["EDM\n평가·지시·모니터링"]
✅ EDM["EDM<br/>평가·지시·모니터링"]

2. No emojis in subgraph labels — causes parse errors

❌ subgraph GOV["🏛️ 거버넌스 영역"]
✅ subgraph GOV["거버넌스 영역"]

3. Wrap all node labels and arrow labels in ""

✅ A["한글 라벨"] -->|"화살표"| B["결과"]

4. Split & chained arrows into separate lines

❌ COBIT --> STR & OPS & CUL
✅ COBIT --> STR
   COBIT --> OPS
   COBIT --> CUL

Color styling

Add style directives for visual clarity:

flowchart LR
    A["단계 1"] --> B["단계 2"] --> C["단계 3"]

    style A fill:#2563EB,stroke:#1D4ED8,color:#fff
    style B fill:#7C3AED,stroke:#6D28D9,color:#fff
    style C fill:#16A34A,stroke:#15803D,color:#fff

Suggested palette:

• 파랑 #2563EB / 보라 #7C3AED / 주황 #EA580C / 녹색 #16A34A
• 청록 #0891B2 / 네이비 #1E3A5F
• 연한 배경: #EFF6FF(파랑), #F0FDF4(녹색), #FFF7ED(주황)

Bold Text Rules (CONTENT_GUIDE.md)

1. Quotes must go outside bold markers

❌ **"따옴표가 안에 있는 볼드"**
✅ "**따옴표가 밖에 있는 볼드**"

2. Don't bold long strings with special characters — bold each word separately

❌ **거버넌스·관리·위험(EGIT)**
✅ **거버넌스**·**관리**·**위험**(EGIT)

Add CONTENT_GUIDE.md to the project root documenting these rules.

Key Conventions

• trailingSlash: false — required for correct GitHub Pages routing
• Korean locale — i18n: { defaultLocale: 'ko', locales: ['ko'] }
• Blog disabled — set blog: false in preset options for pure doc sites
• onBrokenMarkdownLinks — use markdown.hooks.onBrokenMarkdownLinks (not top-level, deprecated in v4)
• MDX comments — use {/ text /}, never <!-- --> (breaks MDX)
• GitHub username — always verify with gh auth status before using in config
• gh-pages branch — must exist before enabling Pages; trigger workflow first if new repo