Documentation Template

Basic page structure

Here is the code for the basic document structure:

---
title: 
description: 
parent: 
---

<h1>Documentation Template</h1>
<article class="bcls-article">
  <summary>This is a template to demonstrate various CSS classes used in our documentation and provide sample code for them.</summary>
  <section class="bcls-section">
    <h2 id=""></h2>
    <p></p>
  </section>
</article>

Dash snippet: docstart

And here is how it works:

The id on the h2 tag is important because it is used to build the Page Contents menu:

Images

Images set off on their own

You can set off images on their own with a border added or no border.

<figure class="bcls-figure">
        <img class="bcls-image" src="/assets/images/doc-template/page-contents.png" alt="Basic Doc Structure">
        <figcaption class="bcls-caption--image">Basic Doc Structure</figcaption>
      </figure>

Dash snippet: bcimg

Image without border

If you wanted an image with no border, use this instead:

<figure class="bcls-figure">
  <img class="bcls-image--no-border" src="" alt="description">
  <figcaption class="bcls-caption--image">description</figcaption>
</figure>

Dash snippet: imgnoborder

For inline images, just use an <img> tag without the figure and caption tags. No special classes for inline images.

Image formats

• For screenshots, use .png or .jpg (png preferred)
• For diagrams use .svg if at all possible (svg resizes better than other formats). Many image editors like Lucidchart allow you to export the image as svg

Task lists

We use some special lists for different purposes.

Task list that resumes numbering when you restart it

1. Step 1
2. Step 2
3. Step 3: code for the list:

   <ol class="bcls-tasklist">
     <li></li>
   </ol>

4. Step 4: Dash snippet: bctasklist

Subheading

Some content you want to add before restarting the steps.

1. Step 5
2. Step 6

Task list with numbers starting at 1

1. Here is step 1 of the task.
2. Step 2 of the task.
3. Code to create this list:

   <ol class="bcls-tasklist-restart">
     <li></li>
   </ol>

Dash snippet: bcnewlist

Tables

We have special styles for tables. Here is the basic code to create one:

<div style="overflow-x: scroll;">
  <table class="bcls-table">
      <caption class="bcls-caption--table">description</caption>
      <thead class="bcls-table__head">
          <tr>
              <th>Table Header</th>
              <th>Table Header</th>
          </tr>
      </thead>
      <tbody class="bcls-table__body">
          <tr>
              <td>Table cell</td>
              <td>Table cell</td>
          </tr>
      </tbody>
  </table>
</div>

Dash snippet: bctable

And below is a sample table:

Notes for information, tips, and warnings

We have special notes styles to highlight important information, tips that might help customers, or warnings about things might go wrong.

Dash snippet: bclsinfo

Dash snippet: bctip

Dash snippet: bcwarning

Embedding videos

Training videos

For training videos, we use an in-page experience. The code looks like this:

<div class="training-video-player-ipx" data-experience="5a73630f7afd7a00101bc1b5" data-video-ids="4878165648001">&nbsp;</div></span>
  <script src="https://players.brightcove.net/20318290001/experience_5a73630f7afd7a00101bc1b5/live.js"></script>

Note that the video id (highlighted above) is the only thing that changes.

Sample videos/players

For samples, it will depend on what the sample is demonstrating. Where possible, use the basic (iframe) embed code, but if you need to add custom CSS or JavaScript, you will need to use the advanced (in-page) embed code. In either case, be sure to use the responsive version of the code.

Short animated-gif style videos

Matt created a special player for these in the In-App Help account.

These also need to be responsive, and making them so is a little more complicated, because the responsive code the Brightcove Player uses assumes a 16:9 aspect ratio, and these videos are usually odd sizes (as we try to make them as small as possible). Here's sample code to show you what needs to be done:

<div style="position: relative; display: block; max-width: 960px;">
  <div style="padding-top: 43.64%;">
    <iframe src="https://players.brightcove.net/6225316964001/Qznf2bKtV_default/index.html?videoId=6267506952001" allowfullscreen="" allow="encrypted-media" style="position: absolute; top: 0px; right: 0px; bottom: 0px; left: 0px; width: 100%; height: 100%;"></iframe>
  </div>
</div>

The key to responsive video is the padding-top value in the second div tag (highlighted above). The value needs to be the actual height of the video divided by the actual width, expressed as a percentage:

