Docsy Shortcodes

Rather than writing all your site pages from scratch, Hugo lets you define and use shortcodes. These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo’s built-in shortcodes, Docsy provides some shortcodes of its own to help you build your pages.

Shortcode blocks

The theme comes with a set of custom Page Block shortcodes that can be used to compose landing pages, about pages, and similar.

These blocks share some common parameters:

height

A pre-defined height of the block container. One of min, med, max, full, or auto. Setting it to full will fill the Viewport Height, which can be useful for landing pages.

color

The block will be assigned a color from the theme palette if not provided, but you can set your own if needed. You can use all of Bootstrap’s color names, theme color names or a grayscale shade. Some examples would be primary, white, dark, warning, light, success, 300, blue, orange. This will become the background color of the block, but text colors will adapt to get proper contrast.

blocks/cover

The blocks/cover shortcode creates a landing page type of block that fills the top of the page.

{{< blocks/cover title="Welcome!" image_anchor="center" height="full" color="primary" >}}
<div class="mx-auto">
	<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
		Learn More <i class="fas fa-arrow-alt-circle-right ml-2"></i>
	</a>
	<a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://example.org">
		Download <i class="fab fa-github ml-2 "></i>
	</a>
	<p class="lead mt-5">This program is now available in <a href="#">AppStore!</a></p>
	<div class="mx-auto mt-5">
		{{< blocks/link-down color="info" >}}
	</div>
</div>
{{< /blocks/cover >}}

Note that the relevant shortcode parameters above will have sensible defaults, but is included here for completeness.

To set the background image, place an image with the word “background” in the name in the page’s Page Bundle. For example, in our the example site the background image in the home page’s cover block is featured-background.jpg, in the same directory.

For available icons, see Font Awesome.

blocks/lead

The blocks/lead block shortcode is a simple lead/title block with centred text and an arrow down pointing to the next section.

{{% blocks/lead color="dark" %}}
TechOS is the OS of the future. 

Runs on **bare metal** in the **cloud**!
{{% /blocks/lead %}}

blocks/section

The blocks/section shortcode is meant as a general-purpose content container. It comes in two “flavors”, one for general content and one with styling more suitable for wrapping a horizontal row of feature sections.

The example below shows a section wrapping 3 feature sections.

