JupiterNebula.Wyam.Shortcodes.TabBlock 1.0.0

JupiterNebula.Wyam.Shortcodes.TabBlock

TabBlock provides a shortcode for Wyam's Markdown module to render Bootstrap-compatible tabs and tab panes in your Markdown pages.

Adding TabBlock to Your Project

The following needs to be added to your config.wyam file:

#n JupiterNebula.Wyam.Shortcodes.TabBlock

That's it! Wyam will discover the shortcode and automatically use it when running the Markdown module.

Configuration

Currently, TabBlock just outputs basic, Bootstrap-compatible tabs and tab panes. Additional customization is planned in the future though, so stay tuned!

Usage

Syntax

TabBlock uses the Wyam shortcode syntax, as defined in Wyam's documentation.

The easiest way to define tabs and tab pane content is by creating an unordered list in Markdown syntax between the opening and closing tag for the TabBlock shortcode as shown below:

Markdown

<?# TabBlock ?>
- ::Tab Label 1::
  All content here will be placed in the tab pane for this tab.
- ::Tab _Label_ 2 with ___formatting___::
  Any _valid_ [Markdown](https://daringfireball.net/projects/markdown/syntax) can
  be put __here__ as long as each line is indented so as to be included in
  the Markdown list item.
- ![Labels Can Be Images](https://jupiternebula.com/favicon.png){style="max-height: 1em;"}
  # Tab Pane Header
  Lorem ipsum...
<?#/ TabBlock ?>

Rendered HTML (formatted by VSCode)

<div class="tab-block" id="TabBlock__PabWwGf5">
    <ul class="nav nav-tabs" role="tablist">
        <li class="nav-item"><a class="nav-link active" data-toggle="tab" aria-selected="true"
                aria-controls="TabBlock__PabWwGf5-0-pane" href="#TabBlock__PabWwGf5-0-pane"
                id="TabBlock__PabWwGf5-0-link"><span>Tab Label 1</span></a></li>
        <li class="nav-item"><a class="nav-link" data-toggle="tab" aria-selected="false"
                aria-controls="TabBlock__PabWwGf5-1-pane" href="#TabBlock__PabWwGf5-1-pane"
                id="TabBlock__PabWwGf5-1-link"><span>Tab <em>Label</em> 2 with
                    <em><strong>formatting</strong></em></span></a></li>
        <li class="nav-item"><a class="nav-link" data-toggle="tab" aria-selected="false"
                aria-controls="TabBlock__PabWwGf5-2-pane" href="#TabBlock__PabWwGf5-2-pane"
                id="TabBlock__PabWwGf5-2-link"><img src="https://jupiternebula.com/favicon.png" class="img-fluid"
                    style="max-height: 1em;" alt="Labels Can Be Images"></a></li>
    </ul>
    <div class="tab-content">
        <div class="tab-pane show active" role="tabpanel" aria-labelledby="TabBlock__PabWwGf5-0-link"
            id="TabBlock__PabWwGf5-0-pane">
            All content here will be placed in the tab pane for this tab.</div>
        <div class="tab-pane" role="tabpanel" aria-labelledby="TabBlock__PabWwGf5-1-link"
            id="TabBlock__PabWwGf5-1-pane">
            Any <em>valid</em><a href="https://daringfireball.net/projects/markdown/syntax">Markdown</a>
            can be put <strong>here</strong> as long as each line is indented so as to be included in
            the Markdown list item.</div>
        <div class="tab-pane" role="tabpanel" aria-labelledby="TabBlock__PabWwGf5-2-link"
            id="TabBlock__PabWwGf5-2-pane">
            <h1 id="tab-pane-header">Tab Pane Header</h1>
            Lorem ipsum...
        </div>
    </div>
</div>

Each tab above is represented as a Markdown list item. The labels in this example come at the beginning of each item, wrapped in a MarkDig custom container. It is not required to wrap your tab labels, but it is good practice to do so. This is because TabBlock receives your content after it has already been rendered into HTML and interprets the first HTML node it encounters in each list item as the label. The remaining nodes are interpretted as the tab pane's content (what is shown to the user when the tab is selected).

As such, wrapping the label's text (in a <span> in the example above) makes sure the label doesn't get mixed up with the tab pane's content and that it doesn't get cut off if you add formatting to your label (such as the second tab above). The third tab's label didn't need to be wrapped because the first node in that case is an <a> element and not just text.

Examples

FizzBuzz in C++, F#, and Rust

Including code snippets in multiple languages is pretty common on software development blogs and documentation pages. The following example presents implementations of FizzBuzz from rosettacode.org for multiple languages as separate tabs.

A demonstration of this in action is found at the top of this document

<?# TabBlock ?>
- C++
  ```cpp
  #include <iostream>
 
  int main ()
  {
      for (int i = 1; i <= 100; i++) 
      {
          if ((i % 15) == 0)
              std::cout << "FizzBuzz\n";
          else if ((i % 3) == 0)
              std::cout << "Fizz\n";
          else if ((i % 5) == 0)
              std::cout << "Buzz\n";
          else
              std::cout << i << "\n";
      }

      return 0;
  }
  ```
- F#
  ```fsharp
  let fizzbuzz n =
    match n%3 = 0, n%5 = 0 with
    | true, false -> "fizz"
    | false, true -> "buzz"
    | true, true  -> "fizzbuzz"
    | _ -> string n
 
  let printFizzbuzz() =
    [1..100] |> List.iter (fizzbuzz >> printfn "%s")
  ```
- Rust
  ```rust
  use std::borrow::Cow; // Allows us to avoid unnecessary allocations
  fn main() {
      (1..101).map(|n| match (n % 3, n % 5) {
          (0, 0) => "FizzBuzz".into(),
          (0, _) => "Fizz".into(),
          (_, 0) => "Buzz".into(),
          _ => Cow::from(n.to_string())
      }).for_each(|n| println!("{}", n));
  }
  ```
<?#/ TabBlock ?>