DocFlow
StaticSite
Reference
Docusaurus
프론트메타

프론트메타

독사우루스에서 마크다운 문서를 작성할 때 프론트 매터(front matter)는 선택 사항이지만, 특정 기능을 사용하려면 포함하는 것이 좋습니다. 프론트 매터는 YAML 형식으로 작성되며, 문서의 메타데이터를 정의하는 데 사용됩니다. 아래는 독사우루스 문서에서 자주 사용하는 프론트 매터 항목들입니다.

예시 

# Example Document

다음은 프론트 매터를 포함한 마크다운 문서의 예시입니다:

필수 항목 설명

  • id: 문서의 고유 식별자입니다. 각 문서마다 유일해야 합니다. 한글 사용은 가능하지만 권장되지 않습니다.
  • title: 문서의 제목입니다. 페이지의 <title> 태그로 사용되며, 문서의 주요 제목으로 표시됩니다.

추가 항목 (선택 사항)

필수 항목 외에, 선택적으로 유용한 몇 가지 항목을 추가할 수 있습니다. 필요에 따라 다음 항목들을 포함할 수 있습니다:

  • sidebar_label: 사이드바에 표시되는 레이블입니다. 문서의 제목을 간단하게 표현할 수 있습니다. 지정하지 않으면, 기본적으로 title 속성이 사이드바에 표시됩니다
  • description: 문서의 간단한 설명으로, SEO와 검색 결과에서 요약 문구로 사용됩니다.
  • keywords: 문서와 관련된 키워드 목록으로, SEO 최적화에 도움이 됩니다.
  • slug: 문서의 URL 경로를 정의합니다. 기본적으로는 id를 사용하지만, 필요에 따라 수정할 수 있습니다.
  • sidebar_position: 사이드바에서 문서의 위치를 정의합니다. 숫자가 낮을수록 상위에 표시됩니다.
# Example Document

추가 항목 

