요즘 Fumadocs를 정말 유용하게 쓰고 있습니다. 기본 기능만으로도 완성도가 훌륭하지만, 조금 더 편리하게 쓰기 위해 몇 가지 요소를 커스텀해 보았습니다. 블로그나 문서를 직접 구축하시는 분들께도 도움이 되었으면 좋겠습니다.

Customizing Fumadocs: A Few New Features I Added

유튜브 임베드 컴포넌트 (YouTube Embed Component)

<YouTubeEmbed> 컴포넌트를 사용하면 유튜브 영상을 안전하게 임베드할 수 있습니다.

mdx
<YouTubeEmbed videoId="LX6A3OmY4uk" title="Video Title" />

이 컴포넌트가 가진 유용한 특징들은 다음과 같습니다:

  • 반응형 (16:9 화면 비율 유지)
  • 올바른 보안 속성 자동 적용
  • 성능 최적화 (지연 로딩 지원)

UI 경로 표시 컴포넌트 (UI Path Display Component)

<UiPath> 컴포넌트를 사용하면 UI의 단계별 흐름을 시각적으로 보여줄 수 있습니다.

mdx
<UiPath>Email activity > Has a hard bounced delivery > Yes</UiPath>

이 컴포넌트의 주요 특징:

  • >로 구분된 경로를 자동으로 파싱
  • 각 단계를 칩(Chip) 형태로 렌더링
  • 마지막 단계는 ‘활성화(Active)’ 스타일로 강조 (파란색 배경)
  • 단계 사이에 화살표(›) 구분자 표시

스타일은 app/globals.css에 정의되어 있으며, 다음 클래스들을 사용합니다:

  • .ui-chip: 기본 칩 스타일 (회색 배경)
  • .ui-chip.is-active: 활성화된 칩 스타일 (파란색 배경)
  • .ui-sep: 구분자 문자 스타일 (›)

게시글 작성일 표시 및 오래된 글 경고 기능

MDX 파일의 프런트매터(Frontmatter)에 created와 updated을 설정하면, 게시글 페이지에 작성일과 최종 수정일이 자동으로 표시됩니다.

mdx
---
title: Article Title
created: 2021-04-18
updated: 2024-02-28
---
  • created: 게시글 최초 작성일
  • updated: 게시글 최종 수정일 (작성일과 동일한 경우 표시되지 않음)

또한, 1년 이상 업데이트되지 않은 게시글에는 다음과 같은 경고 문구가 자동으로 노출됩니다:

이 글은 작성된지 1년이 지났습니다. 일부 내용이 최신 정보와 다를 수 있습니다…

이 기능은 components/article-dates.tsx에 구현되어 있으며, 게시글 제목 바로 아래에 렌더링됩니다.

<RelatedArticles> 컴포넌트를 사용하면 포스트 내부에 연관된 글들을 모아서 보여줄 수 있습니다.

mdx
<RelatedArticles related="blog-japanese,css,embed-html" />

주요 기능:

  • 파일명 슬러그 지정 가능 (예: blog-japanese), 쉼표로 구분
  • 괄호 폴더((pagecreate)/blog-japanese.mdx)와 일반 폴더(payment/cant-free-trial.mdx) 모두 지원
  • 각 게시글의 제목과 카테고리 배지 표시
  • 흰색 배경의 코드 블록 스타일 카드 디자인
  • 제목 옆에 Zap 아이콘, 각 게시글 옆에 NotebookText 아이콘 표시
  • 링크 밑줄 제거 및 마우스 오버 시 색상 변경

사용 예시:

mdx
---
title: Creating a Blog Post
---

## Body

Here are some related articles.

<RelatedArticles related="blog-japanese,css,embed-html" />

쉼표 주변에 공백이 있어도 정상적으로 작동합니다:

mdx
<RelatedArticles related="blog-japanese, css, embed-html" />

