페이지 구성

Nextra에서는 공존하는 _meta.json 파일을 통해 사이트와 페이지 구조를 구성할 수 있습니다. 문서 테마에서는 이를 더욱 사용자 정의할 수 있는 몇 가지 추가 옵션이 있습니다.

이러한 구성은 테마의 전체 레이아웃, 특히 내비게이션 바와 사이드바에 영향을 미칩니다.

페이지

사이드바에 표시되는 페이지의 제목과 순서는 _meta.json 파일에서 키-값 쌍으로 구성해야 합니다. 예를 들어, 다음과 같은 파일 구조가 있다면:

_meta.json 파일을 통해 사이드바에 페이지가 어떻게 표시될지 정의할 수 있습니다:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "about": "About Us"
}

폴더

폴더는 페이지와 같은 방식으로 구성할 수 있습니다. 예를 들어:

최상위 _meta.json 파일에는 최상위 페이지와 폴더에 대한 메타 정보가 포함되어 있습니다:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us"
}

그리고 중첩된 _meta.json 파일에는 같은 폴더 내 페이지에 대한 메타 정보가 포함되어 있습니다:

{
  "apple": "Apple",
  "banana": "Banana"
}

이렇게 하면 페이지에 대한 정보가 디렉토리별로 그룹화됩니다. _meta.json 파일을 변경하지 않고도 디렉토리를 이동할 수 있습니다.

인덱스 페이지가 있는 폴더

인덱스 페이지가 있는 폴더를 만들려면 어떻게 해야 할까요? 폴더와 같은 이름의 MDX 페이지를 같은 디렉토리에 추가할 수 있습니다. 위의 예에서 /fruits 경로를 추가하고 싶다면, pages에 fruits.mdx 파일을 만들 수 있습니다:

그러면 Nextra는 _meta.json의 fruits 키가 인덱스 페이지가 있는 폴더를 정의한다는 것을 알게 됩니다. 사이드바에서 해당 폴더를 클릭하면 폴더가 열리고 동시에 fruits.mdx 페이지가 표시됩니다.

외부 링크

_meta.json에 href가 있는 항목을 추가하여 사이드바에 외부 링크를 추가할 수 있습니다:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us",
  "github_link": {
    "title": "Nextra",
    "href": "https://github.com/shuding/nextra"
  }
}

링크를 항상 새 탭에서 열려면 "newWindow": true 옵션을 활성화하세요:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us",
  "github_link": {
    "title": "Nextra",
    "href": "https://github.com/shuding/nextra",
    "newWindow": true
  }
}

숨겨진 경로

기본적으로 파일 시스템의 모든 MDX 경로가 사이드바에 표시됩니다. 하지만 "display": "hidden" 구성을 사용하여 특정 페이지나 폴더를 숨길 수 있습니다:

{
  "index": "My Homepage",
  "contact": {
    "display": "hidden"
  },
  "about": "About Us"
}

페이지는 여전히 /contact URL을 통해 접근할 수 있지만, 사이드바에는 표시되지 않습니다.

내비게이션 바 항목

하위 문서

최상위 페이지나 폴더를 "type": "page"로 정의하면 사이드바 대신 내비게이션 바에 특별한 페이지로 표시됩니다. 이 기능을 사용하면 여러 개의 "하위 문서"와 "연락처"와 같은 항상 보이는 특별한 페이지나 링크를 가질 수 있습니다.

예를 들어, 프로젝트에 frameworks와 fruits라는 2개의 문서 폴더를 가질 수 있습니다:

최상위 _meta.json 파일에서 모든 것을 일반 사이드바 항목 대신 페이지로 설정할 수 있습니다:

{
  "index": {
    "title": "Home",
    "type": "page"
  },
  "frameworks": {
    "title": "Frameworks",
    "type": "page"
  },
  "fruits": {
    "title": "Fruits",
    "type": "page"
  },
  "about": {
    "title": "About",
    "type": "page"
  }
}