```md

# Example Document

설명

  • description: 문서의 간단한 설명입니다.
  • tags: 문서에 적용할 태그 목록입니다.
  • author: 문서의 작성자입니다.
  • author_url: 작성자의 프로필 URL입니다.
  • author_image_url: 작성자의 이미지 URL입니다.
  • image: 문서와 관련된 이미지 URL입니다.
  • hide_title: true로 설정하면 페이지에서 제목을 숨깁니다.
  • hide_table_of_contents: true로 설정하면 페이지에서 목차를 숨깁니다.
  • toc_min_heading_level: 목차에 포함할 최소 헤딩 레벨을 정의합니다.
  • toc_max_heading_level: 목차에 포함할 최대 헤딩 레벨을 정의합니다.
  • draft: true로 설정하면 문서를 초안 상태로 표시하여 배포하지 않습니다.
  • date: 문서의 작성 날짜입니다.
  • updated: 문서의 마지막 수정 날짜입니다.

프론트 매터의 값이 없는 경우, 일부 속성은 문제가 될 수 있으며, 일부는 문제가 되지 않을 수 있습니다. 빈 값을 정의하면 일부 도구나 파서가 이를 처리하지 못하고 오류를 발생시킬 수 있습니다.

다음은 빈 값을 가질 때의 문제와 해결 방법에 대한 설명입니다:

주요 항목별 빈 값 처리

  • id: 빈 값일 경우 문서의 고유 식별자가 없으므로 문제가 발생합니다. 반드시 값을 입력해야 합니다.
  • title: 빈 값일 경우 문서의 제목이 없으므로 문제가 발생합니다. 반드시 값을 입력해야 합니다.
  • sidebar_label: 빈 값일 경우 사이드바에 표시될 레이블이 없으므로 문제가 발생할 수 있습니다. 기본적으로 title을 사용할 수 있지만 명시적으로 지정하는 것이 좋습니다.
  • sidebar_position: 빈 값일 경우 사이드바에서 문서의 순서가 지정되지 않습니다. 필요하지 않으면 생략할 수 있습니다.
  • slug: 빈 값일 경우 URL 경로가 없으므로 문제가 발생할 수 있습니다. 반드시 값을 입력해야 합니다.
  • description: 빈 값이어도 큰 문제는 없지만 SEO에 영향을 줄 수 있습니다.
  • keywords: 빈 값이어도 큰 문제는 없지만 SEO에 영향을 줄 수 있습니다.
  • tags: 빈 값이어도 큰 문제는 없지만 문서 분류에 영향을 줄 수 있습니다.
  • author: 빈 값이어도 큰 문제는 없습니다.
  • author_url: 빈 값일 경우 문제는 없지만, 의미 없는 링크가 생성될 수 있습니다.
  • author_image_url: 빈 값일 경우 문제는 없지만, 의미 없는 링크가 생성될 수 있습니다.
  • image: 빈 값이어도 큰 문제는 없습니다.
  • hide_title: false로 설정하면 제목을 숨기지 않습니다. true 또는 false로 설정하지 않으면 기본값을 사용합니다.
  • hide_table_of_contents: false로 설정하면 목차를 숨기지 않습니다. true 또는 false로 설정하지 않으면 기본값을 사용합니다.
  • toc_min_heading_level: 빈 값일 경우 기본값이 사용됩니다.
  • toc_max_heading_level: 빈 값일 경우 기본값이 사용됩니다.
  • draft: false로 설정하면 문서를 초안으로 표시하지 않습니다. true 또는 false로 설정하지 않으면 기본값을 사용합니다.
  • date: 빈 값일 경우 문제가 발생할 수 있습니다.
  • updated: 빈 값일 경우 문제가 발생할 수 있습니다.

프론트 매터가 없는 경우

프론트 매터가 없더라도 기본적으로 문서가 작동하지만, 사이드바에 표시되거나 URL 경로가 자동으로 설정되지 않을 수 있습니다. 특히 대규모 문서 사이트를 관리할 때는 프론트 매터를 사용하는 것이 유용합니다.

프론트 매터 없이 기본 문서

프론트 매터 없이 작성된 문서도 독사우루스에서 인식할 수 있습니다. 예를 들어:


# Welcome to Docusaurus

This is a quick introduction to Docusaurus.

이 경우 독사우루스는 파일 이름을 ID로 사용하고, 기본 설정을 적용하여 문서를 처리합니다.

ID 에 한글 사용

독사우루스(Docusaurus)에서 id에 한글을 사용하는 것은 기술적으로 가능합니다. 그러나 몇 가지 고려사항이 있습니다. id는 문서의 고유 식별자이므로 URL 경로, 링크, 네비게이션 등 다양한 부분에서 사용됩니다.

고려사항

  1. URL 인코딩 문제:

    • id가 URL의 일부로 사용될 때 한글은 URL 인코딩이 필요합니다. 이로 인해 URL이 길어지고 가독성이 떨어질 수 있습니다.

  2. 호환성 문제:

    • 일부 시스템이나 브라우저에서는 비영어 문자를 처리하는 데 문제가 있을 수 있습니다. 이는 특히 국제적으로 널리 사용되는 경우 문제가 될 수 있습니다.

  3. 일관성 유지:

    • 프로젝트 전체에서 일관된 스타일을 유지하는 것이 좋습니다. 만약 영어와 한글이 혼합되어 사용된다면 유지보수성이 떨어질 수 있습니다.

권장사항

가능하면 id에는 영어와 숫자를 사용하는 것이 좋습니다. 이는 가독성과 호환성을 높이고, URL 인코딩 문제를 피할 수 있습니다. 만약 한글을 사용해야 한다면, slug 속성을 사용하여 URL 경로를 별도로 지정하는 방법을 고려할 수 있습니다.

예시

한글 id 사용 예시 


# Example Document

This is an example document with a Korean ID.

이 경우 id는 한글을 사용하지만, URL 경로는 slug를 통해 영어로 지정됩니다.

결론

프론트 매터는 선택 사항이지만, 문서의 구조와 네비게이션을 명확하게 정의하고 사용자 경험을 향상시키기 위해 사용하는 것이 좋습니다. 필요에 따라 프론트 매터를 추가하거나 최소한으로 유지할 수 있습니다.

Buy me a coffee Buy me a coffee
작성