Simulate UI buttons

To help users identify buttons in Studio that you are referring to, we've create classes to simulate the buttons in documentation. Examples with the code are below.

Add New

<span class="button-blue">Add New</span>

Add New

<span class="button-blue-text">Add New</span>

Add New

<span class="button-blue-text-bordered">Add New</span>

Add New

<span class="button-red">Add New</span>

Add New

<span class="button-red-text">Add New</span>

Add New

<span class="button-red-text-border">Add New</span>

Add New

<span class="button-gray">Add New</span>

Edit

<span class="button-blue-text-bordered"> <i data-feather="edit-3"></i> Edit</span>

Code and localization

The AWS machine translator we use to localize our sites translates code as if it were ordinary text, which is always wrong! To stop this, I got Amazon to add handling for a special translate="no" attribute that stops the content of the tag from being translated. you can use that attribute on any tag, but it's especially important to use it when you are including sample code.

Inline code

For inline code, just use <code translate="No">some same code</code> (Dash snippet: codent)

Code blocks

For code blocks, we use a library that adds line numbering and syntax highlighting for the code, based on special classes.

HTML

For an HTML block: <pre class="line-numbers"><code class="language-html" translate="No"></code></pre> (Dash snippet: pchtml)

Example

<section class="bcls-section">
  <h2 id=""></h2>
  <p></p>
</section>

CSS

For a CSS block: <pre class="line-numbers"><code class="language-css" translate="No"></code></pre> (Dash snippet: pccss)

Example

.bcls-tasklist-restart {
  list-style-type: none;
  margin-left: 0;
  counter-reset: rstep calc(var(--s) - 1);
}

JavaScript

For a CSS block: <pre class="line-numbers"><code class="language-javascript" translate="No"></code></pre> (Dash snippet: pcjs)

Example

var cookiesArray = document.cookie.split(";"), cookiesObj = {}, i, tmpArray = [];
for (i = 0; i < cookiesArray.length; i++) {
    tmpArray = cookiesArray[i].split("=");
    if (tmpArray[0].indexOf('BC_TOKEN') > -1) {
        cookiesObj.BC_TOKEN = tmpArray[1];
    }
}
window.prompt("BC_TOKEN:", cookiesObj.BC_TOKEN);

Several other languages are supported, including json (Dash snippet: pcljson), swift, objective-c, and java (Dash snippet: pcjava). See this page for all languages Prism supports. Our implementation doesn't support all the languages, but if you need to add one that isn't supported, ask Robert.

If you don't want line numbers for a short snippet, just remove the class="line-numbers" from the pre tag.

Highlighting and marking user input

Sometimes it's useful to highlight an important part of code, or an item that the user needs to replace with their own information.

To highlight some code, use <span class="bcls-highlight">(some code here)</span> (Dash snippet: select the code that you want to highlight, and then type bchighlight)

To mark some code that the user needs to modify, use <span class="bcls-input">{your_access_token}</span> (Dash snippet: select the code that you want to apply this to, and then type bcinput)

Collapsable sections

Here's an example:

The code

<details>
  <summary>This part appears in the page</summary>
  <p>What's in this part can contain any HTML and is hidden until the user clicks on the visible part.</p>
</details>

FAQ

Sample

What HTML can you put in the answer?

Anything you like!

List

• item 1
• item 2

Code

<details>
  <summary>Is this the question?</summary>
  Yes, and this is the answer.
</details>
<details>
  <summary>What HTML can you put in the answer?</summary>
  <p>Anything you like!</p>
  <figure class="bcls-figure">
    <img class="bcls-image" src="/test-assets/images/lunar-eclipse.png" alt="Sample Image">
    <figcaption class="bcls-caption--image">Sample Image</figcaption>
  </figure>
  <h4>List</h4>
  <ul>
    <li>item 1</li>
    <li>item 2</li>
  </ul>
</details>

Button

Sample

BCLS Button

Code

<button class="bcls-button">BCLS Button</button>

Icons

Notes

Note link: Some text with a note^[1-1]

<p>Note link: Some text with a note<sup><strong><a href="#note1-1">[1-1]</a></strong></sup></p>

Notes

• ^[1-1] Here is the note text

<h3>Notes</h3>
  <ul>
  <li id="note1-1" style="list-style: none;"><sup><strong>[1-1]</strong></sup> Here is the note text</li>
</ul>