Ming Light Controller Docs

Ming Light Controller(MLC) 사용 설명서. Docusaurus 3 + i18n (한국어 / English / 日本語).

MLC 는 MingToon 재질을 쓰는 아바타에 VRChat 표현 메뉴를 만들어 주는 별매 Unity 애드온입니다.

배포: https://studioraming.github.io/minglightcontroller-docs/

로컬 실행

npm install               # 처음 한 번 (락파일 그대로 쓰려면 npm ci)
npm start                 # 한국어 (기본)
npm start -- --locale en  # 다른 로케일은 개별 실행
npm run build             # 세 로케일 전부 빌드 + 링크·앵커 검사
npm run serve             # 빌드 결과 미리보기

npm run build 가 배포 게이트입니다. onBrokenLinks 와 onBrokenAnchors 가 throw 라서, 죽은 링크나 없는 앵커가 하나라도 있으면 빌드가 실패합니다.

번역본 검사도 함께 돌립니다.

node scripts/check-translations.mjs en
node scripts/check-translations.mjs ja

세 명령이 모두 통과해야 배포합니다.

문서 구조

경로	내용
`docs/`	한국어 본문 (단일 소스, 기본 로케일)
`i18n/en/docusaurus-plugin-content-docs/current/`	영어 본문 — `docs/` 와 파일 단위로 1:1
`i18n/ja/docusaurus-plugin-content-docs/current/`	일본어 본문 — 같은 규칙
`i18n/<locale>/docusaurus-theme-classic/`	navbar · footer 문자열
`i18n/<locale>/code.json`	테마 UI 문자열
`sidebars.js`	사이드바 구성 (카테고리 라벨은 한국어 원본)
`docusaurus.config.js`	`MLC_VERSION` 상수가 여기 하나
`src/remark/auto-link-terms.mjs`	용어 자동 링크 (한국어 본문 전용)
`src/css/custom.css`	용어 링크 · 버전 배지 · 패치노트 목록 스타일
`scripts/new-patch-note.mjs`	패치노트 3개 국어 스캐폴딩
`scripts/check-translations.mjs`	번역본 불변식 검사
`.github/workflows/deploy.yml`	GitHub Pages 배포

현재 본문은 14개 페이지(intro · getting-started 2 · guides 6 · workflow 1 · platforms 1 · troubleshooting · legal 1 · changelog/0.1.0)이고, 세 로케일이 파일 단위로 1:1 입니다. 사이드바 순서는 intro → 시작하기 → 메뉴 만들기 → 내보내기 → 플랫폼 → 문제 해결 → 패치노트 → 법적 고지 입니다. legal/third-party-credits 는 맨 아래 법적 고지 카테고리에 있고, 푸터와 intro 에서도 링크합니다.

문서 작성 규칙

각 페이지 첫 줄에 "이 문서를 읽으면 할 수 있는 것" 한 줄.
절차는 번호 목록 + 메뉴 전체 경로(GameObject > Studio Raming > Ming Light Controller > ...).
스텝마다 "이렇게 되면 정상입니다" 확인 문장. 시각자료 없이도 검증 가능하게.
스크린샷 자리는  HTML 주석으로 표시해 둡니다. static/img/screenshots/ 에 이미지를 넣고 주석을 ![설명](/img/screenshots/파일명.png) 으로 바꾸세요.

⚠️ {/* SCREENSHOT: … */} (MDX 표현식 주석)은 쓰지 마세요. markdown.format: 'detect' 라서 .md 는 MDX 표현식을 파싱하지 않는 CommonMark 로 처리됩니다. 그래서 {/* … */} 는 주석이 아니라 본문 텍스트로 그대로 렌더링되고 검색 인덱스에도 들어갑니다. 빌드는 성공하므로 눈으로 보기 전까지 모릅니다. 확인:
```
npm run build && grep -rn "SCREENSHOT" build/index.html   # 결과가 있으면 새어 나온 것
```
문서 간 링크는 절대 경로(/getting-started/installation)를 씁니다. 상대 .md 링크는 로케일 폴백에서 깨집니다.
사용자용 용어는 MLC 가 인스펙터·창·메뉴에 실제로 표시하는 문구만 씁니다. 내부 클래스명·함수명은 문서에 쓰지 않습니다.

번역

