{"id":15017526,"url":"https://github.com/try0/mkdocs-toc-md","last_synced_at":"2025-04-12T11:45:15.204Z","repository":{"id":62363075,"uuid":"559457942","full_name":"try0/mkdocs-toc-md","owner":"try0","description":"mkdocs-toc-md is an mkdocs plugin that generates a toc (table of contents) as markdown.  Writes toc to index.md. 目次を生成します。","archived":false,"fork":false,"pushed_at":"2023-11-23T11:46:59.000Z","size":773,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-25T04:42:29.615Z","etag":null,"topics":["documentation","generator","markdown","mkdocs","mkdocs-plugin","python","toc","toc-generator"],"latest_commit_sha":null,"homepage":"https://try0.github.io/mkdocs-toc-md/sample/site/mkdocs-toc-md.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/try0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-30T07:04:52.000Z","updated_at":"2024-04-25T04:42:29.616Z","dependencies_parsed_at":"2024-09-12T01:42:48.925Z","dependency_job_id":"dbce3a8d-25eb-4533-8bf2-4ca6df5d9e78","html_url":"https://github.com/try0/mkdocs-toc-md","commit_stats":{"total_commits":47,"total_committers":2,"mean_commits":23.5,"dds":"0.021276595744680882","last_synced_commit":"c4138524fc81e57eb7128538dd80076c8a93c1f6"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/try0%2Fmkdocs-toc-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/try0%2Fmkdocs-toc-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/try0%2Fmkdocs-toc-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/try0%2Fmkdocs-toc-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/try0","download_url":"https://codeload.github.com/try0/mkdocs-toc-md/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248564362,"owners_count":21125407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","generator","markdown","mkdocs","mkdocs-plugin","python","toc","toc-generator"],"created_at":"2024-09-24T19:50:36.696Z","updated_at":"2025-04-12T11:45:15.184Z","avatar_url":"https://github.com/try0.png","language":"Python","readme":"\n# mkdocs-toc-md\n\n[mkdocs-toc-md](https://pypi.org/project/mkdocs-toc-md/) is a plugin for mkdocs that generates a table of contents in markdown format. To render the table of contents as HTML, the markdown file must be generated before running `mkdocs build`.\n\n![](https://user-images.githubusercontent.com/17096601/199638378-892ddec9-b7af-4eb8-8ca8-a57c02980f53.png)\n\n\n\n## Sample\n\n[File](https://github.com/try0/mkdocs-toc-md/blob/main/sample/docs/index.en.md?plain=1)  \n[Site](https://try0.github.io/mkdocs-toc-md/sample/site/)\n\n\n\n\n## Usage\n\n### Generates toc markdown file.\n\n1. Install plugin. \n    ```\n    pip install mkdocs-toc-md\n    ```\n1. Add plugin config to mkdocs.yml.\n\n    ```yml\n    plugins:\n      - toc-md\n    ```\n\n1. Run `mkdocs serve` to output the toc md file.\n\n1. Check docs/index.md.\n\n\n### Adds description.\nIf you use metadata (front matter), set the value with toc_md_description as a key.\n```\n---\ntoc_md_description: pickup target value\n---\n```\n\nor use options `pickup_description_meta` `pickup_description_class`.\n\n\n\n## Options\n\nMinimum\n```yml\nplugins:\n  - toc-md:\n```\n\nFull\n```yml\nplugins:\n  - toc-md:\n      toc_page_title: Contents\n      toc_page_description: Usage mkdocs-toc-md\n      header_level: 3\n      pickup_description_meta: false\n      pickup_description_class: false\n      output_path: index.md\n      output_log: false\n      ignore_page_pattern: index.*.md$\n      remove_navigation_page_pattern: index.*.md$\n      template_dir_path: custom_template\n      integrate_mkdocs_static_i18n: true\n      languages:\n        en:\n          toc_page_title: Contents\n          toc_page_description: Usage mkdocs-toc-md\n        ja:\n          toc_page_title: 目次\n          toc_page_description: mkdocs-toc-mdプラグインの使い方\n      shift_header: after_h1_of_index\n      extend_module: true\n      output_comment: html\n```\n\n### toc_page_title: str  \nh1 text in the table of contents markdown file.\n\ndefault: Contents\n\n### toc_page_description: str\nThe description will be rendered below the h1 tag in the table of contents.\n\ndefault: None\n\n### header_level: int  \nHeader level (depth) to render.  \nh1→1, h2→2, ...\n\ndefault: 3\n\n### pickup_description_meta: bool  \nThe plugin renders the description after the h2 header in the table of contents markdown file. If you use metadata (front matter), there is no need to set this option.\n```html\n\u003cmata name=\"description\" content=\"pickup target value\" /\u003e\n```\n\ndefault: False\n\n### pickup_description_class: bool  \nThe plugin renders the description after the h2 header in the table of contents markdown file. If you use metadata (front matter), there is no need to set this option.\n\n```md\n# mkdocs-toc-md\n\n\u003cdiv class=\"toc-md-description\"\u003e\npickup target value\n\u003c/div\u003e\n```\ndefault: False\n\n### output_path: str  \nPath to save rendered toc md file.  \nindex.md → docs/index.md\n\ndefault: index.md\n\n### output_log: bool  \nOutput contents of markdown file to console.\n\ndefault: False\n\n### ignore_page_pattern: str  \nRegular expression pattern of markdown file names to be excluded from toc markdown file.  \nTo prevent the table of contents page from listing itself, set the same value as the output file name (output_path).\n\ndefault: ''\n\n### remove_navigation_page_pattern: str  \nRegular expression pattern of markdown file names to remove navigation items.  \nTo hide the navigation on the table of contents page, set the same value as the output file name (output_path).\n\ndefault: ''\n\n### template_dir_path: str\nPath of template dir.\nPut `toc.md.j2` in your custom template dir.\n\ndefault: ''\n\n### beautiful_soup_parser: str\nParser used in BeautifulSoup. Default is html.parser.  \nIf using html5lib or lxml, you need to install additional dependencies.\n\ndefault: html.parser\n\n### integrate_mkdocs_static_i18n: bool\nWith [mkdocs-static-i18n](https://github.com/ultrabug/mkdocs-static-i18n)\n\ndefault: False\n\n### languages: dict\nUse with integrate_mkdocs_static_i18n option.\nSet toc_page_title, toc_page_description for each language.\n\n```yml\nlanguages:\n    en:\n        toc_page_title: Contents\n        toc_page_description: Usage mkdocs-toc-md\n    ja:\n        toc_page_title: 目次\n        toc_page_description: mkdocs-toc-mdプラグインの使い方\n```\n\ndefault: dict()\n\n### shift_header: str (after_index, after_h1_of_index, none)\n`after_index`  \n    Shifts the header level(+1) except for the index file in the directory.\n\n`after_h1_of_index`  \n    Shifts the header level(+1) after h1 in index file and except for the index file in the directory.\n\n`none` (default)\n\n### extend_module: bool\nSome processes can be extended by placing the toc_extend_module.py file in the docs folder.\n\n```\n├─ docs\n│  ├─ mkdocs.yml\n│  ├─ toc_extend_module.py\n```\n\n[Sample/toc_extend_module.py](./sample/toc_extend_module.py)\n\n\n`find_src_elements` -\u003e list[bs4.element.Tag]  \nargs\n\n1. `bs_page_soup`: bs4.BeautifulSoup\n1. `page`: mkdocs.structure.pages.Page\n1. `toc_config`: mkdocs_toc_md.objects.TocConfig\n\n`create_toc_items` -\u003e list[mkdocs_toc_md.objects.TocItem]  \nargs\n\n1. `page`: mkdocs.structure.pages.Page\n1. `page_description`: str\n1. `src_elements`: list[bs4.element.Tag]\n1. `toc_config`: mkdocs_toc_md.objects.TocConfig\n\n`on_create_toc_item`  \nargs\n\n1. `toc_item`: mkdocs_toc_md.objects.TocItem\n1. `src_element`: bs4.element.Tag\n1. `page`: mkdocs.structure.pages.Page\n1. `toc_config`: mkdocs_toc_md.objects.TocConfig\n\n`on_before_output`  \nargs\n\n1. `nav`: mkdocs.structure.nav.Navigation\n1. `toc_items`: list[mkdocs_toc_md.objects.TocItem]\n1. `toc_config`: mkdocs_toc_md.objects.TocConfig\n\n### output_comment: str (html, metadata, none)\n\n`html` (default)\n```html\n\u003c!-- ====================== TOC ====================== --\u003e\n\u003c!-- Generated by mkdocs-toc-md plugin --\u003e\n\u003c!-- ================================================= --\u003e\n```\n\n`metadata`\n```\n---\ntoc_output_comment: Generated by mkdocs-toc-md plugin\n---\n```\n \n`none`","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftry0%2Fmkdocs-toc-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftry0%2Fmkdocs-toc-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftry0%2Fmkdocs-toc-md/lists"}