= [Dev] Less

== 빌드 구조

IntelliJ FileWatcher가 `_`로 시작하지 않는 `.less` 파일을 저장할 때 자동으로 같은 이름의 `.css`로 컴파일한다.
`_`로 시작하는 파일은 컴파일 대상이 아니며 `@import`로만 참조된다.

각 `.less` 파일 상단에 `@import "_mixins";` 를 추가해 공용 변수/믹스인을 사용한다.

IntelliJ 없이 손으로 컴파일할 때는 `app/assets` 에서:

[[[#!Vim bash
lessc --source-map wiki.less wiki.css
]]]

커밋돼 있는 `.css`·`.css.map` 과 바이트 단위로 같은 결과가 나온다(2026-08-19 `wiki.less` 로 실측). 다른 옵션을 쓰면 소스맵이 달라져 고치지 않은 파일이 diff 에 나타난다.

=== 원격 `@import url()` 은 컴파일하던 날의 응답이 박힌다
`lessc` 는 `@import url(https://…)` 를 만나면 그 주소를 받아 응답을 `.css` 에 그대로 붙인다. 브라우저가 받는 것은 Google 의 CSS 가 아니라 컴파일하던 날 `lessc` 가 받은 응답이다. Google Fonts 는 요청한 User-Agent 를 보고 답을 고르는데, `lessc` 에게는 `unicode-range` 로 나눈 woff2 대신 굵기마다 TTF 하나를 줬다.

 * `less.less` 는 2026-10-04 까지 `Noto Sans KR` 을 import 했다. `lessc` 가 받은 그 TTF 에는 한글 글리프가 하나도 없었다(라틴 218자). 게다가 바로 아래 `.defaultFont` 규칙이 `'Noto Sans', sans-serif` 로 덮어써서 쓰인 적도 없다. 그래서 뺐다 — 운영 페이지 6개를 지금 CSS 와 뺀 CSS 로 그려 픽셀을 비교해 차이가 없음을 봤다. 한글은 시스템의 sans-serif 로 그려진다.
 * 진짜 한글 웹폰트를 쓰려면 `@import (css) url(…)` 로 브라우저가 직접 받게 해야 한다. 모든 사이트의 한글 모양이 바뀌므로 하지 않았다.
 * 같은 이유로, 손대지 않은 `.less` 를 다시 컴파일해도 Google 이 그 사이 올린 폰트 버전이 들어온다. 2026-10-04 에 `less.less` 를 그대로 다시 컴파일하니 `notosanskr/v39` 가 `v40` 이 됐다. 커밋된 `.css` 와 다른 줄이 그런 주소뿐이면 정상이다.

`.defaultFont()` 를 부르면 그 이름을 가진 것이 '''모두''' 적용된다 — `_mixins.less` 의 믹스인과 `less.less` 의 `.defaultFont` 규칙이 차례로 `font-family` 를 한 줄씩 내놓고, 마지막 줄이 이긴다. 글꼴 순서를 바꾸려면 마지막에 오는 것을 고쳐야 한다.

== 파일 구조

=== 공용 믹스인 (컴파일 안 함)
 * `app/assets/_mixins.less` - 컴파일되는 `.less` 파일 열 개가 첫 줄에서 import (`_paper`·`_wiki_table` 은 `wiki.less` 안에서 들어오므로 직접 import 하지 않는다)
 * `app/assets/_paper.less` - `wiki.less` 가 import (인쇄용 paperContent)
 * `app/assets/_wiki_table.less` - `wiki.less` 가 import (wikiTableSimple 표)

=== 독립 컴파일 파일

[[[#!Table tsv 1 1
파일	내용	CSS 로딩 위치
`less.less`	테마 CSS 변수(`:root`, dark), html/body, navbar, header/footer, toast, hotkey, MacroThemes 등 코어	모든 페이지
`wiki.less`	`.AhaWiki` 위키 콘텐츠, 테이블, TOC, schema, paperContent 등	모든 페이지
`search.less`	`.search`, `.searchBg`, `.autocomplete-*`, `.searchResult`, `.ahaWikiLoader`	모든 페이지 (검색 오버레이가 전역 단축키로 동작)
`kanban.less`	`.InterpreterKanban`, `.kanban-modal` 등 칸반 전체	모든 페이지 (위키 본문에 칸반 매크로가 올 수 있음)
`interpreter.less`	`.Interpreter`, `.Macro`, `.InterpreterRenderMetaWrapper`, `.interpreterMap`	모든 페이지
`adjacent.less`	`svg.graph`, `.adjacentPagesHud`, `.crawlerPreview` 등 인접 페이지 그래프	모든 페이지
`gantt.less`	`.InterpreterGantt` 간트차트	모든 위키 페이지 (`_baseSkeleton`. Admin 화면의 `_baseAdmin` 은 싣지 않는다)
-
`edit.less`	`.AhaWiki .edit`	`edit.scala.html` 에서만
`blame.less`	`.AhaWiki .blame`	`blame.scala.html` 에서만
`diff.less`	`.AhaWiki .diff`	`diff.scala.html` 에서만
]]]

템플릿은 `.css` 를 `/public/wiki.css` 같은 맨 주소가 아니라 `PublicAsset.url` 로 부른다. 주소에 내용 해시가 붙어서 배포한 CSS 가 브라우저에 바로 닿는다 — [Dev Deploying] '''CSS·JS 주소에는 내용 해시가 붙는다'''.