{"id":14065462,"url":"https://github.com/rosscdh/mkdocs-markdownextradata-plugin","last_synced_at":"2025-04-04T23:08:54.979Z","repository":{"id":48025517,"uuid":"131741200","full_name":"rosscdh/mkdocs-markdownextradata-plugin","owner":"rosscdh","description":"A MkDocs plugin that injects the mkdocs.yml extra variables into the markdown template","archived":false,"fork":false,"pushed_at":"2024-08-22T08:56:51.000Z","size":65,"stargazers_count":87,"open_issues_count":7,"forks_count":17,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T22:12:26.383Z","etag":null,"topics":["injects","mkdocs","mkdocs-plugin","variables"],"latest_commit_sha":null,"homepage":null,"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/rosscdh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2018-05-01T17:18:40.000Z","updated_at":"2025-03-07T08:38:37.000Z","dependencies_parsed_at":"2024-09-16T08:53:47.608Z","dependency_job_id":null,"html_url":"https://github.com/rosscdh/mkdocs-markdownextradata-plugin","commit_stats":{"total_commits":67,"total_committers":13,"mean_commits":5.153846153846154,"dds":0.6119402985074627,"last_synced_commit":"59bb1888f637fc9a821bb4d3d6c2ba1b472b75f2"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosscdh%2Fmkdocs-markdownextradata-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosscdh%2Fmkdocs-markdownextradata-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosscdh%2Fmkdocs-markdownextradata-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosscdh%2Fmkdocs-markdownextradata-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rosscdh","download_url":"https://codeload.github.com/rosscdh/mkdocs-markdownextradata-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261609,"owners_count":20910108,"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":["injects","mkdocs","mkdocs-plugin","variables"],"created_at":"2024-08-13T07:04:30.315Z","updated_at":"2025-04-04T23:08:54.950Z","avatar_url":"https://github.com/rosscdh.png","language":"Python","readme":"# mkdocs-markdownextradata-plugin\n\n[![Build Status](https://travis-ci.org/rosscdh/mkdocs-markdownextradata-plugin.svg?branch=master)](https://travis-ci.org/rosscdh/mkdocs-markdownextradata-plugin)\n\n*A MkDocs plugin that injects the mkdocs.yml extra variables into the markdown template*\n\n**usecase**\n\n```\nAs a user with variables that need to be inserted at the markdown level, not the template level.\nI need a mkdocs plugin that will inject my `extras` variables into the markdown template before it gets rendered to html.\nSo that I can build my markdown pages with different values for images, urls, client_names, etc. \n```\n\n## Installation\n\n\u003e **Note:** This package requires MkDocs version 0.17 or higher. \n\nInstall the package with pip:\n\n```bash\npip install mkdocs-markdownextradata-plugin\n```\n\nEnable the plugin in your `mkdocs.yml`:\n\n```yaml\nplugins:\n    - search\n    - markdownextradata: {}\n```\n\nYou are then able to use the mkdocs `extra: {}` hash to pass context data into your files\n\n\u003e **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\n\n## Features\n\n### Use Extra Variables in your markdown files\n\nThe variables you define in the mkdown.yml `extra:` slot will become available in your templates\n\n```yaml\nsite_name: My fantastic site\n\nplugins:\n    - search\n    - markdownextradata\n\nextra:\n  customer:\n    name: Your name here\n    web: www.example.com\n    salt: salt.example.com\n```\n\nand then in your `*.md` files\n\n```jinja\n{{ customer.name }}\n\u003ca href=\"{{ customer.web }}\"\u003e{{ customer.web }}\u003c/a\u003e\n```\n\n### Using external data files\n\nIf the `extra: {}` hash is not enough for your data then you are able to make use of external yaml files to provide that context data\n\n```yaml\nplugins:\n    - search\n    - markdownextradata:\n        data: path/to/datafiles\n```\n\nor if you have multiple locations provide a comma (,) separated list of locations\n\n```yaml\nplugins:\n    - search\n    - markdownextradata:\n        data: path/to/datafiles, another/path/to/datafiles\n```\n\nif you leave `markdownextradata.data` empty\n\n```yaml\nplugins:\n    - search\n    - markdownextradata\n```\n\nby default it will search in the folder where your mkdocs.yml is kept\nand in the docs folder for another folder called `_data` \n(i.e. `./docs/_data/site.yaml`), available as `{{ site.whatever_variable_in_the_yaml}}`.\n\nIf these paths are found, the plugin will read all `.yml|.yaml` and `.json`\nfiles inside them and add the data in them under the `extra` key.\n\nFor example, if you have a file called `[path/to/datafiles/]sections/captions.yaml` \nwhich includes a variable `foo` - where `[path/to/datafiles/]` is the path declared\nin your configuration under `data` - the data inside that file will be available in\n your templates as `{{sections.captions.foo}}` or `{{sections['captions']['foo']}}`.\n\nAlternatively, you can access all files and variable declared under `data` in template\nusing `extra` key. \nThis is particularly useful if your folder or filename do not comply with the Python\nvariable naming rules.\nFor example, if you have a file `[path/to/datafiles/]1_example/captions.yaml`\nwhich includes a variable `bar`, writting the template as \n`{{1_example.captions.bar}}` returns a `jinja2.exceptions.TemplateSyntaxError` since\nthe folder `1_example` starts with a number. Instead, you can call this file with\n when the template is `{{extra['1_example']['captions']['bar']}}`.\n\n\n### Jinja2 Template Engine Configuration\n\nYou may provide [Jinja2 configuration](https://jinja.palletsprojects.com/en/2.11.x/api/#high-level-api) as plugin options:\n\n```yml\nplugins:\n    - markdownextradata:\n        jinja_options:\n          comment_start_string: __CUSTOMCOMMENTSTART__\n```\n\nThe above example will make it so that instead of `{#`, the template engine will interpret `__CUSTOMCOMMENTSTART__` as comment start delimiter. This is useful in cases where\nyou write Markdown that contains Jinja-like syntax that's colliding with the template engine. Alternatively, it lets you control what the variable delimiter is (instead of the default `{{ }}`).\n\n## Testing\n\n```\nvirtualenv venv -p python3.7\nsource venv/bin/activate\npython setup.py test\npytest test\n```\n\n## Contributing\n\nFrom reporting a bug to submitting a pull request: every contribution is appreciated and welcome.\nReport bugs, ask questions and request features using [Github issues][github-issues].\nIf you want to contribute to the code of this project, please read the [Contribution Guidelines][contributing].\n\n[travis-status]: https://travis-ci.org/rosscdh/mkdocs-markdownextradata-plugin.svg?branch=master\n[travis-link]: https://travis-ci.org/rosscdh/mkdocs-markdownextradata-plugin\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\n[github-issues]: https://github.com/rosscdh/mkdocs-markdownextradata-plugin/issues\n[contributing]: CONTRIBUTING.md\n\n### Contributors\n\n- [Ross Crawford-d'Heureuse](https://github.com/rosscdh)\n- [Emiliano Heyns](https://github.com/retorquere)\n- [Michael Jess](https://github.com/miffels)\n- [João Moura](https://github.com/operte)\n- [Tim Vink](https://github.com/thatlittleboy)\n- [Jeremy Goh](https://github.com/timvink)","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosscdh%2Fmkdocs-markdownextradata-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frosscdh%2Fmkdocs-markdownextradata-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosscdh%2Fmkdocs-markdownextradata-plugin/lists"}