문서 생성 및 게시

이 섹션은 다음을 어떻게 하는지 안내해요.

출처: 문서

본문

이 섹션은 다음을 어떻게 하는지 안내해요.

• 기본 문서 설정 만들기

• 소프트웨어 템플릿 사용하기

• 이미 존재하는 엔터티에 문서 활성화하기

• 독립형(standalone) 문서 만들기

• 문서 작성 및 미리보기

사전 요구 사항 (Prerequisites)

• TechDocs가 설치된 작동하는 Backstage 인스턴스(TechDocs 시작하기 참고)

기본 문서 설정 만들기

TechDocs는 컴포넌트의 문서를 생성하기 위해 다음 아티팩트를 사용해요.

• mkdocs.yml - 컴포넌트 저장소의 루트에 생성되는 파일로, 문서 사이트의 이름과 문서 탐색(navigation)을 제공해요.

• docs - 컴포넌트 저장소 루트에 있는, 문서 markdown 파일을 담는 폴더예요. 이 폴더 이름은 무엇이든 정할 수 있지만, 아래 예시에서는 docs를 사용할 거예요. 최소한 index.md 파일을 포함해야 해요.

• docs/index.md - 문서의 진입점이에요.

예를 들어:

your-great-component/     docs/       index.md     catalog-info.yaml     mkdocs.yml

소스 트리 어디에 있든 심볼릭 링크는 해당 트리 안에서 해석되어야 해요. 그렇지 않으면 TechDocs가 빌드를 거부해요. MkDocs 확장이 저장소 어디에서든 파일을 포함할 수 있으므로, 이 규칙은 docs_dir 밖에서도 적용돼요.

문서를 추가하고 싶은 기존 저장소가 있다면 아래의 '이미 존재하는 엔터티에 문서 활성화하기' 섹션으로 건너뛰세요. 그렇지 않으면 계속 읽어서 처음부터 문서를 포함한 새 소프트웨어 엔터티를 만들어 보세요.

소프트웨어 템플릿 사용하기

TechDocs는 'docs like code'(코드처럼 문서) 접근 방식 위에 구축돼요. 간단히 말해 문서를 코드 가까이에 두어야 한다는 뜻이에요.

Backstage 앱에는 기본적으로 추가된 소프트웨어 템플릿 세트가 있어요. 이 모든 소프트웨어 템플릿은 TechDocs 사이트를 실행하고 문서 작성을 시작하는 데 필요한 모든 것을 포함해요.

기본적으로 문서를 포함하지 않는 소프트웨어 템플릿을 만들었다면, 문서 설정을 구성하는 것을 적극 권장해요. 시작하려면 '소프트웨어 템플릿에 문서 설정을 추가하는 방법' 하우투 가이드를 따라 주세요.

이미 존재하는 엔터티에 문서 활성화하기

사전 요구 사항:

• backstage에 등록된 기존 엔터티(예: catalog-info.yaml 파일을 통해)

기존 엔터티에 문서를 추가하려면:

• 저장소의 루트에 다음 내용으로 mkdocs.yml 파일을 만드세요.

site_name: 'example-docs'nav:  - Home: index.mdplugins:  - techdocs-core

참고

위의 plugins 섹션은 선택 사항이에요. Backstage는 mkdocs 파일에 techdocs-core 플러그인이 없으면 자동으로 추가해요. 이 기능은 Backstage의 구성 옵션으로 끌 수 있어요.

• 컴포넌트의 엔터티 설명을 업데이트해, 저장소 루트의 catalog-info.yaml 파일에 다음 줄을 추가하세요.

metadata:  annotations:    backstage.io/techdocs-ref: dir:.

backstage.io/techdocs-ref 어노테이션은 TechDocs가 엔터티의 TechDocs 사이트를 생성하기 위해 문서 소스 파일을 다운로드하는 데 사용돼요.

• 저장소 루트에 최소한 index.md 파일이 있는 /docs 폴더를 만드세요. (markdown 파일을 더 추가한다면, 문서에 적절한 탐색을 만들기 위해 mkdocs.yml의 nav를 업데이트해야 해요.)

참고

docs는 문서를 저장하는 인기 있는 디렉터리 이름이지만, 다른 이름으로 바꿀 수 있고 mkdocs.yml로 설정할 수 있어요. https://www.mkdocs.org/user-guide/configuration/#docs_dir 참고

• 최소한 docs/index.md 파일을 만드세요. 예를 들어:

# example docsThis is a basic example of documentation.

• 변경 사항을 커밋하고, 풀 리퀘스트를 열고 병합하세요. 이제 Backstage를 실행할 때마다 업데이트된 문서를 볼 수 있어요!

독립형(standalone) 문서 만들기

문서를 코드 가까이에 두고 싶지 않지만 여전히 문서를 게시하고 싶은 상황도 있을 수 있어요. 예를 들어 온보딩 튜토리얼이 그렇죠. 이런 경우 TechDocs의 독립형 부분으로 게시될 문서 컴포넌트를 만들 수 있어요.

• 문서용 엔터티를 만드세요. 최소한의 예시는 다음과 같아요.

catalog-info.yaml

apiVersion: backstage.io/v1alpha1kind: Componentmetadata:  name: a-unique-name-for-your-docs  annotations:    # this could also be `url:<url>` if the documentation isn't in the same location    backstage.io/techdocs-ref: dir:.spec:  type: documentation  lifecycle: experimental  owner: user-or-team-name

• 문서를 파싱하는 데 사용할 mkdocs용 구성 파일을 만드세요.

mkdocs.yml

site_name: a-unique-name-for-your-docssite_description: An informative descriptionplugins:  - techdocs-corenav:  - Getting Started: index.md

• docs/라는 폴더에 원하는 문서를 markdown으로 담은 index.md 파일을 추가하세요. 이제 파일 구조는 다음과 같아야 해요.

your-great-documentation/  docs/    index.md  catalog-info.yaml  mkdocs.yml

• 여러 옵션 중 하나를 사용해 소프트웨어 카탈로그에 컴포넌트를 등록하세요.

문서 작성 및 미리보기

techdocs-cli를 사용하면 로컬 Backstage 인스턴스에서 문서를 미리보고 변경 사항이 있을 때 라이브 리로드를 받을 수 있어요. 문서를 작성하면서 미리보기할 때 유용해요.

이렇게 하려면 다음을 실행하면 돼요.

cd /path/to/docs-repository/npx @techdocs/cli serve

더 알아보기 (Learn more)