Release notes 구조 개선 및 Confluence MDX 변환 도구 리팩토링

[jk-kim0]

Summary

Sidebar 정렬 이슈 해결 및 Confluence MDX 변환 도구 개선

Background: Nextra Sidebar 정렬 버그

이 PR은 Nextra 프레임워크의 sidebar 정렬 버그에 대한 workaround를 포함합니다.

관련 이슈: shuding/nextra#4834 - Incorrect order of pages in sidebar

문제 현상

• _meta.ts에 정의한 페이지 순서가 실제 sidebar에 반영되지 않음
• Nextra 4.3.x 버전부터 발생 (현재 4.6.0 사용 중)

기술적 원인 분석

JavaScript 객체의 key 정렬 규칙:

1. 정수로 파싱 가능한 문자열 key (예: '9190', '1120')는 숫자 오름차순 정렬
2. 그 외 문자열 key (예: '9.19.0', 'hello')는 삽입 순서 유지

// 문제 상황: 숫자로만 구성된 key → 자동 오름차순 정렬
export default {
  '9190': '9.19.0',      // 의도: 1번째
  '1120': '11.2.0',      // 의도: 2번째
  '990': '9.9.0',        // 의도: 3번째
}
// 실제 결과: { '990': ..., '1120': ..., '9190': ... } (오름차순)

// 해결: 점(.)이 포함된 key → 삽입 순서 유지
export default {
  '9.19.0': '9.19.0',    // 1번째 ✓
  '11.2.0': '11.2.0',    // 2번째 ✓
  '9.9.0': '9.9.0',      // 3번째 ✓
}
// 실제 결과: 삽입 순서대로 유지됨

Workaround 적용

• 파일명에 점(.)을 포함하여 정수로 파싱되지 않도록 변경
• 예: 9120-91214/ → 9.12.0-9.12.14/
• 이로 인해 JavaScript가 key를 정수가 아닌 일반 문자열로 인식하여 삽입 순서 유지

이슈 상태

• Status: OPEN (bug label)
• Nextra maintainer의 응답 대기 중

---

Changes

1. Release Notes 구조 개선

• 파일/경로 이름 변경: release-notes 하위 페이지들의 MDX 파일명을 버전 형식으로 변경
  • 예: 9120-91214/ → 9.12.0-9.12.14/, 990-998/ → 9.9.0-9.9.8/
• 이미지 경로 rename: public/release-notes/ 하위 이미지 디렉토리도 동일한 패턴으로 변경
• 리다이렉트 설정 추가: 기존 URL에서 새 URL로의 리다이렉트 설정

2. Confluence MDX 변환 도구 리팩토링

• text_utils.py 모듈 생성: clean_text(), slugify() 함수를 공통 모듈로 통합
  • 숨겨진 유니코드 문자(Zero Width Space, Non-Breaking Space 등) 제거 로직 중앙화
• pages_of_confluence.py 수정:
  • start_page_id(root page)를 list.txt에서 제외하도록 수정
• confluence_xhtml_to_markdown.py 수정:
  • _meta.ts 생성 시 MDX 파일 존재 여부 검증 제거 (processing order 이슈 해결)
  • load_pages_yaml() 로그 메시지 버그 수정 ("0 pages" → 실제 페이지 수 표시)

3. Identity Providers 문서 추가

• identity-providers/_meta.ts 파일 추가 (KO/EN/JA)
• korean-titles-translations.txt에 번역 항목 추가:
  • AWS SSO 연동하기 (SAML 2.0) | Integrating with AWS SSO (SAML 2.0)

4. 다국어 문서 동기화

• 한국어 release-notes 변경사항을 영어/일본어 문서에 동일하게 적용
  • product-versions.mdx 내 release-notes 링크 업데이트
  • 9.10.0-9.10.4.mdx, 9.9.0-9.9.8.mdx 내부 링크 수정
  • menu-improvement-guide-9120.mdx 이미지 경로 수정

Test Plan

• 변경된 release-notes 페이지들이 올바른 URL로 접근 가능한지 확인
• 리다이렉트가 정상 동작하는지 확인
• Identity Providers 페이지 sidebar 표시 확인
• xhtml2markdown.ko.sh 실행 시 _meta.ts가 올바르게 생성되는지 확인

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
querypie-docs	Ready	Preview, Comment	Feb 4, 2026 9:33am

[keIIy-kim]

오홍

[jk-kim0]

문제가 해결되지 않습니다. 원인이 다른 곳에 있나 봅니다. 흠...

[keIIy-kim]

🚀