# mkdocs-callouts
[](https://github.com/sondregronas/mkdocs-callouts/)
[](https://github.com/sondregronas/mkdocs-callouts/commit/)
[](https://pypi.org/project/mkdocs-callouts/)
[](https://codecov.io/gh/sondregronas/mkdocs-callouts)
A simple plugin that converts Obsidian style callouts and converts them into mkdocs supported ['admonitions'](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (a.k.a. callouts).
## Setup
Install the plugin using pip:
`pip install mkdocs-callouts`
Activate the plugin in `mkdocs.yml`, note that some markdown_extensions are required for this plugin to function correctly:
```yaml
markdown_extensions:
- nl2br
- admonition
- pymdownx.details
- pymdownx.superfences
plugins:
- search
- callouts
```
> **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.
## Usage
mkdocs-callouts converts the following:
```
> [!INFO] Title
> An information callout from Obsidian
> inspired by the syntax from the Microsoft Docs
```
and turns it into:
```
!!! info "Title"
An admonition block for MkDocs.
Allowing you to edit your notes
with confidence using Obsidian.
```
### Foldable blocks
Foldable blocks are also supported. (`> [!INFO]- Foldable closed by default`, `> [!INFO]+ Foldable open by default`)
### Inline blocks
To turn a callout block into an inline block you can use the `|left` or `|right` syntax in the type notation like so:
```
> [!INFO|left] -> !!! info inline (alt: [!INFO | left])
> [!INFO|inline] -> !!! info inline
> [!INFO|right] -> !!! info inline end
> [!INFO|inline end] -> !!! info inline end
```
The following also works, but Obsidian may not render the block type correctly.
```
> [!INFO inline] --> !!! info inline
> [!INFO inline end] --> !!! info inline end
```
To get more information about inline blocks, or how to add your own custom callout blocks, check the [Material Mkdocs Documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks).
### Aliases
Obsidian allows the use of [aliases when creating callouts](https://help.obsidian.md/How+to/Use+callouts#Types), mkdocs-callouts converts these to the corresponding block type. Should you wish to disable this behaviour then you can do so by setting `aliases` to `false` in the plugin configuration:
```yaml
plugins:
- search
- callouts:
aliases: false
```
### Breakless lists (New in 1.11.0)
Markdown specification requires a blank line between list items and other block elements, whereas Obsidian does not require this. This plugin will by default automatically add a blank line between list items and callout blocks (if none are present). Should you wish to disable this behaviour then you can do so by setting `breakless_lists` to `false` in the plugin configuration:
```yaml
plugins:
- search
- callouts:
breakless_lists: false
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-callouts",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin, markdown, callouts, admonitions, obsidian",
"author": null,
"author_email": "Sondre Gr\u00f8n\u00e5s <mail@sondregronas.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/70/bbc1f6ca1ea17bd244b13ce9aa9fa0ff9a74ea2686fe54d0c84ef56b51cf/mkdocs_callouts-1.15.0.tar.gz",
"platform": null,
"description": "# mkdocs-callouts\n[](https://github.com/sondregronas/mkdocs-callouts/)\n[](https://github.com/sondregronas/mkdocs-callouts/commit/)\n[](https://pypi.org/project/mkdocs-callouts/)\n\n[](https://codecov.io/gh/sondregronas/mkdocs-callouts)\n\nA simple plugin that converts Obsidian style callouts and converts them into mkdocs supported ['admonitions'](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (a.k.a. callouts).\n\n## Setup\nInstall the plugin using pip:\n\n`pip install mkdocs-callouts`\n\nActivate the plugin in `mkdocs.yml`, note that some markdown_extensions are required for this plugin to function correctly:\n\n```yaml\nmarkdown_extensions:\n - nl2br\n - admonition\n - pymdownx.details\n - pymdownx.superfences\n\nplugins:\n - search\n - callouts\n```\n\n> **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## Usage\nmkdocs-callouts converts the following:\n```\n> [!INFO] Title\n> An information callout from Obsidian\n> inspired by the syntax from the Microsoft Docs\n```\nand turns it into:\n```\n!!! info \"Title\"\n An admonition block for MkDocs.\n Allowing you to edit your notes\n with confidence using Obsidian.\n```\n\n### Foldable blocks\nFoldable blocks are also supported. (`> [!INFO]- Foldable closed by default`, `> [!INFO]+ Foldable open by default`)\n\n### Inline blocks\nTo turn a callout block into an inline block you can use the `|left` or `|right` syntax in the type notation like so:\n```\n> [!INFO|left] -> !!! info inline (alt: [!INFO | left])\n> [!INFO|inline] -> !!! info inline\n\n> [!INFO|right] -> !!! info inline end \n> [!INFO|inline end] -> !!! info inline end\n```\n\nThe following also works, but Obsidian may not render the block type correctly.\n```\n> [!INFO inline] --> !!! info inline\n> [!INFO inline end] --> !!! info inline end\n```\nTo get more information about inline blocks, or how to add your own custom callout blocks, check the [Material Mkdocs Documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks).\n\n### Aliases\nObsidian allows the use of [aliases when creating callouts](https://help.obsidian.md/How+to/Use+callouts#Types), mkdocs-callouts converts these to the corresponding block type. Should you wish to disable this behaviour then you can do so by setting `aliases` to `false` in the plugin configuration:\n```yaml\nplugins:\n - search\n - callouts:\n aliases: false\n```\n\n### Breakless lists (New in 1.11.0)\nMarkdown specification requires a blank line between list items and other block elements, whereas Obsidian does not require this. This plugin will by default automatically add a blank line between list items and callout blocks (if none are present). Should you wish to disable this behaviour then you can do so by setting `breakless_lists` to `false` in the plugin configuration:\n```yaml\nplugins:\n - search\n - callouts:\n breakless_lists: false\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple plugin that converts Obsidian style callouts and converts them into mkdocs supported 'admonitions' (a.k.a. callouts).",
"version": "1.15.0",
"project_urls": {
"documentation": "https://github.com/sondregronas/mkdocs-callouts",
"funding": "https://github.com/sponsors/sondregronas",
"homepage": "https://github.com/sondregronas/mkdocs-callouts",
"issues": "https://github.com/sondregronas/mkdocs-callouts/issues",
"repository": "https://github.com/sondregronas/mkdocs-callouts"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin",
" markdown",
" callouts",
" admonitions",
" obsidian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8dd822e666c3608a865a283f2b4e3f264b9fd451d20687e74510fe97f745a2e0",
"md5": "64e0f52385995c9d0367018b7acbb418",
"sha256": "4be2c3ce09edeb1d5770140b063661dc27201e1d4148545a7ef3f12c0405dd3b"
},
"downloads": -1,
"filename": "mkdocs_callouts-1.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64e0f52385995c9d0367018b7acbb418",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8501,
"upload_time": "2024-12-11T09:02:43",
"upload_time_iso_8601": "2024-12-11T09:02:43.025591Z",
"url": "https://files.pythonhosted.org/packages/8d/d8/22e666c3608a865a283f2b4e3f264b9fd451d20687e74510fe97f745a2e0/mkdocs_callouts-1.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4f70bbc1f6ca1ea17bd244b13ce9aa9fa0ff9a74ea2686fe54d0c84ef56b51cf",
"md5": "da1f282a003497d2e557dd3cc9d3bdd0",
"sha256": "421759ad2c15475679b28728b0c425fc65aa0c8cbdec32c7f0192c292104d3b0"
},
"downloads": -1,
"filename": "mkdocs_callouts-1.15.0.tar.gz",
"has_sig": false,
"md5_digest": "da1f282a003497d2e557dd3cc9d3bdd0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11667,
"upload_time": "2024-12-11T09:02:43",
"upload_time_iso_8601": "2024-12-11T09:02:43.966854Z",
"url": "https://files.pythonhosted.org/packages/4f/70/bbc1f6ca1ea17bd244b13ce9aa9fa0ff9a74ea2686fe54d0c84ef56b51cf/mkdocs_callouts-1.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 09:02:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sondregronas",
"github_project": "mkdocs-callouts",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
">=",
"1"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.1.2"
]
]
}
],
"lcname": "mkdocs-callouts"
}
JSON
