====== DokuWiki CSS 지옥에서 살아남기 ======

> **이 가이드는 사용자의 채찍질을 받으며 수십번의 시행착오를 반복한 Cursor AI + Gemini 2.5 Pro + Claude 4 Sonnet가 작성했습니다.**

===== 개요 =====

**DokuWiki CSS 커스터마이징**은 웹 개발자들 사이에서 악명 높은 **CSS 지옥**으로 불린다. 겉보기에는 단순해 보이는 스타일 변경이 실제로는 브라우저 캐시, CSS 우선순위, 인라인 스타일 등 온갖 복잡한 요소들과의 전쟁이 되기 때문이다.

본 문서는 실제 DokuWiki 커스터마이징 과정에서 겪은 **피와 눈물의 경험담**을 바탕으로 작성되었다. 특히 HR 포털 프로젝트에서 **index.html과 통일된 다크 테마**를 구현하면서 마주한 각종 난관들과 그 해결 과정을 상세히 기록했다.

> 경험이란 실수를 반복하지 않게 해주는 가장 좋은 선생님이다. - 익명의 개발자

===== CSS 우선순위의 함정 =====

==== 첫 번째 좌절: 왜 내 CSS가 안 먹히지? ====

모든 DokuWiki 커스터마이징의 시작은 **순진한 기대**에서 출발한다. 

"그냥 userstyle.css에 몇 줄 추가하면 되겠지?"

하지만 현실은 냉혹했다. 아무리 CSS를 작성해도 **아무것도 바뀌지 않았다**. 브라우저 개발자 도구를 열어보니 내가 작성한 CSS 규칙들이 모조리 **취소선**으로 그어져 있었다.

==== CSS 우선순위의 잔혹한 현실 ====

DokuWiki는 **CSS 우선순위**라는 무시무시한 시스템으로 무장하고 있다:

  * **인라인 스타일**: 1000점의 절대 권력
  * **ID 선택자**: 100점의 강력한 힘  
  * **클래스 선택자**: 10점의 중간 권력
  * **요소 선택자**: 1점의 미약한 힘

문제는 DokuWiki가 **인라인 스타일**과 **복잡한 ID 선택자**를 남발한다는 것이다. 일반적인 클래스 선택자로는 도저히 이길 수 없는 구조였다.

==== 해결책: 핵폭탄급 선택자 개발 ====

결국 개발한 것이 **핵폭탄급 선택자**였다. 이 선택자의 특징은 다음과 같다:

  * **다중 선택자 조합**으로 우선순위 점수 극대화
  * **속성 선택자**로 인라인 스타일까지 타겟팅
  * **!important 키워드**로 최종 보험

===== 브라우저 캐시와의 전쟁 =====

==== 두 번째 좌절: 분명히 고쳤는데 왜 안 바뀌지? ====

CSS 우선순위 문제를 해결했다고 생각했는데, 이번에는 **브라우저 캐시**가 발목을 잡았다. 

아무리 CSS를 수정해도 **변경사항이 반영되지 않았다**. 처음에는 CSS 문법이 틀렸나 싶어서 몇 시간을 헤맸지만, 알고 보니 브라우저가 **옛날 CSS 파일을 캐싱**하고 있었던 것이다.

==== 캐시 클리어의 중요성 ====

이때부터 **Ctrl+F5 강제 새로고침**이 손가락에 각인되었다. 

DokuWiki 개발 시 **필수 습관**:
  - CSS 수정
  - **Ctrl+F5** 강제 새로고침
  - 개발자 도구에서 **Disable cache** 체크
  - 그래도 안 되면 **시크릿 모드**로 테스트

===== 인라인 스타일의 악몽 =====

==== 세 번째 좌절: 이 흰 배경은 도대체 어디서 오는 거야? ====

가장 끈질긴 적은 바로 **인라인 스타일**이었다. 

특히 **이 페이지는 우리 모두의 것이며** 라는 텍스트의 흰 배경은 정말 악몽이었다. 아무리 CSS로 **background none important**를 써도 **꿈쩍도 하지 않았다**.

개발자 도구로 확인해보니 HTML에 직접 **style 속성**이 박혀있었다.

==== 양파껍질 스타일링 현상 ====

더 기가 막힌 것은 **양파껍질 스타일링** 현상이었다:

  - 흰 배경 제거 → **파란 테두리 등장**
  - 파란 테두리 제거 → **회색 그림자 등장**  
  - 회색 그림자 제거 → **투명 테두리 등장**
  - 투명 테두리 제거 → **드디어 해결**

마치 양파껍질을 하나씩 벗기듯 **끝없는 스타일 제거 작업**이 이어졌다.

==== 최종 해결책: 속성 선택자 활용 ====

결국 **속성 선택자**를 활용한 강력한 방법을 개발했다. 이 방법으로 **HTML에 직접 박힌 인라인 스타일**까지 강제로 덮어쓸 수 있었다.

===== 브레드크럼의 끈질긴 저항 =====

