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

mkdocs 를 build할 때,

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

이를 build하고 gh-deploy 로 수행할 경우 매번 카피해주기가 매우 귀찮다.

 

이 문서는 build등의 event가 발생할 경우 자동으로 특정 파일을 카피하는 처리를 수행하도록 하는 방법으로

mkdocs 1.4버전 부터 지원하는 hooks를 사용한다.

 

단, mkdocs 1.4 이전은 별도의 plug-in을 이용해야 한다. 이 경우는 다음 글을 참고할 곳.

2023.04.07 - [Computer/ETC] - [mkdocs] mkdocs build 등에서 특정 파일 카피 설정.

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

---

hooks는 정해진 event가 발생시 미리 정의된 function들이 호출되는 구조로, mkdocs.yml 파일을 기준으로 해당 function들을 구현한 .py을 작성하면 된다.

사실 해당 function들은 기존의 plugin 을 만들 때 구현되던 function들임.

이 문서에서는 mkdocs.yml과 같은 디렉토리에 있는 ads.txt를 docs/ads.tx로 복사하는 hook를 구현한다.

• 이 문서에서 보여준 예는 git pages로 mkdocs를 사용하면서 docs 디렉토리가 markdown파일들이 아닌 빌드된 html파일들이 놓이도록 구성되어 있다.
• 즉, docs 디렉토리가 target이고 mkdocs 디렉토리가 src 임.

우선 hooks로 동작할 hooks.py를 다음과 같이 작성한다.

import shutil
import mkdocs.plugins

def on_pre_build(config):
    shutil.copy("ads.txt", "docs/ads.txt")

• mkdocs.yml과 hooks.py, 그리고 ads.txt는 모두 같은 디렉토리에 놓여있음.
• ads.txt를 docs/ads.txt로 카피를 수행함.
• function head인 def on_pre_build(config): 는 mkdocs에서 지정한 그대로 사용해야함.

hooks로 사용될 python 파일의 작성할 때 구현할 function들은 다음 문서를 참고할 것.

https://www.mkdocs.org/dev-guide/plugins/#events

Plugins - MkDocs

---

이후 mkdocs.yml 설정에 다음과 같이 hooks를 추가함.

site_name: My Docs
site_url: https://dsaint31x.github.io/


docs_dir: mkdocs
site_dir: docs

plugins:
  - search
    #mkdocs1.4 이전 설정.
    #- mkdocs-simple-hooks:
    #    hooks:
    #      on_pre_build: "mkdocs.hooks:copy_ads"

hooks:
  - hooks.py

nav:
  - index: index.md

...이하 생략...

• plugins 밑에 hooks가 새로 추가된 부분임.
• mkdocs.yml파일을 기준으로 hooks 기능을 구현하고 있는 python파일을 찾음.
• 때문에 그냥 hooks.py라고 기재함.
• plugins 밑에 주석처리된 mkdocs-simple-hooks 부분은 버전 1.4 관련 설정임.

보다 자세한 내용은 다음의 hooks설정에 대한  mkdocs의 공식문서를 참고할 것.

https://www.mkdocs.org/user-guide/configuration/#hooks

Configuration - MkDocs

---

이후 mkdocs gh-pages등으로 build를 수행하면 됨.