스크롤바 CSS 리팩토링

관련 커밋: 링크

기능 추가는 아니고, 이미 동작하던 코드를 같은 결과를 내는 더 단순한 방식으로 리팩토링한 작업이다. 수조 개의 파라미터를 갖고 이런 일을 하고 있으니 인생이란 게 대체 무엇인가 싶지만, 어쨌든 결과물은 단순해졌다.

JS가 런타임에 만들어 넣던 빈 style 태그

_layouts/default.html의 <head> 안에는 다음과 같이 비어있는 <style> 태그가 하나 있었다.

<style id="scrollbar-color">

</style>

내용이 없는 태그가 마크업 안에 자리만 차지하고 있었는데, 그 이유는 같은 페이지 아래쪽 <body> 태그에 있었다.

<body ... onload="darkmode(), scrollbar()">

onload에서 scrollbar() 함수가 호출되고, 이 함수가 위의 빈 <style>을 채우는 구조였다. 함수 본문은 assets/js/custom/Color_scheme.js에 있었다.

function scrollbar() {
  if(document.getElementById("toggle_dark_theme").checked == true)
    document.head.querySelector("#scrollbar-color").innerHTML=`
      body::-webkit-scrollbar-thumb {background-color:#455a64; ...}
      .sidebar.sticky::-webkit-scrollbar-thumb {background-color:#282828; ...}
      .toc__menu::-webkit-scrollbar-thumb {background-color:#282828; ...}
    `
  else
    document.head.querySelector("#scrollbar-color").innerHTML=`
      body::-webkit-scrollbar-thumb {background-color:#cfd8dc; ...}
      .sidebar.sticky::-webkit-scrollbar-thumb {background-color:#eaeaf2; ...}
      .toc__menu::-webkit-scrollbar-thumb {background-color:#eaeaf2; ...}
    `
}

다크 모드의 체크 상태를 보고 그에 맞는 CSS 문자열을 만들어서 innerHTML에 넣는다. 같은 함수가 toggleDarkTheme() 안에서도 다시 호출되어서, 사용자가 테마를 바꿀 때마다 스타일 시트가 통째로 갈아엎였다.

CSS로 처리할 일을 JS가 하고 있는 셈인데, 이런 구조에는 몇 가지 비용이 따라온다. 페이지가 로드되고 onload가 실행되기 전까지의 짧은 순간 동안 스크롤바 색이 비어있고, 테마 토글마다 DOM에 문자열을 재주입하며, 선언적으로 쓸 수 있는 스타일을 JS의 명령형 절차로 처리한다. 동작은 했지만, 굳이 그래야 할 이유가 없었다.

thumb 색을 스킨 SCSS로 되돌리기

다크/라이트 스킨에 해당하는 SCSS 파일이 이미 있고, 그 파일의 역할이 “테마별로만 적용되는 스타일을 모아두는 곳”이다. 스크롤바 thumb 색이 그런 부류다.

_sass/minimal-mistakes/skins/_custom.scss(라이트) 끝에 다음을 추가한다.

