{"id":15016768,"url":"https://github.com/vokimon/markdown-customblocks","last_synced_at":"2025-04-12T10:41:55.377Z","repository":{"id":43710800,"uuid":"272220533","full_name":"vokimon/markdown-customblocks","owner":"vokimon","description":"Markdown extension to easily define custom blocks","archived":false,"fork":false,"pushed_at":"2024-01-14T23:24:40.000Z","size":1017,"stargazers_count":32,"open_issues_count":4,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-23T04:00:51.174Z","etag":null,"topics":["admonition","figures","instagram","markdown","markdown-extension","mastodon","openstreetmap","peertube","twitter","wikipedia","youtube"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vokimon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-06-14T14:39:32.000Z","updated_at":"2024-02-08T11:09:47.000Z","dependencies_parsed_at":"2024-01-17T21:27:34.950Z","dependency_job_id":"8893ecb4-1299-479a-a34e-18f4fd4fe6db","html_url":"https://github.com/vokimon/markdown-customblocks","commit_stats":{"total_commits":472,"total_committers":4,"mean_commits":118.0,"dds":"0.26906779661016944","last_synced_commit":"d323cb850e64d70630c51c40ae440a8ea6a56f93"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vokimon%2Fmarkdown-customblocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vokimon%2Fmarkdown-customblocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vokimon%2Fmarkdown-customblocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vokimon%2Fmarkdown-customblocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vokimon","download_url":"https://codeload.github.com/vokimon/markdown-customblocks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248556969,"owners_count":21124156,"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":["admonition","figures","instagram","markdown","markdown-extension","mastodon","openstreetmap","peertube","twitter","wikipedia","youtube"],"created_at":"2024-09-24T19:49:21.536Z","updated_at":"2025-04-12T10:41:55.346Z","avatar_url":"https://github.com/vokimon.png","language":"Python","readme":"![Logo](http://vokimon.github.io/markdown-customblocks/img/logo-customblocks.svg)\n\n# Customblocks for Markdown\n\n[![CI](https://github.com/vokimon/markdown-customblocks/actions/workflows/main.yml/badge.svg)](https://github.com/vokimon/markdown-customblocks/actions/workflows/main.yml)\n[![Coverage](https://img.shields.io/coveralls/vokimon/markdown-customblocks/master.svg?style=flat-square\u0026label=Coverage)](https://coveralls.io/r/vokimon/markdown-customblocks)\n[![PyPi](https://img.shields.io/pypi/v/markdown-customblocks.svg?style=flat-square\u0026label=PyPI)](https://pypi.org/project/markdown-customblocks/)\n[![license: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![downloads](https://img.shields.io/pypi/dm/markdown-customblocks.svg?style=flat-square\u0026label=PyPI%20Downloads)](https://pypi.org/project/markdown-customblocks/)\n\u003c!--\n[![image](https://img.shields.io/pypi/pyversions/markdown-customblocks.svg?style=flat-square\u0026label=Python%20Versions)](https://pypi.org/project/markdown-customblocks/)\n[![image](https://img.shields.io/pypi/implementation/markdown-customblocks.svg?style=flat-square\u0026label=Python%20Implementations)](https://pypi.org/project/markdown-customblocks/)\n--\u003e\n\nCustomblocks is an extension for [Python-Markdown]\nthat settles a **common markup** for **parametrizable and nestable components**\nwhose output can be **redefined** by means of a simple Python function.\n\nMany off-the-shelf components are provided such as\ndiv-containers, admonitions, figures, link cards, maps...\nand some embeded widgets from common sites (wikipedia, youtube, vimeo, peertube, mastodon, twitter, facebook, instagram, goteo, verkami...)\n\nIt also includes convenience tools to ease component definition:\nhyperscript html generation, cached page fetching and metadata page extraction.\n\n[Python-Markdown]: https://python-markdown.github.io/\n\n\n## Installation and setup\n\nTo install:\n\n```bash\n$ pip install markdown-customblocks\n```\n\nAnd then activate it as any other Markdown extension.\n\nFrom command line:\n\n```bash\n$ markdown -x customblocks ...\n```\n\nIn Python code:\n\n```python\nimport markdown\nmd = markdown.Markdown(extensions=[\"customblocks\"])\nmd.convert(markdowncontent)\n```\n\nIn [Pelican](https://blog.getpelican.com/) config:\n\n```python\nMARKDOWN = {\n    'extensions': [\n        'customblocks',\n    ],\n}\n```\n\nFor [MkDocs](https://www.mkdocs.org), add this to `mkdocs.yml`:\n\n```yaml\nmarkdown_extensions:\n  - customblocks\n```\n\nIf you need to specify additional parameters for the extension,\nrefer to the documentation of your generator.\n\n\n## Basic usage\n\nCustomblocks extension parses markup structures like this one:\n\n```markdown\n::: mytype \"value 1\" param2=value2\n    Indented **content**\n```\n\nAnd, by default, generates HTML like this:\n\n```html\n\u003cdiv class=\"mytype value-1\" param2=\"value2\"\u003e\n   \u003cp\u003eIndented \u003cb\u003econtent\u003c/b\u003e\u003c/p\u003e\n\u003c/div\u003e\n```\n\nThis is the output of the default generator: `container`.\nBut we could bound `mytype` to a custom Python function like the following one:\n\n```python\ndef mygenerator(ctx, param1, param2):\n    return f\"\"\"\u003cdiv attrib1=\"{param1}\" attrib2=\"{param2}\"\u003e{ctx.content}\u003c/div\u003e\"\"\"\n```\n\nAnd then, previous Markdown would generate this other HTML:\n\n```html\n\u003cdiv attrib1=\"value 1\" attrib2=\"value2\"\u003eIndented **content**\u003c/div\u003e\n```\n\nNotice that this function is not escaping any received value\nand is not converting anything in the content to Markdown.\nLuckily, `customblocks` provides some useful tools for that:\nthe hyperscript generator and the Markdown subparser:\n\n```python\nfrom customblocks.utils import E, Markdown\n\ndef mygenerator(ctx, param1, param2):\n    return E('', attrib1=param1, attrib2=param2,\n        Markdown(ctx.content, ctx.parser)\n    )\n```\n\nYou can read more about them at the [related documentation](https://vokimon.github.io/markdown-customblocks/defining-generators/#hyperscript).\n\n## Built-in generators\n\nFor convenience, `customblocks` also provides the following predefined generators:\n\n- [`container`](https://vokimon.github.io/markdown-customblocks/generators-container/):\n    A div element with arbitrary classes, attributes and content. This is the default when no type matches.\n- [`admonition`](https://vokimon.github.io/markdown-customblocks/generators-admonition/):\n    Admonitions, boxes for notes, warnings... (quite similar to the [standard extra extension][ExtraAdmonitions]).\n    It is bound to types `note`,  `info`, `error`, `warning`....\n- [`figure`](https://vokimon.github.io/markdown-customblocks/generators-figure/):\n    Full featured figures with captions, lightbox...\n- [`map`](https://vokimon.github.io/markdown-customblocks/generators-map/):\n    Maps from [OpenStreetMaps.org](https://openstreetmap.org)\n- [`linkcard`](https://vokimon.github.io/markdown-customblocks/generators-linkcard/):\n    External link cards (like Facebook and Twitter do, when you post a link)\n- [`wikipedia`](https://vokimon.github.io/markdown-customblocks/generators-wikipedia/):\n    Wikipedia article card by lemma (and language)\n- [`youtube`](https://vokimon.github.io/markdown-customblocks/generators-youtube/):\n    Embeded videos from youtube.\n- [`vimeo`](https://vokimon.github.io/markdown-customblocks/generators-vimeo/):\n    Embeded videos from vimeo.\n- [`peertube`](https://vokimon.github.io/markdown-customblocks/generators-peertube/):\n    Embeded videos from [peertube](https://joinpeertube.org)\n- [`mastodon`](https://vokimon.github.io/markdown-customblocks/generators-mastodon/):\n    Embeded [mastodon](https://joinmastodon.org) posts\n- [`twitter`](https://vokimon.github.io/markdown-customblocks/generators-twitter/):\n    Embeded tweets\n- [`facebook`](https://vokimon.github.io/markdown-customblocks/generators-facebook/):\n    Embeded post from facebook\n- [`instagram`](https://vokimon.github.io/markdown-customblocks/generators-instagram/):\n    Embeded post from instagram\n- [`verkami`](https://vokimon.github.io/markdown-customblocks/generators-verkami/):\n    Fund raising project widget in [Verkami]\n- [`goteo`](https://vokimon.github.io/markdown-customblocks/generators-goteo/):\n    Fund raising project widget in [Goteo]\n\n[ExtraAdmonitions]: https://python-markdown.github.io/extensions/admonition/\n\n\n## General markup syntax\n\nThis is a more complete example of markup:\n\n```markdown\n::: mytype param1 key1=value1 \"other param\" key2='value2 with words' flag1 noflag2\n    Indented **content**\n\n    The block ends whenever the indentation stops\nThis unindented line is not considered part of the block\n```\n\n**The headline:**\nThe line starting with `:::` is the _headline_.\nIt specifies, first, the block type (`mytype`) followed by a set of _values_\nthat will be passed to the generator as parameters.\n\n\n**Block type:**\nThe type is used to select the generator function.\nIf there is no generator bound to the type, the div-container generator, will be used by default.\n\n**Quotes:**\nMuti-word values can be passed by using either single or double quotes.\nYou can skip quotes if your value is single worded.\n\n**Explicit keywords:**\nAlso some values may target an explicit parameter with a _key_.\nThis works as follows:\nfrom the available block parameters, values with a key are set first,\nthen the remaining unset parameters are filled by position.\n\n**Flags (bools):**\nBoolean parameters (flags) can be set by just adding a value with the name of the flag, like `flag1` in the example.\nAnd they can be unset by adding the name with a `no` prefix, like `noflag2` in the example.\n\n**Content:**\nAfter the _headline_, several lines of indented _content_ may follow.\nThe content ends with the very first non-emtpy line back on the previous indentation.\n\nIndentation is removed from the content for the generator to process it.\nA block type may choose to interpret this content as markdown as well.\nSo you can have nested blocks by adding extra indentation.\nFor example:\n\n```markdown\n::: recipe\n    # Sweet water\n    ::: ingredients \"4 persons\"\n        - two spons of suggar\n        - a glass of tap water\n    ::: mealphoto sweetwater.jpg\n        Looks gorgeus!\n    Drop the suggar into the glass. Stir.\n```\n\n::: note\n    A closing `:::` tag is optional.\n    For most cases, indentation should be enough, visually, and functionally.\n    But, seldomly, it is necessary.\n    Like in the example below, where\n    the mealphoto content would be mixed with \n    the later code block\n\n        ::: mealphoto sweetwater.jpg\n                Looks gorgeus!\n        :::\n                This is a code block by indentation\n\n\n## Further reading\n\n- [Full documentation](https://vokimon.github.io/markdown-customblocks)\n- [Code](https://github.com/vokimon/markdown-customblocks)\n- [Release History](https://vokimon.github.io/markdown-customblocks/CHANGES)\n- [Road map](https://vokimon.github.io/markdown-customblocks/TODO)\n- [Motivation and design choices](https://vokimon.github.io/markdown-customblocks/motivation)\n- [Inspiration and kudos](https://vokimon.github.io/markdown-customblocks/inspiration)\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvokimon%2Fmarkdown-customblocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvokimon%2Fmarkdown-customblocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvokimon%2Fmarkdown-customblocks/lists"}