mkdocs-callouts


Namemkdocs-callouts JSON
Version 1.13.2 PyPI version JSON
download
home_page
SummaryA simple plugin that converts Obsidian style callouts and converts them into mkdocs supported 'admonitions' (a.k.a. callouts).
upload_time2024-03-05 11:47:44
maintainer
docs_urlNone
author
requires_python>=3.8
licenseMIT
keywords mkdocs mkdocs-plugin markdown callouts admonitions obsidian
VCS
bugtrack_url
requirements mkdocs pytest
Travis-CI No Travis.
coveralls test coverage
            # mkdocs-callouts
[![Build Status](https://img.shields.io/github/actions/workflow/status/sondregronas/mkdocs-callouts/CI.yml?branch=main)](https://github.com/sondregronas/mkdocs-callouts/)
[![GitHub latest commit](https://img.shields.io/github/last-commit/sondregronas/mkdocs-callouts)](https://github.com/sondregronas/mkdocs-callouts/commit/)
[![PyPi](https://img.shields.io/pypi/v/mkdocs-callouts)](https://pypi.org/project/mkdocs-callouts/)
![MIT license](https://img.shields.io/github/license/sondregronas/mkdocs-callouts)
[![codecov](https://codecov.io/gh/sondregronas/mkdocs-callouts/branch/main/graph/badge.svg?token=N5IDI7Q4NZ)](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": "",
    "name": "mkdocs-callouts",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "mkdocs,mkdocs-plugin,markdown,callouts,admonitions,obsidian",
    "author": "",
    "author_email": "Sondre Gr\u00f8n\u00e5s <mail@sondregronas.com>",
    "download_url": "https://files.pythonhosted.org/packages/21/37/5ab39ecb73099d9c865182a8c7bf99491a8c82649e63d5fc41300f3514e1/mkdocs-callouts-1.13.2.tar.gz",
    "platform": null,
    "description": "# mkdocs-callouts\n[![Build Status](https://img.shields.io/github/actions/workflow/status/sondregronas/mkdocs-callouts/CI.yml?branch=main)](https://github.com/sondregronas/mkdocs-callouts/)\n[![GitHub latest commit](https://img.shields.io/github/last-commit/sondregronas/mkdocs-callouts)](https://github.com/sondregronas/mkdocs-callouts/commit/)\n[![PyPi](https://img.shields.io/pypi/v/mkdocs-callouts)](https://pypi.org/project/mkdocs-callouts/)\n![MIT license](https://img.shields.io/github/license/sondregronas/mkdocs-callouts)\n[![codecov](https://codecov.io/gh/sondregronas/mkdocs-callouts/branch/main/graph/badge.svg?token=N5IDI7Q4NZ)](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.13.2",
    "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": "101e7ff7c932f962f73d8ee179d24067bb8e6a9018510a22e57f47aaf832ad17",
                "md5": "84defe1fb4f034c394deb0b1e43e2def",
                "sha256": "bc3d19f20159aaeffc2e8012a8c6b70cd3ba0cbacf38defe3abffa7510170100"
            },
            "downloads": -1,
            "filename": "mkdocs_callouts-1.13.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "84defe1fb4f034c394deb0b1e43e2def",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 7565,
            "upload_time": "2024-03-05T11:47:43",
            "upload_time_iso_8601": "2024-03-05T11:47:43.250537Z",
            "url": "https://files.pythonhosted.org/packages/10/1e/7ff7c932f962f73d8ee179d24067bb8e6a9018510a22e57f47aaf832ad17/mkdocs_callouts-1.13.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "21375ab39ecb73099d9c865182a8c7bf99491a8c82649e63d5fc41300f3514e1",
                "md5": "374f2e5b0b69b557e3e56f4010dd76a9",
                "sha256": "ebb114fe005b1f968498eb677059f7a77236fed3a4feb18607b0fda09f0968ba"
            },
            "downloads": -1,
            "filename": "mkdocs-callouts-1.13.2.tar.gz",
            "has_sig": false,
            "md5_digest": "374f2e5b0b69b557e3e56f4010dd76a9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 10052,
            "upload_time": "2024-03-05T11:47:44",
            "upload_time_iso_8601": "2024-03-05T11:47:44.425184Z",
            "url": "https://files.pythonhosted.org/packages/21/37/5ab39ecb73099d9c865182a8c7bf99491a8c82649e63d5fc41300f3514e1/mkdocs-callouts-1.13.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-05 11:47:44",
    "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"
}
        
Elapsed time: 0.21733s