한국어 문서에 대해 Confluence 원문 링크를 TOC 영역에 제공합니다

[jk-kim0]

참조를 위해 docs.querypie.com 문서의 오른쪽 TOC 영역에, Confluence 원문의 링크를 제공합니다.

• 디버깅용
• MDX 문서에 오류가 발생하는 경우, Confluence 원문 참조를 위해

---

구현 방안

개요

한국어(ko) 문서 페이지의 오른쪽 TOC 영역에 해당 페이지의 Confluence 원문 링크를 표시합니다.

방식: MDX Frontmatter에 Confluence URL 저장 + Nextra 표준 훅으로 접근

각 MDX 파일의 frontmatter에 Confluence 원문 URL을 직접 저장하고, Nextra 내장 useConfig() 훅으로 클라이언트 컴포넌트에서 접근합니다.

# MDX frontmatter 예시
---
title: '라이선스 설치'
confluenceUrl: 'https://querypie.atlassian.net/wiki/spaces/QM/pages/912326893/'
---

Nextra 내부 데이터 흐름:

MDX frontmatter (Record<string, any>)
  → 빌드 시 PageMap에 저장
  → normalizePages() → activeMetadata = activePath.at(-1)?.frontMatter
  → useConfig().normalizePagesResult.activeMetadata?.confluenceUrl

Step 1: Confluence 변환기 수정

파일: confluence-mdx/bin/converter/core.py — remark 프로퍼티 수정

• page_v1['id']로 Confluence URL을 구성하여 frontmatter에 confluenceUrl 필드 추가
• URL 패턴: https://querypie.atlassian.net/wiki/spaces/QM/pages/{page_id}/

Step 2: 기존 MDX 파일에 confluenceUrl 일괄 추가

변환기 수정 후 Confluence → MDX 변환을 재실행하거나, 별도 스크립트로 기존 554개 ko MDX 파일에 frontmatter를 일괄 추가합니다.

Step 3: TOC 영역에 Confluence 원문 링크 컴포넌트 추가

신규 파일: src/components/confluence-source-link.tsx

'use client'
import { useConfig } from 'nextra-theme-docs'

export function ConfluenceSourceLink() {
  const { normalizePagesResult } = useConfig()
  const url = normalizePagesResult.activeMetadata?.confluenceUrl
  if (!url) return null
  return <a href={url} target="_blank" rel="noopener noreferrer">Confluence 원문 ↗</a>
}

수정 파일: src/app/[lang]/layout.tsx — toc.title에 컴포넌트 추가

toc={{
  title: (
    <>
      <LanguageSelector2/>
      <ConfluenceSourceLink/>
      <p>On This Page</p>
    </>
  ),
}}

영향 범위

파일	변경 유형
confluence-mdx/bin/converter/core.py	수정 (frontmatter에 confluenceUrl 추가)
src/content/ko/**/*.mdx (554개)	수정 (frontmatter에 confluenceUrl 추가)
src/components/confluence-source-link.tsx	신규 생성
src/app/[lang]/layout.tsx	수정 (컴포넌트 추가)