가이드 · 아키텍처

세 갈래 분할

이 툴킷으로 만드는 문서/위키 사이트는 세 부분으로 조립되며, 각 부분은 정확히 한 계층씩 소유합니다. 그 사이의 경계선은 취향이 아닙니다 — 하나하나가, 넘는 순간 이빨을 드러내는 제약을 등에 지고 있습니다.

저장소 셋 · 주인 셋 · 외울 것은 한 줄

§1세 계층, 세 주인

• astro-inkbrush(엔진): 미니멀 CMS입니다 — 브라우저 안에서 블록을 그 자리에서 편집하고, 블록 단위 수정 이력과 되돌리기, 댓글, AI 질의응답·고쳐쓰기·번역, 수신함 가져오기를 제공합니다. 그리고 CMS의 소유로는 어울리지 않아 보이는 것 하나를 더 갖습니다: Markdown 방언과 콘텐츠 가드. 이유는 단단합니다: 편집기가 받아들이는 문법과 페이지가 렌더링하는 문법은 같은 하나여야 하며, 아니라면 "편집기에서는 잘 저장되는데 페이지에서는 잘못 렌더링된다"는 시간문제일 뿐입니다. 그래서 파서 규칙은 엔진 안에 한 번만 쓰이고, 세 곳에서 소비됩니다 — 사이트 렌더링, CMS 저장 검증, CI 검사.
• astro-inkstone(종이 — 이 패키지): 공유되는 외관·파이프라인 계층입니다 — 두 문맥으로 나뉜 2계층 디자인 토큰, 콘텐츠 스타일시트 base.css와 둘러보기 서가 browse.css, 컴포넌트 라이브러리, siteMarkdown 파이프라인 프리셋, 이 정원이 딛고 도는 분류·백링크 헬퍼, Maple Mono CN 코드 폰트 서브셋, 그리고 렌더링 계층 프로브. 사이트 아이덴티티는 하지 않습니다: 브랜드 색, 레이아웃 크롬, 라우팅과 배포는 이 패키지의 소관이 아닙니다.
• 사이트(지금 읽고 계신 이 정원 같은): 아이덴티티 색을 위해 1계층 토큰을 덮어쓰고, 자기 사이드바와 내비게이션 크롬을 소유하며(이 사이트의 구현이 모범 답안입니다), 콘텐츠를 어떻게 조직할지, 라우트가 어떤 모양일지, 어디에 배포할지 결정합니다.

외울 것은 한 줄입니다: 엔진은 편집하고, 종이는 보여 주고, 사이트는 곧 당신입니다.

§2경계선이 이 자리에 놓인 이유

절단면 하나하나가 실제 제약을 등에 지고 있습니다:

방언은 엔진의 것입니다. 플러그인 구성이 사이트와 다른 검사기는 검사기가 없는 것보다 나쁩니다 — 수식 플러그인이 빠진 검사기는 수식의 중괄호를 JSX 표현식으로 오독하고, GFM이 없는 검사기는 표의 파이프를 그냥 통과시킵니다. 문법은 한 번 쓰여 세 곳에서 소비되므로, 결코 어긋날 수 없습니다.

스타일은 종이의 것입니다. 사이트 여럿이 각자 콘텐츠 스타일시트를 유지하면, 대비 수정 하나를 사이트 수만큼 되풀이해야 합니다 — 하나를 빠뜨리면 그 사이트의 작은 글자가 AA 아래로 떨어집니다. 공유 계층에서는 수정 하나가 모든 곳에 내려앉습니다.

아이덴티티는 사이트의 것입니다. 공유 계층이 어느 한 사이트의 브랜드 색을 흡수하는 순간, 다른 모든 사이트는 덮어쓰기로 그 색과 싸워야 합니다. 2계층 토큰이 여기서 나옵니다: 사이트는 1계층 원료 팔레트(--p-*)만 덮어쓰고, 시맨틱 계층과 컴포넌트 계층은 손대지 않은 채 따라옵니다 — 두 계층 팔레트와 테마 참조.

§3둘러보기 장치는 어디에 사는가

지금 여러분이 타고 다니는 내비게이션에도 같은 규율이 적용됩니다. 패키지는 역학을 싣습니다 — createTaxonomy(종류/분야/태그 해석, 허브 상속, 로케일 미러), createBacklinks(연결된 언급 색인), 그리고 랜딩 페이지의 노트 카드와 패싯 행 같은 표시 전용 컴포넌트. 사이트는 어휘와 라우트를 소유합니다: 이 정원의 종류와 분야는 정원 자신의 레지스트리 파일에 살고, /kind/…, /domain/…, /tag/… 페이지는 소비하는 사이트가 복사해 고쳐 쓰는 평범한 Astro 페이지입니다. 같은 분할이 한 층 위에서 반복됩니다: 역학은 패키지에, 의미는 사이트에.

§4사이트가 얻는 것

사이트의 관점에서, 이 패키지에 엔진을 더해 소비하면 다음을 얻습니다:

• astro-inkstone/styles/tokens.css + base.css + browse.css: 토큰 먼저, 그다음 읽기 열, 그다음 둘러보기 서가 — @import 세 줄로 외관 전부;
• siteMarkdown(...): Markdown 파이프라인 전체가 한 줄, 스위치 설명은 시작하기에;
• astro-inkstone/components/ 아래의 컴포넌트, 필요할 때 경로로 임포트;
• astro-inkstone/lib/ 아래의 분류 팩토리와 백링크 빌더, 사이트 자신의 레지스트리에 바인딩;
• WIKI 모드에서는 엔진의 완전한 CMS(이 사이트에서 npm run wiki 명령으로 직접 시험할 수 있습니다);
• 다섯 가지 검사: check-content, check-wikilinks, check-dist(엔진과 함께 배포), ui_probe, contrast_probe(이 패키지와 함께 배포) — 다섯 가지 검사 참조.

이 정원 모든 페이지의 모든 렌더링 효과가 그 분할의 산물입니다 — 노트가 곧 매뉴얼, 매뉴얼이 곧 데모입니다.