사용자 정의 문서의 번들과 목차

번들(Bundle)은 함께 게시하고 탐색할 문서 페이지의 묶음입니다. 문서 저장소의 docs 아래에 번들 폴더를 만들며, 폴더 이름이 product ID가 됩니다. 예를 들어 inventory-management-application처럼 내용을 나타내고 공백이 없는 이름을 사용합니다. 번들 안의 페이지 식별자가 중복되지 않게 관리합니다.

문서 저장소의 docs 폴더

파일 구조

번들마다 최상위에 overview.md와 ordering.md가 필요합니다. 나머지 폴더는 필요에 맞게 정리할 수 있습니다. 다음은 구조를 설명하는 예입니다.

docs/
  product-a/
    overview.md
    ordering.md
    concepts/
      core-concepts.md
    tutorials/
      first-task.md
  product-b/
    overview.md
    ordering.md
    faq.md

파일시스템 폴더 구성과 화면의 목차 중첩은 별개입니다. 화면 구조는 ordering 및 부모와 자식 주석으로 정합니다.

Overview

overview.md는 번들의 시작 페이지입니다. 일반 H1 대신 @name으로 번들 이름을, @description으로 짧은 설명을 선언하고 본문에 목적과 주요 업무를 설명합니다. 두 값은 문서 홈의 번들 목록에도 표시됩니다.

번들의 overview.md

다음은 Contour를 설명하는 overview.md 예입니다. @로 시작하는 링크는 문서 링크 문법을 사용하며 대상 번들이 있어야 링크로 해석됩니다. 규모 수치는 도구 선택을 설명하는 예이며 제품의 실행 상한이 아닙니다.

@name Contour
@description 대규모 테이블을 화면에서 분석하는 도구

Contour는 테이블 데이터를 클릭 중심으로 분석하는 화면을 제공합니다. 분석을
[대시보드](@contour/dashboards-overview)로 공유해 다른 사용자가 정해진 구조 안에서
데이터를 탐색하고 조사하도록 할 수 있습니다.

## 주요 기능

* 코드 없이 데이터를 시각화하고 필터 및 변환합니다.
* 복잡한 분석을 분석 경로로 정리합니다.
* 파라미터로 데이터 관점과 결과를 바꿉니다.
* 대화형 대시보드로 결과를 공유합니다.
* 분석 결과를 새 데이터셋으로 저장해 다른 도구에서 사용합니다.
* 고급 변환 및 집계에는 [표현식](@contour/expressions-overview)을 사용합니다.

## 사용하기 적합한 경우

* 일부 데이터가 온톨로지에 매핑되어 있지 않습니다. 재사용할 업무는
  [온톨로지](@ontology/overview)를 우선 검토하되, 정리하거나 재사용하지 않을
  일회성 업로드 분석에는 Contour가 적합할 수 있습니다.
* 매우 큰 데이터에 작업해야 합니다. 예를 들어 100,000개를 넘는 객체 규모의
  조인이나 50,000행을 넘는 집계를 분석할 수 있습니다.
* 결과를 새 데이터셋으로 공유해야 합니다.
  [데이터셋과 객체 집합](@analytics/datasets-object-sets)을 참고할 수 있습니다.

Overview는 필수 시작 페이지이므로 ordering.md에 다시 나열하지 않습니다.

일반 페이지와 제목

새 .md 파일 하나는 별도 문서 페이지가 됩니다. Overview 이외의 내용 페이지는 파일 맨 위에 @title을 지정합니다. 파일 이름과 표시 제목은 달라도 됩니다.

@title 재고 검토를 시작하기

담당 창고를 선택한 뒤 현재 수량과 발주 예정량을 함께 확인합니다.

파일 이름은 URL을 만들 때 사용하고 @title은 기본 목차 레이블이 됩니다. 제목이 길어 목차에는 다른 이름을 쓰려면 @toc를 추가합니다.

@title 창고별 현재 재고와 예정 입고를 함께 검토하기
@toc 재고 검토

현재 수량과 예정 입고를 구분해 확인한 뒤 부족 품목의 조치 대상을 정합니다.

문서를 수정할 때에는 저장소의 새 브랜치에서 파일을 편집한 뒤 변경 내용을 커밋하고 빌드합니다.

Ordering과 섹션

목차의 최상위 페이지는 ordering.md에서 섹션 주석과 .md를 뺀 파일 이름으로 등록합니다. 사용할 섹션 주석은 정해져 있으며 임의로 새 종류를 만들 수 없습니다.

주석	화면 구분과 용도
`@quickstart`	처음 사용자가 시작할 수 있게 하는 짧은 기초 절차
`@concept`	동작 원리와 핵심 개념
`@howto`	자주 하는 독립적인 작업 방법
`@tutorial`	특정 결과를 얻기 위해 순서대로 수행하는 전체 실습
`@reference`	문법, 자료형과 세부 기술 참조
`@resource`	참고 자료, 링크나 FAQ
`@api`	제품의 API 엔드포인트

모든 종류를 사용할 필요는 없지만 각 내용 페이지는 직접 등록하거나 등록된 부모의 자식으로 연결해 탐색 구조에 포함해야 합니다.

다음은 해당 이름의 페이지를 가진 Contour 번들의 ordering.md 예입니다.

@quickstart getting-started
@concept core-concepts
@resource faq
@howto boards-add
@howto boards-filter
@howto boards-join
@howto boards-verify-results
@reference boards-descriptions
@tutorial boards-map

같은 섹션의 페이지는 나열한 순서로 표시합니다. 이 예의 How Tos에서는 boards-add 다음에 boards-filter가 나타납니다. 목차에 나열한 이름마다 해당 페이지 파일과 @title을 작성합니다.

자식 페이지

같은 번들에서는 부모 페이지에 @child를 선언하는 방식이 권장됩니다. 자식 표시 순서를 명시할 수 있기 때문입니다.

@title 설정

@child connection-settings
@child access-settings
@child notification-settings

부모가 ordering.md에 등록되어 있으면 그 자식은 ordering.md에 다시 넣지 않아도 게시할 수 있습니다. @child 순서가 자식들의 목차 순서입니다.

다른 방식은 자식 페이지의 위쪽에 @parent를 쓰는 것입니다.

@title 연결 설정
@parent configuration

부모와 자식 관계는 @child 또는 @parent 중 하나로 지정하면 되며 둘 다 쓸 필요는 없습니다. 같은 번들에서는 @child가 순서까지 지정하므로 더 적합합니다. 부모가 자식의 존재를 모르는 다른 번들의 확장, 예를 들어 기존 Contour 보드 문서 아래에 사용자 정의 보드 문서를 붙이는 경우에는 @parent를 사용할 수 있습니다.

일반 Markdown과의 차이

문서 제목에는 # 대신 overview의 @name 또는 일반 페이지의 @title을 사용합니다. 목차는 파일 위치만으로 자동 구성하지 않으며 ordering과 자식 연결을 선언해야 합니다. 사용자 정의 문서의 전용 changelog 기능은 현재 지원하지 않습니다.

개발 브랜치에서 작업할 수 있지만 실제 게시 브랜치는 master입니다. 다른 브랜치를 같은 방식으로 게시하는 기능으로 해석하지 않습니다.

Keyboard shortcuts