https://github.com/diplodoc-platform/tabs-extension

https://github.com/diplodoc-platform/tabs-extension

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/diplodoc-platform/tabs-extension
• Owner: diplodoc-platform
• License: mit
• Created: 2023-06-26T13:06:00.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-10-21T10:37:52.000Z (2 months ago)
• Last Synced: 2024-10-21T14:59:46.877Z (2 months ago)
• Language: TypeScript
• Size: 851 KB
• Stars: 2
• Watchers: 12
• Forks: 4
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Codeowners: CODEOWNERS

Awesome Lists containing this project

README

        
# Diplodoc tabs extension

[![NPM version](https://img.shields.io/npm/v/@diplodoc/tabs-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/tabs-extension)

This is an extension of the Diplodoc platform, which allows adding switchable tabs in the documentation.

The extension contains some parts:

- [Prepared runtime](#prepared-runtime)

- [MarkdownIt transform plugin](#markdownit-transform-plugin)

- [Tabs API](#api)

- [React hook for smart control](#react-hook-for-smart-control)

## Quickstart

Attach the plugin to the transformer:

```js

import tabsExtension from '@diplodoc/tabs-extension';

import transform from '@diplodoc/transform';

const {result} = await transform(`

{% list tabs %}

- Tab 1

- Tab 2

- Tab 3

{% endlist %}

`, {

    plugins: [

        tabsExtension.transform({ bundle: false })

    ]

});

```

## Prepared runtime

It is necessary to add `runtime` scripts to make tabs interactive on your page.


You can add assets files which were generated by the [MarkdownIt transform plugin](#markdownit-transform-plugin).

```html

    

        

        

        

    

    

        ${result.html}

    

```

Or you can just include runtime's source code in your bundle.

```js

import '@diplodoc/tabs-extension/runtime'

import '@diplodoc/tabs-extension/runtime/styles.css'

```

## MarkdownIt transform plugin

Plugin for [@diplodoc/transform](https://github.com/diplodoc-platform/transform) package.

Options:

- `runtimeJsPath` - name on runtime script which will be exposed in results `script` section.


  Default: `_assets/tabs-extension.js`


- `runtimeCssPath` - name on runtime css file which will be exposed in results `style` section.


  (Default: `_assets/tabs-extension.css`)


- `bundle` - boolean flag to enable/disable copying of bundled runtime to target directory.


  Where target directore is `/`


  Default: `true`


- `containerClasses` - additional classes which will be added to tab's container node. It allows to customize the tabs view.


  Example: `my-own-class and-other-class`


  Default: `undefined`


## API

### Syntax

You can synchronize the opening of tabs between different tabs groups on the page. To do this, you just need to add optional property `group=` in `list tab` command. The active tabs with the same keys in one tabs group will be synchronized.

Example:

```

{% list tabs group=group_1 %}

- Tab 1

- Tab 2

- Tab 3

{% endlist %}

{% list tabs group=group_1 %}

- Tab 1

- Tab 2

- Tab 3

{% endlist %}

```

Additionally, you can use different render mosed using a contruction

```

{% list tabs  %}

  - Tab 1

    Text 1.

    * You can use list

    * And **other** features.

  - Tab 2

    Text 2.

{% endlist %}

```

The keys for the tabs are generated automatically. They are based on the tab's names using the github anchors style.

You can set your own keys for tabs with this statement:

```

{% list tabs group=group_1 %}

- Tab 1 {#my-tab-1}

- Tab 2 {#my-tab-2}

{% endlist %}

```

## React hook for smart control

You can use the React hook to handle active tab changing or to select opened tab programmatically.

```TypeScript

import React, { useEffect } from 'react'

import {UseDiplodocTabsCallback, useDiplodocTabs, Tab} from '@diplodoc/tabs-extension/react';

export const App: React.FC = () => {

    const selectTabHandler = useCallback(

        (tab: Tab, currentTabId?: string) => {

            const {group, key} = tab;

            // Group could be empty

            if (group) {

                // ...

            }

        },

        [],

    );

    const {selectTab, selectTabById} = useDiplodocTabs(selectTabHandler);

    useEffect(() => {

        selectTab({ group: 'group_1', key: 'my-key' });

        // selectTabById('my-key-2');

    }, [selectTab, selectTabById]);

}

```