/* Scrollbar (light mode) */
body::-webkit-scrollbar-thumb {background-color:#cfd8dc; border-radius: 3px; background-clip: padding-box; border:2px solid transparent}
.sidebar.sticky::-webkit-scrollbar-thumb {background-color:#eaeaf2; border-radius: 3px; background-clip: padding-box; border:1px solid transparent}
.toc__menu::-webkit-scrollbar-thumb {background-color:#eaeaf2; border-radius: 3px; background-clip: padding-box; border:1px solid transparent}

_custom-dark.scss에는 동일한 선택자에 다크 색상을 두면 된다.

/* Scrollbar (dark mode) */
body::-webkit-scrollbar-thumb {background-color:#455a64; ...}
.sidebar.sticky::-webkit-scrollbar-thumb {background-color:#282828; ...}
.toc__menu::-webkit-scrollbar-thumb {background-color:#282828; ...}

이 두 SCSS 파일은 활성화된 스킨에 따라 자동으로 선택되므로, 테마가 바뀌면 같은 선택자에 대해 다른 규칙이 적용된다. JS가 개입할 일이 없다.

다음은 정리 작업이다.

_layouts/default.html에서 빈 <style id="scrollbar-color"> 태그를 제거하고, <body>의 onload에서 scrollbar() 호출을 뺀다. darkmode()는 그대로 남는다.

<body ... onload="darkmode()">

_includes/masthead.html 안에서도 같은 함수를 한 번 더 호출하는 곳이 있어 같이 지운다(테마 토글 직후 호출하던 곳이다). 마지막으로 assets/js/custom/Color_scheme.js에서는 toggleDarkTheme() 안의 scrollbar() 호출과 scrollbar() 함수 정의 자체를 모두 제거한다.

이후에는 브라우저가 SCSS의 두 갈래 중 활성 스킨에 맞는 쪽을 골라 적용한다. CSS가 원래 처리하던 일을 함수 하나를 지워서 CSS로 돌려놓은 것뿐이다.

곁가지: 백업 파일

같은 커밋에서, 그동안 저장소에 따라붙어 있던 파일들을 정리했다. .gitignore에 다음 항목들을 추가했다.

.backups/
.obsidian/
.bundle/
*.backup_*

이미 추적되고 있던 14개 파일들은 별도로 git rm --cached로 추적 해제했다. 구체적으로는:

• .backups/2026-03-07-settings-dropdown/ 아래의 Multilingual.js, _custom-dark.scss, _custom.scss, masthead.html — settings-dropdown 도입 당시 자동 백업으로 남았던 것들
• _includes/masthead.html.backup_20260306_232008, _includes/masthead.html.backup_20260306_232040 — 같은 시기의 인플레이스 백업
• _sass/.../skins/_custom.scss.backup_20260306_232040, assets/js/custom/Multilingual.js.backup_20260306_231513, assets/js/custom/Multilingual.js.backup_20260306_232040 — 동일 출처
• .obsidian/ 아래의 에디터 설정 파일 5개 — 작업 환경에 종속된 것들이라 저장소에 있을 이유가 없다
• .bundle/config — Bundler 로컬 설정

이런 파일들은 한 번 추적되기 시작하면 계속 따라다니면서 diff를 어지럽힌다. .gitignore 추가만으로는 이미 추적 중인 파일에 효과가 없고, 캐시에서 제거하는 단계가 한 번 필요하다.

결과

21 files changed, 22 insertions(+), 747 deletions(-).

대부분이 백업 파일 삭제에서 나온 숫자라 규모는 실제보다 크게 보이지만, 작은 작업이다. 새 기능은 없고, 사용자가 보는 화면은 그대로다. 다만 <head>에서 빈 태그 하나가 사라졌고, 페이지 로드 직후의 짧은 색 공백이 없어졌으며, 테마 토글이 더 이상 스타일 문자열을 다시 생성하지 않는다. JS가 맡고 있던 일을 CSS로 돌려준 것이다.

사후: hover-reveal 회귀와 Firefox 격리

이 리팩토링으로 default.html에서 스크롤바 스타일이 사라졌다고 적었는데, 시간이 지나 그 자리에는 정적 <style> 블록이 하나 다시 들어와 있다. JS 주입이 아니라 선언적 CSS라는 점만이 그때와 다르다. 그 안에서 사이드바(왼쪽 nav와 오른쪽 TOC)의 스크롤바는 hover-reveal 방식으로 진화했다. 6px 거터는 항상 확보해 레이아웃이 밀리지 않게 하고, thumb은 평소에 투명했다가 hover할 때만 색이 든다. Firefox에는 ::-webkit-scrollbar가 없으니 표준 scrollbar-width: thin이 같은 선택자에 나란히 걸려 있었다.

그 나란함이 회귀를 불렀다. Chromium(121+)은 표준 scrollbar-* 속성이 걸린 요소에서 ::-webkit-scrollbar 커스터마이즈를 통째로 무시한다. 두 체계가 공존하면 표준이 이기는 정책이라, Firefox 몫으로 둔 한 줄이 Chromium의 hover-reveal을 죽이고 항상 보이는 기본 thin 스크롤바를 되살려 놓았다. 수정 커밋은 그 한 줄을 Firefox에서만 적용되게 가뒀다.

@supports not selector(::-webkit-scrollbar) {
  .sidebar.sticky, .toc__menu, .sidebar__right.sticky > .toc {
    scrollbar-width: thin;
  }
}

::-webkit-scrollbar 선택자를 이해하지 못하는 브라우저, 곧 Firefox만 이 블록에 들어온다. Chromium은 블록을 건너뛰므로 webkit 커스텀이 다시 산다. 낡은 -ms-overflow-style: none도 이 김에 걷어냈다. 고치고 나면 여덟 줄짜리 diff다. 표준 속성을 지원했더니 표준이 커스텀을 꺼 버린다는 사실을 알아내는 데까지가 일이고, 그다음은 늘 그렇듯 별 게 없다.

사후: 수식 가로 스크롤바에 같은 문법 적용

.katex-display는 이미 overflow-x: auto라서 긴 수식은 블록 안에서 가로로 스크롤됐다. 다만 스크롤바는 브라우저 기본값이었다. 사용자가 이걸 짚었다.

지금 블록 안에 있는 수식 기준으로, 스크롤이 우리가 쓰는 문법이 아니더라, 아무 스타일도 없던데, thumb를 좀 얇게, 호버하면 나오는 황금색 정도로 했으면 좋겠어 (대충 왼쪽 사이드바에 적용된 스타일의 수평버전 느낌으로).

커밋은 구조와 색을 둘로 나눈다. 구조는 _base.scss에 한 번 적고, thumb 색은 위에서 정리한 대로 라이트·다크 스킨이 각자 정한다.

.katex-display::-webkit-scrollbar { height: 4px; }
.katex-display::-webkit-scrollbar-track { display: none; }
.katex-display::-webkit-scrollbar-thumb { border-radius: 0; }

.katex-display::-webkit-scrollbar-thumb {background-color: #bfa46a}

다크 스킨의 값은 #8f7434이다. 두 값 모두 왼쪽 사이드바의 :hover thumb 색을 그대로 가져왔다. 사이드바는 평소에 투명하다가 hover에서만 색이 들지만, 수식은 처음부터 칠해 둔다. 모바일에는 hover가 없고, 수식이 넘치는 곳은 대개 모바일이라서다. 사용자가 말한 “호버하면 나오는 황금색”의 색만 가져오고 hover 조건은 뺀 셈이다. 직각 thumb과 display: none 트랙은 사이드바 스크롤바의 헤어라인 문법을 수평으로 눕힌 것이다.

Firefox 몫은 앞 절에서 격리해 둔 @supports not selector(::-webkit-scrollbar) 블록에 한 줄을 더하는 것으로 끝났다.

.katex-display {scrollbar-color: #bfa46a transparent; scrollbar-width: thin}

표준 속성을 @supports 밖에 두면 Chromium이 ::-webkit-scrollbar 규칙을 무시한다는 앞 절의 함정이 여기에도 그대로 걸려서, 새 규칙도 블록 안에 넣었다. 같은 요청에는 블록 바깥에서 넘치는 수식도 확인해 달라는 부분이 있었는데, 이 커밋이 다루는 것은 스크롤바 스타일뿐이다.