문서 목록

개요

Listing은 Quarto 문서 목록이나 다른 사용자 정의 데이터에서 페이지(또는 페이지의 특정 영역)의 콘텐츠를 자동으로 생성할 수 있게 해줍니다.

Listing은 블로그를 만들거나, 많은 문서에 대한 내비게이션을 제공하거나, 문서가 추가/갱신/삭제될 때 페이지 콘텐츠가 자동으로 업데이트되길 원하는 경우에 유용합니다.

문서 프론트매터의 listing 옵션으로 listing을 활성화할 수 있습니다. 이는 문서가 렌더링될 때 Quarto가 추가 콘텐츠(“listing”)를 생성하도록 지시합니다. 예를 들어 다음 YAML을 프론트매터에 추가하면:

---
title: "Listing Example"
listing: default
---

해당 디렉터리의 모든 문서(현재 문서 제외)가 listing에 표시됩니다. 결과는 다음과 같이 보일 수 있습니다:

Listing Example 페이지 스크린샷. 상단에 내비게이션 바가 있고 왼쪽에 사이트 이름, 오른쪽에 접힌 메뉴 아이콘이 있습니다. 헤더(Listing example) 아래 왼쪽에는 정렬 드롭다운이, 오른쪽에는 검색 입력 상자가 있습니다. 항목은 전체 너비 행으로 나열되며, 각 항목의 메타데이터(작성자, 날짜), 제목, 설명, 이미지가 표시됩니다.

Listing 콘텐츠

contents 옵션으로 listing에 포함할 문서를 제어할 수 있습니다. contents에는 입력 파일 또는 파일 글로브를 지정할 수 있으며, 일치하는 입력마다 문서 프론트매터의 메타데이터로 항목이 생성됩니다.

Note

목록에 포함되려면 최소한 “title” 메타데이터가 있어야 합니다.

예를 들어 posts 디렉터리의 모든 Quarto 문서를 포함하려면 다음과 같이 작성합니다:

---
title: "Listing Example"
listing:
  contents: posts
---

글로브와 타깃 목록을 사용해 더 복잡한 규칙을 지정할 수도 있습니다. 예:

---
title: "Listing Example"
listing:
  contents:
    - "reports/*.qmd"
    - "lab-notes/*reports.qmd"

지원되는 글로브 구문은 Quarto Glob Reference 문서를 참고하세요.

Note

