Welcome

Blocks is a preprocessor for mdBook which transforms Blocks markdown into beautiful Bootstrap components.

Blocks is in constant development, contribute @ https://github.com/SlipperyBrick/Blocks

Elements which are created with Blocks are constructed into Bootstrap components that inherit the default style of your enabled mdBook theme.

Whether you are using mdBook for creating a blogging site, technical documentation, a personal portfolio, or even a complete website solution, Blocks gives you the ability to continue writing your book pages in markdown whilst adding modern looking components straight from the Bootstrap framework.

Check the examples to see what is possible with Blocks, and also visit the Blocks component library for a list of supported components.

Hi!

Keep your content looking fresh.

Welcome!

With modern Bootstrap components.

To ...

That you can write in markdown.

Blocks!

Using the power of Blocks.

Installation

Blocks is built using TypeScript and has weekly updates via npm. You can find the most recent update of the Blocks preprocessor here, it is recommend to use the @latest tag.

Prerequisites

There are a two dependencies that you are required to install in order to use mdBook and the Blocks preprocessor. Below are the steps you should follow if you do not have these dependencies installed.

Step 1Install NodeJS

Windows and Mac: Download from the NodeJS official website, we recommend opting for the LTS version.
Linux: Use nvm installation to manage multiple NodeJS versions easily. See nvm installation guide.

Step 2Install mdBook CLI

Option 1: GitHub Binaries

Go to mdBook Releases on GitHub.
Download the latest release for your OS.
Extract the binary to a location and add to your PATH.

Option 2: Cargo Installation (requires Rust)

Install Rust and cargo from the official Rust site.
Run cargo install mdBook in the terminal.

Step 3Setup your mdBook Project

Initialize npm Project: Navigate to your project root and execute npm init and follow the instructions.
Install Blocks: Run npm install blocks-preprocessor@latest to get the latest version of the Blocks preprocessor.

Step 4Configure mdBook for Blocks

Initialize mdBook project: Run mdBook init and follow the instructions.
Edit your book.toml to include the Blocks preprocessor and Bootstrap resources:

[preprocessor.blocks]
command = "node node_modules/blocks-preprocessor/dist/blocks.js"
[output.html]
additional-css = ["node_modules/blocks-preprocessor/dist/mdBook-blocks/resources/bootstrap/scss/bootstrap.css", "node_modules/blocks-preprocessor/dist/mdBook-blocks/resources/blocks/scss/blocks.css"]
additional-js = ["node_modules/blocks-preprocessor/dist/mdBook-blocks/resources/bootstrap/js/bootstrap.js"]

Step 4Begin Using Blocks

With your environment setup, you can start incorporating Bootstrap components into your mdBook content using the Blocks' markdown syntax.

Support

If you require extra support to install the required dependencies please raise an issue here and use the "help wanted" label.

Deploy with Docker

Markdown Syntax Guide

Markdown is a lightweight markup language designed to format text on the web quickly. This guide will walk you through the basics of Markdown, enabling you to create formatted text for you mdBook projects.

For a more comprehensive guide on Markdown visit here.

Getting Started

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, which then converts to structured HTML. Below are the steps to start writing Markdown.

Text Formats

Text in Markdown can be easily formatted to improve the readability and high important sections.

Bold: To make text bold, wrap it with two asterisks

This text will be bold

Italic: Italicize text by wrapping text with a single asterisk

This text will be italicize

Strikethrough: To strikethrough text use two tildes

~~Strikethrough text using tildes~~

Headings

Headings in Markdown range from 1-6 and are created using the hash or pound symbol #

H1 Heading

H2 Heading

H3 Heading

H4 Heading

H5 Heading

H6 Heading

Lists

You can organize content by using lists which can be ordered or unordered.

Blocks Markdown

Discuss the syntax of blocks markdown. Demo how a single component works ...

title: "Hi!"
caption: "Keep your content looking fresh."
image: "../assets/blocks-watermark.png"
button: "Alerts"
link: "components/alerts.md"

or, how grouping multiple components can work through the blocks top-level constructs such as rows, or containers ...

<blocks-row

```blocks-card
title: "Hi!"
caption: "Keep your content looking fresh."
image: "../assets/blocks-watermark.png"
button: "Alerts"
link: "components/alerts.md"
```
```blocks-card
title: "Welcome"
caption: "With modern Bootstrap components."
image: "../assets/blocks-watermark.png"
button: "Badges"
link: "components/badges.md"
```
```blocks-card
title: "To ..."
caption: "That you can write in markdown."
image: "../assets/blocks-watermark.png"
button: "Buttons"
link: "components/buttons.md"
```
```blocks-card
title: "Blocks!"
caption: "Using the power of Blocks."
image: "../assets/blocks-watermark.png"
button: "Cards"
link: "components/cards.md"
```

Alerts

Alerts are a versatile tool that can captivate your audience's attention while efficiently delivering essential messages. Whether you want to celebrate achievements or provide critical warnings, alerts empower you to communicate with impact in a sleek and stylish manner.

Attributes

Attribute	Value
content	Enclose the message you wish to display within double quotes
icon	Optionally, include a FontAwesome icon within double quotes to enhance visual context.