{{< blocks/section color="dark" >}}
{{% blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" %}}
The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
Please follow this space for updates!
{{% /blocks/feature %}}
{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}
{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/GoHugoIO" %}}
For announcement of latest features etc.
{{% /blocks/feature %}}
{{< /blocks/section >}}

blocks/feature

{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
{{% /blocks/feature %}}

blocks/link-down

The blocks/link-down shortcode creates a navigation link down to the next section. It’s meant to be used in combination with the other blocks shortcodes.

<div class="mx-auto mt-5">
	{{< blocks/link-down color="info" >}}
</div>

Shortcode helpers

alert

The alert shortcode creates an alert block that can be used to display notices or warnings.

{{% alert title="Warning" color="warning" %}}
This is a warning.
{{% /alert %}}

Renders to:

pageinfo

The pageinfo shortcode creates a text box that you can use to add banner information for a page: for example, letting users know that the page contains placeholder content, that the content is deprecated, or that it documents a beta feature.

{{% pageinfo color="primary" %}}
This is placeholder content.
{{% /pageinfo %}}

Renders to:

imgproc

The imgproc shortcode finds an image in the current Page Bundle and scales it given a set of processing instructions.

{{< imgproc spruce Fill "400x450" >}}
Norway Spruce Picea abies shoot with foliage buds.
{{< /imgproc >}}

Norway Spruce Picea abies shoot with foliage buds.
Photo: Bjørn Erik Pedersen / CC-BY-SA

The example above has also a byline with photo attribution added. When using illustrations with a free license from WikiMedia and similar, you will in most situations need a way to attribute the author or licensor. You can add metadata to your page resources in the page front matter. The byline param is used by convention in this theme:

resources:
- src: "**spruce*.jpg"
  params:
    byline: "Photo: Bjørn Erik Pedersen / CC-BY-SA"

swaggerui

The swaggerui shortcode can be placed anywhere inside a page with the swagger layout; it renders Swagger UI using any OpenAPI YAML or JSON file as source. This can be hosted anywhere you like, for example in your site’s root /static folder.

---
title: "Pet Store API"
type: swagger
weight: 1
description: Reference for the Pet Store API
---

{{< swaggerui src="/openapi/petstore.yaml" >}}

You can customize Swagger UI’s look and feel by overriding Swagger’s CSS or by editing and compiling a Swagger UI dist yourself and replace themes/docsy/static/css/swagger-ui.css.

iframe

With this shortcode you can embed external content into a Docsy page as an inline frame (iframe) - see: https://www.w3schools.com/tags/tag_iframe.asp

Tabbed panes

Sometimes it’s very useful to have tabbed panes when authoring content. One common use-case is to show multiple syntax highlighted code blocks that showcase the same problem, and how to solve it in different programming languages. As an example, the table below shows the language-specific variants of the famous Hello world! program one usually writes first when learning a new programming language from scratch:

• C
• C++
• Go
• Java
• Kotlin
• Lua
• PHP
• Python
• Ruby
• Scala

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

#include <iostream>

int main()
{
  std::cout << "Hello World!" << std::endl;
}

package main
import "fmt"
func main() {
  fmt.Printf("Hello World!\n")
}

class HelloWorld {
  static public void main( String args[] ) {
    System.out.println( "Hello World!" );
  }
}

fun main(args : Array<String>) {
    println("Hello, world!")
}

print "Hello world"

<?php
echo 'Hello World!';
?>

print("Hello World!")

puts "Hello World!"

object HelloWorld extends App {
  println("Hello world!")
}

The Docsy template provides two shortcodes tabpane and tab that let you easily create tabbed panes. To see how to use them, have a look at the following code block, which renders to a pane with three tabs:

{{< tabpane >}}
  {{< tab header="English" >}}
    Welcome!
  {{< /tab >}}
  {{< tab header="German" >}}
    Herzlich willkommen!
  {{< /tab >}}
  {{< tab header="Swahili" >}}
    Karibu sana!
  {{< /tab >}}
{{< /tabpane >}}

This code translates to the tabbed pane below, showing a Welcome! greeting in English, German or Swahili:

• English
• German
• Swahili

Welcome!

Herzlich willkommen!

Karibu sana!

Shortcode details

Tabbed panes are implemented using two shortcodes:

• The tabpane shortcode, which is the container element for the tabs. This shortcode can optionally hold the named parameters lang and/or highlight. The values of these optional parameters are passed on as second LANG and third OPTIONS arguments to Hugo’s built-in highlight function which is used to render the code blocks of the individual tabs. In case the header text of the tab equals the language used in the tab’s code block (as in the first tabbed pane example above), you may specify langEqualsHeader=true in the surrounding tabpane shortcode. Then, the header text of the individual tab is automatically set as language parameter of the respective tab.
• The various tab shortcodes which actually represent the tabs you would like to show. We recommend specifying the named parameter header for each text in order to set the header text of each tab. If needed, you can additionally specify the named parameters lang and highlight for each tab. This allows you to overwrite the settings given in the parent tabpane shortcode. If the language is neither specified in the tabpane nor in the tabshortcode, it defaults to Hugo’s site variable .Site.Language.Lang.

Card panes

When authoring content, it’s sometimes very useful to put similar text blocks or code fragments on card like elements, which can be optionally presented side by side. Let’s showcase this feature with the following sample card group which shows the first four Presidents of the United States:

George Washington

*1732     †1799

President: 1789 – 1797

John Adams

* 1735     † 1826

President: 1797 – 1801

Thomas Jefferson

* 1743     † 1826

President: 1801 – 1809

James Madison

* 1751     † 1836

President: 1809 – 1817

Docsy supports creating such card panes via different shortcodes:

• The cardpane shortcode which is the container element for the various cards to be presented.
• The card shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A card shortcode can hold text, images or any other arbitrary kind of markdown or HTML markup as content. If your content is programming code, you are advised to make use of the card-code shortcode, a special kind of card with code-highlighting and other optional features like line numbers, highlighting of certain lines, ….

Shortcode card (for text, images, …)

As stated above, a card is coded using one of the shortcode card or card-code. If your content is any kind of text other than programming code, use the universal cardshortcode. The following code sample demonstrates how to code a card element:

{{< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono"
          footer="![SignatureJohnLennon](https://server.tld/…/signature.png \"Signature John Lennon\")">>}}
Imagine there's no heaven, It's easy if you try<br/>
No hell below us, above us only sky<br/>
Imagine all the people living for today…

…
{{< /card >}}

This code translates to the left card shown below, showing the lyrics of John Lennon’s famous song Imagine. A second explanatory card element to the right indicates and explains the individual components of a card:

Imagine

Artist and songwriter: John Lennon

Co-writer: Yoko Ono

Imagine there’s no heaven, It’s easy if you try
No hell below us, above us only sky
Imagine all the people living for today…

Imagine there’s no countries, it isn’t hard to do
Nothing to kill or die for, and no religion too
Imagine all the people living life in peace…

Imagine no possessions, I wonder if you can
No need for greed or hunger - a brotherhood of man
Imagine all the people sharing all the world…

You may say I’m a dreamer, but I’m not the only one
I hope someday you’ll join us and the world will live as one

Header: specified via named parameter Header

Card title: specified via named parameter title

Card subtitle: specified via named parameter subtitle

Content: inner content of the shortcode, this may be formatted text, images, videos, … . If the extension of your page file equals .md, markdown format is expected, otherwise, your content will be treated as plain HTML.

Footer: specified via named parameter footer

While the main content of the card is taken from the inner markup of the card shortcode, the optional elements footer, header, title, and subtitle are all specified as named parameters of the shortcode.

Shortcode card-code (for programming code)

In case you want to display programming code on your card, a special shortcode card-code is provided for this purpose. The following sample demonstrates how to code a card element with the famous Hello world!application coded in C:

{{< card-code header="**C**" lang="C" >}}
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}
{{< /card-code >}}

This code translates to the card shown below:

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

The card-code shortcode can optionally hold the named parameters lang and/or highlight. The values of these optional parameters are passed on as second LANG and third OPTIONS arguments to Hugo’s built-in highlight function which is used to render the code block presented on the card.

Card groups

Displaying two ore more cards side by side can be easily achieved by putting them between the opening and closing elements of a cardpane shortcode. The general markup of a card group resembles closely the markup of a tabbed pane:

{{< cardpane >}}
  {{< card header="Header card 1" >}}
    Content card 1
  {{< /card >}}
  {{< card header="Header card 2" >}}
    Content card 2
  {{< /card >}}
  {{< card header="Header card 3" >}}
    Content card 3
  {{< /card >}}
{{< /cardpane >}}

Contrary to tabs, cards are presented side by side, however. This is especially useful it you want to compare different programming techniques (traditional vs. modern) on two cards, like demonstrated in the example above:

File[] hiddenFiles = new File("directory_name")
  .listFiles(new FileFilter() {
    public boolean accept(File file) {
      return file.isHidden();
    }
  });

File[] hiddenFiles = new File("directory_name")
  .listFiles(File::isHidden);

Include external files

Sometimes there’s content that is relevant for several documents, or that is maintained in a file that is not necessarily a document. For situations like these, the readfile shortcode allows you to import the contents of an external file into a document.

Reuse documentation

In case you want to reuse some content in several documents, you can write said content in a separate file and include it wherever you need it.

For example, suppose you have a file called installation.md with the following contents:

## Installation

1.  Download the installation files.

1.  Run the installation script
    
    `sudo sh install.sh`

1.  Test that your installation was successfully completed.

You can import this section into another document:

The following section explains how to install the database:

{{% readfile "installation.md" %}}

This will be rendered as if the instructions were in the parent document:

The following section explains how to install the database:

Installation

1. Download the installation files.

2. Run the installation script

   sudo sh install.sh

3. Test that your installation was successfully completed.

The parameter is the relative path to the file. Only relative paths under the parent file’s working directory are supported.

For files outside the current working directory you can use an absolute path starting with /. The root directory is the /content folder.

Include code files

Suppose you have an includes folder containing several code samples you want to use as part of your documentation. You can use readfile with some additional parameters:

To create a new pipeline, follow the next steps:

1.  Create a configuration file `config.yaml`:

    {{< readfile file="includes/config.yaml" code="true" lang="yaml" >}}

1.  Apply the file to your cluster `kubectl apply config.yaml`

This code automatically reads the content of import/config.yaml and inserts it into the document. The rendered text looks like this:

To create a new pipeline, follow the next steps:

1. Create a configuration file config.yaml:

   apiVersion: tekton.dev/v1beta1
   kind: Task
   metadata:
     name: hello
   spec:
     steps:
       - name: echo
         image: alpine
         script: |
           #!/bin/sh
           echo "Hello World"          
   

2. Apply the file to your cluster kubectl apply config.yaml

The “file” parameter is the relative path to the file. Only relative paths under the parent file’s working directory are supported.

For files outside the current working directory you can use an absolute path starting with /. The root directory is the /content folder.