MkDocs

MKDocs 는 글쓰기 도구입니다. 글쓰기 도구에는 sphinx, read docs 등 다양한 도구들이 있습니다. MKDocs 는 간편하고, 마크다운 방식으로 글쓰기를 하며, serve 라는 명령어를 통해서 실시간으로 글쓰는 모습을 확인할수 있어서 선택하였습니다.

Categories

Plugins

• Material for MkDocs
• mkdocs-minify-plugin - A mkdocs plugin to minify the HTML of a page before it is written to disk.
• mkdocs-alias-plugin - An MkDocs plugin allowing links to your pages using a custom alias
• mkdocs-autolinks-plugin - An MkDocs plugin that automagically generates relative links between markdown pages
• mkdocs-meta-descriptions-plugin - 📑 Generate meta descriptions from the first paragraphs in your MkDocs pages
• mkdocs-minify-plugin - A mkdocs plugin to minify the HTML of a page before it is written to disk.
• mkdocs-ezlinks-plugin - Plugin for mkdocs which enables easier linking between pages
• mkdocs-redirects - Open source plugin for Mkdocs page redirects
• mkdocs-print-site-plugin - 모든 페이지를 하나의 페이지로 결합하여 PDF와 독립형 HTML로 Export 하기 쉽게 만든다.
• mkdocs-simple-hooks - 새로운 패키지를 만들지 않아도 Hooking 할 수 있게 도와줌.
• mkdocs-exclude - 문서화 예외 조건을 설정한다.
• mkdocs-literate-nav - nav 를 mkdocs.yml 이 아닌 별도의 페이지에서 구성 가능하다.
• mkdocs-extract-listings-plugin - 전체 페이지를 리스팅한다.
• mkdocs-pagetree-plugin - 페이지 트리를 출력해준다.

Markdown Extensions

mkdocs.yml 파일에 다음과 같이 추가하면 된다:

markdown_extensions:
  - md_in_html
  - pymdownx.arithmatex:
      generic: true

상세 목록은 Python-Markdown#Extensions 항목 참조.

sitemap.xml 생성 방법

mkdocs.yml 파일에 site_url을 설정해야 sitemap.xml이 생성됩니다:

site_name: "My Docs"
site_url: "https://example.com/docs/"

Linking to pages

• Writing Your Docs - MkDocs

WARNING
링크에 절대 경로를 사용하는 것은 공식적으로 지원되지 않습니다. 상대 경로는 MkDocs에서 조정하여 항상 페이지에 상대적이 되도록 합니다. 절대 경로는 전혀 수정되지 않습니다. 즉, 절대 경로를 사용하는 링크는 로컬 환경에서는 잘 작동할 수 있지만 프로덕션 서버에 배포하면 끊어질 수 있습니다.

Troubleshooting

Doc file 'XXX.md' contains a link 'YYY.md', but the target is not found among documentation files

Doc file 'Index.md' contains a link 'mutex.md', but the target is not found among documentation files.

링크했지만 파일을 찾을 수 없을 경우 방생되는 경고.

Doc file 'xxx.md' contains an absolute link '/yyy.md', it was left as is.

INFO    -  Doc file '1BITDRAGON.md' contains an absolute link '/Music.md', it was left as is.
INFO    -  Doc file '1BITDRAGON.md' contains an absolute link '/Scorewriter.md', it was left as is.

로그를 숨기고 싶다면 mkdocs.yml 파일에:

validation:
  links:
    absolute_links: ignore

See also

• Documentation generator
• YAML frontmatter
• SSG
• Docusaurus

Favorite site

• MkDocs web site
• Getting Started - MkDocs
• 홈 - MKDocs 튜토리얼
• 6.6 MkDocs - 공학자를 위한 Python
• [추천] mkdocs/catalog: 🏆 📚 A list of awesome MkDocs projects and plugins.
• Blimped | Creating a beautiful documentation site with MkDocs