한국어가 원본입니다. docs/ 에 먼저 쓰고, 그다음 i18n/en·i18n/ja 에 같은 경로로 씁니다. 한 언어라도 비우면 그 페이지는 한국어로 폴백되어, 번역된 것처럼 보이면서 실제로는 안 된 상태가 됩니다.
링크와 앵커는 세 언어가 동일합니다. 앵커는 한국어 원본 그대로 씁니다 — 영어 페이지에서도 ](/guides/menu#부착).
명시적 heading id {#...} 는 번역하지 않습니다. 제목 문구만 번역합니다.
frontmatter 의 id·slug·sidebar_position 은 세 언어가 같아야 합니다. title·sidebar_label·description 만 번역합니다.
Admonition 종류와 개수도 세 언어가 같아야 합니다.

scripts/check-translations.mjs 가 위 불변식(heading id · admonition 마커 · 링크 URL · frontmatter)을 기계적으로 검사합니다. 통과하지 못하면 배포하지 않습니다.

Admonition 문법 — v3 형식만 씁니다

:::tip[제목]
본문
:::

Docusaurus v2 의 :::tip 제목(대괄호 없음)은 v3 에서 지시자로 파싱되지 않고 :::tip 제목 그대로 화면에 찍힙니다. 빌드는 성공하므로 눈으로 보기 전까지 모릅니다.

확인:

grep -rn "^:::[a-z]\+ " docs   # 결과가 있으면 v2 문법이 남아 있는 것

용어 자동 링크

src/remark/auto-link-terms.mjs 가 용어집 하나를 들고 빌드 때 링크를 붙입니다. 본문 마크다운에는 링크를 박지 않으므로, 페이지가 옮겨지면 용어집 한 곳만 고치면 됩니다.

규칙:

페이지마다 첫 등장 한 번만 링크. 문단이 파란 벽이 되지 않게
제목 · 코드 · 이미 걸린 링크 · admonition 제목 안에서는 링크하지 않음
자기 페이지로는 링크하지 않음
긴 용어 우선 — 긴 용어가 짧은 용어로 쪼개지지 않음
ASCII 용어는 단어 경계를 봄

GLOSSARY 는 '용어': '/경로' 형태입니다. 앵커를 붙여도 되지만 명시적 heading id({#...})만 씁니다 — 그것만 check-translations.mjs 가 세 언어에서 동일하게 유지하고, 자동 생성 id 는 언어마다 달라져 onBrokenAnchors: 'throw' 로 빌드가 죽습니다. 스타일은 src/css/custom.css 의 .mlc-term — 본문 색을 유지하고 점선 밑줄만 답니다.

검색

@easyops-cn/docusaurus-search-local 로 오프라인 검색을 씁니다. 인덱스가 사이트에 함께 빌드되므로 외부 서비스로 나가는 것이 없고, 크롤러가 사이트에 접근할 필요도 없습니다.

로케일마다 인덱스가 하나씩 생기고, 한국어·일본어는 각자의 lunr 토크나이저를 씁니다. 개발 서버(npm start)에서는 인덱스가 만들어지지 않으므로, 검색을 확인하려면 npm run build && npm run serve 를 쓰세요.

패치노트 배선

패치노트 경로는 켜져 있습니다 — sidebars.js 의 패치노트 카테고리, navbar 의 패치노트 링크와 v… 배지가 모두 살아 있고 docs/changelog/0.1.0.md 가 배지의 대상입니다. MLC_VERSION 을 올릴 때는 그 버전의 패치노트 페이지를 먼저 만드세요. 배지가 /changelog/<버전> 으로 직행하고 onBrokenLinks: 'throw' 라서, 페이지 없이 버전만 올리면 빌드가 죽습니다.

다음 버전을 추가하는 순서:

node scripts/new-patch-note.mjs 0.1.1 — 한국어·영어·일본어 세 파일이 docs/changelog/_template.md 에서 생성되고 id·sidebar_position·slug 는 스크립트가 계산합니다. 손으로 만들지 마세요 — sidebar_position 을 틀리면 버전 순서가 뒤집힙니다 (음수 버전 코드로 최신이 위에 옵니다).

sidebars.js 에 패치노트 카테고리를 추가합니다.

{
  type: 'category',
  label: '패치노트',
  link: {
    type: 'generated-index',
    slug: '/changelog',
    title: '패치노트',
    description: '버전별 변경 사항입니다. 최신 버전이 위에 있습니다.',
  },
  items: [{type: 'autogenerated', dirName: 'changelog'}],
},

docusaurus.config.js navbar 의 주석 처리된 두 항목(패치노트 링크와 v… 배지)을 되살립니다.
MLC_VERSION 을 그 버전으로 올립니다.
npm run write-translations 를 한 번 돌려 새 i18n 키를 만들고, 세 로케일의 current.json(카테고리 라벨)과 navbar.json(배지 라벨)을 채웁니다.
npm run build 로 확인합니다.

작성 규칙 전문은 docs/changelog/_template.md 위쪽 주석에 있습니다. 요약하면:

세 언어를 항상 함께 채웁니다.
섹션 순서: 업그레이드 시 확인할 것 → 새 기능 → 변경 → 개선 → 수정 → 문서. 해당 없는 섹션은 통째로 지웁니다.
업그레이드 시 확인할 것 에는 기존 작업물이 깨지거나 동작이 달라지는 것만 씁니다.
항목은 한 줄. 배경 설명은 문서 페이지로 링크하고 결론만 남깁니다.
링크 앵커는 세 언어 모두 한국어 원본 그대로 씁니다.

_ 로 시작하는 파일(_template.md)은 사이트에 나오지 않고 번역 검사에서도 제외됩니다.

편집 권한

문서에 "이 페이지 편집" 링크를 두지 않습니다(editUrl 미설정). 독자에게 편집 진입점이 노출되지 않습니다.
저장소의 Issues · Wiki · Projects 는 끕니다.
push 권한은 StudioRaming 한 계정뿐입니다.

배포 — GitHub Pages

main 에 푸시하면 .github/workflows/deploy.yml 이 npm ci → npm run build → 아티팩트 업로드 → 배포 순서로 자동 실행됩니다. 수동 실행은 Actions 탭의 Run workflow(workflow_dispatch).

처음 한 번만 설정이 필요합니다.

GitHub 에서 StudioRaming/minglightcontroller-docs 저장소를 만듭니다 (Public 권장 — Private 은 GitHub Pages 에 유료 플랜이 필요합니다). README·.gitignore·라이선스는 추가하지 마세요. 이미 로컬에 있습니다.

밀어 넣습니다.

git init
git add -A
git commit -m "Initial docs site for Ming Light Controller"
git branch -M main
git remote add origin https://github.com/StudioRaming/minglightcontroller-docs.git
git push -u origin main

저장소 → Settings → Pages → Build and deployment → Source 를 GitHub Actions 로 바꿉니다. (기본값인 "Deploy from a branch" 가 아닙니다.)
Actions 탭에서 Deploy to GitHub Pages 워크플로가 도는지 봅니다.

끝나면 https://studioraming.github.io/minglightcontroller-docs/ 에서 열립니다.

주소를 바꿔야 한다면

docusaurus.config.js 의 url 과 baseUrl 두 값이 실제 주소와 맞아야 합니다. 안 맞으면 사이트가 뜨긴 하지만 CSS·JS 경로가 깨집니다.

배포 위치	`url`	`baseUrl`
`studioraming.github.io/minglightcontroller-docs` (현재)	`https://studioraming.github.io`	`/minglightcontroller-docs/`
커스텀 도메인 루트	`https://docs.example.com`	`/`

커스텀 도메인을 쓰면 static/CNAME 파일에 도메인을 한 줄로 넣습니다.

문의

studioraming@gmail.com

Navigation Menu

Repository files navigation

Ming Light Controller Docs

로컬 실행

문서 구조

문서 작성 규칙

번역

Admonition 문법 — v3 형식만 씁니다

용어 자동 링크

검색

패치노트 배선

편집 권한

배포 — GitHub Pages

주소를 바꿔야 한다면

문의

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
i18n		i18n
scripts		scripts
src		src
static		static
.gitignore		.gitignore
README.md		README.md
docusaurus.config.js		docusaurus.config.js
package-lock.json		package-lock.json
package.json		package.json
sidebars.js		sidebars.js

Latest commit

History

Folders and files

Repository files navigation

Ming Light Controller Docs

로컬 실행

문서 구조

문서 작성 규칙

번역

Admonition 문법 — v3 형식만 씁니다

용어 자동 링크

검색

패치노트 배선

편집 권한

배포 — GitHub Pages

주소를 바꿔야 한다면

문의

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages