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 & Alerts

Alerts

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

{% include alert.html title='Caution' text='This is the alert body text. You can use <strong>HTML</strong> markup in it to add emphasis.' %}

Caution

This is the alert body text. You can use HTML markup in it to add emphasis.

Callouts

You can also use a generic callout which has more subtle styling for less urgent messages. Include the callout.html template located at _includes/callout.html. The information icon can be optionally swapped out for another.

{% include callout.html title='Tip' text='Don\'t forget to add text and body fields. You can still use <strong>HTML</strong> markup to add emphasis.' %}

Tip

Don't forget to add text and body fields. You can still use HTML markup to add emphasis.

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