Skip to main content

A Python-Markdown extension which provides a simple syntax for including Bootstrap objects within a Markdown document.

Project description

Bootstrap4Markdown

A Python-Markdown extension which provides a simple syntax for including Bootstrap objects within a Markdown document.

Installation

To install the extension, run the following command:

pip install bootstrap4markdown

Usage

To use the extension, include its name in the list of extensions passed to Python-Markdown.

import markdown
markdown.markdown(src, extensions=['bs4md'])

Note that this extension only generates the requisite HTML for the supported Bootstrap components. The user is responsible for providing the necessary CSS and Javascript for the Bootstrap theme being used. The generated HTML assumes Bootstrap version 5.3.

Syntax

Bootstrap4Markdown is built on top of the Blocks extension. Therefore, all blocks use the same basic form.

/// name-of-block | argument
    option: value

content
///

Therefore, each supported Bootstrap object maps to a specific block name as defined below.

Alerts

Bootstrap based alerts can be defined using blocks named alert.

/// alert
This is an alert.
///

A title (or heading) can be defined using the block's argument.

/// alert | Title
This alert has a title.
///

The color of the alert can be altered using the type option. For example, setting type: warning will result in the alert-warning style being used from your Bootstrap theme.

/// alert | Warning
    type: warning

This is a **warning** alert with a title.
///

Valid types are the string names of any of Bootstraps contextual classes: primary, secondary, success, danger, warning, info, light, and dark.

Notice that the body content body of the alert contains standard Markdown content. By default the content will be parsed as a single block (paragraph) and only inline level Markdown parsing will be applied to the content. However, if the markdown option is set to block, then block-level parsing will be applied to the content as well.

/// alert
    markdown: block

This alert contains two paragraphs of Markdown text.

This is the second paragraph.
///

An alert will include a dismiss button if dismissable is set to true.

/// alert
    dismissable: true

You can dismiss me!
///

Finally, any additional HTML attributes can be defined for the outer element of the alert using the attrs option.

/// alert
    attrs:
        id: mycustomid
        class: p-5

Custom padding is set for this alert using on of Bootstraps'
[spacing](https://getbootstrap.com/docs/5.3/utilities/spacing/)
classes. (`p-5`).
///

Options

Option Type Description Default
type string A string which matches one of Bootstrap's contextual classes. primary
dismissable boolean Enable or disable a dismiss button. false
markdown string Indicate whether body content should be parsed as block or inline content. inline
attrs key:value pairs Define custom HTML attributes for the wrapping element. {}

Carousel

A Bootstrap based carousel (or slideshow) can be defined using two types of blocks: the outer carousel block and a separate slide block for each component of the slideshow.

//// carousel

/// slide | image1.jpg
    alt: Slide one.
///

/// slide | image2.jpg
    alt: Slide two.
///

////

Note that all slide blocks must be nested in a carousel block. Also, be sure to use a different number of slashes for the parent carousel block than the child slide blocks.

Carousel Block

The outer carousel block is used to define global options which apply to the entire slideshow.

//// carousel
    attrs: {id: 'mycustomid'}
    controls: false
    indicators: true
    fade: true
    autoplay: carousel
    touch: false

...
////
Option Type Description Default
controls boolean Display previous/next buttons. true
indicators boolean Display indicators to jump to a specific slide. false
fade boolean Enable a crossfade transition between slides. false
autoplay boolean or string Enable autoplay. Set to carousel to autoplay on page load or true to autoplay after first interaction. false
attrs key:value pairs Define custom HTML attributes for the wrapping carousel element. {}

Note that Boostrap requires each carousel to have a unique id defined for it to work correctly. If one is not defined in the attrs, then a random UUID string will be generated and assigned as the id of the carousel.

Slide Block

Nested within the carousel block, each slide is defined by a slide block. Slides may take one of a few forms. The simplest form is an image.

///
slide | path/to/image.jpg
    alt: Some alt text for the image.
///

Note that the path to the image is defined in the argument and the alt text in the alt option.

Image slides can also define a caption, which is text that overlays the image. The caption is defined in the body of the image.

///
slide | path/to/image.jpg
    alt: Some alt text for the image.

# Caption Title

Caption Body.
///

However, if no argument is provided, then the body content is used as the body of the slide. In both cases, Markdown processing is applied to the body content.

/// slide
    attrs: {class: 'text-center pt-5 bg-primary-subtle text-primary-emphasis min-vh-100'}

# HTML Slide

Slide Body
///

Note that various Bootstrap classes were set on the above slide. As Bootstrap's documentation explains:

Carousels don’t automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content.

Of course, raw HTML can be used as well. For example, the following slide includes a slide comprised of an SVG element.

/// slide
    markdown: inline

<svg class="d-block w-100" width="800" height="400" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Placeholder" preserveAspectRatio="xMidYMid slice" focusable="false">
<title>Placeholder</title>
<rect width="100%" height="100%" fill="#777"></rect>
<text x="50%" y="50%" fill="#555" dy=".3em">SVG Slide</text>
</svg>
///

In the above slide, the markdown option was set to inline so that the svg would not be wrapped in a Markdown paragraph. However, when using block-level raw HTML, you will want to indent the content one level (4 spaces) and set the markdown option to raw to ensure that Markdown parsing does not muck up your custom crafted HTML.

/// slide
    markdown: raw

    <h4>Title</h4>
    <p>Custom Body Content</p>
///
Option Type Description Default
alt string Alt text for an image slide. Ignored for none-image slides. ''
active boolean Set this slide to be the active slide. false
interval integer or null Number of seconds to display slide when autoplaying. Set to null to use Bootstrap's default. null
markdown string Indicate whether body or caption content should be parsed as block, inline, or raw content. block.
attrs key:value pairs Define custom HTML attributes for the slide element. {}

Note that if more that one slide is set to active: true, then only the first of all "active" slides is actually set to active. If no slides are explicitly set to be active, then the first slide in the carousel is set to be active by default.

License

The Bootstrap4Markdown Extension to Python-Markdown is licensed under the MIT License as defined in LICENSE.

Change Log

Version 0.1 (2023-03-07)

The initial release. Includes support for Alerts and Carousels.

Project details


Release history Release notifications | RSS feed

This version

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bootstrap4markdown-0.1.tar.gz (8.4 kB view details)

Uploaded Source

Built Distribution

bootstrap4markdown-0.1-py3-none-any.whl (9.4 kB view details)

Uploaded Python 3

File details

Details for the file bootstrap4markdown-0.1.tar.gz.

File metadata

  • Download URL: bootstrap4markdown-0.1.tar.gz
  • Upload date:
  • Size: 8.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.1

File hashes

Hashes for bootstrap4markdown-0.1.tar.gz
Algorithm Hash digest
SHA256 848197bc0a6f2bd7569c457b9442559549a8528270c31c8b4dd7a3bf36ade107
MD5 c814619a400b2e32d9150e93cf9c4cac
BLAKE2b-256 0bc5b08fb5573ade30109f5d615e72aa7121d55e1e064e6720add969a080d52c

See more details on using hashes here.

File details

Details for the file bootstrap4markdown-0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for bootstrap4markdown-0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6278599cfe31c9fb35c5fa575e2afa16ea8a603028f7203c36cf02227630287a
MD5 430af1b43bf2e55c477c230570875ff6
BLAKE2b-256 48db986b27b8122d3561400e9489a22ef8ea561ad9de0c16225c60f23ba2f9b1

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page