carousel Shortcode

carousel shortcode allows you to create Bissetii compatible Carousel HTML codes when Bissetii is used as Hugo Theme. Carousel codes are usually long and thick so this shortcode is created to ease some of the coding burden while deploying to various outputs like Vanilla HTML and AMP HTML simultenously.

Example usage:

1
2
{{< carousel "horizontal-slide"
	"bissetii.data.carousels.picture-gallery" >}}

This shortcode is available starting from v1.12.1.

Heads-Up

While the shortcode is useful, it breaks the Markdown syntax conventions due to Hugo specific shortcode feature. Therefore, when using other Markdown renderer, these shortcodes would be rendered as text instead of HTML code fragments.

Also, be careful and stay safe while using this shortcode. It allows any form of HTML to be embedded into your Markdown page.

There are a number of requirements for using carousel shortcodes. You should create the component listed here starting from top to bottom.

Create Slide Contents

Bissetii has 3 ways to produce the slide contents:

  1. Creating HTML partials (first detection)
  2. Process as Markdown content (second fallback)
  3. Process as HTML content (final fallback)

You can create the slides' content directly inside the data file or as a separate HTML partial files.

Create Dataset in Data File

Due to the complexity of a carousel HTML codes and the fact that Hugo can generate multiple outputs simultenously, it makes a lot of sense to create a data file to hold the data structure. Carousel shortcode recogizes the following TOML pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Label       = "MyGallery"       # Aria-label
Timing      = "5000"            # Slide presentation duration in millisecond

[HTML]                          # Output Format (all uppercase)
Width       = "auto"            # Carousel width as a whole
Height      = "500px"           # Carousel height
Layout      = "responsive"      # Carousel styling layout
Autoplay    = true              # Carousel autoplay flag (true / false)

[AMP]
Width       = "1200px"
Height      = "500px"
Layout      = "responsive"
Autoplay    = true


[slides.1]                      # arrange slides in a numbering position array
HTML = "path/to/slide1.html"                    # HTML content
AMPHTML = "part/to/slide1.amp.html"             # AMP content


[slides.2]
HTML = """
### This can be a markdown.
Yes, it can be markdown.
"""
AMPHTML = """
### This can be a markdown.
Yes, it can be markdown.
"""


[slides.3]
HTML = """
<h3>This can also be HTML</h3>
<p>Yes, you can use HTML here</p>
"""
AMPHTML = """
<h3>This can also be HTML</h3>
<p>Yes, you can use HTML here</p>
"""

You may repeat the slide dataset as much as you want to increase the carousel slides. As shown above, the example carousel has 3 slides.

Add Required Dependencies

You need to add carousel into your [modules] - extension list. Depending on output format (e.g. AMP), this is a required step. Example:

1
2
3
4
5
6
7
8
9
...

[modules]
extensions = [
	...,
	"carousel",
]

...

Shortcode Parameter

{{< carousel "<type>" "<dataPath>" >}}

carousel shortcode only takes in 2 inputs:

  1. type - the type of carousel.
  2. dataPath - the data path for the dataset in the data path.

type parameter

The first type parameter is a reserved parameter mainly to facilitate various kinds of carousels in the future. To see all types of carousel, please visit: Carousel Component .

dataPath parameter

The second dataPath parameter is a Pathing.Name combination to select a dataset from a given data file inside data/ directory. It goes by the format of relative.path.to.file, combining filepath and dataset name.

For example:

Stored File:  data/subdirectory/myCarousel.toml
dataPath   :       subdirectory.myCarousel

The dataPath should be subdirectory.myCarousel.

Example Usage

Since this is a HTML renderer in Markdown file, you want to call in the shortcode using the < symbol instead of %. The brackets are as follow:

1
2
3
4
5
6
7
# This is Markdown Heading
Your normal text here.

{{< carousel "horizontal-slide"
	"bissetii.data.carousels.picture-gallery" >}}

## Back to Markdown

Depending on which output (e.g. AMP or Vanilla) HTML you’re viewing, this will render the output as:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
<h1>This is Markdown Heading</h1>
<section class="Carousel"
	aria-label="MyGallery"
	style="
		min-height:500px;
		height:500px;
		min-width:auto;
		width:auto;">
	<ol class="Carousel-viewport">
		<li id="mygallery-slide-1">
			<article><blockquote>
<p>Slide 1</p>
</blockquote>
</article>
			<nav>
				<a class="Carousel-previous"
					href="#mygallery-slide-3">mygallery-slide-3</a>
				<a class="Carousel-next"
					href="#mygallery-slide-2">mygallery-slide-2</a>
			</nav>
		</li>
		<li id="mygallery-slide-2">
			<article><blockquote>
<p>Slide 2</p>
</blockquote>
</article>
			<nav>
				<a class="Carousel-previous"
					href="#mygallery-slide-1">mygallery-slide-1</a>
				<a class="Carousel-next"
					href="#mygallery-slide-3">mygallery-slide-3</a>
			</nav>
		</li>
		<li id="mygallery-slide-3">
			<article><blockquote>
<p>Slide 3</p>
</blockquote>
</article>
			<nav>
				<a class="Carousel-previous"
					href="#mygallery-slide-2">mygallery-slide-2</a>
				<a class="Carousel-next"
					href="#mygallery-slide-3">mygallery-slide-3</a>
			</nav>
		</li>
	</ol>
<nav class="Carousel-nav-panel"><ol>
	<li><a href="#mygallery-slide-1">mygallery-slide-1</a></li>
	<li><a href="#mygallery-slide-2">mygallery-slide-2</a></li>
	<li><a href="#mygallery-slide-3">mygallery-slide-3</a></li>
</ol></nav>
</section>

<h2>Back to Markdown></h2>

Epilogue

That’s all for carousel shortcode. If you have any question, please feel free to raise your query in our Issues Section.