| Name | mkdocs-snippets JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | Snippets for MkDocs |
| upload_time | 2023-02-10 18:49:48 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
mkdocs
snippets
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mkdocs Snippets Plugin
This plugin allows you to include snippets into your mkdocs documentation.
## Features
* Multiple snippets per file thanks to YAML syntax.
* Snippets are loaded from any (nested) directory inside the configured `snippets_dir`.
* This allows you to organize your snippets in a way that makes sense for you.
* Recursively include snippets in snippets.
* Links in snippets are automatically converted to relative links based on the snippet's location.
* This allows you to use links in your snippets without having to worry about the snippet's location.
* Snippets preserve the indentation of the snippet call.
* This allows you to use snippets in lists and code blocks without having to worry about indentation.
* Customizable snippet syntax.
## Installation
`pip install mkdocs-snippets`
Consider adding the plugin to a `requirements.txt` file alongside other Python dependencies for your project.
## Configuration
Add the plugin to your `mkdocs.yml` file:
```yaml
plugins:
- search
- snippets
```
The plugin will load snippets from the default directory `snippets` which must be inside your documentation directory.
The default snippet syntax is `@Snippet:snippetFile:snippetID`.
If you want to customize the snippet syntax or directory, you can do so by adding the following configuration:
```yaml
plugins:
- search
- snippets:
directory: "mySnippetDirectory"
delimiter: "|"
identifier: "snip"
divider_char: ">"
```
It is recommended to use the mkdocs-exclude plugin to exclude the snippet directory from the documentation build.
```yaml
plugins:
- search
- exclude:
glob:
- snippets/*
- snippets:
directory: "mySnippetDirectory"
delimiter: "|"
identifier: "snip"
divider_char: ">"
```
## Usage
### Snippet Syntax
The default snippet syntax is `@snippet:snippetFile:snippetID`.
### Links in Snippets
Links in snippets are automatically converted to relative links based on the snippet's location.
This allows you to use links in your snippets without having to worry about the snippet's location.
Therefore, links in the snippet must be written as if they were in the root of the documentation directory.
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocs-snippets",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "mkdocs,snippets",
"author": "",
"author_email": "CyberOtter <contact@betonquest.org>",
"download_url": "https://files.pythonhosted.org/packages/07/2e/deb428854b9980d326d899ef18fdd9a33d78c35108e395a40d761e36637b/mkdocs-snippets-1.0.0.tar.gz",
"platform": null,
"description": "# Mkdocs Snippets Plugin\r\n\r\nThis plugin allows you to include snippets into your mkdocs documentation.\r\n\r\n## Features\r\n\r\n* Multiple snippets per file thanks to YAML syntax.\r\n* Snippets are loaded from any (nested) directory inside the configured `snippets_dir`.\r\n * This allows you to organize your snippets in a way that makes sense for you. \r\n* Recursively include snippets in snippets.\r\n* Links in snippets are automatically converted to relative links based on the snippet's location.\r\n * This allows you to use links in your snippets without having to worry about the snippet's location.\r\n* Snippets preserve the indentation of the snippet call.\r\n * This allows you to use snippets in lists and code blocks without having to worry about indentation. \r\n* Customizable snippet syntax.\r\n\r\n## Installation\r\n`pip install mkdocs-snippets`\r\nConsider adding the plugin to a `requirements.txt` file alongside other Python dependencies for your project.\r\n\r\n## Configuration\r\nAdd the plugin to your `mkdocs.yml` file:\r\n```yaml\r\nplugins:\r\n - search\r\n - snippets\r\n```\r\n\r\nThe plugin will load snippets from the default directory `snippets` which must be inside your documentation directory.\r\nThe default snippet syntax is `@Snippet:snippetFile:snippetID`.\r\n\r\n\r\nIf you want to customize the snippet syntax or directory, you can do so by adding the following configuration:\r\n```yaml\r\nplugins:\r\n - search\r\n - snippets:\r\n directory: \"mySnippetDirectory\"\r\n delimiter: \"|\"\r\n identifier: \"snip\"\r\n divider_char: \">\"\r\n```\r\nIt is recommended to use the mkdocs-exclude plugin to exclude the snippet directory from the documentation build.\r\n\r\n```yaml\r\nplugins:\r\n - search\r\n - exclude:\r\n glob:\r\n - snippets/*\r\n - snippets:\r\n directory: \"mySnippetDirectory\"\r\n delimiter: \"|\"\r\n identifier: \"snip\"\r\n divider_char: \">\"\r\n```\r\n\r\n## Usage\r\n\r\n### Snippet Syntax\r\nThe default snippet syntax is `@snippet:snippetFile:snippetID`.\r\n\r\n### Links in Snippets\r\nLinks in snippets are automatically converted to relative links based on the snippet's location.\r\nThis allows you to use links in your snippets without having to worry about the snippet's location.\r\nTherefore, links in the snippet must be written as if they were in the root of the documentation directory.\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Snippets for MkDocs",
"version": "1.0.0",
"split_keywords": [
"mkdocs",
"snippets"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d18eb5de257477c6f3c0bfed33d62011fdf58c79fe8e6038599290c20a6a63b0",
"md5": "a47e2e93cf8a05dc33c4d04b563596a3",
"sha256": "6e9c088f2c50a67a327eea672bed590a53441f0400c6add7f6256ec4a422fc86"
},
"downloads": -1,
"filename": "mkdocs_snippets-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a47e2e93cf8a05dc33c4d04b563596a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5358,
"upload_time": "2023-02-10T18:49:47",
"upload_time_iso_8601": "2023-02-10T18:49:47.202891Z",
"url": "https://files.pythonhosted.org/packages/d1/8e/b5de257477c6f3c0bfed33d62011fdf58c79fe8e6038599290c20a6a63b0/mkdocs_snippets-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "072edeb428854b9980d326d899ef18fdd9a33d78c35108e395a40d761e36637b",
"md5": "505241a72a8c8c07aa646af364accd77",
"sha256": "c35033cf1ef801dd00249ddc3c19824864d380fc1c3e59fd95aab3c998b8b543"
},
"downloads": -1,
"filename": "mkdocs-snippets-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "505241a72a8c8c07aa646af364accd77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4930,
"upload_time": "2023-02-10T18:49:48",
"upload_time_iso_8601": "2023-02-10T18:49:48.501990Z",
"url": "https://files.pythonhosted.org/packages/07/2e/deb428854b9980d326d899ef18fdd9a33d78c35108e395a40d761e36637b/mkdocs-snippets-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-10 18:49:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "mkdocs-snippets"
}
