Eundms · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -37,6 +37,10 @@ jobs:
       - name: Build docs (sphinx, English -> /en/)
         run: tox -e docs-en
 
+      - name: Check external links (non-blocking)
+        run: tox -e linkcheck
+        continue-on-error: true
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -88,13 +88,53 @@ reStructuredText conventions
 Documentation style guide
 ==========================
 
-* **Translated documents**: Convey the meaning of the source (English) text
-  accurately while prioritizing natural Korean prose. When a technical term
-  first appears, write it as ``한글(English)``.
-* **Proper nouns / project names**: Keep the original spelling for names such
-  as OpenStack, Kubernetes, Nova, and Neutron.
-* **Commands / code**: Specify the appropriate language for ``code-block``
+Korean prose conventions
+------------------------
+
+Korean is the source language of this repository, so these rules keep the
+pages consistent and keep the gettext catalog stable.
+
+* **Sentence endings**: use the polite ``합니다`` style
+  ("Neutron 은 ... 서비스입니다"), not the plain ``한다`` style. The only
+  exception is ``doc/source/glossary.rst``, where dictionary-style ``한다``
+  definitions are used throughout.
+* **Spacing around particles**: put a space between a Latin word and the
+  Korean particle that follows it — ``Neutron 은``, ``Pod 가``, ``VM 의``,
+  ``openstack-helm 으로``. Particles after a bare number stay attached
+  (``폭이 2로``), and particles after a closing parenthesis stay attached
+  (``제어 평면(control plane)이라고``).
+* **First use of a term**: write it as ``한글(English, ABBR)`` — for example
+  ``특별 관심 그룹(Special Interest Group, SIG)`` or
+  ``역할 기반 접근 제어(role-based access control, RBAC)``. Use the
+  abbreviation alone afterwards.
+* **Proper nouns / project names**: keep the original spelling for names such
+  as OpenStack, Kubernetes, Nova, and Neutron. Write the project name as
+  ``openstack-helm`` in lower case, and spell ``Kubernetes`` out rather than
+  abbreviating it to ``K8s``.
+* **Preferred terms**: ``Pod`` (not 파드), ``VM`` (not 가상 머신 after the
+  first use), ``Octavia`` (not 옥타비아). When in doubt, follow the headword
+  used in ``doc/source/glossary.rst`` and link the first mention with
+  ``:term:``.
+
+Markup and links
+----------------
+
+* **Commands / code**: specify the appropriate language for ``code-block``
   directives (``console``, ``yaml``, ``bash``, etc.).
