{"id":15017480,"url":"https://github.com/mondeja/mkdocs-include-markdown-plugin","last_synced_at":"2025-05-15T16:06:21.939Z","repository":{"id":39317855,"uuid":"318447428","full_name":"mondeja/mkdocs-include-markdown-plugin","owner":"mondeja","description":"Mkdocs Markdown includer plugin","archived":false,"fork":false,"pushed_at":"2025-03-07T23:18:44.000Z","size":467,"stargazers_count":127,"open_issues_count":1,"forks_count":24,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-11T22:47:51.207Z","etag":null,"topics":["documentation","inclusion","markdown","mkdocs","plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mondeja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2020-12-04T08:09:34.000Z","updated_at":"2025-05-08T21:34:13.000Z","dependencies_parsed_at":"2023-12-20T13:32:58.469Z","dependency_job_id":"be4b6e49-6e97-4b85-b213-7daea0b09630","html_url":"https://github.com/mondeja/mkdocs-include-markdown-plugin","commit_stats":{"total_commits":196,"total_committers":16,"mean_commits":12.25,"dds":0.2857142857142857,"last_synced_commit":"c1db293575f6deec8e383e185e0a8c16663c5067"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondeja%2Fmkdocs-include-markdown-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondeja%2Fmkdocs-include-markdown-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondeja%2Fmkdocs-include-markdown-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondeja%2Fmkdocs-include-markdown-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mondeja","download_url":"https://codeload.github.com/mondeja/mkdocs-include-markdown-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253645527,"owners_count":21941317,"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","inclusion","markdown","mkdocs","plugin"],"created_at":"2024-09-24T19:50:32.474Z","updated_at":"2025-05-15T16:06:21.922Z","avatar_url":"https://github.com/mondeja.png","language":"Python","readme":"\u003c!-- mdpo-disable-next-line --\u003e\n\n# mkdocs-include-markdown-plugin\n\n\u003c!-- mdpo-disable --\u003e\n\n[![PyPI][pypi-version-badge-link]][pypi-link]\n[![License][license-image]][license-link]\n[![Tests][tests-image]][tests-link]\n[![Coverage status][coverage-image]][coverage-link]\n[![Downloads][downloads-image]][downloads-link]\n\n\u003c!-- mdpo-enable --\u003e\n\nMkdocs Markdown includer plugin.\n\n\u003c!-- mdpo-disable --\u003e\n\u003c!-- mdpo-enable-next-line --\u003e\n\n\u003e Read this document in other languages:\n\u003e\n\u003e - [Español][es-readme-link]\n\u003e - [Français][fr-readme-link]\n\n\u003c!-- mdpo-enable --\u003e\n\n## Installation\n\n```bash\npip install mkdocs-include-markdown-plugin\n```\n\n## Documentation\n\n### Setup\n\nEnable the plugin in your `mkdocs.yml`:\n\n```yaml\nplugins:\n  - include-markdown\n```\n\n### Configuration\n\nThe global behaviour of the plugin can be customized in the configuration.\n\nMost of the settings will define the default values passed to arguments\nof directives and are documented in the [reference](#reference).\n\n```yaml\nplugins:\n  - include-markdown:\n      encoding: ascii\n      preserve_includer_indent: false\n      dedent: false\n      trailing_newlines: true\n      comments: true\n      rewrite_relative_urls: true\n      heading_offset: 0\n      start: \u003c!--start--\u003e\n      end: \u003c!--end--\u003e\n      recursive: true\n```\n\n#### `opening_tag` and `closing_tag`\n\nDefault opening and closing tags. When not specified they are `{%` and `%}`.\n\n```yaml\nplugins:\n  - include-markdown:\n      opening_tag: \"{!\"\n      closing_tag: \"!}\"\n```\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### `exclude`\n\nGlobal exclusion wildcard patterns. Relative paths defined here will be\nrelative to the [`docs_dir`] directory.\n\n```yaml\nplugins:\n  - include-markdown:\n      exclude:\n        - LICENSE.md\n        - api/**\n```\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### `cache`\n\nExpiration time in seconds for cached HTTP requests when including from URLs.\n\n```yaml\nplugins:\n  - include-markdown:\n      cache: 600\n```\n\nIn order to use this feature, the dependency [platformdirs] must be installed\nor the setting [`cache_dir`](#cache_dir) must be defined. You can include\n[platformdirs] in the installation of the plugin adding the `cache` extra:\n\n```txt\n# requirements.txt\nmkdocs-include-markdown-plugin[cache]\n```\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### `cache_dir`\n\nDirectory where cached HTTP requests will be stored. If set, [platformdirs] is not\nneeded to be installed to use [`cache`](#cache).\n\n```yaml\nplugins:\n  - include-markdown:\n      cache: 600\n      cache_dir: ./mkdocs-include-markdown-cache\n```\n\nA _.gitignore_ file will be added to the cache directory if not exists to avoid\ncommitting the cache files.\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### `directives`\n\nCustomize the names of the directives.\n\n```yaml\nplugins:\n  - include-markdown:\n      directives:\n        include-markdown: include-md\n        include: replace\n```\n\n### Reference\n\nThis plugin provides two directives, one to include Markdown files and another\nto include files of any type.\n\nPaths of included files can be either:\n\n- URLs to include remote content.\n- Local files:\n  - Absolute paths (starting with a path separator).\n  - Relative from the file that includes them (starting with `./` or `../`).\n  - Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is\n    _./docs/_, then `includes/header.md` will match the file\n    _./docs/includes/header.md_.\n- [Bash wildcard globs] matching multiple local files.\n\nFile paths to include and string arguments can be wrapped by double `\"` or\nsingle `'` quotes, which can be escaped prepending them a `\\` character as\n`\\\"` and `\\'`.\n\nThe arguments **start** and **end** may contain usual (Python-style) escape\nsequences like `\\n` to match against newlines.\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### **`include-markdown`**\n\nIncludes Markdown files content, optionally using two delimiters to filter the\ncontent to include.\n\n- \u003ca name=\"include-markdown_start\" href=\"#include-markdown_start\"\u003e#\u003c/a\u003e\n  **start**: Delimiter that marks the beginning of the content to include.\n- \u003ca name=\"include-markdown_end\" href=\"#include-markdown_end\"\u003e#\u003c/a\u003e\n  **end**: Delimiter that marks the end of the content to include.\n- \u003ca name=\"include-markdown_preserve-includer-indent\" href=\"#include-markdown_preserve-includer-indent\"\u003e#\u003c/a\u003e\n  **preserve-includer-indent** (_true_): When this option is enabled (default),\n  every line of the content to include is indented with the same number of\n  spaces used to indent the includer `{% %}` template. Possible values are\n  `true` and `false`.\n- \u003ca name=\"include-markdown_dedent\" href=\"#include-markdown_dedent\"\u003e#\u003c/a\u003e\n  **dedent** (_false_): If enabled, the included content will be dedented.\n- \u003ca name=\"include-markdown_exclude\" href=\"#include-markdown_exclude\"\u003e#\u003c/a\u003e\n  **exclude**: Specify with a glob which files should be ignored. Only useful\n  when passing globs to include multiple files.\n- \u003ca name=\"include-markdown_trailing-newlines\" href=\"#include-markdown_trailing-newlines\"\u003e#\u003c/a\u003e\n  **trailing-newlines** (_true_): When this option is disabled, the trailing newlines\n  found in the content to include are stripped. Possible values are `true` and `false`.\n- \u003ca name=\"include-markdown_recursive\" href=\"#include-markdown_recursive\"\u003e#\u003c/a\u003e\n  **recursive** (_true_): When this option is disabled, included files are not\n  processed for recursive includes. Possible values are `true` and `false`.\n- \u003ca name=\"include-markdown_encoding\" href=\"#include-markdown_encoding\"\u003e#\u003c/a\u003e\n  **encoding** (_'utf-8'_): Specify the encoding of the included file.\n  If not defined `'utf-8'` will be used.\n- \u003ca name=\"include-markdown_rewrite-relative-urls\" href=\"#include-markdown_rewrite-relative-urls\"\u003e#\u003c/a\u003e\n  **rewrite-relative-urls** (_true_): When this option is enabled (default),\n  Markdown links and images in the content that are specified by a relative URL\n  are rewritten to work correctly in their new location. Possible values are\n  `true` and `false`.\n- \u003ca name=\"include-markdown_comments\" href=\"#include-markdown_comments\"\u003e#\u003c/a\u003e\n  **comments** (_false_): When this option is enabled, the content to include\n  is wrapped by `\u003c!-- BEGIN INCLUDE --\u003e` and `\u003c!-- END INCLUDE --\u003e` comments\n  which help to identify that the content has been included. Possible values\n  are `true` and `false`.\n- \u003ca name=\"include-markdown_heading-offset\" href=\"#include-markdown_heading-offset\"\u003e#\u003c/a\u003e\n  **heading-offset** (0): Increases or decreases the Markdown headings depth\n  by this number. Only supports number sign (`#`) heading syntax. Accepts\n  negative values to drop leading `#` characters.\n\n##### Examples\n\n```jinja\n{%\n    include-markdown \"../README.md\"\n    start=\"\u003c!--intro-start--\u003e\"\n    end=\"\u003c!--intro-end--\u003e\"\n%}\n```\n\n```jinja\n{%\n    include-markdown 'includes/header.md'\n    start='\u003c!--\\n\\ttable-start\\n--\u003e'\n    end='\u003c!--\\n\\ttable-end\\n--\u003e'\n    rewrite-relative-urls=false\n    comments=true\n%}\n```\n\n```jinja\n{%\n    include-markdown \"includes/header.md\"\n    heading-offset=1\n%}\n```\n\n```jinja\n{%\n    include-markdown \"../LICENSE*\"\n    start=\"\u003c!--license \\\"start\\\" --\u003e\"\n    end='\u003c!--license \"end\" --\u003e'\n    exclude=\"../*.rst\"\n%}\n```\n\n```jinja\n{%\n    include-markdown \"**\"\n    exclude=\"./{index,LICENSE}.md\"\n%}\n```\n\n```jinja\n{% include-markdown '/escap\\'ed/single-quotes/in/file\\'/name.md' %}\n```\n\n\u003c!-- mdpo-disable-next-line --\u003e\n\n#### **`include`**\n\nIncludes the content of a file or a group of files.\n\n- \u003ca name=\"include_start\" href=\"#include_start\"\u003e#\u003c/a\u003e\n  **start**: Delimiter that marks the beginning of the content to include.\n- \u003ca name=\"include_end\" href=\"#include_end\"\u003e#\u003c/a\u003e\n  **end**: Delimiter that marks the end of the content to include.\n- \u003ca name=\"include_preserve-includer-indent\" href=\"#include_preserve-includer-indent\"\u003e#\u003c/a\u003e\n  **preserve-includer-indent** (_true_): When this option is enabled (default),\n  every line of the content to include is indented with the same number of\n  spaces used to indent the includer `{% %}` template. Possible values are\n  `true` and `false`.\n- \u003ca name=\"include_dedent\" href=\"#include_dedent\"\u003e#\u003c/a\u003e\n  **dedent** (_false_): If enabled, the included content will be dedented.\n- \u003ca name=\"include_exclude\" href=\"#include_exclude\"\u003e#\u003c/a\u003e\n  **exclude**: Specify with a glob which files should be ignored. Only useful\n  when passing globs to include multiple files.\n- \u003ca name=\"include_trailing-newlines\" href=\"#include_trailing-newlines\"\u003e#\u003c/a\u003e\n  **trailing-newlines** (_true_): When this option is disabled, the trailing newlines\n  found in the content to include are stripped. Possible values are `true` and `false`.\n- \u003ca name=\"include_recursive\" href=\"#include_recursive\"\u003e#\u003c/a\u003e\n  **recursive** (_true_): When this option is disabled, included files are not\n  processed for recursive includes. Possible values are `true` and `false`.\n- \u003ca name=\"include_encoding\" href=\"#include_encoding\"\u003e#\u003c/a\u003e\n  **encoding** (_'utf-8'_): Specify the encoding of the included file.\n  If not defined `'utf-8'` will be used.\n\n##### Examples\n\n```jinja\n~~~yaml\n{% include \"../examples/github-minimal.yml\" %}\n~~~\n```\n\n```jinja\n    {%\n        include \"../examples.md\"\n        start=\"~~~yaml\"\n        end=\"~~~\\n\"\n    %}\n```\n\n```jinja\n{%\n    include '**'\n    exclude='./*.md'\n%}\n```\n\n## Acknowledgment\n\n- [Joe Rickerby] and [contributors] for\n  [giving me the permissions][cibuildwheel-470] to\n  [separate this plugin][cibuildwheel-475] from the\n  documentation of [cibuildwheel][cibuildwheel-repo-link].\n\n[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax\n\n\u003c!-- mdpo-disable --\u003e\n\n[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin\n[pypi-version-badge-link]: https://img.shields.io/pypi/v/mkdocs-include-markdown-plugin?logo=pypi\u0026logoColor=white\n[tests-image]: https://img.shields.io/github/actions/workflow/status/mondeja/mkdocs-include-markdown-plugin/ci.yml?logo=github\u0026label=tests\u0026branch=master\n[tests-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/actions?query=workflow%3ACI\n[coverage-image]: https://img.shields.io/codecov/c/github/mondeja/mkdocs-include-markdown-plugin?logo=codecov\u0026logoColor=white\n[coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin\n[license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green\u0026logo=apache\u0026logoColor=white\n[license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE\n[downloads-image]: https://img.shields.io/pypi/dm/mkdocs-include-markdown-plugin\n[downloads-link]: https://pepy.tech/project/mkdocs-include-markdown-plugin\n[platformdirs]: https://pypi.org/project/platformdirs/\n[cibuildwheel-470]: https://github.com/pypa/cibuildwheel/issues/470\n[cibuildwheel-475]: https://github.com/pypa/cibuildwheel/pull/475\n[cibuildwheel-repo-link]: https://github.com/pypa/cibuildwheel\n[es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md\n[fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md\n[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir\n[Joe Rickerby]: https://github.com/joerick\n[contributors]: https://github.com/mondeja/mkdocs-include-markdown-plugin/graphs/contributors\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmondeja%2Fmkdocs-include-markdown-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmondeja%2Fmkdocs-include-markdown-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmondeja%2Fmkdocs-include-markdown-plugin/lists"}