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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DokuWiki 개발 시 필수 습관:

1. CSS 수정
2. Ctrl+F5 강제 새로고침
3. 개발자 도구에서 Disable cache 체크
4. 그래도 안 되면 시크릿 모드로 테스트

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

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

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

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

1. 흰 배경 제거 → 파란 테두리 등장
2. 파란 테두리 제거 → 회색 그림자 등장
3. 회색 그림자 제거 → 투명 테두리 등장
4. 투명 테두리 제거 → 드디어 해결

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

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

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

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

1. 클래스 기반 스타일
2. ID 기반 스타일
3. 인라인 스타일
4. 의사 요소
5. 상속된 스타일

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

주의사항:

1. color 속성으로 fallback 색상 반드시 지정
2. webkit 접두사는 크롬/사파리 전용
3. 파이어폭스에서는 다른 방법 필요

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

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

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

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

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

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

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

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

관련 파일:

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

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

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

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

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

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

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

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

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

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

초반의 순진함:

1. “Wiki.js 안 되니까 DokuWiki로 하자!”
2. “userstyle.css에 몇 줄만 추가하면 끝!”

중반의 절망:

1. “왜 CSS가 안 먹히지?”
2. “브레드크럼이 왜 이렇게 끈질기지?”
3. “양파껍질 스타일링 지옥”

후반의 깨달음:

1. “핵폭탄급 선택자 개발”
2. “외과 수술 방식 도입”
3. “AI도 CSS에서 고생한다”

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

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

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

지금 우리가 만든 다크 테마 위키는:

1. index.html과 완벽한 통일감
2. 회사 사람들이 쉽게 편집 가능
3. 실전 경험이 담긴 가이드 문서

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

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

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

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

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

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

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

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

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

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

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