+* Use inline literals (``` ``like this`` ```) only for code, paths, commands
+  and identifiers. To emphasize a phrase, use ``**bold**`` instead.
+* Prefer ``` ``literal`` ``` over the ``:code:`` role for inline code.
+* Write ordered lists with ``#.`` so the numbering stays automatic.
+* Point external links at their final URL, not at one that redirects
+  (``https://docs.openstack.org/magnum/latest/``, not
+  ``https://docs.openstack.org/magnum/``). ``tox -e linkcheck`` reports both
+  broken links and redirects.
+
+Translated documents
+--------------------
+
+Convey the meaning of the source text accurately while prioritizing natural
+prose, and record the source document and its version.
 
 For detailed rST/Sphinx conventions, see the ``doc/source/documentation/``
 section.

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -17,7 +17,6 @@
 # -- 일반 설정 ---------------------------------------------------------------
 
 extensions = [
-    'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
 ]
 
@@ -49,9 +48,19 @@
 
 html_title = 'OpenStack & Kubernetes 한글 문서화 프로젝트'
 
-# -- intersphinx 설정 --------------------------------------------------------
-# 외부 공식 문서로의 교차 참조. 네트워크가 없는 환경에서도 빌드가
-# 실패하지 않도록 타임아웃을 짧게 둡니다.
+# -- 링크 검사 (linkcheck) ---------------------------------------------------
+# ``tox -e linkcheck`` 로 외부 링크의 유효성을 확인합니다.
+# 리다이렉트는 문서에서 최종 URL 로 바로 적는 것을 원칙으로 합니다.
 
-intersphinx_mapping = {}
-intersphinx_timeout = 5
+# 봇 접근을 차단해 403 을 돌려주지만 사람은 정상적으로 볼 수 있는 링크.
+linkcheck_ignore = [
+    r'https://www\.netapp\.com/learn/.*',
+]
+
+# 링크 검사 시 동시 요청 수와 재시도 (CI 에서의 산발적 실패를 줄입니다).
+linkcheck_workers = 5
+linkcheck_timeout = 15
+linkcheck_retries = 2
+
+# 외부 공식 문서로의 교차 참조가 필요해지면 ``sphinx.ext.intersphinx`` 를
+# extensions 에 추가하고 여기에 intersphinx_mapping 을 정의하세요.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
@@ -1,6 +1,6 @@
-======
+====
 기여
-======
+====
 
 이 프로젝트에 기여하는 방법을 안내합니다. 기여는 크게 문서화와 번역·국제화로
 나뉘며, 각각의 도구와 관례는 하위 문서에서 다룹니다.

diff --git a/doc/source/documentation/kubernetes-doc-conventions.rst b/doc/source/documentation/kubernetes-doc-conventions.rst
@@ -1,6 +1,6 @@
-=========================
+====================
 Kubernetes 문서 관례
-=========================
+====================
 
 Kubernetes 공식 문서는 OpenStack 과 달리 `Hugo <https://gohugo.io/>`_ 와
 Markdown 기반입니다. 본 프로젝트는 rST/Sphinx 로 작성하지만, Kubernetes
@@ -15,7 +15,7 @@ Markdown 기반입니다. 본 프로젝트는 rST/Sphinx 로 작성하지만, Ku
 핵심 출처
 =========
 
-* Kubernetes Documentation (website) — https://kubernetes.io/docs/
+* Kubernetes Documentation (website) — https://kubernetes.io/docs/home/
 * Contribute to Kubernetes docs —
   https://kubernetes.io/docs/contribute/
 

diff --git a/doc/source/documentation/openstack-doc-conventions.rst b/doc/source/documentation/openstack-doc-conventions.rst
@@ -1,6 +1,6 @@
-========================
+===================
 OpenStack 문서 관례
-========================
+===================
 
 OpenStack 은 문서 기여에 대한 체계적인 가이드를 제공합니다. 본 프로젝트는
 이 관례를 학습 모델로 삼습니다.

diff --git a/doc/source/documentation/review-guidelines.rst b/doc/source/documentation/review-guidelines.rst
@@ -16,9 +16,15 @@
 
 * [ ] 로컬에서 ``tox -e docs`` 빌드가 통과하는가
 * [ ] ``tox -e pep8`` (doc8) 린트가 통과하는가
+* [ ] ``tox -e linkcheck`` 에서 깨진 링크·리다이렉트가 없는가
 * [ ] 새 문서를 상위 ``toctree`` 에 등록했는가
+* [ ] 새 문서로 들어오는 ``:doc:`` 링크를 관련 문서에 하나 이상 넣었는가
 * [ ] 교차 참조(``:doc:``)와 외부 링크가 유효한가
-* [ ] 용어를 :doc:`../glossary` 와 일관되게 사용했는가
+* [ ] 문장을 합니다체로 썼는가 (용어집은 예외)
+* [ ] 로마자 뒤 조사를 띄어 썼는가 (``Neutron 은``, ``Pod 가``)
+* [ ] 용어를 :doc:`../glossary` 와 일관되게 쓰고, 첫 등장에 ``:term:`` 을
+  걸었는가
+* [ ] 용어 첫 등장을 ``한글(English, ABBR)`` 형식으로 적었는가
 * [ ] 번역 문서라면 원문 출처와 버전을 명시했는가
 
 
@@ -30,6 +36,7 @@
 * **명확성** — 입문자가 이해할 수 있는가
 * **구조** — 적절한 섹션/제목 레벨을 사용했는가
 * **일관성** — 용어·표기·스타일이 프로젝트 관례를 따르는가
+  (``CONTRIBUTING.rst`` 의 Documentation style guide 참고)
 * **빌드** — GitHub Actions 문서 빌드가 통과했는가
 
 

diff --git a/doc/source/documentation/rst-sphinx-basics.rst b/doc/source/documentation/rst-sphinx-basics.rst
@@ -1,10 +1,10 @@
-====================
+=================
 rST / Sphinx 기초
-====================
+=================
 
-본 프로젝트는 reStructuredText(rST)와 `Sphinx <https://www.sphinx-doc.org/>`_
-로 문서를 작성합니다. 이 문서는 처음 기여하는 분을 위한 최소한의 기초를
-정리합니다.
+본 프로젝트는 reStructuredText(rST)와
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_ 로 문서를 작성합니다.
+이 문서는 처음 기여하는 분을 위한 최소한의 기초를 정리합니다.
 
 
 왜 rST/Sphinx 인가

diff --git a/doc/source/foundations/bridging-concepts.rst b/doc/source/foundations/bridging-concepts.rst
@@ -1,6 +1,6 @@
-==========================================
+======================================
 OpenStack ↔ Kubernetes 연동 인터페이스
-==========================================
+======================================
 
 가상화 기초·OpenStack·Kubernetes 세 레이어를 이해했다면, 다음은 두 기술을
 실제로 잇는 표준 인터페이스입니다. 각 개념의 상세는 통합 패턴·네트워킹·
@@ -15,7 +15,7 @@ OpenStack ↔ Kubernetes 연동 인터페이스
 
 
 연동 표준 인터페이스
-========================
+====================
 
 Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점입니다. 각
 인터페이스가 OpenStack 의 무엇과 이어지는지가 핵심입니다.
@@ -32,7 +32,8 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
      - :doc:`../openstack-on-kubernetes/cni-and-neutron`
    * - CSI
      - 퍼시스턴트 스토리지 ↔ Cinder
-     - :doc:`../kubernetes-on-openstack/cinder-csi`
+     - :doc:`kubernetes-csi` (개념),
+       :doc:`../kubernetes-on-openstack/cinder-csi` (연동)
    * - CCM
      - LoadBalancer·노드 수명주기 ↔ OpenStack
      - :doc:`../kubernetes-on-openstack/cloud-provider-openstack`
@@ -50,7 +51,7 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
 .. _bridging-concepts-provisioning:
 
 배포·프로비저닝
-========================
+===============
 
 두 기술을 결합하는 방법으로, 방향에 따라 나뉩니다.
 
@@ -62,22 +63,22 @@ Kubernetes 가 클라우드(OpenStack) 자원을 쓰기 위한 표준 확장점
      - 한 줄 정의
      - 상세
    * - openstack-helm
-     - OpenStack 을 K8s 에 배포 (OpenStack → K8s)
+     - OpenStack 을 Kubernetes 에 배포 (OpenStack → Kubernetes)
      - :doc:`../openstack-on-kubernetes/openstack-helm`
    * - Magnum
-     - OpenStack 이 K8s 클러스터를 생성 (K8s → OpenStack)
+     - OpenStack 이 Kubernetes 클러스터를 생성 (Kubernetes → OpenStack)
      - :doc:`../kubernetes-on-openstack/magnum`
    * - Cluster API (CAPO)
-     - 선언적으로 K8s 클러스터 프로비저닝 (K8s → OpenStack)
+     - 선언적으로 Kubernetes 클러스터 프로비저닝 (Kubernetes → OpenStack)
      - :doc:`../kubernetes-on-openstack/cluster-api`
 
 
 .. _bridging-concepts-baremetal:
 
 베어메탈 (물리 서버)
-========================
+====================
 
-멀티노드 운영은 결국 물리 서버로 내려갑니다. 여기서 K8s 의 Metal3 와
+멀티노드 운영은 결국 물리 서버로 내려갑니다. 여기서 Kubernetes 의 Metal3 와
 OpenStack 의 Ironic 이 만나는데, Metal3(CRD)가 내부적으로 Ironic 을 호출하는
 구조라 두 스택의 베어메탈 관리가 한 지점으로 수렴합니다.
 
@@ -92,15 +93,16 @@ OpenStack 의 Ironic 이 만나는데, Metal3(CRD)가 내부적으로 Ironic 을
      - OpenStack 의 베어메탈 프로비저닝 서비스
      - 전용 문서 예정
    * - Metal3
-     - K8s(CRD)로 베어메탈 관리 — 내부적으로 Ironic 사용
+     - Kubernetes(CRD)로 베어메탈 관리 — 내부적으로 Ironic 사용
      - 전용 문서 예정
 
 
 공용 스토리지
-========================
+=============
 
-두 스택이 같은 스토리지 백엔드(Ceph)를 공유하는 수렴 지점입니다. K8s 측은
-Rook 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이 같은 Ceph 를 바라봅니다.
+두 스택이 같은 스토리지 백엔드(:term:`Ceph`)를 공유하는 수렴 지점입니다.
+Kubernetes 측은 :term:`Rook` 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이
+같은 Ceph 를 바라봅니다.
 
 .. list-table::
    :header-rows: 1
@@ -110,7 +112,7 @@ Rook 오퍼레이터로, OpenStack 측은 Cinder·Glance 등이 같은 Ceph 를
      - 한 줄 정의
      - 상세
    * - Ceph / Rook
-     - OpenStack·K8s 공용 스토리지 백엔드 (Rook = K8s 오퍼레이터)
+     - OpenStack·Kubernetes 공용 스토리지 백엔드 (Rook = Kubernetes 오퍼레이터)
      - :doc:`../storage/ceph`
 
 .. todo::

diff --git a/doc/source/foundations/helm.rst b/doc/source/foundations/helm.rst
@@ -1,25 +1,25 @@
-===============
+==============
 Helm 핵심 개념
-===============
+==============
 
-OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도구입니다. Helm
-은 K8s 애플리케이션의 패키징·배포를 선언적으로 다룹니다. 도구 자체의 상세는
-공식 문서로 링크하고, 여기서는 "이 개념이 OpenStack·K8s 결합에서 무엇에
-쓰이는가"에 초점을 둡니다.
+OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도구입니다.
+Helm 은 Kubernetes 애플리케이션의 패키징·배포를 선언적으로 다룹니다. 도구
+자체의 상세는 공식 문서로 링크하고, 여기서는 "이 개념이 OpenStack·Kubernetes
+결합에서 무엇에 쓰이는가"에 초점을 둡니다.
 
 .. note::
 
    기여자 작업용 골격입니다. 도구 사용법을 재설명하지 말고, 각 개념이
-   OpenStack·K8s 결합의 어디에 쓰이는지(왜 알아야 하는지)를 한 줄로 유지하세요.
-   상세는 공식 문서와 해당 섹션으로.
+   OpenStack·Kubernetes 결합의 어디에 쓰이는지(왜 알아야 하는지)를 한 줄로
+   유지하세요. 상세는 공식 문서와 해당 섹션으로.
 
 
 핵심 구성요소
 =============
 
 .. todo::
 
-   * Chart / Values / Release → K8s 애플리케이션을 패키징·배포하는 단위
+   * Chart / Values / Release → Kubernetes 애플리케이션을 패키징·배포하는 단위
    * Values 오버라이드 → 환경별 설정 주입 (openstack-helm 배포의 핵심 조작점)
 
 
@@ -28,8 +28,8 @@ OpenStack 을 Kubernetes 위에 올릴 때 반복해서 등장하는 전제 도
 
 .. todo::
 
-   * openstack-helm 의 기반 → OpenStack 을 K8s 에 올리는 여러 방식의 전제 도구
-     (:doc:`../openstack-on-kubernetes/openstack-helm`)
+   * openstack-helm 의 기반 → OpenStack 을 Kubernetes 에 올리는 여러 방식의
+     전제 도구 (:doc:`../openstack-on-kubernetes/openstack-helm`)
    * Rook 등 오퍼레이터 설치에도 Helm Chart 사용 (:doc:`../storage/ceph`)
 
 

diff --git a/doc/source/foundations/index.rst b/doc/source/foundations/index.rst
@@ -1,6 +1,6 @@
-==========
+=========
 기초 개념
-==========
+=========
 
 실습에 앞서 이해해 두면 좋은 개념 레이어를 정리합니다. 가상화 기초에서
 시작해 OpenStack 핵심 개념과 그 네트워킹·스토리지 서비스, Kubernetes 핵심