사이트 URL
url 키
플레이북의 site 키 아래에 정의된 사이트의 url 키는 선택사항이지만 권장됩니다.
이 키가 설정되지 않으면 사이트 URL이 필요한 특정 기능들이 자동으로 비활성화됩니다.
자세한 내용은 사이트 URL은 언제 설정해야 하나요?를 참조하세요.
site:
title: Site Title
url: https://docs.example.comurl 키는 사이트가 게시된 후 접근할 수 있는 위치를 정의합니다.
url 키의 값은 절대 URL (https://docs.example.com, https://example.com/docs) 또는 루트 상대 URL (/products)일 수 있습니다.
값이 단일 슬래시 (/)인 경우를 제외하고는 url 값에 끝에 슬래시를 포함하지 마세요.
사이트 URL은 절대 URL이나 루트 상대 URL이 필요한 생성된 사이트의 모든 곳에 나타납니다. 자세한 내용은 How Antora Builds URLs를 참조하세요.
절대 사이트 URL 구성하기
절대 URL 값은 URL 스키마로 시작하고 바로 뒤에 콜론과 두 개의 슬래시 (https://)가 오며 그 다음에 도메인 (docs.example.org)이 옵니다.
URL 끝에 슬래시를 넣지 마세요.
site:
title: Docs for Example Site
url: https://docs.example.com절대 사이트 URL에는 하위 경로가 포함될 수 있습니다 (예: https://example.com/docs, https://example.com/path/to/subfolder). 하위 경로는 경로 세그먼트 또는 경로 이름이라고도 하며, Antora가 관리하는 사이트가 게시되는 도메인의 루트로부터의 위치를 나타냅니다. 사이트가 도메인의 하위 폴더에 게시되는 경우, 절대 사이트 URL에 이 경로를 포함해야 합니다. 하위 경로는 루트 상대 URL과 동일한 구문을 가집니다.
site:
title: Docs for Example Site
url: https://example.com/docs절대 사이트 URL에 하위 경로가 있을 때, Antora는 하위 경로를 추출하여 사이트 경로 이름 (/docs, /path/to/subfolder)에 할당하여 도메인 상대 URL이 필요한 곳에서 사용합니다.
도메인 하위 폴더에 사이트를 게시하는 것에 대한 자세한 정보는 사이트 URL에 하위 경로를 포함해야 하는 경우는 언제인가요?를 참조하세요.
루트 상대 사이트 URL 구성하기
루트 상대 URL은 도메인에 상대적인 URL이지만 도메인 자체를 지정할 필요가 없습니다. 루트 상대 URL은 슬래시로 시작해야 합니다 (/products).
site:
title: Docs Hosted Somewhere
url: /products동일한 사이트를 여러 도메인에 게시하거나 여러 도메인을 통해 접근해야 하는 경우 절대 URL 대신 루트 상대 URL을 사용할 수 있습니다.
루트 상대 URL을 사용하면 사이트 URL 할당의 많은 이점을 활용할 수 있습니다.
그러나 url에 할당된 값이 절대 URL이 아닌 경우 Antora는 절대 사이트 URL에 의존하는 모든 기능을 비활성화합니다.
Antora는 루트 상대 URL을 도메인 상대 URL을 계산하기 위해 직접 사이트 경로 이름에 할당합니다.
url을 루트 상대 URL로 설정하되 사이트 경로 이름을 비워두고 싶다면 값을 단일 슬래시로 설정하세요.
site:
title: The Docs
url: /사이트 URL은 언제 설정해야 하나요?
Antora 사이트는 오프라인에서 그리고 로컬 파일 시스템에서 볼 수 있도록 설계되었습니다. 이러한 이유로 사이트를 구축하는 데 사이트 URL이 필요하지 않습니다.
그러나 게시와 관련된 특정 기능들은 사이트 URL이 필요하며, 일부는 절대 URL이 필요합니다. 사이트 URL이 설정되지 않으면 이러한 기능들이 자동으로 비활성화됩니다. 이 섹션에서는 이러한 기능들과 그들이 필요로 하는 사이트 URL의 종류를 설명합니다.
사이트 URL에 의존하는 기능들
사이트 URL이 허용 가능한 값으로 설정되면 다음 기능들이 활성화됩니다:
-
모든 AsciiDoc 문서에
site-url속성이 설정됩니다. -
UI 모델에
site.url속성이 설정됩니다 (플레이북의site.url키 값 사용). -
사이트 경로 이름 속성인
site.path가 UI 모델에 설정됩니다 (플레이북의site.url키에서 파생). -
404 페이지가 생성됩니다.
-
플레이북에
site.robots도 정의된 경우 robots.txt 파일이 생성됩니다. -
비어 있지 않은 경우 리다이렉트에 사이트 경로 이름(
site.path)이 포함됩니다. 이는 상대 URL을 사용하는 정적 리다이렉트 기능에는 영향을 미치지 않습니다. -
네비게이션 바 왼쪽 상단의 링크가 상대 경로 대신 사이트 URL을 가리킵니다 (기본 UI에 특정한 동작).
사이트 URL이 절대 URL로 설정되면 다음과 같은 추가 기능이 활성화됩니다:
-
사이트맵 파일이 생성됩니다.
-
UI 모델에
page.canonicalUrl이 설정되며, 이는 참조 UI에서 head의 정규 링크 태그를 생성하는 데 사용됩니다.
사이트 URL이 설정되지 않으면 위에서 언급한 모든 기능이 비활성화됩니다.
사이트 URL에 하위 경로를 포함해야 하는 경우는 언제인가요?
사이트 URL의 하위 경로는 Antora가 관리하는 사이트가 위치한 도메인 루트로부터의 위치를 나타냅니다. 다시 말해, 사이트 URL은 방문자를 사이트 시작 페이지의 리다이렉트가 위치한 URL로 안내합니다. 사이트가 도메인의 하위 폴더에 게시되는 경우, 사이트 URL에 이 경로를 포함해야 합니다 (예: /path/to/subfolder).
필요한 경우 Antora는 사이트 URL을 사용하여 사이트 페이지에 대한 절대 및 도메인 상대 URL을 구성하며, 이는 항상 지정된 경우 하위 경로를 포함합니다. 여기에는 '절대 URL’인 사이트맵의 URL과 도메인 '상대 URL’를 통한 재작성 규칙(Rewrite Rule)이 포함됩니다.
서버 리다이렉트 규칙을 만들 때 하위 경로가 어떻게 사용되는지 예를 들어 살펴봅시다. 다음 조건이 참이라고 가정해 봅시다:
Antora를 실행하면 다음과 같은 리다이렉트 규칙이 생성됩니다:
/component-a/old-page.html /component-a/new-page.html 301!
리다이렉트 규칙의 도메인 상대 URL에 선행 /docs 세그먼트가 포함되어 있지 않음을 주목하세요.
이는 https://example.com/docs/component-a/old-page.html을 방문하면 규칙이 일치하지 않기 때문에 새 페이지로 리다이렉트되지 않는다는 것을 의미합니다.
이를 수정해 봅시다.
플레이북을 편집하고 url 키를 https://example.com/docs로 설정합니다.
이제 Antora를 실행하면 올바른 리다이렉트 규칙이 생성됩니다:
/docs/component-a/old-page.html /docs/component-a/new-page.html 301!
도메인 상대 URL에 선행 /docs 세그먼트가 있음을 주목하세요.
이제 https://example.com/docs/component-a/old-page.html을 방문하면 새 페이지로 리다이렉트됩니다.
사이트가 도메인의 하위 폴더에 게시되는 경우 절대 사이트 URL에 경로를 포함하는 것이 중요합니다.
사이트를 특정 도메인에 연결하지 않으려면 대신 루트 상대 사이트 URL을 할당하세요.
어느 쪽이든, 사이트를 도메인의 하위 폴더에 게시하는 경우 사이트의 url 키에 할당하는 값에 하위 경로를 포함해야 합니다.
정규 URL
Antora는 정규 URL에 대한 내장 지원을 제공합니다. 정규 URL은 페이지의 선호 버전에 대한 절대 URL입니다. 즉, 검색 엔진이 색인화하기를 원하는 페이지입니다.
사이트 URL에 절대 URL을 할당하면 Antora는 적용 가능한 모든 페이지에 대해 정규 URL을 계산하고 UI 모델의 page.canonicalUrl 속성에 할당합니다.
적용 가능한 페이지는 적어도 하나의 비 프리릴리스 버전이 있는 컴포넌트의 모든 게시 가능한 페이지입니다.
사이트 URL이 절대 URL로 설정되지 않았거나 페이지가 적어도 하나의 비 프리릴리스 버전이 있는 컴포넌트에 속하지 않은 경우, Antora는 정규 URL을 채우지 않습니다.
정규 URL은 페이지의 최신 비 프리릴리스 버전의 절대 URL입니다. 정규 URL은 사이트 URL(하위 경로 포함)을 해당 페이지의 (루트 상대) URL 앞에 붙여 계산됩니다.
정규 URL은 현재 페이지가 최신 비 프리릴리스 버전인 경우에만 현재 페이지를 가리킵니다. 그렇지 않으면 정규 URL은 현재 페이지의 최신 비 프리릴리스 버전을 가리킵니다.
주의: 페이지가 삭제된 경우, 페이지의 최신 버전이 컴포넌트의 최신 버전에 있지 않을 수 있습니다.
정규 URL 링크 태그
검색 크롤러가 정규 URL을 인식하려면 UI 템플릿이 이를 페이지에 포함해야 합니다.
정규 URL은 페이지의 <head> 태그 내에 있는 <link rel="canonical"> 태그의 href 속성 값으로 선언되어야 합니다.
Antora의 Default UI는 이를 자동으로 처리합니다.
다음은 Antora의 Default UI에서 이 <link> 태그를 생성하는 템플릿 로직입니다:
{{#with page.canonicalUrl}}
<link rel="canonical" href="{{{this}}}">
{{/with}}다음은 생성된 페이지에서 정규 URL이 어떻게 나타나는지 보여줍니다:
<link ref="canonical" href="https://docs.example.org/component-name/2.0/page-name.html">정규 URL이 참조하는 페이지가 컴포넌트의 모든 버전에 존재한다고 가정하면, 페이지의 모든 버전에 동일한 <link> 태그가 포함됩니다.
페이지가 프리릴리스 버전에 있는 경우, 최신(비 프리릴리스) 버전의 페이지를 참조합니다.
| 사용자 정의 UI에 정규 URL을 페이지 템플릿에 포함할지 여부는 해당 UI 제작자의 결정입니다. Antora는 단순히 UI 페이지 모델을 통해 이 정보를 제공합니다. Antora의 기본 UI는 페이지 템플릿에 필요한 태그를 포함합니다. |
정규 URL의 작동 방식
정규 URL의 목적은 검색 엔진이 동일한 페이지의 여러 버전을 연관 짓고 어떤 버전의 페이지가 선호되는지(즉, 색인화할 버전)를 제안하는 데 도움을 주는 것입니다. 검색 엔진이 현재 URL과 다른 정규 URL을 가진 페이지를 발견하면, 해당 페이지를 색인화하지 않고 정규 URL이 가리키는 페이지를 색인화해야 합니다. 정규 URL을 정의함으로써 오래된 버전의 페이지가 검색 결과에 나타나지 않도록 할 수 있습니다.
한 가지 주의할 점은 페이지가 컴포넌트의 이전 버전에는 있지만 최신 버전에는 없는 경우, 정규 URL이 이전 버전의 페이지를 가리키게 되어 색인화될 수 있다는 것입니다. 이를 원하지 않는다면, 최신 버전의 컴포넌트에서 다른 페이지가 페이지 별칭을 사용하여 해당 페이지를 참조하도록 해야 합니다. 이렇게 하면 Antora가 정규 URL을 해당 페이지를 참조하는 페이지로 설정하여 이전 페이지가 색인화되는 것을 방지할 수 있습니다.