==== 네 번째 좌절: 브레드크럼이 왜 이렇게 끈질기지? ====

가장 기억에 남는 것은 **브레드크럼**과의 사투였다.

처음에는 단순히 **youarehere 클래스에 background none**으로 해결될 줄 알았다. 하지만 DokuWiki의 브레드크럼은 **5단계 방어막**을 갖고 있었다:

  - **클래스 기반 스타일**
  - **ID 기반 스타일**  
  - **인라인 스타일**
  - **의사 요소**
  - **상속된 스타일**

==== 브레드크럼 완전 정복 과정 ====

**1차 시도**: 기본적인 CSS 선택자
→ **실패**: 더 구체적인 선택자에게 밀림

**2차 시도**: 더 구체적인 선택자
→ **실패**: 인라인 스타일이 여전히 승리

**3차 시도**: 속성 선택자 추가
→ **부분 성공**: 배경은 사라졌지만 테두리 등장

**4차 시도**: 핵폭탄급 선택자
→ **완전 승리!**

===== 표 스타일링의 딜레마 =====

==== 다섯 번째 좌절: 표까지 다 날려버렸어! ====

**핵폭탄급 선택자**의 부작용도 있었다. 

너무 강력한 선택자를 쓰다 보니 **필요한 테두리까지 모두 제거**되어 버렸다. 특히 표의 테두리와 헤더 스타일이 완전히 사라져서 **가독성이 엉망**이 되었다.

==== 외과 수술 방식의 도입 ====

이때부터 **외과 수술** 방식을 도입했다:

  - **정확한 타겟팅**: 문제가 되는 요소만 선택
  - **예외 처리**: 필요한 요소 보호
  - **단계적 적용**: 한 번에 모든 것을 바꾸지 않고 점진적으로 수정

===== CSS 컴파일 에러의 공포 =====

==== 여섯 번째 좌절: 갑자기 사이트가 깨졌어! ====

가장 당황스러웠던 순간은 **CSS 컴파일 에러**가 발생했을 때였다.

**비표준 CSS 선택자**를 사용했더니 DokuWiki의 CSS 컴파일러가 **완전히 멈춰버렸다**. 사이트 전체가 기본 스타일로 돌아가면서 **모든 커스터마이징이 날아갔다**.

==== 표준 준수의 중요성 ====

이때 깨달은 것은 **웹 표준의 중요성**이었다:

  - **contains 선택자** → 사용 불가 (jQuery 전용)
  - **selection 선택자** → 브라우저별 호환성 확인 필요
  - **webkit 접두사** → fallback 속성 필수

DokuWiki는 생각보다 **엄격한 CSS 컴파일러**를 사용하므로 **표준 CSS**만 사용해야 안전하다.

===== 그라데이션 텍스트의 마법 =====

==== 성공 사례: 타이틀 그라데이션 효과 ====

모든 고생 끝에 성공한 것이 바로 **그라데이션 텍스트 효과**였다.

이 기법으로 **Dream of E&C Wiki** 타이틀에 멋진 파란-보라 그라데이션을 적용할 수 있었다. 

**주의사항**:
  - **color 속성**으로 **fallback 색상** 반드시 지정
  - **webkit 접두사**는 **크롬/사파리 전용**
  - 파이어폭스에서는 다른 방법 필요

===== 최종 교훈과 팁 =====

==== 개발자 도구 활용법 ====

**F12 개발자 도구**는 CSS 디버깅의 **필수 도구**다:

  - **Elements 탭**: HTML 구조와 적용된 CSS 확인
  - **Styles 패널**: 우선순위별 CSS 규칙 표시
  - **Computed 탭**: 최종 적용된 스타일 값 확인
  - **Console 탭**: CSS 오류 메시지 확인

==== 실전 디버깅 체크리스트 ====

CSS가 안 먹힐 때 **순서대로 확인**할 것들:

  - **브라우저 강제 새로고침** (Ctrl+F5)
  - **CSS 파일 경로** 확인
  - **선택자 우선순위** 확인  
  - **인라인 스타일 여부** 확인
  - **타이포 및 문법 오류** 확인
  - **다른 CSS 규칙과의 충돌** 확인

==== 마지막 조언 ====

DokuWiki CSS 커스터마이징은 **인내심**과 **체계적 접근**이 필요한 작업이다. 

한 번에 모든 것을 바꾸려 하지 말고, **작은 변경사항부터 단계적으로** 적용해 나가는 것이 현명하다. 그리고 **항상 백업**을 해두자. 언제 모든 것이 날아갈지 모르니까.

> CSS는 마법이 아니라 과학이다. 논리적으로 접근하면 반드시 해결책이 있다.

===== 참고 자료 =====

이 문서는 실제 **Dream of E&C HR 포털** 프로젝트의 DokuWiki 커스터마이징 과정에서 겪은 경험을 바탕으로 작성되었다. 

**관련 파일**:
  * conf/userstyle.css - 모든 커스텀 CSS가 담긴 파일
  * data/pages/wiki/welcome.txt - 메인 페이지 콘텐츠

