Scroll ViewPort 로 Confluence theme 꾸미기 #1 - 기본 설정
소개
Scroll viewport 는 Scroll Office Exporter 와 Scroll PDF Exporter 로 유명한 k15t 사의 Confluence 용 테마 플러그인입니다.
밋밋한 Confluence 의 기본 테마에 비해 비교적 미려하고 사용자 친화적인 테마를 기본 내장하고 있으며 특히 제품이나 API 매뉴얼 사이트를 Confluence 로 만들 때 유용합니다.
실제로 Atlassian 사의 제품 매뉴얼 사이트인 https://confluence.atlassian.com/ 도 Scroll ViewPort 를 사용해서 제공되고 있습니다.
기본 테마도 충분히 쓸만하지만 더 강력하게 customizing 을 하고 싶을 경우 직접 css 와 JS 를 만들수 있는 custom theme 기능도 제공하며 Atlassian markplace 에서 viewport 를 찾아서 설치하면 됩니다.
ViewPort 는 개별 Space 마다 설정할 수 있으므로 적용할 스페이스에 들어간 후에 Space tools → Apps 메뉴에 진입하면 ViewPort 를 설정할 수 있습니다.
Create Viewport 를 클릭하면 구성 요소를 설정할 수 있으며 다음 4가지 요소로 구성되어 있습니다.
- Theme: 어떤 ViewPort 테마를 사용할 지 설정할 수 있습니다.
- Content: Page, Blog 등 어떤 콘텐츠를 표시할 지 설정합니다. .
- URL: 사이트의 URL 과 Path 를
- Permissions: viewPort 를 설정할 수 있는 권한을 부여합니다.
Theme 설정
기본적으로 "Web Help" 와 "Help Center" 2가지 테마를 제공합니다. 사용할 테마를 설정하기 위해서는 기본 테마의 ... 을 눌러서 메뉴를 표시한 후에 Copy 를 선택해서 테마를 하나 복제해 둡니다.
그후에 사용할 테마를 클릭해서 선택한 후에 Save 를 클릭하면 해당 테마가 적용되며 lesstif.com 은 "Help Center" 테마를 복제해서 사용하고 있습니다.
상세 테마 설정은 메뉴에서 Edit 를 클릭해서 할수 있고 자세한 내용은 Scroll ViewPort 로 Confluence theme 꾸미기 #2 - 테마 설정 을 참고하세요.
Content 설정
viewport 로 제공할 콘텐츠를 설정하며 Page와 Blog 를 선택할 수 있습니다. Scroll Versions 나 Translation 같은 다른 k15t 사의 제품을 사용할 경우 Viewport 와도 통합할 수 있습니다
URL 설정
중요한 내용이니 내용을 읽어보시고 꼭 flat URL 로 설정하세요.
viewport 로 제공할 contents 의 URL 을 설정할 수 있습니다. 스페이스를 단일 viewport 로 묶을 경우 "Domain Name" 항목에 같은 도메인을 지정해 주면 됩니다.
Path 항목에는 해당 스페이스를 접근할 수 경로를 설정할 수 있으며 아래 설정은 /gitbook 이라는 패스를 통해 접근할 수 있도록 합니다.
Page Path 는 굉장히 중요한 설정으로 기본 설정은 "Hierarchical " 인데 페이지에 계층적으로 접근할 수 있도록 해줍니다.
즉 /gitbook 스페이스 밑에 다음과 같은 계층 구조로 페이지가 있다고 가정해 보겠습니다.
- git-환경 설정
- git config
- git-명령어
- git pull
Hierarchical 일 경우 제목을 기반으로 ascii 문자 기반의 slug 방식 url이 생성되므로 git-config 페이지에 접근할 경우 /gitbook/git/git-config 와 같은 URL 로 접근할 수 있습니다.
직관적인 URL 이지만 Hierarchical 방식은 다음과 같은 큰 단점이 있습니다.
- 한글 제목이 있을 경우 페이지 제목에서 한글이 사라져서 URL 이 생성되므로 위와 같이 "git 환경 설정", "git 명령어" 2개의 페이지가 같은 계층에 있을 경우 둘 다 동일한 Path(git) 로 생성되어 404 에러가 나게 됩니다.
- 페이지 제목으로 URL 이 생성되므로 페이지 제목을 변경할 경우 이미 검색엔진에서 인덱싱한 URL 과 달라져서 검색 엔진을 타고 들어올 경우에도 404 에러가 날 수 있습니다.
위와 같은 문제점을 해결하려면 계층 구조가 아니라 단일 패스로 URL 이 생성되는 flat 방식의 URL 로 설정하면 됩니다.
flat 방식도 한글을 제거해서 페이지 URL 을 만들지만 "https://www.lesstif.com/ats/confluence-jira-email-mailgun-gmail-30704922.html" 처럼 URL 의 마지막에 페이지의 ID 가 포함되므로 다음과 같은 장점이 있습니다.
- 한글을 제거했을 때 동일한 제목의 페이지가 있어도 페이지 URL 이 중복되지 않습니다.
- ID 가 URL에 포함되었으므로 https://www.lesstif.com/ats/confluence-30704922.html 와 같이 다른 URL 로 호출해도 ID만 있으면 404 에러가 나지 않으며 제목을 변경해도 검색엔진을 통해 제대로 인입됩니다.
Permission 설정
지정한 그룹만 confluence 순정 UI 에 접근할 수 있도록 합니다.
특별히 설정하지 않을 경우 confluence-admin 그룹만 가능하며 해당 그룹의 사용자로 로그인하면 첨부처럼 좌측에 관리자 패널이 표시되므로 여기에서 viewport 를 바로 설정하거나 Confluence UI 로 접근할 수 있습니다.
다음은 "Help Center" 테마 상세 설정 에 대해서 알아 보겠습니다.