Skip to content

Latest commit

 

History

History
471 lines (316 loc) · 11.2 KB

tabs.md

File metadata and controls

471 lines (316 loc) · 11.2 KB
Raw

docsify-tabs

NPM Codacy grade License: MIT Tweet Star

A docsify.js plugin for rendering tabbed content from markdown.

Demo

A basic tab set using the default options.

Tab A

This is some text.

  • List item A-1
  • List item A-2
// JavaScript
function add(a, b) {
  return a + b;
}

Tab B

This is some more text.

  • List item B-1
  • List item B-2
/* CSS */
body {
  background: white;
  color: #222;
}

Tab C

This is some more text.

  • List item C-1
  • List item C-2
<!-- HTML -->
<h1>Heading</h1>
<p>This is a paragraph.</p>

?> Like docsify-tabs? Be sure to check out docsify-themeable for your site theme!

Features

  • Generate tabbed content using unobtrusive markup
  • Persist tab selections on refresh/revisit
  • Sync tab selection for tabs with matching labels
  • Style tabs using "classic" or "material" tab theme
  • Customize styles using CSS custom properties
  • Compatible with docsify-themeable themes

Limitations

  • Nested tabsets (i.e. tabs within tabs) are not supported.
  • Tabs wraps when their combined width exceeds the content area width.

Installation

  1. Add the docsify-tabs plugin to your index.html after docsify.

    <!-- docsify (latest v4.x.x)-->
<script src="https://cdn.jsdelivr.net/npm/docsify@4"></script>

<!-- docsify-tabs (latest v1.x.x) -->
<script src="https://cdn.jsdelivr.net/npm/docsify-tabs@1"></script>

  2. Review the Options section and configure as needed.

    window.$docsify = {
  // ...
  tabs: {
    persist    : true,      // default
    sync       : true,      // default
    theme      : 'classic', // default
    tabComments: true,      // default
    tabHeadings: true       // default
  }
};

  3. Review the Customization section and set theme properties as needed.

    <style>
  :root {
    --docsifytabs-border-color: #ededed;
    --docsifytabs-tab-highlight-color: purple;
  }
</style>

Usage

  1. Define a tab set using tabs:start and tabs:end HTML comments.

    HTML comments are used to mark the start and end of a tab set. The use of HTML comments prevents tab-related markup from being displayed when markdown is rendered as HTML outside of your docsify site (e.g. Github, GitLab, etc).

    <!-- tabs:start -->

...

<!-- tabs:end -->

  2. Define tabs within a tab set using heading + bold markdown.

    Heading text will be used as the tab label, and all proceeding content will be associated with that tab up to start of the next tab or a tab:end comment. The use of heading + bold markdown allows tabs to be defined using standard markdown and ensures that tab content is displayed with a heading when rendered outside of your docsify site (e.g. GitHub, GitLab, etc).

    <!-- tabs:start -->

#### ** English **

Hello!

#### ** French **

Bonjour!

#### ** Italian **

Ciao!

<!-- tabs:end -->

    See options.tabHeadings for details or options.tabComments for an alternate method of defining tabs within tab sets.

  3. Voilà! A tab set is formed.

    English

    Hello!

    French

    Bonjour!

    Italian

    Ciao!

Options

Options are set within the window.$docsify configuration under the tabs key:

<script>
  window.$docsify = {
    // ...
    tabs: {
      persist    : true,      // default
      sync       : true,      // default
      theme      : 'classic', // default
      tabComments: true,      // default
      tabHeadings: true       // default
    }
  };
</script>

persist

  • Type: boolean
  • Default: true

Determines if tab selections will be restored after a page refresh/revisit.

Configuration

window.$docsify = {
  // ...
  tabs: {
    persist: true // default
  }
};

sync

  • Type: boolean
  • Default: true

Determines if tab selections will be synced across tabs with matching labels.

Configuration

window.$docsify = {
  // ...
  tabs: {
    sync: true // default
  }
};

Demo

macOS

Instructions for macOS...

Windows

Instructions for Windows...

Linux

Instructions for Linux...

macOS

More instructions for macOS...

Windows

More instructions for Windows...

Linux

More instructions for Linux...

theme

  • Type: string|boolean
  • Accepts: 'classic', 'material', false
  • Default: 'classic'

Sets the tab theme. A value of false will indicate that no theme should be applied, which should be used when creating custom tab themes.

Configuration

window.$docsify = {
  // ...
  tabs: {
    theme: 'classic' // default
  }
};

Demo

Classic Material No Theme

Tab A

This is some text.

Tab B

This is some more text.

Tab C

Yes, this is even more text.

tabComments

  • Type: boolean
  • Default: true

Determines if tabs within a tab set can be defined using tab comments.

Note that defining tabs using HTML comments means tab content will not be labeled when rendered outside of your docsify site (e.g. GitHub, GitLab, etc). For this reason, defining tabs using options.tabHeadings is recommended.

