TechDocs 문제 해결
TechDocs 문제 해결 (Troubleshooting TechDocs)
이 문제는 TechDocs를 "out-of-the-box"(기본) 구성으로 설정했을 때 발생할 수 있어요.
출처: 문서
본문
생성 시 문서를 찾을 수 없음
이 문제는 TechDocs를 "out-of-the-box" 구성으로 설정했을 때 발생할 수 있어요. 이러한 구성에서는 문서가 TechDocs 백엔드에 의해 동적으로 빌드되며, TechDocs 파일이 git 기반 소스 제어 관리 시스템(예: GitHub, BitBucket 등)에서 가져와지기 때문이에요.
이 문제를 겪는다면, 관련 저장소의 .gitattributes 파일에 있는 export-ignore 속성이 TechDocs 관련 파일(예: markdown, 자산 또는 mkdocs.yml 파일)과 일치하지 않는지 확인하세요.
TechDocs 백엔드는 이러한 파일을 볼 수 없기 때문에 결과적으로 부분적(또는 전혀 없는) TechDocs를 생성할 수 있어요.
소스 코드를 기반으로 tar 아카이브를 배포하는 방식을 다시 고려해야 해요(그리고 내부 문서가 그 아카이브에 포함되지 않도록 방지하는 방법도요). 또는 권장되는 TechDocs 아키텍처(CI/CD에서 문서를 생성·게시하는 방식)로 전환하는 것을 고려할 수도 있어요.
MkDocs 빌드 오류
TechDocs CLI를 사용하면 MkDocs 빌드 문제를 로컬에서 해결할 수 있어요. 이를 위해서는 이미지를 실행할 수 있는 Docker가 필요해요. 먼저 대상 저장소를 로컬에 git clone하고, 저장소 루트에서 다음을 실행하세요.
npx @techdocs/cli serve
예를 들어 저장소에 MkDocs 구성 파일을 넣는 것을 잊었다면, 결과 오류는 다음과 같아요.
npx: installed 278 in 9.089s[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000INFO - Building documentation...Config file '/content/mkdocs.yml' does not exist.
작동하면 Backstage와 사이트의 로컬 사본이 모두 로컬에서 실행돼요.
npx: installed 278 in 9.682s[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000INFO - Building documentation...WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.INFO - Cleaning site directoryDEBUG - Successfully imported extension module "plantuml_markdown".DEBUG - Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension".INFO - Documentation built in 0.23 seconds[I 210115 19:00:45 server:335] Serving on http://0.0.0.0:8000INFO - Serving on http://0.0.0.0:8000[I 210115 19:00:45 handlers:62] Start watching changesINFO - Start watching changes[I 210115 19:00:45 handlers:64] Start detecting changesINFO - Start detecting changes
svg_object를 사용한 PlantUML이 렌더링되지 않음
mkdocs-techdocs-core에 포함된 plantuml-markdown MkDocs 플러그인은 다이어그램 렌더링을 위한 여러 형식을 지원해요. 하지만 TechDocs는 그 모두를 지원하지는 않아요.
svg_object 형식은 다이어그램을 HTML <object> 태그로 렌더링하지만, 이는 악의적인 사용자가 문서 페이지에 유해한 콘텐츠를 주입할 수 있게 하므로 허용되지 않아요. 자세한 내용은 CVE-2021-32661을 참고하세요.
대신 <svg> 태그로 렌더링되고 svg_object와 같은 이점을 제공하는 svg_inline을 사용하세요.