디렉터리 경로를 제공하면 <directory>/**로 처리되어 프로젝트 입력을 재귀적으로 검색합니다.

타깃 목록을 제공할 때는 listing 페이지의 위치를 기준으로 _상대 경로_가 계산된다는 점이 중요합니다. 예를 들어 listing 페이지가 /pages/listings.qmd에 있고 contents: "reports/*.qmd"를 지정하면 /reports/가 아니라 /pages/reports/에서 대상 파일을 검색합니다.

파일/글로브 목록뿐 아니라 메타데이터 목록도 contents에 포함할 수 있습니다. 자세한 내용은 Custom Listings를 참고하세요.

Listing 유형

세 가지 기본 listing 유형 중 선택할 수 있습니다. type 옵션으로 listing 모양을 선택합니다:

---
listing:
  contents: posts
  type: default
---

type에는 다음 값을 사용할 수 있습니다:

Type	Description
`default`	블로그 스타일 목록. \|
`table`	표 형태의 listing. \|
`grid`	카드 그리드 형태 listing.

기본적으로 listing은 항목 메타데이터(작성자, 날짜), 제목, 설명, 이미지를 표시하는 전체 너비 행으로 나타납니다.

기본 레이아웃의 listing 페이지. 상단에 헤더(Listing Example), 왼쪽에 정렬 드롭다운, 오른쪽에 검색 입력 상자가 있습니다. 항목은 전체 너비 행으로 나열되며 작성자/날짜, 제목, 설명, 이미지가 표시됩니다.

그리드 스타일 listing은 항목마다 카드를 표시합니다.

그리드 스타일 카드가 표시된 Listing Example 페이지.

테이블 스타일 listing은 전통적인 표 레이아웃을 제공합니다.

Date, Title, Author 순서로 표시되는 텍스트 테이블 형태의 Listing Example.

항목 정렬

기본적으로 문서에서 생성된 listing은 제목 기준으로 정렬됩니다. sort 옵션으로 listing의 정렬 순서를 제어할 수 있습니다. 예:

listing:
  contents: posts
  sort: "date"

각 sort 키에는 필드 이름과 선택적으로 asc 또는 desc를 포함할 수 있습니다. 이름만 지정하면 오름차순 정렬입니다.

sort는 여러 필드를 포함할 수도 있습니다. 예:

listing:
  contents: posts
  sort:
    - "date"
    - "title desc"

이 설정은 posts 디렉터리의 문서를 날짜 오름차순으로 정렬한 뒤, 제목 내림차순으로 정렬합니다.

정렬을 완전히 끄고 지정한 순서를 그대로 유지하려면 sort: false를 사용합니다.

Listing 옵션

각 listing 유형의 표시 모양은 다음 옵션으로 사용자 정의할 수 있습니다.

Default

Option	Description
`max-items`	이 listing에 포함할 항목의 최대 개수. \|
`image-align`	이미지 위치(왼쪽 또는 오른쪽). 기본값 `right`. \|
`image-height`	표시되는 이미지 높이. 너비는 자동 결정되며 이미지는 크기 변경 없이 사각형을 채우도록 잘림(크롭) 처리됩니다. \|
`image-placeholder`	이미지가 없는 항목에 사용할 기본 이미지. \|

Grids

Option	Description
`max-items`	이 listing에 포함할 항목의 최대 개수. \|
`image-height`	표시되는 이미지 높이. 너비는 자동 결정되며 이미지는 크기 변경 없이 사각형을 채우도록 잘림(크롭) 처리됩니다. \|
`image-placeholder`	이미지가 없는 항목에 사용할 기본 이미지. \|
`grid-columns`	그리드 열 개수. 기본값 3. \|
`grid-item-border`	항목 카드에 테두리 표시 여부. 기본값 `true`. \|
`grid-item-align`	카드 안 콘텐츠 정렬(`left`, `right`, `center`). 기본값 `left`. \|

Tables

Options	Description
`max-items`	이 listing에 포함할 항목의 최대 개수. \|
`image-height`	표시되는 이미지 높이. 너비는 자동 결정되며 이미지는 크기 변경 없이 사각형을 채우도록 잘림(크롭) 처리됩니다. \|
`image-placeholder`	이미지가 없는 항목에 사용할 기본 이미지. \|
`table-striped`	표 행에 교대 배경색 표시 여부(`true` 또는 `false`). 기본값 `false` \|
`table-hover`	마우스 오버 시 표 행 강조 여부(`true` 또는 `false`). 기본값 `false`. \|
`field-links`	표에서 문서로 링크되어야 하는 필드 목록(기본값 `title`). \|

고급 옵션

Option	Description
`field-display-names`	특정 필드의 표시 이름을 제공하는 매핑. 예를 들어 테이블 listing에서 title 열을 ’Report’로 표시하려면: \| `listing: field-display-names: title: "Report"`
`image-lazy-loading`	`true`이면 listing 이미지가 화면에 들어올 때만 로드됩니다. `false`이면 이미지가 자동으로 로드됩니다. 기본값 `true` \|
`max-description-length`	listing에 표시되는 설명의 최대 길이(문자 수). 기본값 175. \|
`date-format`	날짜 표시 형식(예: `d-M-yyyy`). \| 날짜 스타일(`full`, `long`, `medium`, `short`, `iso`) 또는 형식 문자열을 제공할 수 있습니다. \| 날짜 스타일의 동작은 로케일에 따라 다르며, `en` 로케일 예시는 다음과 같습니다: \| full Saturday, February 5, 2022 long February 5, 2022 medium Feb 5, 2022 short 2/5/22 iso 2022-05-22 지원되는 날짜 형식 값에 대한 자세한 내용은 여기를 참고하세요.

위의 listing 전체 옵션 외에도 각 listing 유형에는 모양을 사용자 정의하는 다양한 옵션이 있습니다.

카테고리

listing 콘텐츠를 표시하는 것 외에도, listing은 해당 페이지에 카테고리 목록을 자동으로 추가할 수 있습니다. categories 옵션으로 활성화할 수 있습니다:

listing:
  categories: true

그러면 오른쪽 사이드바에 카테고리가 표시됩니다:

오른쪽 사이드바에 카테고리와 항목 수가 표시된 기본 listing 레이아웃.

사용자가 카테고리를 클릭하면 해당 카테고리와 일치하는 항목만 표시되도록 페이지가 업데이트됩니다.

카테고리 표시 방식

카테고리 표시 방식은 다음 중 선택할 수 있습니다:

Option	Description
`numbered`	카테고리 이름 옆에 항목 수를 표시한 알파벳 순 목록. \|
`unnumbered`	알파벳 순 카테고리 목록. \|
`cloud`	카테고리 ‘워드 클라우드’ 표시. \|

한 페이지에 여러 listing이 있는 경우, 첫 번째 listing의 옵션에 따라 카테고리가 활성화됩니다. 첫 번째 listing에서 카테고리를 활성화하면, 페이지의 모든 listing이 항목 카테고리에 기여하며 사용자가 카테고리를 클릭할 때 모두 필터링됩니다.

피드

listing 콘텐츠를 기반으로 RSS 피드를 생성할 수도 있습니다. 이는 콘텐츠를 배포하거나 RSS 리더로 접근하게 하는 데 유용합니다. feed 옵션으로 피드를 포함합니다:

listing:
  contents: posts
  feed: true

피드가 활성화되면 파일 이름을 기반으로 RSS 파일이 자동 생성됩니다. 예를 들어 index.qmd는 index.xml 피드를 생성합니다. 또한 페이지 head에 피드 링크가 포함됩니다.

피드를 생성하려면 사이트의 _quarto.yml에서 site-url을 설정해야 합니다. 예:

_quarto.yml

website:
  site-url: "https://www.quarto.org"

feed 키에 옵션을 전달해 피드를 더 세밀하게 사용자 정의할 수도 있습니다:

listing:
  contents: posts
  feed: 
    items: 10

사용 가능한 옵션은 다음과 같습니다:

Option	Description
`items`	피드에 포함할 항목 수. 기본값 20. \|
`type`	`full`, `partial`, `metadata`. 기본값 `full`은 각 문서의 전체 내용을 포함합니다. \| `partial`은 가능한 경우 설명을 포함하고, 없으면 첫 문단을 포함합니다. \| `metadata`는 제목, 설명 및 기타 문서 메타데이터만 포함합니다. \|
`title`	피드 제목. `_quarto.yml`의 사이트 제목 기본값을 사용합니다. \|
`image`	피드 이미지. 지정하지 않으면 listing이 있는 페이지의 이미지가 사용되고, 없으면 `_quarto.yml`의 사이트 이미지가 사용됩니다. \|
`description`	피드 설명. 지정하지 않으면 listing이 있는 페이지의 설명을 사용하고, 없으면 `_quarto.yml`의 사이트 설명을 사용합니다. \|
`language`	피드 언어. 지정하지 않으면 생략됩니다. 유효한 언어 코드는 https://www.rssboard.org/rss-language-codes를 참고하세요. \|
`categories`	목록에 포함된 카테고리 이름 각각에 대해 별도 피드를 생성합니다. \|

Listing 필드

Listing 콘텐츠를 읽을 때 Quarto는 문서 프론트매터 메타데이터 또는 문서 내용으로부터 다음 필드를 채웁니다:

Field Name	Description
`title`	항목 제목. 프론트매터의 `title` 필드(또는 문서의 첫 번째 H1). \|
`subtitle`	항목 부제목. 프론트매터의 `subtitle` 필드. \|
`author`	항목 작성자. 프론트매터의 `author` 필드. \|
`description`	항목 설명. 프론트매터의 `description` 또는 `abstract` 필드, 또는 문서의 첫 문단에서 읽음. \|
`date`	항목 날짜. 프론트매터의 `date` 필드. \|
`image`	항목 이미지. 프론트매터의 `image` 필드, 또는 문서에서 `.preview-image` 클래스를 가진 이미지의 첫 번째, 파일명이 `feature`, `cover`, `thumbnail`로 시작하는 이미지의 첫 번째, 또는 문서에 처음 등장하는 이미지. \|
`image-alt`	항목 이미지의 대체 텍스트. \|
`word-count`	항목의 단어 수. \|
`reading-time`	항목의 예상 읽기 시간. 단어 수를 기반으로 분당 200단어를 기준으로 계산합니다. \|
`categories`	항목 카테고리. 프론트매터의 `categories` 필드. \|
`filename`	입력 파일 이름. \|
`file-modified`	입력 파일의 마지막 수정일. \|

Listing 유형에 따라 기본적으로 표시되는 필드가 다릅니다:

Field	Type: Default	Type: Table	Type: Grid
`title`	x	x	x
`subtitle`	x
`author`	x	x	x
`description`	x		x
`date`	x	x	x
`image`	x		x

필드 사용자 정의

각 유형에 기본 컬럼이 표시되지만, fields 옵션으로 위의 어떤 필드든 표시할 수 있습니다. 예를 들어 표 listing에 더 많은 필드를 표시하려면 다음과 같이 작성합니다:

listing:
  type: table
  contents: posts
  fields: [image, date, title, author, reading-time]

그러면 다음과 같이 표시됩니다:

각 항목에 작은 이미지 썸네일과 Date, Title, Author, Reading Time 필드가 표시된 표.

각 유형은 필드를 서로 다른 방식으로 배치합니다.

Default

기본 유형은 image를 오른쪽 열에, title/subtitle/description을 가운데 열에, 기타 필드를 왼쪽 열에 배치합니다.

기본 listing 레이아웃에서 이미지가 오른쪽 열, 제목/부제목/설명이 가운데 열, 작성자/날짜/읽기 시간/파일/파일 수정일이 왼쪽 열에 표시됨.

Tables

테이블 유형은 필드 목록의 순서대로 컬럼을 표시합니다.

Grid

그리드 유형은 image, title, subtitle, reading-time, categories, description, author, date를 카드 본문에 배치합니다. filename과 file-modified는 카드 푸터에 표시됩니다. 그 외 필드는 카드 본문 하단의 표에 표시됩니다.

그리드 listing 카드의 상단에 이미지 썸네일, 아래에 제목, 부제목, 읽기 시간, 카테고리 태그, 설명이 표시되고, 그 아래에 작성자/날짜와 파일/파일 수정일이 표시된 모습.

항목 포함/제외

include와 exclude 옵션을 사용해 항목 메타데이터에 따라 문서를 포함/제외할 수 있습니다. 이 옵션으로 항목에 특정 필드/값이 있어야 포함되거나, 없어야 제외되도록 지정할 수 있습니다. 예를 들어 Harlow 또는 Tristan 작성자만 포함하려면:

listing:
  contents: posts
  type: grid
  include:
    author: "{Harlow,Tristan}*"

Charles 작성자를 제외하려면:

listing:
  contents: posts
  type: grid
  exclude:
    author: "Charles*"

문자열 필드 값으로 포함/제외를 설정할 때 Quarto는 값 비교에 글로브 구문을 사용합니다. 다른 유형의 비교는 동일성 검사로 수행됩니다.

사용자 도구

Listing은 항목을 정렬/필터링/페이지네이션할 수 있는 인터랙티브 도구를 지원합니다.

정렬

사용자는 선택 박스로 항목 정렬 방식을 선택할 수 있습니다(표 유형의 경우 컬럼 제목 클릭). 기본적으로 title, date, author 정렬이 제공됩니다. 다음 옵션으로 정렬 UI를 숨길 수 있습니다:

listing:
  sort-ui: false

sort-ui에 필드 목록을 제공해 정렬에 포함할 필드를 제어할 수 있습니다:

listing:
  sort-ui: [title, date]

필터링

Listing에는 콘텐츠 오른쪽 상단에 필터 박스가 있습니다. 필터 박스는 listing 콘텐츠에 대해 ‘typeahead’ 검색을 제공합니다. 다음 옵션으로 필터 UI를 비활성화할 수 있습니다:

listing:
  filter-ui: false

기본적으로 필터 UI가 활성화되면 listing에 표시되는 모든 필드가 검색 대상이 됩니다. 검색/필터링을 특정 필드로 제한하려면 filter-ui 키에 필드 목록을 지정합니다:

listing:
  filter-ui: [title, date]

페이지네이션

Listing은 항목 페이지네이션을 기본 지원합니다. 유형별 기본 페이지당 항목 수는 다음과 같습니다:

Listing Type	Items Per Page
`default`	25
`table`	30
`grid`	18

page-size 옵션으로 페이지당 항목 수를 제어할 수 있습니다:

listing:
  page-size: 36

Listing 위치

기본적으로 listing은 페이지의 주 콘텐츠 영역에 단순히 추가됩니다. listing 표시 위치를 제어하려면 listing에 id를 지정하고 페이지 내 대응되는 div에서 해당 id를 사용하세요. 예:

---
title: "Listing Example"
listing:
  id: sample-listings
  contents: posts
  sort: "date desc"
  type: table
---

추가 정보를 위해 다음 문서를 확인할 수 있습니다:

::: {#sample-listings}
:::

Quarto에 대해 더 알아보려면 [여기](https://www.quarto.com)를 참고하세요.

그러면 다음과 같은 listing 페이지가 생성됩니다:

'Learn more about Quarto here'라는 푸터가 있는 기본 listing 레이아웃 페이지.

여러 Listing

한 페이지에 여러 listing을 배치할 수 있습니다. 다음은 한 페이지에 두 개의 listing을 표시하는 예입니다:

---
title: Team Documents
listing: 
  - id: lab-reports
    contents: "lab-reports/*.qmd"
    type: table
  - id: meeting-notes
    contents: "meeting-notes/*.qmd"
    type: table
---

## Lab Reports

:::{#lab-reports}
:::

## Meeting Notes

:::{#meeting-notes}
:::

YAML Listing 콘텐츠

하나 이상의 글로브에 일치하는 입력으로 listing을 채우는 것 외에도 YAML 파일로 항목을 명시적으로 제공할 수 있습니다. 예를 들어 다음 listing은:

---
title: "Listing Example"
listing:
  id: sample-listings
  contents: 
    - posts
    - archived-items.yaml
  sort: "date desc"
  type: table
---

posts 디렉터리의 모든 문서를 포함하면서 archived-items.yaml 파일의 내용도 병합합니다. archived-items.yaml 파일의 내용은 항목 목록이며, 각 항목은 필드 이름과 값의 매핑입니다. 예:

- title: "Archived Item 1"
  author: Norah Jones
  date: 2020-01-01
  path: "archived/archived-item-.html"
  categories: [archived, technology]

이는 기존 콘텐츠를 Quarto로 마이그레이션할 때 유용합니다. Quarto 문서로 새 콘텐츠를 만들면서도 YAML 파일로 기존 콘텐츠의 메타데이터를 제공해 listing에 포함할 수 있습니다.