Starlight 0.39 공부 정리 | 사이드바랑 다국어가 달라졌다

Astro 공식 블로그에서 Starlight 0.39 릴리스 노트를 봤다. Starlight는 Astro 기반의 문서 사이트 프레임워크인데, 이번 버전에서 자동 생성 사이드바가 더 유연해지고, 스타일링이 개선됐고, 다국어 지원이 강화됐다는 내용이었다. 사이드바가 유연해진다는 게 구체적으로 뭘 의미하는 건지 궁금해서 좀 더 살펴봤다.

문서 사이트를 만들 때 사이드바 구성이 생각보다 까다롭다는 걸 프로젝트 하나 건드려보면서 알게 됐다. 페이지가 몇 개 안 될 때는 괜찮은데, 구조가 복잡해지면 파일 이름 순서와 내가 원하는 탐색 구조가 달라지기 시작한다. 그 간극을 메우는 방법이 항상 좀 번거로웠다.

1️⃣ 이게 뭐냐?

Starlight는 Astro 위에서 동작하는 문서 전용 프레임워크다. 마크다운이나 MDX로 내용을 작성하면 사이드바, 검색, 목차 같은 기능이 거의 자동으로 붙는다. 설정 파일에서 큰 구조를 잡아두면, 나머지는 프레임워크가 처리해주는 방식이다.

0.39에서 달라진 건 크게 세 방향으로 보였다. 자동 생성 사이드바를 좀 더 세밀하게 제어할 수 있게 됐다는 것, 스타일링 옵션이 늘어났다는 것, 그리고 다국어 문서 작업이 더 매끄러워졌다는 것. 구체적인 설정 방법이나 API 변경 내용은 자세한 건 원문을 직접 확인하는 게 맞을 것 같다.

특히 사이드바 개선이 눈에 들어왔다. 기존에는 파일 구조와 사이드바 구조가 1:1에 가까웠을 텐데, 유연성이 생겼다는 건 콘텐츠 구조와 내비게이션 구조를 어느 정도 분리해서 설계할 수 있는 여지가 생겼다는 뜻 아닐까 싶었다. 파일을 어떤 순서로 두든 내가 원하는 탐색 흐름을 따로 잡을 수 있다면, 꽤 다른 문제가 된다.

2️⃣ 내가 든 생각

다국어 지원 강화가 개인적으로 가장 흥미로웠다. i18n은 나중에 붙이려고 하면 생각보다 구조를 많이 손봐야 하는 작업이다. 라우팅, 콘텐츠 경로, UI 텍스트 분리까지 한꺼번에 엮이는데, 처음부터 프레임워크가 이걸 지원해주면 접근 방식이 달라진다.

👉🏻 “강화됐다”는 표현이 어느 수준까지인지가 궁금했다. 이미 만들어진 문서 사이트에 언어를 추가할 때도 매끄럽게 되는 건지, 아니면 처음부터 다국어를 고려해서 설계해야 하는 건지. 그게 어떻게 달라지느냐에 따라 이 기능을 쓰는 타이밍이 완전히 바뀐다.

디자이너 입장에서 보면, 스타일링 개선도 눈에 들어왔다. 기술 문서 사이트는 디자인이 단조롭기 쉬운데, 기본 제공 스타일이 나아질수록 커스터마이징에 쏟는 에너지가 줄어드는 편이다. 프레임워크 기본값이 좋으면 내용 자체에 더 집중할 수 있게 된다는 점에서, 스타일링 개선이 단순 미관 문제만은 아니라는 생각이 들었다.

💡 여기서 드는 질문? 사이드바 구조가 유연해진다면, 문서를 콘텐츠 구조와 사용자 탐색 흐름으로 따로 설계할 수 있게 되는 걸까? 그렇다면 이건 프레임워크 기능 문제가 아니라 UX 설계 문제가 된다.

3️⃣ 앞으로 어떻게 쓸까?

지금 당장 Starlight를 쓸 계획은 없다. 그런데 포트폴리오나 프로젝트 문서화가 필요해지면 선택지로 올려두고 싶다는 생각이 생겼다. 마크다운으로 빠르게 시작할 수 있고, 처음부터 다국어를 고려한 구조라는 점이 특히 마음에 걸렸다.

써봐야 알겠지만, 자동 생성 사이드바가 실제로 얼마나 유연한지는 직접 건드려보기 전까진 감이 잘 안 올 것 같다.

⭐️ 마지막으로, 문서 프레임워크를 공부하며 느낀 점

정리해보니 이번 업데이트에서 중요한 건 기능 추가라기보다 “얼마나 덜 제약받는가”에 가까운 것 같다. 사이드바를 자동으로 만들어주되, 내 의도대로 바꿀 수 있는 여지가 생긴다는 쪽이 더 맞는 표현일 것 같다. 다국어도, 스타일링도 그 방향이 비슷하다.

---

참고 원문: Starlight 0.39