Styles & Markup

TailwindCSS

We use TailwindCSS to apply styles to this site.

TailwindCSS Config & Theme

Our theme colors and configuration can be found in tailwind.config.js. TailwindCSS includes a default base configurations but it can be overidden here.

...
theme: {
      extend: {
        fontFamily: {
          'sans': ['"Sora"', 'sans-serif']
        },
        colors: {
          'vermillion-orange': '#FE3B1E',
          'deep-kaimurasaki': '#221C34',
          'magenta': '#D2007D',
          'deep-magenta': '#740049',
          'eggshell': '#F0E5D0',
          'alabastor': '#FCF9EC'
        },
      },
    },
...

Theme Templates

In addition to the TailwindCSS theme config, template files are located in several places in the project.

- swimos-docs # Project root
  - _includes/ # Theme components/small templates
  - _layouts/ # Page layouts
  - assets/ # Asset directory
    - css/
    - images/
    - js/
  - 404.html # Top level HTML pages live in the project root.
  - community.html
  - index.html # https://swimos.org index page

Template files are raw HTML with Liquid template syntax sprinkled in to render pages.

Table of Contents

The Table of Contents on each document page is generated by the jekyll-toc plugin.

TOC Styles

The TOC is styled in _config.yml. We use TailwindCSS classes to style it, but you can also create your own styles for classes generated by the plugin.

# _config.yml
toc:
  list_id: toc # id of the <ul> for the toc
  list_class: mt-1 px-2 # We use TailwindCSS classes but you can also create your own
  sublist_class: '' # We use TailwindCSS classes but you can also create your own
  item_class: hover:text-vermillion-orange block rounded-md py-2 pr-2 pl-9 text-sm leading-6 text-gray-700 # You guessed it, more TailwindCSS classes.
  item_prefix: toc- # Adds a toc-* class to each list item for styling. Ex. toc-h2 for list items that refer to an h2 in the doc body.

You can learn more about styling the TOC in the jekyll-toc README

Callouts

A number of different callout variants are available to choose depending on the urgency and content of the message. Each of them implements the base callout-base.html template.

Information

You can add informational callouts to any document by including the callout-info.html template located at _includes/callout-info.html.

{% include callout-info.html title='FYI' text='Here is something you might want to know. You can use <strong>HTML</strong> markup here to add emphasis, even <a href="https://swimos.org/meta/styles.html">links</a>.' %}

FYI

Here is something you might want to know. You can use HTML markup here to add emphasis, even links.

OK

When things are going well you can call attention to it by including the callout-ok.html template located at _includes/callout-ok.html.

{% include callout-ok.html title='Huzzah!' text='All of my code works and I actually understand why! You can use <strong>HTML</strong> markup here to add emphasis, even <a href="https://swimos.org/meta/styles.html">links</a>.' %}

Huzzah!

All of my code works and I actually understand why! You can use HTML markup here to add emphasis, even links.

Warnings

You can add warning callouts to any document by including the callout-warning.html template located at _includes/callout-warning.html.

{% include callout-warning.html title='Look out!' text='This is the warning body text. You can use <strong>HTML</strong> markup here to add emphasis, even <a href="https://swimos.org/meta/styles.html">links</a>.' %}

Look out!

This is the warning body text. You can use HTML markup here to add emphasis, even links.

Errors and Other Bad Stuff

Inversely, when something is bad or has gone wrong, you can use the callout-bad.html template located at _includes/callout-bad.html.

{% include callout-bad.html title='Uh oh!' text='We need to fix something. Here is where you\'ll find more details. You can use <strong>HTML</strong> markup here to add emphasis, even <a href="https://swimos.org/meta/styles.html">links</a>.' %}

Uh oh!

We need to fix something. Here is where you'll find more details. You can use HTML markup here to add emphasis, even links.

Custom Callouts

