Authoring and editing content - triplecanopy/b-ber GitHub Wiki

Authoring and editing content

b-ber projects are authored in Markdown using a combination of the CommonMark syntax and 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 page of the Wiki.

::: 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 to the output such as classes and epub:types.

Media directives

b-ber offers support for 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 toc.yml file automatically during build. A toc.yml file is the project's table of contents.

b-ber will also detect the figure's dimensions and apply a corresponding class name, such as figure__large--portrait or figure__small--landscape. Class names used by b-ber follow BEM naming conventions.

Without caption

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

Output (HTML: Inline thumbnail)

<!-- START: figure:figure#figure-ID; _markdown/chapter-one.md:6 -->

<div class="figure__small figure__small--landscape">
  <figure id="reffigure-ID">
    <a href="figurefigure-ID.xhtml#figure-ID">
      <img src="../images/figure.jpg" alt="Figure Title" />
    </a>
  </figure>
</div>

With caption

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

Output (HTML: Inline thumbnail)

<!-- START: figure:figure#image-square; _markdown/chapter-one.md:10 -->

<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__large--square">
  <figure id="image-square">
    <div class="figure__items">

      <a href="bar.xhtml#refimage-square">
        <img class="square" alt="Inline Square Image caption." src="../images/square.jpg" />
      </a>
      <div class="figcaption">
        <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">


      <img class="square" alt="Inline Portrait Square Image caption." src="../images/square.jpg" />

      <div class="figcaption">
        <p class="small"> <em>Inline Square Image</em> caption.
        </p>
      </div>

    </div>
  </figure>
</div>

Other directives

⚠️ **GitHub.com Fallback** ⚠️