구현 파일:

  • components/related-articles.tsx: 연관글 표시 컴포넌트
  • lib/getPageBySlug.ts: 슬러그로 페이지 정보를 가져오는 헬퍼 함수
    • getPageBySlug(slug): 슬러그 하나로 단일 페이지 조회
    • getPagesBySlugs(slugs): 슬러그 목록으로 여러 페이지 조회
    • getCategoryTitleFromPage(page): 페이지에서 카테고리 제목 추출

기술적 디테일:

  • 성능 최적화를 위해 슬러그-페이지 매핑 캐싱 적용
  • 파일 경로를 기반으로 카테고리 자동 감지 (괄호 폴더 포함)
  • 카테고리 정보는 메모리 내 캐시를 사용하여 meta.json 또는 index.mdx에서 가져옴

홈페이지 기능

홈페이지(content/docs/index.mdx)에는 다음과 같은 기능들이 구현되어 있습니다.

최근 추가된 글 및 최근 수정된 글

프런트매터에 created 또는 updated가 설정된 게시글을 날짜순으로 정렬하여 보여줍니다.

mdx
import { RecentCreatedPosts, RecentUpdatedPosts } from '@/components/recent-posts';

## Recently Added Articles

<RecentCreatedPosts limit={10} />

## Recently Updated Articles

<RecentUpdatedPosts limit={10} />

주요 기능:

  • 각 게시글을 마우스 호버 효과가 있는 카드 형태로 표시
  • 게시글 제목 앞에 FileText 아이콘 표시
  • 카테고리 배지 표시 (예: Billing, Products/Lessons 등)
  • 날짜는 표시하지 않고 깔끔한 목록 형태로 구성

구현 파일:

  • components/recent-posts.tsx: 게시글 목록 표시 컴포넌트
  • lib/recent-posts.ts: 게시글 데이터 조회 함수 (getRecentCreatedPosts, getRecentUpdatedPosts)

추천 토픽 및 게시글 (카테고리별 표시)

카테고리당 최대 5개의 게시글을 보여주는 숏코드 컴포넌트입니다.

mdx
import { CategoryPosts } from '@/components/category-posts';

## Featured Topics & Articles

<CategoryPosts category="payment" limit={5} />

<CategoryPosts category="product" limit={5} />

<CategoryPosts category="students" limit={5} />

주요 기능:

  • 카테고리 이름을 링크로 표시하며, 클릭 시 해당 카테고리 페이지로 이동
  • 각 게시글 앞에 BookText 아이콘 표시
  • 최근 수정일 기준(수정일이 없는 경우 작성일 기준)으로 정렬
  • MDX 파일에서 <CategoryPosts /> 호출 순서를 변경하여 섹션 순서 조절 가능

사이트 전체에 공통으로 표시되는 푸터입니다. components/footer.tsx에 구현되어 있습니다.

레이아웃:

  • 반응형 2단 레이아웃 (큰 화면에서는 좌우 배치, 모바일에서는 상하로 적재)
  • 왼쪽 컬럼: 사이트 로고, 설명, 소셜 미디어 아이콘, 로그인된 유저 정보
  • 오른쪽 컬럼: 사이트 공지사항 (이용약관, 업데이트 정보 등)

왼쪽 컬럼 내용:

  • 사이트 타이틀 (/docs로 연결되는 링크)
  • 사이트 설명
  • 소셜 미디어 아이콘 (GitHub, Discord, YouTube, Twitter/X)
  • 로그인 유저 정보 (플레이스홀더)
    • “로그인됨” 상태 표시
    • 사용자 이름 표시
    • 로그아웃 / 비밀번호 변경 버튼

오른쪽 컬럼 내용:

  • 사이트 설명 및 공지
  • 정보 업데이트 방식에 대한 안내
  • 새 글 추가 방식에 대한 안내

구현 파일:

  • components/footer.tsx: 푸터 컴포넌트
  • app/layout.tsx: 루트 레이아웃에 푸터 추가

푸터는 모든 페이지에 자동으로 노출되며, Fumadocs의 테마 변수를 활용해 스타일링되었습니다.