Skip to content

Authoring and editing content

Jump to bottom
Maxwell Simmer edited this page May 8, 2019 · 7 revisions

Authoring and editing content

b-ber projects are authored in Markdown, using a combination of the CommonMark syntax, along with a custom b-ber syntax extensions called "directives." b-ber directives are used to create more complex formatting and relationships in the HTML than is possible with Markdown alone.

The most common syntax for a b-ber directive is:

::: directive:unique-ID

Text goes here.

::: exit:unique-ID

Directives can include attributes, which will commonly map to HTML attributes, such as titles or classes. The full list of directives can be found in the All directives.

::: directive:unique-ID title:"My Directive"

Text goes here.

::: exit:unique-ID

Container directives

The most common directive for authoring content is the container directive. A container directive wraps its content in an HTML section element. This maintains structural semantics throughout the document and is useful for scoping CSS styles. Container directives must always be closed with a corresponding exit directive.

Here is an example of the chapter directive:

Input (Markdown)

::: chapter:chapter-one

# Chapter One Title

Text goes here.

::: exit:chapter-one

Output (HTML)

<section id="chapter-one" epub:type="bodymatter chapter" class="bodymatter chapter">
    <h1>Chapter One Title</h1>
    <p>Text goes here.</p>
</section>

Note: b-ber automatically adds some HTML attributes the output such as classes and epub:types.

Media directives

b-ber offers support for including images, videos, and audio. There are a number of options to chose from, but the default system uses a thumbnail that links to a figures section. The links and page order of the figures section are automatically generated. The reason we developed this system is to maintain design integrity throughout a project to avoid clipped images and strange formatting that can be introduced when a user modifies their viewing preferences.

Figures

The figure directive will create new HTML pages for each of the figures encountered in the Markdown, and add these new pages to the <type>.yml files automatically during build. A <type>.yml file is the projects table of contents. b-ber will also detect the figure's dimensions and apply a corresponding class, such as landscape, portrait, square, portrait-long.

Without caption

Input (Markdown)
::: figure:figure-ID source:figure.jpg alt:"Figure Title"

With caption

Input (Markdown)
::: figure:image-square source:square.jpg alt:"Inline Square Image caption."
:: *Square Image* caption.
:::

Output (HTML: Inline thumbnail)

<div class="figure__small figure__small--square">
    <figure id="refimage-square">
        <a href="figureimage-square.xhtml#image-square">
            <img src="../images/square.jpg" alt="Inline Square Image caption." />
        </a>
    </figure>
</div>
Output (HTML: figures section)
<div class="figure__large">
    <figure id="image-square">
        <div class="figure__items" style="width:85%;margin:0 auto;">
            <a href="images.xhtml#refimage-square">
                <img class="square" alt="Inline Square Image caption." src="../images/square.jpg" style="width:100%;max-width:100%;height:auto;" />
            </a>
            <div class="figcaption" style="width:100%;max-width:100%;height:auto;">
                <p class="small"> <em>Square Image</em> caption.
                </p>
            </div>
        </div>
    </figure>
</div>

Inline Figures

Inline figures display an image in the flow of the project on its own page or column.

Input (Markdown)

::: figure-inline:inline-image-square source:square.jpg alt:"Inline Portrait Square Image caption."
:: *Inline Square Image* caption.
::

Output (HTML)

<div class="figure__large figure__inline figure__inline--square">
    <figure id="inline-image-square">
        <div class="figure__items" style="width:85%;margin:0 auto;">

            <img class="square" alt="Inline Portrait Square Image caption." src="../images/square.jpg"
                style="width:100%;max-width:100%;height:auto;" />

            <div class="figcaption" style="width:100%;max-width:100%;height:auto;">
                <p class="small"> <em>Inline Square Image</em> caption.
                </p>
            </div>
        </div>
    </figure>
</div>

Other directives

b-ber

Getting started

Creating and authoring content

Publishing the project

Directives

Styling and theming

Misc

b-ber development

Clone this wiki locally