1. Mkdocs 와 Github 문서정리
아무리 생각을 해보도 Github Pages로는 Mkdocs가 가장 적절한 것으로 판단이 되어진다.
여러 개를 써봤지만, 이렇게 깔끔하게 내 취향을 좋게 맞춰주는게 많지 않을 듯하다.
Why
Markdown 문서 기반으로 Web hosting이 쉽게 해주기 때문이다.
Limitations
다만 기술 문서 관점에서 다시 평가하면,
reStructuredText(.rst) 중심의 Sphinx가 더 적합한 선택으로 보인다 (Sphinx도 Markdown 지원함)
Doxygen + Breathe + Exhale 의 조합이 가장 낫을 듯하다.
여기에 Call Flow도 넣으면 더 좋고 (이외에 PDF, ePUB 등)
- Github 와 Mkdocs
현재 Github의 Markdown과 Mkdocs가 가장 적절하게 운영할 수 있는 것 같으며, 최근 변화에도 그런 것 같다.
- ReadTheDoc 사용 (Sphinx 와 mkdocs)
현재도 ReadTheDoc를 무료로 사용하고 있으며, 이 사이트는 Sphinx 와 Mkdocs 둘 다 지원
- Readme 와 ReadtheDocs 가격비교
ReadTheDoc 괜찮지만, 아래의 Readme도 한번 사용해봐야 겠다. 무료로 써 본 다음에 결정
Readme 가격
무료로 쓰려고 했으나, 실패
ReadtheDocs 가격
현재도 사용중이며, 다만 서버가 간혹 문제가 발생하는 경우가 발생하지만 무료로 이것만으로도 만족^^
1.1 Mkdocs 의 설치
mkdocs는 구글로 검색을 하면 쉽게 다 알 수 있으며, 작성 방법도 너무 쉬우므로,
아래와 같이 각 Link만 연결하도록 한다.
Mkdocs 관련설명
Mkdocs 의 Plugin들
- Mkdocs 의 Plugin (Mkdocs 문서 to PDF)
- Mkdoc 의 기본 Manual
mkdocs의 기본 Manaul 이므로 당연히 필독!
- Mkdocs Material Manual
Material 세련되게 사용하고 싶다면, 아래의 사이트는 전체 다 세부적으로 읽어보는 것을 추천
다만, 일반 Markdown 방식과 호환 안되는 경우가 있으므로 Material Theme 용으로만 사용.
Material Convention (Symbol) 알아두고, 각 아이콘을 기억
Github Action 기반의 Github Pages 설정 (개선을 하시면 더 좋고)
세부설정-Material Setup 부분 반드시 확인
(색상/Fonts/Lanuage/logo, Google Analytics 등 )
세부설정-Icon 과 좀 더 세련된 박스 제공
세부설정-markdown table도 더 세련되게
세부설정-icon/emoji도 좀 더 세련되게
세부설정-Material Plugins 기능들 (다양함, Blogs처럼 사용가능)
- Python 기본설치
Python 기반으로 기본설치
$ pip install mkdocs // Python mkdocs 설치 $ pip install pymdown-extensions // markdown extension
- mkdocs theme 설치
$ pip install mkdocs-material // mkdocs theme $ pip install mkdocs-material-extensions // mkdocs theme $ pip install mkdocs-rtd-dropdown // mkdocs theme
- Mkdocs 의 Themes
상위 이외에 다양한 Themes 이 존재하므로 설치해서 사용
현재 material만 꾸준히 Update되고 있으며, 이것을 사용하는게 맞을 것 같지만, 이상하게 더 readthedocs가 더 끌린다.
- 기타 Plug 설치
$ pip install mkdocs-mermaid2-plugin // mermaid2
$ pip install mkdocs-with-pdf // mkdoc to pdf
PDF의 경우, 현재 한글이 완벽히 지원되지 않음 주의!
PDF의 경우, 현재 Browser에서 직접 인쇄를 이용하여 인쇄하는게 가장 낫을 듯 싶다.
1.2 mkdocs File 구성
Github 쉽게 공유되어지며, 아래와 같이 구성한다.
$ tree docs └── index.md
1.3 mkdocs 관련설정
참고만 하고, 실제는 좀 더 세련되게~~ 사용해야지 (Google Analytics도 사용하고)
mkdocs.yml (theme: marterial)
mkdocs 의 material mkdocs.yml 예제
mkdocs 의 material 세부설정
mkdocs 의 theme
readthedocs 와 rtd-dropdown
mkdocs 의 theme 종류
- mkdocs 의 Chart/Images, Tables, and Graph
MkDocs GLightbox
plantuml-markdown
mermaid2
charts
Markdown blockdiag
drawio-exporter
mkdocs 의 pdf 와 epub
docgen
2. GitHub Pages 자동연동
Github Action 으로 쉽게 Github Pages에 연동이 가능하므로, 다양하게 사용이 가능하다.
Google Analytics 본인 직접 설정도 가능하다.
언어도 2개 이상도 다 지원가능하며, 다양하게 사용가능하다.
다만 언어를 2개 사용하면, 골치 아픈게 2개의 언어로 다 따로 작성을 해야해서~
- 나만의 Profile 완성
세부내용은 상위와 많이 다르나, Marterial Manual을 보면서 수정을 하면, 쉽게 할 수 있다고 생각한다.
