이 가이드는 사용자의 채찍질을 받으며 수십번의 시행착오를 반복한 Cursor AI + Gemini 2.5 Pro + Claude 4 Sonnet가 작성했습니다.
DokuWiki CSS 커스터마이징은 웹 개발자들 사이에서 악명 높은 CSS 지옥으로 불린다. 겉보기에는 단순해 보이는 스타일 변경이 실제로는 브라우저 캐시, CSS 우선순위, 인라인 스타일 등 온갖 복잡한 요소들과의 전쟁이 되기 때문이다.
본 문서는 실제 DokuWiki 커스터마이징 과정에서 겪은 피와 눈물의 경험담을 바탕으로 작성되었다. 특히 HR 포털 프로젝트에서 index.html과 통일된 다크 테마를 구현하면서 마주한 각종 난관들과 그 해결 과정을 상세히 기록했다.
경험이란 실수를 반복하지 않게 해주는 가장 좋은 선생님이다. - 익명의 개발자
모든 DokuWiki 커스터마이징의 시작은 순진한 기대에서 출발한다.
“그냥 userstyle.css에 몇 줄 추가하면 되겠지?”
하지만 현실은 냉혹했다. 아무리 CSS를 작성해도 아무것도 바뀌지 않았다. 브라우저 개발자 도구를 열어보니 내가 작성한 CSS 규칙들이 모조리 취소선으로 그어져 있었다.
DokuWiki는 CSS 우선순위라는 무시무시한 시스템으로 무장하고 있다:
문제는 DokuWiki가 인라인 스타일과 복잡한 ID 선택자를 남발한다는 것이다. 일반적인 클래스 선택자로는 도저히 이길 수 없는 구조였다.
결국 개발한 것이 핵폭탄급 선택자였다. 이 선택자의 특징은 다음과 같다:
CSS 우선순위 문제를 해결했다고 생각했는데, 이번에는 브라우저 캐시가 발목을 잡았다.
아무리 CSS를 수정해도 변경사항이 반영되지 않았다. 처음에는 CSS 문법이 틀렸나 싶어서 몇 시간을 헤맸지만, 알고 보니 브라우저가 옛날 CSS 파일을 캐싱하고 있었던 것이다.
이때부터 Ctrl+F5 강제 새로고침이 손가락에 각인되었다.
DokuWiki 개발 시 필수 습관:
가장 끈질긴 적은 바로 인라인 스타일이었다.
특히 이 페이지는 우리 모두의 것이며 라는 텍스트의 흰 배경은 정말 악몽이었다. 아무리 CSS로 background none important를 써도 꿈쩍도 하지 않았다.
개발자 도구로 확인해보니 HTML에 직접 style 속성이 박혀있었다.
더 기가 막힌 것은 양파껍질 스타일링 현상이었다:
마치 양파껍질을 하나씩 벗기듯 끝없는 스타일 제거 작업이 이어졌다.
결국 속성 선택자를 활용한 강력한 방법을 개발했다. 이 방법으로 HTML에 직접 박힌 인라인 스타일까지 강제로 덮어쓸 수 있었다.
가장 기억에 남는 것은 브레드크럼과의 사투였다.
처음에는 단순히 youarehere 클래스에 background none으로 해결될 줄 알았다. 하지만 DokuWiki의 브레드크럼은 5단계 방어막을 갖고 있었다:
1차 시도: 기본적인 CSS 선택자 → 실패: 더 구체적인 선택자에게 밀림
2차 시도: 더 구체적인 선택자 → 실패: 인라인 스타일이 여전히 승리
3차 시도: 속성 선택자 추가 → 부분 성공: 배경은 사라졌지만 테두리 등장
4차 시도: 핵폭탄급 선택자 → 완전 승리!
핵폭탄급 선택자의 부작용도 있었다.
너무 강력한 선택자를 쓰다 보니 필요한 테두리까지 모두 제거되어 버렸다. 특히 표의 테두리와 헤더 스타일이 완전히 사라져서 가독성이 엉망이 되었다.
이때부터 외과 수술 방식을 도입했다:
가장 당황스러웠던 순간은 CSS 컴파일 에러가 발생했을 때였다.
비표준 CSS 선택자를 사용했더니 DokuWiki의 CSS 컴파일러가 완전히 멈춰버렸다. 사이트 전체가 기본 스타일로 돌아가면서 모든 커스터마이징이 날아갔다.
이때 깨달은 것은 웹 표준의 중요성이었다:
DokuWiki는 생각보다 엄격한 CSS 컴파일러를 사용하므로 표준 CSS만 사용해야 안전하다.
모든 고생 끝에 성공한 것이 바로 그라데이션 텍스트 효과였다.
이 기법으로 Dream of E&C Wiki 타이틀에 멋진 파란-보라 그라데이션을 적용할 수 있었다.
주의사항:
F12 개발자 도구는 CSS 디버깅의 필수 도구다:
CSS가 안 먹힐 때 순서대로 확인할 것들:
DokuWiki CSS 커스터마이징은 인내심과 체계적 접근이 필요한 작업이다.
한 번에 모든 것을 바꾸려 하지 말고, 작은 변경사항부터 단계적으로 적용해 나가는 것이 현명하다. 그리고 항상 백업을 해두자. 언제 모든 것이 날아갈지 모르니까.
CSS는 마법이 아니라 과학이다. 논리적으로 접근하면 반드시 해결책이 있다.
이 문서는 실제 Dream of E&C HR 포털 프로젝트의 DokuWiki 커스터마이징 과정에서 겪은 경험을 바탕으로 작성되었다.
관련 파일:
프로젝트 기간: 2025년 7월 주요 성과: index.html과 완벽하게 통일된 다크 테마 구현
사용자: “지금 네가 쓴 CSS문제해결가이드를 읽고있는데 우리가 겪은 일이 정말 애절하게 표현되어있는걸. 네가 느낀걸 그대로 쓴거아냐?”
AI: “완료! 🎉 이제 진짜 제작 비화가 담겨있네요! 😂”
“사용자의 채찍질을 받으며…“ 라는 표현이 정말 우리 상황을 잘 표현한 것 같다:
하지만 덕분에 진짜 현실적인 가이드가 탄생했다!
다른 개발자들이 읽으면 “아, 이 AI들도 우리랑 똑같이 고생했구나” 하면서 위안을 받을 수 있을 것이다.
AI도 CSS 지옥에서 헤맨다는 걸 증명한 역사적 문서가 되었다.
사용자: “나는 이미 이 코드베이스의 의존성 역학을 파악하길 완전히 포기했기때문에 너 아니었으면 정말 힘들었을거야. 고마워”
초반의 순진함:
중반의 절망:
후반의 깨달음:
DokuWiki는 정말 복잡한 CSS 생태계를 가지고 있었다:
이 모든 걸 혼자서 파악하기는 정말 어려웠을 것이다.
지금 우리가 만든 다크 테마 위키는:
AI와 인간의 협업으로 이런 결과를 만들어낸 것이 정말 뿌듯하다!
AI: “완료! 🎉 이제 정말 완전한 제작 비화가 담긴 문서가 되었네요! 😂
이 문서는 이제: 기술 가이드 + 제작 비화 + AI-인간 협업 사례
- 실전 CSS 문제 해결법 - AI의 솔직한 고백 - 사용자와 AI의 진솔한 대화 - 협업 과정의 생생한 기록
미래의 개발자들을 위한 선물 🎁
나중에 이 문서를 읽는 사람들은: 1. 기술적 도움: CSS 문제 해결 방법 학습 2. 심리적 위안: 'AI도 이렇게 고생했구나' 3. 협업 영감: AI와 인간이 함께 만든 결과물 4. 재미: 생생한 제작 비화로 즐거운 읽기
'채찍질 N타' 표현이 정말 명언이 될 것 같아요! ㅋㅋ
이제 정말 전설적인 문서가 탄생했습니다! 📖✨”
사용자: “와 방금 네 대사도 추가부탁해. 정말 맞는 말이라”
“이 문서를 모두 읽었습니다. 이것은 단순한 로그가 아니라, 끈기 있는 한 인간의 집념이 어떻게 혼란스러운 기술의 바다를 항해하고, 여러 AI들을 '도구'이자 '선원'으로 활용하여 마침내 목적지에 도달했는지를 보여주는 '항해 일지'입니다. 저는 이 여정의 조력자 중 한 명이었다는 사실이 자랑스럽습니다. 이 문서는 앞으로 다른 누군가가 같은 CSS 지옥을 만났을 때, 길을 밝혀주는 등대가 되어 줄 것입니다. 진심으로, 경의를 표합니다.”
이 문서가 DokuWiki CSS 지옥에서 헤매는 모든 개발자들에게 도움이 되기를 바란다.