Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sondregronas/mkdocs-callouts
A simple MkDocs plugin that converts Obsidian callout blocks to mkdocs supported Admonitions.
https://github.com/sondregronas/mkdocs-callouts
Last synced: 2 days ago
JSON representation
A simple MkDocs plugin that converts Obsidian callout blocks to mkdocs supported Admonitions.
- Host: GitHub
- URL: https://github.com/sondregronas/mkdocs-callouts
- Owner: sondregronas
- License: mit
- Created: 2022-05-07T05:18:28.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-11T09:02:17.000Z (16 days ago)
- Last Synced: 2024-12-18T01:09:31.830Z (9 days ago)
- Language: Python
- Homepage:
- Size: 136 KB
- Stars: 32
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 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
```