Markdown Formatting

The renderer that we use (markdown-it), supports the default markdown syntax with some extra features. Please refer to markdown reference sheet for markdown syntax.

Inline Vs. Block

In HTML we have block and inline elements. Block elements usually add a newline and extra spaces around the content, while inline elements will only take up as much width as is needed to display the content. Paragraphs <p>, headers <h#>, and division <div> are some of the common block elements. Span <span>, images <img>, and anchors <a> are examples for inline blocks.

This concept exists in markdown-it too. If we parse the content as a block, if the given markdown value does not produce a proper block element, it will be wrapped in a <p> tag. While rendering it inline, will not add the <p> tag. Also newline (\n) is not acceptable in values of inline elements.

[caption](http://example.com)

#inline output
<a href="http://example.com">caption</a>

#block output
<p>
  <a href="http://example.com">caption</a>
</p>

Therefore sometimes we prefer to render the value as inline. markdown-it also has different set of rules for inline and block. All the inline tags are acceptable while rendering a block, but not the other way around. For example you cannot have a header in inline. So you need to be careful while using the blocks. The following are different places that we are rendering inline. Other parts of code accept block elements.

  • row-name logic. More specifcally the logic for processing row_markdown_pattern.
  • While processing markdown_name (used on facets, columns, tables, and schemas).

Attributes

You can attach attributes to any element in your markdown. Generally you can attach the attributes in {} to your element. For example if you want to add attributes to a link, you can use the [caption](link){attributes} template. The acceptable format for attributes:

  • Any attribute that starts with a . will be treated as class name.
[class example](http://example.com){.test}

#OUTPUT
<p>
  <a href="http://example.com" class="test">class example</a>
</p>
  • If you want to define multiple attributes just seperate them with space.
**Multiple attributes Example**{.test .cls-2 val=1 disabled}

#OUTPUT
<p>
  <strong class="test cls-2" val="1" disabled="">Multiple attributes Example</strong>
</p>

Multiple attributes Example

  • Attach attributes to markdown table
|header|\n|-|\n|text|{.class-name}

#OUTPUT
<table class="class-name">
  <thead>
    <tr>
      <th>heading</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>text</td>
    </tr>
  </tbody>
</table>
heading
text

Examples

2. Download Button

Download button is a link with some predefined attributes. You can use these attributes to ensure consistent display for the download buttons.download and target="_blank" which will allow it to open in a new tab with classes .btn and .btn-primary for CSS styling.

[Jquery Download](https://code.jquery.com/jquery-3.1.0.js){download .btn .btn-primary target=_blank}

# OUTPUT:
<p>
    <a href="https://code.jquery.com/jquery-3.1.0.js" download="" class="btn btn-primary" target="_blank">Jquery Download</a>
</p>

NOTE: please stick to the above format only to generate a download link.

3. Image

By adding ! at the begining of a link definition, it will display the image. Images are inline elements.

![Image](http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg)

# OUTPUT:
<p>
    <img src="http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg" alt="Image">
</p>

Image

You can define the width and height attributes for an image.

![ImageWithSize](http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg){width=800 height=300}

# OUTPUT:
<p>
    <img src="http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg" alt="ImageWithSize" width="800" height="300">
</p>

ImageWithSize

You can also add extra styles to the image to ensure it is displayed correctly.

![ImageWithSize](http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg){width=500 style="max-height:300px;max-width:800px;"}

# OUTPUT:
<p>
    <img src="http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg" alt="ImageWithSize" width="500" style="max-height:300px;max-width:800px;">
</p>

ImageWithSize

NOTE: You can add any style content to your markdown. For more info on styling you can refer this tutorial

4. Thumbnail Image With Aspect Ratio and Height

With attributes height=400 and target=_blank is to open it in new tab

# [![alt text](thumbnail-URL){height=400}](destination-URL){target=_blank}

[![Image](http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg){height=400}](https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg){target=_blank}

# OUTPUT:
<p>
    <a href="https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg" target="_blank">
        <img src="http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg" alt="Image" height="400">
    </a>
</p>

Image

Multiple Adjacent Images

With attributes height=200 and target=_blank is to open it in new tab

# [![alt text](thumbnail-URL){height=200}](destination-URL){target=_blank}

[![Image](http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg){height=200}](https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg){target=_blank} [![Image](https://c.fastcompany.net/multisite_files/fastcompany/imagecache/1280/poster/2015/06/3046722-poster-p-1-the-psychology-of-living-in-skyscrapers.jpg){height=200}](https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg){target=_blank}

# OUTPUT:
<p>
    <a href="https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg" target="_blank">
        <img src="http://assets.barcroftmedia.com.s3-website-eu-west-1.amazonaws.com/assets/images/recent-images-11.jpg" alt="Image" height="200">
    </a>
    <a href="https://static.pexels.com/photos/2324/skyline-buildings-new-york-skyscrapers.jpg" target="_blank">
        <img src="https://c.fastcompany.net/multisite_files/fastcompany/imagecache/1280/poster/2015/06/3046722-poster-p-1-the-psychology-of-living-in-skyscrapers.jpg" alt="Image" height="200">
    </a>
</p>

Image Image

6. Iframe

This is not part of commonMark specification and it will result in a block. You have to follow the syntax completely (notice the newline in the closing tag).

Without any attributes (eg: height and width)

::: iframe [CAPTION](https://dev.isrd.isi.edu/chaise/search) \n:::

# OUTPUT:
<figure class="embed-block">
    <figcaption class="embed-caption">CAPTION</figcaption>
    <iframe src="https://dev.isrd.isi.edu/chaise/search"></iframe>
</figure>

With attributes width=800, height=300

::: iframe [CAPTION](https://dev.isrd.isi.edu/chaise/search){width=800 height=300} \n:::

# OUTPUT:
<figure class="embed-block">
    <figcaption class="embed-caption">CAPTION</figcaption>
    <iframe src="https://dev.isrd.isi.edu/chaise/search" width="800" height="300" ></iframe>
</figure>

If you provide an invalid link then instead of an iframe you will just get the internal markdown rendered

:::iframe *Invalid [CAPTION](https://dev.isrd.isi.edu/chaise/search) \n:::

# OUTPUT:
<p>
    <em>Invalid</em>
    <a href="https://dev.isrd.isi.edu/chaise/search">CAPTION</a>
</p>

Invalid CAPTION

Iframe With a linkable caption

::: iframe [CAPTION](https://dev.isrd.isi.edu/chaise/search){width="800" height="300" link="https://dev.isrd.isi.edu/chaise/search"} \n:::

# OUTPUT:
<figure class="embed-block">
    <figcaption class="embed-caption">
        <a href="https://dev.isrd.isi.edu/chaise/search" target="_blank">CAPTION</a>
    </figcaption>
    <iframe src="https://dev.isrd.isi.edu/chaise/search" width="800" height="300"></iframe>
</figure>

Iframe with a linkable caption positioned at its bottom

::: iframe [CAPTION](https://dev.isrd.isi.edu/chaise/search){width="800" height="300" link="https://dev.isrd.isi.edu/chaise/search" pos="bottom" } \n:::

# OUTPUT:
<figure class="embed-block">
    <iframe src="https://dev.isrd.isi.edu/chaise/search" width="800" height="300"></iframe>
        <figcaption class="embed-caption">
        <a href="https://dev.isrd.isi.edu/chaise/search" target="_blank">CAPTION</a>
    </figcaption>
</figure>

Iframe with a linkable caption positioned at its bottom with iframe class and style

To style the whole iframe enclosing block you can either specify classes using iframe-class or CSS style using iframe-style.

::: iframe [CAPTION](https://example.com){pos="bottom" iframe-class="iclass" iframe-style="border:1px solid;"  link="https://example.com} \n:::

# OUTPUT:
<figure class="embed-block iclass">
    <figcaption class="embed-caption">
        <a href="https://example.com" target="_blank">CAPTION</a>
    </figcaption>
    <iframe src="https://example.com" width="800" height="300"></iframe>
</figure>

Iframe with caption positioned at its bottom with caption class and style

To style the caption of an iframe you can either specify classes using caption-class or CSS style using caption-style.

::: iframe [CAPTION](https://example.com){pos="bottom" caption-class="cclass" caption-style="font-weight:500;"  link="https://example.com} \n:::

# OUTPUT:
<figure class="embed-block">
    <figcaption class="embed-caption cclass" style="font-weight:500;">CAPTION</a></figcaption>
    <iframe src="https://example.com" width="800" height="300"></iframe>
</figure>

Iframe with iframe class, style, caption class and style

::: iframe [CAPTION](https://example.com){pos="bottom" iframe-class="iclass" iframe-style="border:1px solid;" caption-class="cclass" caption-style="font-weight:500;"  link="https://example.com} \n:::

# OUTPUT:
<figure class="embed-block iclass" style="border:1px solid;">
    <figcaption class="embed-caption cclass" style="font-weight:500;">CAPTION</a></figcaption>
    <iframe src="https://example.com" width="800" height="300"></iframe>
</figure>

8. Vocabulary

To show text as vocabulary, you can use the predefined vocab class. The following markdown pattern turns a bock of text, to a gray bold bubble with color blue.

**some bold term**{.vocab}
# OUTPUT: <strong class="vocab">some bold term</strong>

9. Video

This is not part of commonMark specification and it will result in a block. You have to follow the syntax completely (notice the newline in the closing tag).

markdown syntax: '::: video [<caption>](<source>)[{attribute list}] \n:::'

There must be a space before \n:::.

  • caption: The caption provides a short description of the video
  • source: The address to the location of the video
  • attribute list: The attributes supported will be (height, width, preload, loop, muted, autoload, pos)
    • height: Sets the height of the video player
    • width: Sets the width of the video player
    • preload: Specifies if and how the author thinks the video should be loaded when the page loads
    • loop: Specifies that the video will start over again, every time it is finished
    • muted: Specifies that the audio output of the video should be muted
    • pos: Specifies where the caption of video should appear (top or bottom)

Examples

  • Without any attributes
::: video [This is sample video](http://techslides.com/demos/sample-videos/small.mp4)\n:::

# OUTPUT:
<figure>
     <figcaption>This is sample video</figcaption>
     <video controls ><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
     </video>
</figure>
  • With attributes width=400, height=300
::: video [This is sample video](http://techslides.com/demos/sample-videos/small.mp4){width=400 height 300} \n:::

# OUTPUT:
<figure>
    <figcaption>This is sample video</figcaption>
    <video controls width=400 height=300 ><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
    </video>
</figure>"
  • With boolean attributes muted, autoload, loop, preload
::: video [This is sample video](http://techslides.com/demos/sample-videos/small.mp4){autoload muted loop preload} \n:::

# OUTPUT:
<figure>
    <figcaption>This is sample video</figcaption>
    <video controls autoload muted loop preload ><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
    </video>
</figure>
  • To put the video caption at bottom or top, use the pos attribute (bootom or top)
::: video [My Caption](http://techslides.com/demos/sample-videos/small.mp4){pos=bottom loop preload} \n:::
# Output:
<figure>
    <video controls loop preload><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
    </video>
    <figcaption>My Caption</figcaption>
</figure>
  • With invalid attributes Invalid attributes provided to the attribute list will be simple ignored.
::: video [This is sample video](http://techslides.com/demos/sample-videos/small.mp4){preplay mute} \n:::
`preplay and mute being invalid attribute`

# OUTPUT:
<figure>
    <figcaption>This is sample video</figcaption>
    <video controls ><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
    </video>
</figure>
  • Valid attributes after a set of invalid attributes will be used while templating
::: video [This is sample video](http://techslides.com/demos/sample-videos/small.mp4){muted=3 height=300} \n:::
`muted beign a boolean swtich for video tag, muted=3 makes it an invalid attribute but height is treated as a valid attribute here`

# OUTPUT:
<figure>
    <figcaption>This is sample video</figcaption>
    <video controls height=300 ><source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
    </video>
</figure>

10. Subscript

This is not part of commonMark specification and it will result in an inline element.

~This~ should be subscript.

# OUTPUT:
<p>
    <sub>This</sub> should be subscript.
</p>

This should be subscript.

With attributes

~This~{.class-name} should be subscript.

# OUTPUT:
<p>
    <sub class="class-name">This</sub> should be subscript.
</p>

This should be subscript.

11. Superscript

This is not part of commonMark specification and it will result in an inline element.

Without attributes

~This~ should be superscript.

# OUTPUT:
<p>
    <sup>This</sup> should be superscript.
</p>

This should be superscript.

With attributes

^This^{.class-name} should be superscript.

# OUTPUT:
<p>
    <sup class="class-name">This</sup> should be superscript.
</p>

This should be superscript.

12. Span (Attach Attributes To Text)

This is not part of commonMark specification and it will result in an inline element. Opening tag is :span: and closing is :/span:.

This :span:text:/span:{.cl-name style="color:red"} has new color.

# OUTPUT:
<p>
    This <span class="cl-name" style="color:red">text</span> has new color.
</p>
This text has new color.

You can also have empty span. You can use this to display glyphicons.

:span::/span:{.glyphicon .glyphicon-download-alt}

# OUTPUT:
<p>
    <span class="glyphicon glyphicon-download-alt"></span>
</p>