Refer to the FontAwesome icon cheatsheet for a selection of available icons

Example

Explore an example showcasing a straightfoward alert with both an icon and a message:

[blocks-alert]
icon: "fa-info-circle"
content: "A simple alert"
[/blocks-alert]

Output

The example above renders as:

A simple alert

The "fa-info-circle" icon from FontAwesome is utilized in this case to denote an informational message.

Feel free to experiment with various icons and messages to tailor your alerts to your content's context.

Remember to consistently use double quotes and maintain proper indentation for polished syntax.

Badges

Get ready to elevate your user experience with the powerful and flexible badge headings at your fingertips! Create a seamless and intuitive user experience that keeps your audience engaged and informed.

Attributes

Attribute	Value
title	A content string wrapped in double-quotes
content	A content string wrapped in double-quotes

Example

[blocks-badge]
title: "A Simple Badge"
content: "New"
[/blocks-badge]

Output

A Simple BadgeNew

Badges are a great way to add a touch of engagement to your webpage. Highlight new content sections, or draw attention to specific information that you want focus on.

Buttons

Prepare to unleash the power of buttons on your webpage! With their ability to guide users and provide easy access to other areas of content, buttons are an essential tool for creating a seamless and intuitive user experience.

Attributes

Attribute	Value
content	A content string wrapped in double-quotes
link	A path to a markdown file wrapped in double-quotes

Example

[blocks-button]
content: "Go Somewhere"
link: "../welcome.md"
[/blocks-button]

Output

Up to seven buttons can be perfectly aligned by wrapping a row component around them.

Example

[blocks-row]
[blocks-button]
content: "Button 1"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 2"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 3"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 4"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 5"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 6"
link: "../welcome.md"
[/blocks-button]
[blocks-button]
content: "Button 7"
link: "../welcome.md"
[/blocks-button]
[/blocks-row]

Output

Cards

Behold the awe-inspiring power of the card! An unrivaled vessel for your content, the card is a flexible and adaptable container that is sure to capture your audience's attention. With options for customization, you can easily tailor your card to suit your needs to bring forward your vision.

Attributes

Attribute	Value
title	A content string wrapped in double-quotes
caption	A content string wrapped in double-quotes
image	A path to an image wrapped in double-quotes
button	A caption string wrapped in double-quotes
link	A path to a markdown file wrapped in double-quotes

Example

[blocks-card]
title: "A Card"
caption: "Here is a beautiful card to transport you to the Welcome page"
image: "../assets/blocks-watermark.png"
button: "Take me there!"
link: "../welcome.md"
[/blocks-card]

Output

A Card

Here is a beautiful card to transport you to the Welcome page

The card offers a myriad of potential display options that enable you to present your content in distinctive and captivating ways. Whether you choose to stack your cards or utilize the row or container layout components, the possibilities for creative expression are limitless. You have complete freedom to experiment with various layouts to make your content stand out and leave a lasting impression on your audience.

Example

[blocks-row]
[blocks-card]
title: "Card 1"
caption: "I am card 1"
image: "../assets/blocks-watermark.png"
button: "See More"
link: "../welcome.md"
[/blocks-card]
[blocks-card]
title: "Card 2"
caption: "I am card 2"
image: "../assets/blocks-watermark.png"
button: "See More"
link: "../welcome.md"
[/blocks-card]
[blocks-card]
title: "Card 3"
caption: "I am card 3 and I have more content than the other cards"
image: "../assets/blocks-watermark.png"
button: "See More"
link: "../welcome.md"
[/blocks-card]
[blocks-card]
title: "Card 4"
caption: "I am card 4"
image: "../assets/blocks-watermark.png"
button: "See More"
link: "../welcome.md"
[/blocks-card]
[/blocks-row]

Output

Card 1

I am card 1

Card 2

I am card 2

Card 3

I am card 3 and I have more content than the other cards

Card 4

I am card 4

Rows

Prepare to witness the power of alerts! With their ability to grab attention and convey important information, alerts are an essential tool for creating a dynamic and engaging user experience. From success messages that display accomplishments to warning messages that prevent potential issues, alerts can provide insight to valuable feedback with their compact and stylish form.

Attributes

Attribute	Value
content	A content string wrapped in double-quotes

Example

blocks-alert
content: "A simple alert"

Output

content: "A simple alert"

Containers

Attributes

Attribute	Value
content	A content string wrapped in double-quotes

Example

blocks-alert
content: "A simple alert"

Output

content: "A simple alert"

Introducing Aurora Smart Glasses: Vision Redefined

Special Launch Offer: Be among the first 100 to pre-order and get 20% off plus a free wireless charger.

Get ready to experience the futureDecember 2024

AR Navigation

Navigate the world with enhanced reality overlays directly in your field of vision.

Instant Translation

Communicate in any language with real-time audio translations.

Health Monitoring

Keep track of your vital signs and activity levels for a healthier lifestyle.

Social Media Integration

Share moments and connect with friends through integrated social media features.

Hear from Our Beta Testers

"The Aurora Smart Glasses have changed how I interact with my city and friends. Absolutely groundbreaking!" - Jane Doe

"As a tech enthusiast, I'm genuinely impressed by the innovation and practicality of these glasses." - John Smith