Confluence
개요
Atlassian Confluence는 팀 협업을 지원하는 배포 플랫폼입니다. Confluence에는 무료 및 유료 구독 플랜을 포함한 다양한 호스팅 옵션이 있습니다.
현재 배포 기능은 Confluence Cloud로 제한됩니다. Confluence Server 또는 Confluence Data Center에는 아직 배포를 지원하지 않습니다.
Quarto는 개별 문서뿐 아니라 여러 문서로 구성된 프로젝트를 Confluence Spaces에 배포할 수 있도록 지원합니다.
Quarto로 Confluence 콘텐츠를 관리하면 Markdown으로 콘텐츠를 작성하고, Git과 GitHub 같은 익숙한 버전 관리 도구로 관리하며, 계산 결과를 포함하는 Quarto 도구를 활용할 수 있습니다.
다음 섹션인 Confluence 배포 기초에서는 단일 페이지를 Confluence에 배포하는 과정을 안내합니다. Quarto에서 Confluence 계정 설정, Confluence Space 내 문서의 배포 대상 지정 방법을 포함합니다.
Confluence 배포를 프로젝트에 사용하기 전에 이 페이지의 나머지 섹션을 읽어보세요.
프로젝트 배포에서는 문서 모음을 배포하는 방법과 프로젝트 구조가 Confluence Space의 페이지 구조로 어떻게 변환되는지 설명합니다.
배포 워크플로에서는 Quarto에서 배포된 Confluence 페이지 업데이트 모델과 배포 시 설정되는 페이지 권한을 설명합니다.
Confluence용 저작에서는 Confluence용 저작과 Quarto 웹사이트 저작의 차이를 설명합니다.
배포 설정에서는 배포 설정을 관리하는 방법을 다룹니다.
공개 Confluence 공간에 Quarto 문서를 배포하면 해당 문서의 내용이 공개됩니다. Confluence Space의 권한을 이해하고 배포 대상을 확인해 민감하거나 기밀인 콘텐츠가 공개되지 않도록 보호하는 것은 사용자의 책임입니다.
Confluence 배포 기초
Confluence 배포 과정을 보여주기 위해 단일 문서 confluence-demo.qmd를 Confluence 공간의 페이지로 배포해 보겠습니다. confluence-demo.qmd의 내용은 다음과 같습니다.
---
title: Confluence Demo
format: confluence-html
---
## Overview
Write your content in Quarto documents and publish to Confluence.문서 YAML에서 형식이 confluence-html로 설정되어 있음에 유의하세요. 이렇게 하면 로컬 미리보기가 Confluence에서의 최종 모습과 유사하게 표시됩니다. 다른 Quarto 문서와 동일하게 RStudio의 Render 버튼, VS Code와 Positron의 Preview 버튼 또는 Quarto: Preview 명령, 혹은 명령줄의 quarto preview로 로컬 미리보기를 확인할 수 있습니다.
Terminal
quarto preview confluence-demo.qmdconfluence-demo.qmd를 로컬에서 미리본 결과는 다음과 같습니다.
미리보기는 콘텐츠의 실제 표시를 최대한 정확하게 보여주려 합니다. 그러나 헤더의 배포 날짜, 작성자, 읽기 시간 같은 일부 항목은 자리 표시자일 뿐입니다. 문서를 Confluence에 배포하면 이러한 항목은 Confluence가 생성합니다.
Confluence에 문서를 배포하려면 quarto publish confluence 뒤에 파일 이름을 지정하세요.
Terminal
quarto publish confluence confluence-demo.qmd이전에 Confluence에 배포한 적이 없다면 계정을 설정하고 페이지 배포 대상을 선택하라는 안내가 표시됩니다.
계정 설정
Confluence에 처음 배포할 때 Quarto에서 Confluence 계정 설정을 요청합니다. 준비를 위해 Confluence에 로그인하고 배포하려는 공간 또는 공간 내 페이지로 이동하세요.
먼저 Confluence 도메인을 입력하라는 안내가 표시됩니다. 이는 배포하려는 Confluence 페이지 URL의 앞부분입니다. 예:
Terminal
? Confluence Domain: ›
❯ e.g. https://mydomain.atlassian.net/다음으로 이 Confluence 도메인에 사용되는 계정의 이메일 주소를 입력하라는 안내가 표시됩니다(확실하지 않다면 Confluence의 계정 프로필을 확인하세요).
Terminal
? Confluence Account Email: › 마지막으로 API 토큰을 입력해야 합니다.
Terminal
? Confluence API Token: ›
❯ Create an API token at https://id.atlassian.com/manage/api-tokensConfluence API 토큰은 계정에 종속됩니다. 토큰을 생성한 뒤 복사하여 이 프롬프트에 붙여넣으세요. 액세스 토큰에 대한 자세한 내용은 Confluence API 토큰 문서를 참고하세요.
Quarto는 이 계정 정보(도메인, 이메일, 토큰)를 저장하여 이후 quarto publish confluence 호출에 사용할 수 있습니다. 마지막 프롬프트에서 페이지의 배포 대상을 선택합니다.
배포 대상 선택
Confluence의 페이지는 계층 구조로 구성되며, 모든 페이지에는 부모가 있습니다. Quarto에서 Confluence로 배포할 때 페이지의 부모를 URL로 지정해야 합니다.
Terminal
? Space or Parent Page URL: ›
❯ Browse in Confluence to the space or parent, then copy the URL페이지를 공간의 최상위에 두려면 공간 자체를 지정하세요. 예:
https://domain.atlassian.net/wiki/spaces/ABBR그렇지 않다면 부모 페이지의 URL을 지정하세요. 예:
https://domain.atlassian.net/wiki/spaces/ABBR/pages/123456배포 대상을 지정하면 Quarto가 페이지를 렌더링한 뒤 Confluence에 배포하고, 배포된 페이지를 보기 위해 브라우저를 엽니다.
confluence-demo.qmd가 배포된 예시는 다음과 같습니다.
대상을 공간 URL로 설정했기 때문에 사이드바 탐색에서 이 페이지는 Pages 아래의 최상위로 표시됩니다.
프로젝트 배포
문서 모음을 배포하려면 문서를 Quarto 프로젝트로 구성하고 confluence 프로젝트 유형을 사용하세요. Confluence 프로젝트의 최소 _quarto.yml 파일은 다음과 같습니다.
_quarto.yml
project:
type: confluence이 파일을 프로젝트 디렉터리에 포함하고 .qmd 또는 .ipynb 문서를 원하는 배포 계층 구조로 배치하세요. 예:
_quarto.yml
index.qmd
team.qmd
projects/
planning.qmd
retrospectives.qmd또는 새 디렉터리에서 템플릿 프로젝트로 시작하려면 quarto create를 사용하세요.
Terminal
quarto create project confluence문서와 마찬가지로 VS Code와 RStudio의 Render 명령 또는 명령줄의 quarto preview로 프로젝트를 미리볼 수 있습니다.
Terminal
quarto preview프로젝트 미리보기는 사이드바에 자동으로 내비게이션이 추가된 HTML 웹사이트를 생성합니다. 이 내비게이션은 편의를 위한 것이며, 배포된 페이지의 내비게이션은 Confluence가 내부적으로 처리합니다.
프로젝트 미리보기는 Confluence에서의 표시를 최대한 반영하려 하지만, 일부 표현이 다를 수 있습니다.
프로젝트를 배포하려면 프로젝트 폴더에서 quarto publish confluence를 실행하세요.
Terminal
quarto publish confluence 단일 문서를 배포할 때와 동일한 단계(필요한 경우 계정 설정, Confluence에서 프로젝트의 배포 대상 선택)를 거쳐 Confluence에 프로젝트를 배포합니다.
프로젝트 구조
프로젝트의 폴더 안 문서 계층 구조는 배포 과정에서 그대로 반영됩니다. Confluence에서 폴더는 페이지가 자식 페이지를 가질 수 있는 구조이므로, 폴더는 Confluence에서 페이지로 표현됩니다.
프로젝트를 배포하면 이를 담는 단일 페이지가 Confluence에 생성됩니다. 프로젝트 최상위 문서는 이 프로젝트 페이지 아래에 중첩된 페이지로 배포됩니다. 프로젝트 내부 폴더는 페이지로 표현되며, 그 폴더 안의 문서(또는 다른 폴더)는 해당 폴더 페이지 아래에 중첩됩니다.
예를 들어 다음과 같은 프로젝트 구조가 있다고 가정해 보겠습니다.
example-project/
├── _quarto.yml
├── project-roadmap.qmd
├── reports-folder
│ ├── 2023-01.qmd
│ └── 2023-03.qmd
└── team-members.qmd이 프로젝트를 공간의 최상위에 배포하면 다음과 같은 Confluence 구조가 됩니다.
Confluence 사이드바 탐색에 표시되는 제목은 문서 YAML과 _quarto.yml에 지정된 페이지 및 프로젝트 제목을 사용하며, 폴더는 폴더 이름에서 생성됩니다. Quarto는 공간 내 페이지 이름이 모두 고유해야 한다는 Confluence 요구 사항을 충족하기 위해 추가 문자를 더할 수 있습니다.
index.qmd
폴더를 나타내는 Confluence 페이지는 해당 폴더 안에 index.qmd가 없으면 내용이 없습니다. index.qmd 파일이 있으면 그 내용이 폴더 페이지에 채워집니다. 예를 들어 다음 index.qmd를 보세요.
index.qmd
---
title: Reports
---
Monthly reports on project progress이를 reports-folder 폴더에 추가하고 사이트를 다시 배포하면, 이 폴더를 대표하는 페이지 이름이 “Reports”로 바뀌고 해당 내용이 페이지에 추가됩니다.
배포 워크플로
Confluence에서는 많은 사용자가 페이지를 직접 편집할 수 있습니다. 그러나 Quarto로 콘텐츠를 관리하려면 관점 전환이 필요합니다. 페이지 편집은 Quarto 프로젝트에서만 수행하고, 변경 사항은 한 계정에서만 Confluence로 배포해야 합니다.
Confluence로의 배포는 단방향입니다. Confluence에서 편집한 내용을 Quarto 프로젝트로 되돌릴 방법이 없습니다. Confluence에서의 편집 내용은 다음에 Quarto에서 페이지를 배포할 때 덮어쓰기 됩니다. 페이지를 업데이트하려면 Quarto에서 문서를 수정한 뒤 다음을 다시 실행해야 합니다.
Terminal
quarto publish confluence Quarto로 관리하는 페이지를 누군가 실수로 편집하는 상황을 막기 위해, 배포 시 권한이 설정되어 공간에 접근 가능한 모든 사용자는 페이지를 볼 수 있지만 게시자인 본인만 편집할 수 있습니다.
페이지 편집 권한에는 업데이트 배포도 포함되므로, 페이지 업데이트는 최초 배포와 같은 계정에서 배포해야 합니다.
페이지 권한을 제어할 수 없는 대상으로 배포하려 하면 이를 감지해 경고를 표시합니다. 계속 배포할 수는 있지만, 배포된 모든 페이지는 공간에 접근 가능한 누구나 보고 편집할 수 있습니다.
Confluence에서 페이지를 삭제한 뒤 Quarto에서 다시 배포하면 다음 오류가 표시됩니다.
ERROR: API Error: 404 - Not Found이는 Quarto가 Confluence의 페이지 위치를 _publish.yml에 저장해 재사용하기 때문입니다. 페이지가 Confluence에서 삭제되면 해당 위치가 더 이상 존재하지 않습니다. 해결하려면 _publish.yml에서 해당 항목을 삭제한 뒤 다시 배포하세요. 그러면 배포 대상을 다시 설정하라는 안내가 표시됩니다. _publish.yml에 대한 자세한 내용은 배포 설정 섹션을 참고하세요.
저작
Confluence용 저작은 HTML 문서나 Quarto 웹페이지 저작과 매우 유사합니다. 다만 몇 가지 핵심 제한과 Confluence 배포에 특화된 기능이 있습니다.
콘텐츠 제한
confluence-html 형식은 표, 콜아웃, 상호 참조 등 거의 모든 표준 Quarto 마크다운 콘텐츠 유형을 지원합니다.
하지만 현재 인용, 비디오, 다이어그램, 탭셋, 수식은 지원하지 않습니다. 향후 Confluence에서 해당 기능을 지원할 수 있는 동등한 기능이 있다면 추가될 수 있습니다.
링크
Confluence 프로젝트 내 페이지 간 링크를 만들 때 Confluence 페이지 경로 대신 소스 파일을 링크 대상으로 사용할 수 있습니다. 문서의 특정 섹션으로 링크하려면 소스 파일에 해시 식별자(#)를 추가할 수 있습니다. 예:
[about](about.qmd)
[about](about.qmd#section)Raw Confluence 블록
Raw Confluence 블록은 Quarto를 변경 없이 통과해 Confluence가 직접 해석해야 하는 콘텐츠를 포함할 수 있게 합니다. 예를 들어 Confluence Storage Format에는 작업 목록을 위한 특정 태그가 있습니다. 문서에 Confluence 작업 목록을 포함하려면 raw Confluence 블록 안에서 이 태그를 사용하세요.
```{=confluence}
<ac:task-list>
<ac:task>
<ac:task-status>incomplete</ac:task-status>
<ac:task-body>task list item</ac:task-body>
</ac:task>
</ac:task-list>
```Confluence에 배포하면 다음과 같은 목록이 표시됩니다.
웹사이트 제한
Confluence 프로젝트는 특별한 유형의 웹사이트로, Listings, Themes, Navigation 같은 전통적인 웹사이트 기능을 지원하지 않습니다(Confluence 내부에서 처리되기 때문입니다).
Confluence 제한
배포 워크플로에서 설명했듯이 Confluence에서 페이지 콘텐츠를 편집하면 Quarto에서 배포할 때 덮어쓰기 됩니다. Confluence에서 작성한 인라인 댓글도 마찬가지입니다. 페이지 레벨 이모지와 페이지 레벨 댓글은 배포 간에 유지됩니다.
배포 설정
Confluence에 배포한 뒤에는 배포 및 계정 설정을 어떻게 관리하는지 알고 싶을 수 있습니다.
_publish.yml
_publish.yml 파일은 배포 대상을 지정하는 데 사용됩니다. 이 파일은 quarto publish 명령을 실행할 때마다 자동으로 생성(또는 업데이트)되며, 프로젝트 또는 문서 디렉터리에 위치합니다.
배포된 콘텐츠의 서비스, id, URL은 _publish.yml에 지정됩니다. 예:
- source: project
confluence:
- id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
url: "https://myteam.atlassian.net/wiki/spaces/TEAMSPACE/pages/123456/Plan"다음에 같은 문서나 프로젝트를 배포할 때 _publish.yml 파일을 사용해 계정과 공간 정보를 제공하므로, 이 정보를 다시 입력할 필요가 없습니다.
이미 배포하려는 Confluence Space가 있다면 위 예시와 같은 _publish.yml 파일을 수동으로 만들고, 문서에 맞는 id와 url 값을 넣어야 합니다.
계정 정보는 _publish.yml에 저장되지 않으므로 버전 관리에 포함하거나 여러 게시자가 공유해도 안전합니다.
계정 관리
quarto publish accounts 명령으로 저장된 Confluence 계정을 조회하고 제거할 수 있습니다.
$ quarto publish accounts
? Manage Publishing Accounts
❯ ✔ Confluence: jj@posit.co
✔ Netlify: jj@posit.co
❯ Use the arrow keys and spacebar to specify
accounts you would like to remove. Press
Enter to confirm the list of accounts you
wish to remain available.