TechDocs FAQ
이 페이지는 TechDocs에 대해 자주 묻는 질문들에 답해요.
출처: 문서
본문
이 페이지는 TechDocs에 대해 자주 묻는 질문들에 답해요.
기술 (Technology)
-
TechDocs는 어떤 정적 사이트 생성기를 사용하나요?
-
mkdocs-techdocs-core 플러그인이란 무엇인가요?
-
TechDocs는 Markdown 외의 파일 형식(예: RST, AsciiDoc)을 지원하나요?
-
외부 빌드와 스토리지를 사용할 때
backstage.io/techdocs-ref의 값은 무엇이어야 하나요? -
사용자가 TechDocs 페이지에 변경 제안을 하거나 피드백을 남길 수 있나요?
TechDocs는 어떤 정적 사이트 생성기를 사용하나요?
TechDocs는 내부적으로 MkDocs를 사용해 프로젝트 문서를 빌드해요. techdocs-container로 빌드된 문서는 MkDocs Material 테마를 사용해요.
mkdocs-techdocs-core 플러그인이란 무엇인가요?
mkdocs-techdocs-core 패키지는 여러 MkDocs 플러그인(예: MkDocs Monorepo 플러그인)과 TechDocs가 지원하는 여러 Python Markdown 확장 기능을 감싸는(wrapper) 역할을 하는 MkDocs 플러그인이에요.
TechDocs는 Markdown 외의 파일 형식(예: RST, AsciiDoc)을 지원하나요?
지금은 아닙니다. 현재는 MkDocs를 사용해 소스에서 문서를 생성하기 때문에 파일은 Markdown 형식이어야 해요. 하지만 향후에는 다른 정적 사이트 생성기를 지원해 다른 파일 형식도 사용할 수 있도록 하고 싶어요.
외부 빌드와 스토리지를 사용할 때 backstage.io/techdocs-ref의 값은 무엇이어야 하나요?
backstage.io/techdocs-ref 메타데이터 어노테이션의 값은 TechDocs의 빌드 과정에서 사용돼요. 하지만 app-config.yaml에서 techdocs.builder가 'external'로 설정되어 있으면 이 어노테이션의 값은 사용되지 않아요. 그래도 엔터티에 TechDocs가 활성화되어 있다는 것을 Backstage가 알 수 있도록 어노테이션 자체는 엔터티 설명 파일(예: catalog-info.yaml)에 여전히 있어야 해요.
backstage.io/techdocs-entity 어노테이션을 사용하는 엔터티의 TechDocs URL로 이동하면 어떻게 되나요?
backstage.io/techdocs-ref 어노테이션 대신 backstage.io/techdocs-entity 어노테이션을 가진 엔터티에 대해 docs/{namespace}/{kind}/{name} 형식의 TechDocs URL로 이동하면, Backstage가 그 어노테이션 값이 가리키는 엔터티의 TechDocs 페이지로 리다이렉트해요.
사용자가 TechDocs 페이지에 변경 제안을 하거나 피드백을 남길 수 있나요?
소스 코드가 GitHub나 GitLab에 호스팅된 TechDocs 사이트에서는 이 기능을 지원해요. TechDocs 페이지에 "이 페이지 편집"과 "피드백 남기기" 버튼을 추가하려면 MkDocs 지침에 따라 mkdocs.yml 파일에 repo_url과 edit_uri 값이 있어야 해요.
소스 코드 호스팅 URL의 호스트 이름에 github나 gitlab이 포함되어 있지 않다면, 소스 코드 제공자를 가리키는 app-config.yaml의 integrations 항목도 필요해요(host 키만 있으면 충분해요).