For custom callouts you may use the base callout template located at _includes/callout-base.html. Since no pre-defined variant is being used, individual callout properties must each be provided, including: icon, iconColor, border, backgroundColor, title, titleStyles, text, and textStyles. For the icon property, provide the font-awesome CSS classes which correspond to the desired icon. Lastly, be aware that with some background colors you may encounter contrast issues with some of the markup text (e.g. links on a royal blue background), so please be sure to address that.

{% include callout-base.html icon='fa-solid fa-circle-question' iconColor='text-purple-500' border='border-purple-500 border-4 border-dashed' backgroundColor='bg-purple-300' title='A Special Case' text='Feel free to apply any combination of text, border, or background Tailwind styles here.' %}

A Special Case

Feel free to apply any combination of text, border, or background Tailwind styles here.

Cookbook Banner

If cookbook: is set in a page’s front matter, a banner will render to tell readers that a cookbook example exists and will link them to the cookbook repo. This banner is located in _includes/cookbook.html and is included in _layouts/page.html only if page.cookbook is set.

Cookbook

This guide has a corresponding cookbook with working examples. Please see the README for more information on how to run these projects.

Announcement Banner

An announcement banner can be toggled on and off via _config.yml. All options are required to be set for the banner to render properly.

When developing locally, you will need to stop and re-start the Jekyll server to see changes.

# Set display to true/false to toggle announcements on/off
# If developing locally, this requires a jekyll serve restart to test.
announcement:
  display: true
  cta: "Join us at StreamCon 2023!"
  text: "We'll be at booth #9001."
  cta-link: "https://nstream.io/"

The template for this banner can be found in _includes/banner.html.

“Prose” styles for Markdown

Tailwind CSS has a Typography plugin that implements prose classes with default styles. This is useful for rendering Markdown content so that we don’t have to style every block through tailwind.config.js.

Paragraph Lead

This is an example of a paragraph lead.

You can use this to add emphasis to the opening word or sentence of a paragraph to highlight a main point.

Horizontal Rule

Blockquote

This is a really important quote from someone you should listen to.

Table

Table 3.1: Professional wrestlers and their signature moves.
Wrestler Signature Move(s)
"Stone Cold" Steve Austin Stone Cold Stunner, Lou Thesz Press
Bret "The Hitman" Hart The Sharpshooter
Razor Ramon Razor's Edge, Fallaway Slam

Code Blocks

Inline Code

You can render inline code snippets by using <code></code> tags or backticks:

“This is a className.”

This is also a className.

// Two ways to render code tags inline
"This is a <code>className</code>."

This is also a `className`.

Pre Code

Pre code blocks can be rendered by placing three backticks (```) around the beginning and the end of a piece of code. Jekyll uses the Rouge syntax highlighter to render code blocks. You can add a language name after the opening backticks to highlight code in the specified language. You can find a list of supported languages and lexers in the Rouge Wiki. You can follow this guide to create custom lexers as well.

<div class="rounded-md bg-swim-dark-blue p-4">
    <div class="flex">
        <div class="flex-shrink-0">
            <svg class="h-8 w-8 text-swim-teal" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
                <path fill-rule="evenodd"
                    d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z"
                    clip-rule="evenodd" />
            </svg>
        </div>
        <div class="ml-3">
          <h3 class="text-lg font-medium text-white mt-1 no_toc">Title</h3>
            <div class="mt-2 text-sm text-white prose-strong:text-swim-blue">
                <p>
                    Example Text.
                </p>
            </div>
        </div>
    </div>
</div>

You can also just use three backticks to render a non-hilighted code block:

<div class="rounded-md bg-swim-dark-blue p-4">
    <div class="flex">
        <div class="flex-shrink-0">
            <svg class="h-8 w-8 text-swim-teal" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
                <path fill-rule="evenodd"
                    d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z"
                    clip-rule="evenodd" />
            </svg>
        </div>
        <div class="ml-3">
          <h3 class="text-lg font-medium text-white mt-1 no_toc">Title</h3>
            <div class="mt-2 text-sm text-white prose-strong:text-swim-blue">
                <p>
                    Example Text.
                </p>
            </div>
        </div>
    </div>
</div>
Diátaxis Framework