그러면 다음과 같이 보일 것입니다:

"display": "hidden" 옵션을 사용하여 홈과 같은 링크를 내비게이션 바에서 숨길 수도 있습니다.

메뉴

"type": "menu"와 "items" 옵션을 사용하여 내비게이션 바에 메뉴를 추가할 수도 있습니다:

{
  "company": {
    "title": "Company",
    "type": "menu",
    "items": {
      "about": {
        "title": "About",
        "href": "/about"
      },
      "contact": {
        "title": "Contact Us",
        "href": "mailto:[email protected]"
      }
    }
  }
}

링크

외부 링크 옵션과 마찬가지로 내비게이션 바에도 외부 링크를 가질 수 있습니다:

{
  "index": {
    "title": "Home",
    "type": "page"
  },
  "about": {
    "title": "About",
    "type": "page"
  },
  "contact": {
    "title": "Contact Us",
    "type": "page",
    "href": "https://example.com/contact",
    "newWindow": true
  }
}

폴백 (Fallbacks)

위의 하위 문서 예제에서는 모든 페이지에 대해 "type": "page" 옵션을 정의해야 했습니다. 이를 더 쉽게 하기 위해 "*" 키를 사용하여 이 폴더의 모든 항목에 대한 폴백 구성을 정의할 수 있습니다:

{
  "*": {
    "type": "page"
  },
  "index": "홈",
  "frameworks": "프레임워크",
  "fruits": "과일",
  "about": "소개"
}

이는 모든 항목에 "type": "page"가 설정된 것과 동일합니다.

구분자

"type": "separator"를 가진 "플레이스홀더" 항목을 사용하여 사이드바의 항목 사이에 구분선을 만들 수 있습니다:

{
  "index": "My Homepage",
  "---": {
    "type": "separator"
  },
  "contact": "Contact Us"
}

고급

테마 컴포넌트

"theme" 옵션을 사용하여 각 페이지의 테마를 구성할 수 있습니다. 예를 들어, 특정 페이지에 대해 특정 컴포넌트를 비활성화하거나 활성화할 수 있습니다:

{
  "index": {
    "title": "Home",
    "theme": {
      "breadcrumb": false,
      "footer": true,
      "sidebar": false,
      "toc": true,
      "pagination": false
    }
  }
}

이 옵션은 폴더에 설정된 경우 모든 하위 페이지에 상속됩니다.

레이아웃

기본적으로 각 페이지는 테마 구성에서 "layout": "default"를 가지고 있으며, 이는 기본 동작입니다.

Raw 레이아웃

기본적으로 Nextra는 MDX 콘텐츠(h1, h2, h3 등)를 테마가 적용된 컴포넌트로 렌더링하고, 콘텐츠 컨테이너 안에 넣습니다. "raw" 레이아웃을 사용하면 Nextra가 콘텐츠에 어떤 스타일도 주입하지 않도록 할 수 있습니다:

{
  "index": {
    "title": "Home",
    "theme": {
      "layout": "raw"
    }
  }
}

Full 레이아웃

일부 페이지를 전체 컨테이너 너비와 높이로 렌더링하면서도 다른 모든 스타일은 유지하고 싶을 수 있습니다. 이를 위해 "full" 레이아웃을 사용할 수 있습니다:

{
  "index": {
    "title": "Home",
    "theme": {
      "layout": "full"
    }
  }
}

타이포그래피

"typesetting" 옵션은 글꼴 특성, 제목 스타일, li와 code와 같은 컴포넌트의 타이포그래피 세부 사항을 제어합니다. 문서 테마에서는 "default"와 "article" 타이포그래피를 사용할 수 있습니다.

기본 설정은 대부분의 경우(예: 문서)에 적합하지만, "article" 타이포그래피를 사용하여 우아한 기사 페이지처럼 보이게 할 수 있습니다:

{
  "about": {
    "title": "회사 소개",
    "theme": {
      "typesetting": "article"
    }
  }
}