[mkdocs] mkdocs build 등에서 특정 파일 카피 설정.

mkdocs 를 build할 때,

특정 파일을 build 시 build된 파일들이 놓이는 특정 디렉토리에 특정 파일들을 카피해야하는 경우가 있을 수 있는데,

이를 매번 build하고 gh-deploy 로 적용할 때 자동화되어있지 않을 경우

자주 잊어버려 해당 파일에 대한 링크가 깨지는 경우들이 발생하는 등의 문제가 일어날 수 있다.

 

2023.07.26 변경 사항

위의 문제를 해결하기 위해 mkdocs 1.4 전에는 mkdocs-simple-hooks plugin을 사용하여 처리했었다.

 

하지만, mkdocs 1.4 이후부터는 hooks를 mkdocs 자체적으로 지원을 하게 되었고, 이를 이용하는게 낫다.

해당 내용은 다음을 참고하라.

https://dsaint31.tistory.com/entry/mkdocs-mkdocs-%EC%9D%98-hooks-%EA%B8%B0%EB%8A%A5-%EC%82%AC%EC%9A%A9%EB%B2%95

[mkdocs] mkdocs 의 hooks 기능 사용법.

---

mkdocs 1.4 이전 버전

 

아래는mkdocs-simple-hooks plugin을 사용한 방법이 기재되어 있다.

---

plugin 설치

pip install mkdocs-simple-hooks

hook로 동작할 .py을 build의 대상 디렉토리에 생성. (내 경우 mkdocs이고 기본으로는 docs임.)

우선 hook로 동작할 function을 구현하고 있는 python파일을 만든다.

내 경우, hooks.py라는 이름으로 만들었음.

import shutil

def copy_ads(*args, **kwargs):
    shutil.copy('ads.txt', 'docs/ads.txt')

• 일반적인 mkdocs 설정과 달리, 내 경우엔, src 디렉토리가 mkdocs이고 target 디렉토리가 docs임.
• 때문에 mkdocs/ads.txt가 build를 수행시 docs/ads.txt로 복사되도록 지정한 것임.

mkdocs.yml에서 src 디렉토리는 docs_dir 에 설정하며, target 디렉토리는 site_dir 에 설정됨.
해당 문서는 다음과 같이 설정이 된 mkdocs에서 수행됨.
docs_dir: mkdoc
ssite_dir: docs

mkdocs.yml 파일을 다음과 같이 수정.

plugins:
  - mkdocs-simple-hooks:
      hooks:
        hook-name: mkdocs.hooks:copy_ads

• mkdoc 밑에 hook.py가 놓이므로 hook로 동작할 python 모듈을 가르키는 hook-name에 mkdocs.hooks가 들어감.
• colon : 뒤에 호출될 함수 copy_ads를 놓음.

Reference

• plugin : mkdocs-simple-hook