TechDocs 하우투 가이드
참고
이 문서는 새 Backstage 앱에서 기본이 되는 새 프론트엔드 시스템을 기준으로 작성됐어요. Backstage 앱이 여전히 이전 프론트엔드 시스템을 사용한다면, 이 가이드의 이전 프론트엔드 시스템 버전을 대신 읽어 주세요.
출처: 문서
본문
참고
이 문서는 새 Backstage 앱에서 기본이 되는 새 프론트엔드 시스템을 기준으로 작성됐어요. Backstage 앱이 여전히 이전 프론트엔드 시스템을 사용한다면, 이 가이드의 이전 프론트엔드 시스템 버전을 대신 읽어 주세요.
TechDocs Basic에서 Recommended 배포 방식으로 마이그레이션하는 방법
TechDocs Basic과 Recommended 배포 방식의 주요 차이는 문서를 어디서 생성하고 저장하느냐예요. Basic 또는 기본(out-of-the-box) 설정에서는 문서가 Backstage 인스턴스를 실행하는 서버에서 생성되고 저장돼요. 하지만 권장 설정은 CI/CD에서 문서를 생성하고 생성된 사이트를 외부 스토리지(예: AWS S3 또는 GCS)에 저장하는 거예요. Backstage 인스턴스의 TechDocs는 읽기 전용 모드로 전환돼야 해요. 자세한 내용과 이점은 TechDocs 아키텍처 문서에서 읽어 보세요.
Basic에서 Recommended 설정으로 전환하는 데 필요한 단계는 다음과 같아요.
1. 클라우드 스토리지 준비
AWS, Google Cloud 또는 Microsoft Azure 같은 클라우드 스토리지 제공자를 선택하세요. TechDocs에서 클라우드 스토리지 사용에 관한 자세한 지침을 따르세요.
2. CI/CD에서 스토리지로 게시
소스 markdown 파일을 담고 있는 각 저장소의 CI/CD 워크플로에서 TechDocs 사이트 게시를 시작하세요. CI/CD 구성에 관한 자세한 지침을 읽으세요.
3. TechDocs를 읽기 전용 모드로 전환
Backstage 인스턴스의 app-config.yaml에서 techdocs.builder를 'local'에서 'external'로 설정하세요. 이렇게 하면 TechDocs가 문서를 생성하려고 시도하지 않아요. 참조는 TechDocs 설정 문서를 보세요.
techdocs-ref 어노테이션 값을 이해하는 방법
TechDocs가 문서를 생성하도록 구성되어 있다면, 먼저 엔터티의 catalog-info.yaml 파일에 정의된 backstage.io/techdocs-ref 어노테이션 값을 기반으로 소스 파일을 다운로드해요. 이를 Prepare 단계라고도 불러요.
거의 모든 상황에서 문서화된 각 카탈로그 엔터티의 catalog-info.yaml에 있는 backstage.io/techdocs-ref 어노테이션을 dir:.으로 설정할 것을 강력히 권장해요. TechDocs가 "docs like code" 철학에 맞춰져 있기 때문이에요. 즉 문서는 기반 소프트웨어의 소스 코드와 함께 작성·관리되어야 한다는 뜻이에요.
dir:.이 보이면 다음과 같이 해석할 수 있어요.
-
문서 소스 코드가
catalog-info.yaml파일과 같은 위치에 있다는 뜻. -
특히
mkdocs.yml파일이catalog-info.yaml과 형제(sibling)라는 뜻(즉, 같은 디렉터리에 있다는 뜻). -
그 두 파일이 들어 있는 디렉터리(그리고 모든 하위 디렉터리)를 다운로드하면 문서의 모든 소스 콘텐츠를 사용할 수 있다는 뜻.
엔터티의 디렉터리 트리는 대략 다음과 같아요.
├── catalog-info.yaml├── mkdocs.yml└── docs └── index.md
예를 들어 루트 디렉터리를 간결하게 유지하고 싶다면, mkdocs.yml 파일을 하위 디렉터리에 두고 backstage.io/techdocs-ref 어노테이션 값을 그에 맞게(예: dir:./sub-folder) 업데이트할 수 있어요.
├── catalog-info.yaml└── sub-folder ├── mkdocs.yml └── docs └── index.md
TechDocs 소스 콘텐츠가 catalog-info.yaml과 완전히 별도의 위치에서 관리·저장되는 드문 상황에서는 URL 위치 참조를 지정할 수 있어요. 정확한 값은 소스 코드 호스팅 제공자에 따라 달라져요. dir: 접두어 대신 url: 접두어가 사용된다는 점에 유의하세요. 예를 들어:
-
GitHub:
url:https://githubhost.com/org/repo/tree/<branch_name> -
GitLab:
url:https://gitlabhost.com/org/repo -
Bitbucket:
url:https://bitbuckethost.com/project/repo/src/<branch_name> -
Azure:
url:https://azurehost.com/organization/project/_git/repository
참고로 dir: 접두어로 하위 디렉터리를 지정할 수 있는 것처럼, 저장소 안의 mkdocs.yml 파일과 docs/ 디렉터리가 들어 있는 루트가 아닌 디렉터리 경로도 제공할 수 있어요. 상대 경로 해석이 일관되게 동작하려면 '/'로 끝나야 하는 것이 중요해요.
예:
url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component/
URL Reader가 git clone보다 빠른 이유
URL Reader는 소스 코드 호스팅 제공자를 사용해 저장소의 zip 또는 tarball을 다운로드해요. 아카이브에는 git 히스토리가 붙어 있지 않아요. 또한 압축 파일이에요. 따라서 git clone이 전송해야 하는 데이터보다 파일 크기가 훨씬 작아요.
TechDocs 홈 페이지를 커스터마이즈하는 방법
TechDocs는 Backstage의 Search 및 Catalog 플러그인과 유사한 합성(composability) 패턴을 사용해요. 기본 TechDocs 홈 페이지는 Catalog 플러그인이 제공하는 것과 유사한 테이블 경험을 제공해요. TechDocs에는 대안적인 grid 기반 레이아웃과 panel 레이아웃도 함께 제공돼요.
새 프론트엔드 시스템에서 TechDocs 홈 페이지 커스터마이즈는 page:techdocs 확장을 재정의해 수행돼요. TechDocs 홈 페이지는 PageBlueprint를 사용해 만든 표준 페이지 확장이므로, 다른 페이지 확장처럼 재정의할 수 있어요.
가장 간단한 방법은 plugin.withOverrides 메서드를 사용해 교체용 페이지 확장을 제공하는 거예요. TechDocs 페이지 확장의 ID가 page:techdocs이므로, techdocs 플러그인 네임스페이스 아래 새 페이지 확장을 만들어 재정의할 수 있어요.
packages/app/src/techdocs/TechDocsHomePage.tsx
import { PageBlueprint } from '@backstage/frontend-plugin-api';import techdocsPlugin from '@backstage/plugin-techdocs/alpha';export default techdocsPlugin.withOverrides({ extensions: [ PageBlueprint.make({ params: { path: '/docs', routeRef: techdocsPlugin.routes.root, loader: async () => { const { CustomTechDocsHome } = await import('./CustomTechDocsHome'); return <CustomTechDocsHome />; }, }, }), ],});
그런 다음 앱에 재정의된 플러그인을 설치해요.
packages/app/src/App.tsx
import { createApp } from '@backstage/frontend-defaults';import techdocsPlugin from './techdocs/TechDocsHomePage';const app = createApp({ features: [techdocsPlugin],});export default app.createRoot();
기존 페이지를 완전히 교체하지 않고 커스터마이즈하고 싶다면 원본 확장에 .override(...) 메서드를 사용할 수도 있어요. 확장 재정의와 사용 가능한 여러 재정의 패턴에 대한 자세한 내용은 확장 재정의 문서를 참고하세요.
TechDocs 리더 페이지를 커스터마이즈하는 방법
TechDocs 리더 페이지는 app-config.yaml을 통해 구성할 수 있어요. 예를 들어 문맥 내 검색이나 헤더를 비활성화할 수 있어요.
app-config.yaml
app: extensions: - page:techdocs/reader: config: withoutSearch: true
app-config.yaml
app: extensions: - page:techdocs/reader: config: withoutHeader: true
리더 페이지를 더 고급스럽게 커스터마이즈하려면 페이지 확장을 재정의할 수 있어요. 자세한 내용은 확장 재정의 문서를 참고하세요.
TechDocs Alpha에서 Beta로 마이그레이션하는 방법
이 가이드는 "recommended" TechDocs 배포 방식(외부 스토리지 제공자와 외부 CI/CD를 사용하는 방식)에만 적용돼요. "basic" 또는 "out-of-the-box" 설정을 사용한다면 여기서 멈춰도 돼요! 필요한 조치는 없어요.
이 가이드의 목적상 TechDocs Beta 버전은 다음과 같이 정의돼요.
-
TechDocs 플러그인: 최소
v0.11.0 -
TechDocs 백엔드 플러그인: 최소
v0.10.0 -
TechDocs CLI: 최소
v0.7.0
TechDocs 베타 버전은 TechDocs 콘텐츠를 접근하고 저장하는 방식에 큰 변경(breaking change)을 가져왔어요. 이제 페이지를 대소문자를 구분하지 않는 엔터티 트리플릿 경로로 접근할 수 있어요(예: /docs/namespace/kind/name. 이전 버전에서는 /docs/namespace/Kind/name으로만 접근할 수 있었어요). 이 변경을 활성화하려면 문서를 엔터티 트리플릿이 소문자인 객체 키를 사용해 외부 스토리지 제공자에 저장해야 해요.
베타 버전 이후의 TechDocs 새 설치물은 별도의 조치 없이 잘 동작하지만, 이 버전 이전부터 TechDocs를 실행하고 있었다면 스토리지 버킷의 모든 기존 콘텐츠가 소문자 엔터티 트리플릿 기대치와 일치하도록 마이그레이션을 수행해야 해요.
-
스토리지 제공자에 올바른 권한이 있는지 확인하세요. 스토리지 제공자의 파일을 마이그레이션하려면
techdocs-cli가 파일을 읽고/복사하고/이름을 바꾸고/이동하고/삭제할 수 있어야 해요. 정확한 지침은 스토리지 제공자마다 다르지만, 클라우드 스토리지 사용 페이지에서 자세한 내용을 확인하세요. -
파일의 비파괴적(non-destructive) 마이그레이션을 실행하세요. 최신 버전의
techdocs-cli가 설치되어 있는지 확인하세요. 그런 다음 제공자/구성에 맞는 세부 정보를 사용해 다음 명령을 실행하세요. 이 명령은 원래 파일을 제거하지 않고 예를 들어namespace/Kind/name/index.html의 모든 파일을namespace/kind/name/index.html로 복사해요.
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose
-
업데이트된 TechDocs 플러그인 버전을 배포하세요. 위 마이그레이션을 실행한 뒤, TechDocs 백엔드와 프론트엔드 플러그인의 베타 버전을 Backstage 인스턴스에 배포할 수 있어요.
-
TechDocs 사이트가 여전히 로드/접근 가능한지 검증하세요. 여러 엔터티 트리플릿 대소문자 변형(예:
/docs/namespace/KIND/name또는/docs/namespace/kind/name)을 사용해 TechDocs 사이트에 접근해 보세요. 사용하는 URL 경로 대소문자와 관계없이 TechDocs 사이트가 로드되어야 해요. -
스토리지에서 이전 객체를 정리하세요. TechDocs 사이트에 접근할 수 있음을 확인한 뒤, TechDocs CLI에서
migrate명령을removeOriginal플래그를 추가로 전달해 다시 실행해 스토리지 버킷을 정리할 수 있어요.
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose
- CI/CD 파이프라인을 업데이트해 TechDocs CLI의 베타 버전을 사용하세요. 마지막으로 모든 CI/CD 파이프라인을 업데이트해 최소 v0.x.y의 TechDocs CLI를 사용하게 하고, 앞으로 모든 사이트가 새롭고 소문자인 엔터티 트리플릿 경로로 게시되도록 하세요.
이 마이그레이션 실행 중 문제가 발생하면 이슈를 보고해 주세요. 다음 구성 변경으로 베타 이전의 스토리지 기대치로 일시적으로 되돌릴 수 있어요.
techdocs: legacyUseCaseSensitiveTripletPaths: true
자체 TechDocs API를 구현하는 방법
TechDocs 플러그인은 기본적으로 두 가지 주요 API 구현을 제공해요. 렌더링할 파일을 가져오기 위해 TechDocs 스토리지와 통신하는 TechDocsStorageApi와 techdocs-backend와 통신하는 TechDocsApi예요.
이 두 API를 직접 구현해 필요에 맞게 커스터마이즈해야 할 때가 있을 수 있어요. 이 가이드의 목적은 두 단계로 그 방법을 안내하는 거예요.
- 필요에 따라
TechDocsStorageApi와TechDocsApi인터페이스를 구현하세요.
export class TechDocsCustomStorageApi implements TechDocsStorageApi { // your implementation}export class TechDocsCustomApiClient implements TechDocsApi { // your implementation}
@backstage/frontend-plugin-api의createApiExtension을 사용해 커스텀 API 확장을 만들어 기본 API 확장을 재정의하고, 앱에 설치하세요. 커스텀 API 확장을 만들고 설치하는 방법에 대한 자세한 내용은 Utility APIs 문서를 참고하세요.
소프트웨어 템플릿에 문서 설정을 추가하는 방법
Backstage의 Software Templates(소프트웨어 템플릿)는 사용자가 이미 구성된 템플릿에서 새 컴포넌트를 만들 수 있게 도와주는 도구예요. 사용할 기본 템플릿 세트가 함께 제공되지만, 직접 템플릿을 추가할 수도 있어요.
자체 템플릿을 설정했다면, 그 템플릿에 TechDocs에 필요한 설정을 포함할 것을 적극 권장해요. 새 컴포넌트를 만들 때 사용자가 자동으로 TechDocs 사이트를 실행해 기술 문서 작성을 바로 시작할 수 있게 되기 때문이에요.
이 하우투 가이드의 목적은 새 템플릿에 필요한 구성과 일부 기본 markdown 파일을 추가하는 방법을 안내하는 거예요. 단계를 진행할 때 react-ssr-template을 참조로 사용할 수 있어요.
사전 요구 사항:
-
최소한
catalog-info.yaml이 들어 있는 skeleton 폴더와 함께template.yaml을 포함한 기존 소프트웨어 템플릿. -
skeleton 폴더의
catalog-info.yaml에 다음 줄을 추가해 컴포넌트의 엔터티 설명을 업데이트하세요.
annotations: backstage.io/techdocs-ref: dir:.
backstage.io/techdocs-ref 어노테이션은 TechDocs가 엔터티의 TechDocs 사이트를 생성하기 위해 문서 소스 파일을 다운로드하는 데 사용돼요.
- skeleton 폴더의 루트에 다음 내용으로
mkdocs.yml파일을 만드세요.
site_name: ${{values.component_id}}site_description: ${{values.description}}nav: - Introduction: index.mdplugins: - techdocs-core
- skeleton 폴더에 최소한
index.md파일이 있는/docs폴더를 만드세요.
docs/index.md는 예를 들어 다음과 같은 내용을 가질 수 있어요.
# ${{ values.component_id }}${{ values.description }}## Getting startedStart writing your documentation by adding more markdown (.md) files to thisfolder (/docs) or replace the content in this file.
참고
site_name, component_id, site_description의 값은 template.yaml을 어떻게 구성했는지에 따라 달라져요.
완료! 이제 자체 소프트웨어 템플릿에서 TechDocs를 지원할 수 있어요!
외부 폰트 비활성화
techdocs.generator.mkdocs.disableExternalFonts
(선택) 생성기가 인터넷에 연결할 수 없을 때(예: air-gapped 또는 제한된 네트워크) 사용해요. 그렇지 않으면 MkDocs Material이 생성 중에 Google에서 Roboto 폰트를 다운로드하려고 해요.
true로 설정하면 TechDocs가 생성 중에 각 mkdocs.yml을 패치해요. theme 섹션이 없으면 name: material과 font: false를 추가하고, theme는 있지만 font가 없으면 font: false를 설정하며, 파일에 font가 이미 설정되어 있으면 값을 그대로 둬요.
예시:
techdocs: generator: mkdocs: disableExternalFonts: true
또는 mkdocs.yml을 수동으로 설정할 수도 있어요.
theme: name: material font: false
참고: mkdocs.yml에서 theme.font를 사용할 때는 theme.name: material이 필요해요. 파일에 font가 이미 설정되어 있으면 app-config 패치가 이를 덮어쓰지 않아요. font가 설정되어 있지 않을 때만 font: false를 추가해요.
CI/CD에서 techdocs-cli 사용하기
CI/CD 워크플로에서 techdocs-cli를 사용해 TechDocs 사이트를 생성할 때 --disableExternalFonts 플래그를 사용할 수 있어요.
techdocs-cli generate --disableExternalFonts
이렇게 하면 로컬 생성을 위한 app-config.yaml 옵션과 마찬가지로 생성 과정에서 mkdocs.yml 파일을 자동으로 패치해요.
TechDocs에서 iframe을 활성화하는 방법
TechDocs는 DOMPurify 라이브러리를 사용해 HTML을 살균(sanitize)하고 XSS 공격을 방지해요.
허용 호스트 목록을 기반으로 일부 iframe을 허용할 수 있어요. 이렇게 하려면 app-config.yaml의 techdocs.sanitizer.allowedIframeHosts 구성에 허용 호스트를 추가하세요.
예를 들어:
techdocs: sanitizer: allowedIframeHosts: - drive.google.com
이렇게 하면 src 속성의 호스트가 sanitizer.allowedIframeHosts 목록에 있는 모든 iframe이 표시돼요.
TechDocs에서 커스텀 요소를 활성화하는 방법
TechDocs는 DOMPurify 라이브러리를 사용해 HTML을 살균하고 XSS 공격을 방지해요.
허용 패턴 목록을 기반으로 커스텀 요소를 허용할 수 있어요. 이렇게 하려면 app-config.yaml의 techdocs.sanitizer.allowedCustomElementTagNameRegExp와 allowedCustomElementAttributeNameRegExp 구성에 허용 요소와 속성을 추가하세요.
예를 들어:
techdocs: sanitizer: allowedCustomElementTagNameRegExp: '^backstage-', allowedCustomElementAttributeNameRegExp: 'attribute1|attribute2',
이렇게 하면 <backstage-element attribute1="value"></backstage-element> 같은 커스텀 요소가 결과 HTML에서 허용돼요.
TechDocs에서 추가 URI 프로토콜을 허용하는 방법
TechDocs는 DOMPurify 라이브러리를 사용해 HTML을 살균하고 XSS 공격을 방지해요.
프로토콜 목록을 기반으로 추가 URI 프로토콜을 허용할 수 있어요. 이렇게 하려면 app-config.yaml의 techdocs.sanitizer.additionalAllowedURIProtocols와 additionalAllowedURIProtocols 구성에 허용 프로토콜을 추가하세요.
예를 들어:
techdocs: sanitizer: additionalAllowedURIProtocols: ["vscode"],
이렇게 하면 <a href="vscode://settings/">VSCode Settings<a> 같은 링크가 결과 HTML에서 허용돼요.
TechDocs에서 PlantUML 다이어그램을 렌더링하는 방법
PlantUML을 사용하면 일반 텍스트 언어에서 다이어그램을 만들 수 있어요. 각 다이어그램 설명은 다이어그램 종류에 따라 키워드(@startXYZ와 @endXYZ)로 시작해요. UML 다이어그램의 경우 @startuml과 @enduml 키워드가 사용되어야 해요. 모든 유형의 다이어그램에 대한 자세한 내용은 PlantUML Language Reference Guide에서 찾을 수 있어요.
UML 다이어그램 상세
포함된(Embedded) PlantUML 다이어그램 예시
여기서는 markdown 파일 자체에 다이어그램 설명이 들어 있어요.
```plantuml@startumltitle Login Sequence ComponentA->ComponentB: Login Request note right of ComponentB: ComponentB logs message ComponentB->ComponentA: Login Response@enduml```
참조된(Referenced) PlantUML 다이어그램 예시
여기서는 markdown 파일이 다이어그램 설명을 담고 있는 다른 파일(*.puml 또는 *.pu)을 참조해요.
```plantuml!include umldiagram.puml```
참고: 외부 다이어그램 파일을 참조하려면 경로에 diagrams 디렉터리를 포함해야 해요. 자세한 내용은 Dockerfile을 참고하세요.
TechDocs에 Mermaid 지원을 추가하는 방법
TechDocs에 Mermaid 지원을 추가하는 방법은 몇 가지가 있어요. Kroki나 markdown-inline-mermaid를 사용해 빌드 시점에 다이어그램을 생성하거나, backstage-plugin-techdocs-addon-mermaid 플러그인을 사용해 브라우저에서 다이어그램을 생성할 수 있어요. 현재 Demo 사이트의 Mermaid 예시에는 backstage-plugin-techdocs-addon-mermaid 플러그인을 사용하고 있어요.
Kroki 사용하기
TechDocs에 Mermaid 지원을 추가하려면 텍스트 설명에서 다이어그램을 만드는 kroki를 사용할 수 있어요. 모든 인기 있는 diagrams-as-a-code 도구를 위한 단일 렌더링 게이트웨이예요. 엄청나게 많은 다이어그램 유형을 지원해요.
- Docker 이미지를 만들고 게시하세요. 다음
Dockerfile에서 Docker 이미지를 만들고 DockerHub에 게시하세요.
FROM python:3.10-alpineRUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfigRUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0RUN pip install mkdocs-kroki-pluginENTRYPOINT [ "mkdocs" ]
DockerHub에 저장소를 만들고 Dockerfile이 있는 폴더에서 아래 명령을 실행하세요.
docker build . -t dockerHub_Username/repositoryName:tagName
Docker 이미지가 준비되면 DockerHub에 푸시하세요.
- app-config.yaml을 업데이트하세요. 앱이 TechDocs를 생성할 때 DockerHub에서 도커 이미지를 가져오도록 하려면 이렇게 해요.
techdocs: builder: 'local' # Alternatives - 'external' generator: runIn: 'docker' # Alternatives - 'local' dockerImage: dockerHub_Username/repositoryName:tagName pullImage: true publisher: type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
mkdocs.yml에kroki플러그인을 추가하세요.
plugins: - techdocs-core - kroki
참고
mkdocs.yml에 kroki의 ServerURL 구성도 설정하고 싶을 가능성이 매우 높아요. 기본값은 공개 호스팅된 kroki.io예요. 조직의 다이어그램에 민감한 정보가 있다면 자체 서버를 설정해 그걸 대신 사용해야 해요. 자세한 플러그인 구성은 mkdocs-kroki-plugin 구성을 확인하세요.
- TechDocs에 mermaid 코드를 추가하세요.
```kroki-mermaidsequenceDiagramGitLab->>Kroki: Request renderingKroki->>Mermaid: Request renderingMermaid-->>Kroki: ImageKroki-->>GitLab: Image```
완료! 이제 mermaid와 함께 다음 다이어그램을 지원할 수 있어요.
-
PlantUML -
BlockDiag -
BPMN -
ByteField -
SeqDiag -
ActDiag -
NwDiag -
PacketDiag -
RackDiag -
C4 with PlantUML -
Ditaa -
Erd -
Excalidraw -
GraphViz -
Nomnoml -
Pikchr -
Svgbob -
UMlet -
Vega -
Vega-Lite -
WaveDrom
markdown-inline-mermaid 사용하기
TechDocs에서 markdown-inline-mermaid를 사용해 Mermaid 다이어그램을 생성하려면 다음을 수행해야 해요.
- Dockerfile에서
markdown-inline-mermaid와 그 의존성을 설치했는지 확인하고,@mermaid-js/mermaid-cli도 설치해야 해요.
Dockerfile
RUN apt-get install -y chromiumRUN pip3 install mkdocs-techdocs-core markdown-inline-mermaidRUN npm install -g @mermaid-js/mermaid-cliENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
- 이제
mkdocs.yml파일에 다음 섹션을 추가해야 해요(이미 있어야 하는plugins처럼 루트 수준이에요).
mkdocs.yml
markdown_extensions: - markdown_inline_mermaid
- 이제 이 준비가 되어 있으면 Markdown 파일에 다음과 같이 Mermaid 다이어그램을 추가할 수 있어요.
```mermaidsequenceDiagramAlice->>John: Hello John, how are you?John-->>Alice: Great!Alice-)John: See you later!```
backstage-plugin-techdocs-addon-mermaid 플러그인 사용하기
플러그인의 README에 있는 Getting Started 지침을 따르세요.
하이브리드 빌드 전략을 구현하는 방법
Recommended 배포의 한계 중 하나는 사용자의 경험을 위해 TechDocs를 게시하려면 CI/CD 프로세스를 수정해야 한다는 점이에요. 일부 사용자에게는 이게 불필요할 수 있고, 사용자를 Backstage로 온보딩하는 데 장벽이 될 수 있어요. 하지만 순수 로컬 TechDocs 빌드는 TechDocs 작성자가 Backstage에 포함된 도구와 Backstage에 포함된 mkdocs 설치에 제공되는 플러그인과 기능만 사용하도록 제한해요.
이 두 사용 사례를 모두 수용하기 위해, 사용자는 어떤 TechDocs를 로컬로 빌드할지, 어떤 것을 외부에서 빌드할지를 결정하는 로직으로 커스텀 Build Strategy를 구현할 수 있어요.
이 하이브리드 빌드 모델을 달성하려면:
-
Backstage 인스턴스의
app-config.yaml에서techdocs.builder를'local'로 설정하세요. 이렇게 하면 'out-of-the-box' 경험을 원하는 사용자를 위해 Backstage가 문서를 빌드하게 해요. -
프로덕션 배포처럼 TechDocs의 외부 스토리지를 정상적으로 구성하세요. 이렇게 하면 Backstage가 스토리지에 문서를 게시할 수 있을 뿐만 아니라, 다른 사용자가 자체 CI/CD 파이프라인에서 문서를 게시할 수 있어요.
-
DocsBuildStrategy인터페이스를 구현하고 주어진 엔터티에 대해 문서를 빌드할지 결정하는 커스텀 로직을 구현하는 커스텀 빌드 전략을 만드세요. 예를 들어 엔터티에company.com/techdocs-builder어노테이션이'local'로 설정된 경우에만 문서를 빌드하려면:
export class AnnotationBasedBuildStrategy { private readonly config: Config; constructor(config: Config) { this.config = config; } async shouldBuild(_: Entity): Promise<boolean> { return ( this.entity.metadata?.annotations?.['company.com/techdocs-builder'] === 'local' ); }}
- 이 Build Strategy 인스턴스를 TechDocs 백엔드
createRouter메서드의docsBuildStrategy매개변수로 전달하세요.
이제 사용자는 엔터티에 company.com/techdocs-builder 어노테이션을 추가해 문서가 TechDocs 백엔드에 의해 빌드·게시되도록 선택할 수 있어야 해요. 이 어노테이션 값이 'local'이면 TechDocs 백엔드가 문서를 빌드하고 게시해요. company.com/techdocs-builder 어노테이션 값이 'local' 이외의 것이면, 사용자가 문서를 TechDocs 외부 스토리지의 적절한 위치에 게시할 책임이 있어요.
백엔드 시스템을 사용한 하이브리드 빌드 전략
백엔드 시스템을 사용해 하이브리드 빌드 전략을 설정하려면 위와 같은 단계를 따르되, 4단계에서는 다음을 수행해야 해요.
packages/backend/src/index.ts
const backend = createBackend();import { createBackendModule } from '@backstage/backend-plugin-api';import { DocsBuildStrategy, techdocsBuildsExtensionPoint,} from '@backstage/plugin-techdocs-node';const techdocsCustomBuildStrategy = createBackendModule({ pluginId: 'techdocs', moduleId: 'customBuildStrategy', register(env) { env.registerInit({ deps: { techdocs: techdocsBuildsExtensionPoint, }, async init({ techdocs }) { const docsBuildStrategy: DocsBuildStrategy = { shouldBuild: async params => params.entity.metadata?.annotations?.[ 'demo.backstage.io/techdocs-builder' ] === 'local', }; techdocs.setBuildStrategy(docsBuildStrategy); }, }); },});// Other plugins...backend.add(import('@backstage/plugin-techdocs-backend'));backend.add(techdocsCustomBuildStrategy);backend.start();
참고
아직 import되지 않았다면 백엔드 package.json에 @backstage/plugin-techdocs-node 패키지를 추가해야 할 수 있어요.
다른 mkdocs 플러그인을 사용하는 방법
기본 플러그인 mkdocs-techdocs-core는 TechDocs를 활성화하기 위한 최소 필수 플러그인으로 볼 수 있는 플러그인 세트를 제공해요. 조직에 core 세트 이상의 요구 사항이 있을 수 있는데, 다른 플러그인을 활성화하는 권장 방법은 다음과 같아요.
플러그인 설치
CI 생성 사용
@techdocs/cli를 사용해 CI에서 HTML 파일을 생성한다면, cli가 실행되는 런타임(예: 도커 이미지 또는 Jenkins 노드)에 원하는 mkdocs 플러그인을 설치해야 해요. cli와 함께 --no-docker 플래그를 사용해 방금 설치한 플러그인을 선택하세요.
로컬 생성 사용
spotify/techdocs를 확장하는 새 Docker 이미지를 만들어요. 대략:
FROM spotify/techdocs:<version>pip install <the_plugin_you_want>...
그런 다음 이미지를 게시하고 techdocs.generator.dockerImage 키 아래의 구성에서 사용하세요.
mkdocs 구성에 플러그인 지정
플러그인을 사용하려면 mkdocs.yaml 파일에 나열되어야 해요. 적용되는 파일에 플러그인을 추가하거나 기본값을 지정할 수 있어요.
TechDocs는 MkDocs 플러그인 선언을 검증하고 기본적으로 작은 내장 집합을 허용해요. 플러그인이 그 집합에 없으면 앱 구성의 techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins를 사용해 명시적으로 허용하세요.
또한 플러그인을 모든 TechDocs 컴포넌트에 기본으로 제공하려면 techdocs.generator.mkdocs.defaultPlugins에 추가하거나 --defaultPlugin CLI 옵션을 사용하세요. defaultPlugins에 나열된 플러그인은 자동으로 허용되므로 두 곳 모두에 나열할 필요는 없어요.
자세한 내용은 허용된 MkDocs 플러그인 구성 참조를 참고하세요.
다른 컴포넌트의 TechDocs 참조하기
시스템에 Website와 API가 있는 System처럼 여러 엔터티가 있는 시스템에서, Monorepo로 서빙될 때 저장소의 한 위치에 TechDocs를 유지하고 싶을 수 있어요.
이 경우 backstage.io/techdocs-entity 어노테이션을 추가하고 소유자의 entityRef를 가리키도록 한 뒤 해당 TechDocs를 사용할 수 있어요. 이렇게 하면 하위 컴포넌트가 상위 문서를 읽을 수 있어 AboutCard 요소와 Techdocs 탭의 TechDocs 링크를 채울 수 있어요.
apiVersion: backstage.io/v1alpha1kind: Systemmetadata: name: example namespace: default title: Example description: This is the parent entity annotations: backstage.io/techdocs-ref: dir:.---apiVersion: backstage.io/v1alpha1kind: Componentmetadata: name: example-platform title: Example Application Platform namespace: default description: This is the child entity annotations: backstage.io/techdocs-entity: system:default/example
TechDocs로 딥 링킹
backstage.io/techdocs-entity-path 어노테이션을 사용해 컴포넌트 TechDocs 내 특정 페이지로 딥 링크할 수 있어요. 이를 backstage.io/techdocs-entity와 함께 사용하거나 단독으로 사용할 수 있어요.
apiVersion: backstage.io/v1alpha1kind: Systemmetadata: name: example namespace: default title: Example description: This is the parent entity annotations: backstage.io/techdocs-ref: dir:.---apiVersion: backstage.io/v1alpha1kind: Componentmetadata: name: example-platform title: Example Application Platform namespace: default description: This is the child entity annotations: backstage.io/techdocs-entity: system:default/example backstage.io/techdocs-entity-path: /path/to/component/docs
문서 사이트에서 이동되거나 이름이 바뀐 페이지의 끊어진 링크를 해결하는 방법
TechDocs는 mkdocs-redirects 플러그인을 사용해 모든 TechDocs 사이트에 대한 리다이렉트 맵을 만드는 것을 지원해요. 이를 통해 사이트에서 이름이 바뀌거나 이동된 페이지의 끊어진 링크를 지정된 대체 URL로 리다이렉트할 수 있어요. TechDocs는 사용자가 접근하려는 페이지가 더 이상 관리되지 않는다는 것을 알려준 뒤 리다이렉트해요. 외부 사이트 리다이렉트는 지원되지 않아요. 외부 리다이렉트가 제공되면 사용자는 대신 문서 사이트의 인덱스 페이지로 리다이렉트돼요.
정적 자산용 다운로드 링크 만들기
PDF 문서, 이미지, 코드 템플릿 같은 파일을 사용자가 다운로드할 수 있게 만들고 싶을 수 있어요. docs 디렉터리에 포함된 파일의 다운로드 링크는 markdown 링크 뒤에 {: download }를 추가해 만들 수 있어요.
[Link text](https://example.com/foo.jpg){: download }
링크를 클릭하면 사용자의 브라우저가 파일을 download.jpg로 다운로드해요.
파일 이름을 지정해 다운로드될 때 파일이 받을 이름을 제어할 수 있어요.
[Link text](https://example.com/foo.jpg){: download="foo.jpg" }