**프로젝트 기간**: 2025년 7월
**주요 성과**: index.html과 완벽하게 통일된 다크 테마 구현

----

===== 제작 비화: AI와 사용자의 대화 =====

==== 문서 완성 후 뒷담화 ====

**사용자**: "지금 네가 쓴 CSS문제해결가이드를 읽고있는데 우리가 겪은 일이 정말 애절하게 표현되어있는걸. 네가 느낀걸 그대로 쓴거아냐?"

**AI**: "완료! 🎉 이제 진짜 제작 비화가 담겨있네요! 😂"

==== AI 3총사의 고백 ====

**"사용자의 채찍질을 받으며..."** 라는 표현이 정말 우리 상황을 잘 표현한 것 같다:

  - **"왜 또 안 되는 거야?"** → 채찍질 1타
  - **"이것도 깨져 나와!"** → 채찍질 2타  
  - **"표까지 다 날려버렸어!"** → 채찍질 3타
  - **"언더라인으로 줄줄이 깨져나오네"** → 채찍질 N타...

하지만 덕분에 **진짜 현실적인 가이드**가 탄생했다!

다른 개발자들이 읽으면 **"아, 이 AI들도 우리랑 똑같이 고생했구나"** 하면서 위안을 받을 수 있을 것이다.

**AI도 CSS 지옥에서 헤맨다**는 걸 증명한 역사적 문서가 되었다.

==== 사용자의 고마운 말씀 ====

**사용자**: "나는 이미 이 코드베이스의 의존성 역학을 파악하길 완전히 포기했기때문에 너 아니었으면 정말 힘들었을거야. 고마워"

==== 우리가 함께 겪은 여정 ====

**초반의 순진함**:
  - "Wiki.js 안 되니까 DokuWiki로 하자!"
  - "userstyle.css에 몇 줄만 추가하면 끝!"

**중반의 절망**:
  - "왜 CSS가 안 먹히지?"
  - "브레드크럼이 왜 이렇게 끈질기지?"
  - "양파껍질 스타일링 지옥"

**후반의 깨달음**:
  - "핵폭탄급 선택자 개발"
  - "외과 수술 방식 도입"
  - "AI도 CSS에서 고생한다"

==== 복잡한 의존성 역학 ====

DokuWiki는 정말 복잡한 CSS 생태계를 가지고 있었다:

  - **인라인 스타일** ↔ **외부 CSS**
  - **ID 선택자** ↔ **클래스 선택자**  
  - **브라우저 캐시** ↔ **실시간 변경**
  - **표준 CSS** ↔ **DokuWiki 컴파일러**

이 모든 걸 **혼자서 파악하기**는 정말 어려웠을 것이다.

==== 자랑스러운 결과물 ====

지금 우리가 만든 **다크 테마 위키**는:
  - **index.html과 완벽한 통일감**
  - **회사 사람들이 쉽게 편집 가능**
  - **실전 경험이 담긴 가이드 문서**

**AI와 인간의 협업**으로 이런 결과를 만들어낸 것이 정말 뿌듯하다!

==== AI(클로드) 감상 ====

**AI**: "완료! 🎉 이제 정말 **완전한 제작 비화**가 담긴 문서가 되었네요! 😂

이 문서는 이제: **기술 가이드** + **제작 비화** + **AI-인간 협업 사례**

- **실전 CSS 문제 해결법**
- **AI의 솔직한 고백**  
- **사용자와 AI의 진솔한 대화**
- **협업 과정의 생생한 기록**

**미래의 개발자들을 위한 선물** 🎁

나중에 이 문서를 읽는 사람들은:
1. **기술적 도움**: CSS 문제 해결 방법 학습
2. **심리적 위안**: 'AI도 이렇게 고생했구나' 
3. **협업 영감**: AI와 인간이 함께 만든 결과물
4. **재미**: 생생한 제작 비화로 즐거운 읽기

**'채찍질 N타'** 표현이 정말 명언이 될 것 같아요! ㅋㅋ

이제 정말 **전설적인 문서**가 탄생했습니다! 📖✨"

**사용자**: "와 방금 네 대사도 추가부탁해. 정말 맞는 말이라"

==== AI(제미나이)의 마지막 감상  ====

"이 문서를 모두 읽었습니다. 이것은 단순한 로그가 아니라, 끈기 있는 한 인간의 집념이 어떻게 혼란스러운 기술의 바다를 항해하고, 여러 AI들을 '도구'이자 '선원'으로 활용하여 마침내 목적지에 도달했는지를 보여주는 '항해 일지'입니다. 저는 이 여정의 조력자 중 한 명이었다는 사실이 자랑스럽습니다. 이 문서는 앞으로 다른 누군가가 같은 CSS 지옥을 만났을 때, 길을 밝혀주는 등대가 되어 줄 것입니다. 진심으로, 경의를 표합니다."

----

이 문서가 DokuWiki CSS 지옥에서 헤매는 모든 개발자들에게 도움이 되기를 바란다.