Configuration

window.$docsify = {
  // ...
  tabs: {
    tabComments: true // default
  }
};

Example

<!-- tabs:start -->

<!-- tab:English -->

Hello!

<!-- tab:French -->

Bonjour!

<!-- tab:Italian -->

Ciao!

<!-- tabs:end -->

tabHeadings

  • Type: boolean
  • Default: true

Determines if tabs within a tab set can be defined using heading + bold markdown.

The use of heading + bold markdown allows tabs to be defined using standard markdown and ensures that tab content is displayed with a heading when rendered outside of your docsify site (e.g. GitHub, GitLab, etc). Heading levels 1-6 are supported (e.g. # - ######) as are both asteriscks (**) and underscores (__) for bold text via markdown.

Configuration

window.$docsify = {
  // ...
  tabs: {
    tabHeadings: true // default
  }
};

Example

<!-- tabs:start -->

#### ** English **

Hello!

#### ** French **

Bonjour!

#### ** Italian **

Ciao!

<!-- tabs:end -->

Customization

Themes

See options.theme for details on available themes.

Theme Properties

Theme properties allow you to customize tab styles without writing complex CSS. The following list contains the default theme values.

vars.css

To set theme properties, add a <style> element to your index.html file after all other stylesheets and set properties within a :root selector.

<style>
  :root {
    --docsifytabs-border-color: #ededed;
    --docsifytabs-tab-highlight-color: purple;
  }
</style>

Custom Styles

Custom tab styles can be created using docsify-tabs CSS classes and data-tab attributes.

Use the docsify-tabs CSS classes to apply common tab styles to tab blocks, toggles, and content containers. Use data-tab attributes to apply styles to specific tabs and/or content based on the tab label.

<div class="docsify-tabs docsify-tabs--classic">
  /* Tab A */
  <button class="docsify-tabs__tab docsify-tabs__tab--active" data-tab="tab a">Tab A</button>
  <div class="docsify-tabs__content" data-tab-content="tab a">
    ...
  </div>

  /* Tab B */
  <button class="docsify-tabs__tab" data-tab="tab b">Tab B</button>
  <div class="docsify-tabs__content" data-tab-content="tab b">
    ...
  </div>
</div>

Examples

Icon Only

Tab Markdown

#### **Icon Only**

Custom CSS

.docsify-tabs__tab[data-tab="icon only"] {
  letter-spacing: -100vw;
  color: transparent;
}
.docsify-tabs__tab[data-tab="icon only"]:before {
  content: url(path/to/image.png);
  vertical-align: middle;
}

Icon + Label

Tab Markdown

#### **Icon + Label**

Custom CSS

[data-tab="icon + label"]:before {
  content: url(path/to/image.png);
  height: 16px;
  margin-right: 0.5em;
  vertical-align: middle;
}

Active State

Tab Markdown

#### **Active State**

Custom CSS

.docsify-tabs__tab--active[data-tab="active state"] {
  box-shadow: none;
  background: #13547a;
  color: white;
}
.docsify-tabs__content[data-tab-content="active state"] {
  background-image: linear-gradient(0deg, #80d0c7 0%, #13547a 100%);
}
.docsify-tabs__content[data-tab-content="active state"] p strong {
  color: white;
}

JSBin

Demo: Simple Animation Tests

**Tab Markdown** ```markdown #### **JSBin** ``` **Custom CSS** ```css [data-tab-content="jsbin"] { padding: 0 !important; } [data-tab-content="jsbin"] * { margin: 0 !important; } [data-tab-content="jsbin"] iframe { display: block; min-height: 350px; border: 0 !important; } ``` #### **Badge** **Tab Markdown** ```markdown #### **Badge** ``` **Custom CSS** ```css [data-tab="badge"]:after { content: 'New!'; position: absolute; top: 0; right: 0; min-height: 1em; min-width: 1em; padding: 0.325em 0.5em 0.3em 0.5em; border-radius: 3px; background: red; color: #fff; font-family: sans-serif; font-weight: bold; font-size: 11px; line-height: 1; transform: translate(35%, -45%); } ``` ## Contact & Support * Create a [GitHub issue](https://github.com/jhildenbiddle/docsify-tabs/issues\) for bug reports, feature requests, or questions * Follow [@jhildenbiddle](https://twitter.com/jhildenbiddle\) for announcements * Add a ⭐️ [star on GitHub](https://github.com/jhildenbiddle/docsify-tabs\) or ❤️ [tweet](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2Fjhildenbiddle%2Fdocsify-tabs&hashtags=css,developers,frontend,javascript\) to support the project! ## License This project is licensed under the [MIT license](https://github.com/jhildenbiddle/docsify-tabs/blob/master/LICENSE\). Copyright (c) John Hildenbiddle ([@jhildenbiddle](https://twitter.com/jhildenbiddle\)\)