K-State CS Hugo Theme

This is an adaptation of Hugo Relearn Theme that has been customized for use by K-State Computer Science to build online textbooks. It contains some features that are specifically designed for our use case, but they may be useful to others.

More information can be found on GitHub

Some features developed for this theme:

Fonts and layouts customized to match K-State’s websites and color scheme, as well as Instructure Canvas.
Each page generates an embeddable version that strips menus, headers and footers (add /embed.html to almost any URL). This is meant to be embedded in an iFrame within another page, such as an HTML wiki page in Canvas.
- By doing so, we can embed course content in Canvas while editing it via Hugo, taking advantage of tools such as git for versioning. In addition, by updating the source website, all versions of the course in Canvas are updated immediately.
Each page also generates a teleprompter version to allow creation of course videos (add /tele.html to almost any URL). Many pages are used as a video script for multi-modal learning.
- The teleprompter pages include auto-scroll capabilities. It is compatible with an IKAN Teleprompter Remote, but can be controlled using the number keys or easily customized. See /static/js/tele-scroll.js for details.

Chapter 0

Basic Content

The Basics of this Template

Chapter 0

Section

A subsection example.

Simple Page

This is a simple Hugo page. It supports all Markdown formatting.

Simple Page

This is a simple Hugo page. It supports all Markdown formatting.

Reveal.js Example

Resources

Slides

Info

This theme includes a special template for developing presentations using Reveal.js.

To do this, there are a few steps:

Create an html file with the .html file extension
Use the following frontmatter:

---
type: "reveal"
hidden: true
---

In that file, write the contents of the Reveal.js presentation. Each slide should be contained in a <section> tag.

The contents of each slide is simply HTML, and pretty much any standard HTML tag can be used. Custom CSS can also be added via the style attribute on individual elements.

When editing the slides, it is recommended to manually update the highlighting used by your preferred editor to HTML. This is relatively simple to do in Atom or Notepad++.

Examples

Below are some example slides to show the formatting that can be done in this presentation. Each slide is present in the Slides page.

Simple Title Slide

<section>
	<h2>Welcome to the</h2>
	<img class="plain stretch" src="/images/core-logo-on-white.svg">
	<h2>trial course!</h2>
</section>

The image uses the stretch class, which is detailed below.

Slide with Bulleted List

<section>
	<h2>Undergrad Certificate</h2>
	<ul style="font-size: 65px">
		<li><i><b>CC 110</b> - Introduction to Computing (Coming Soon)</i></li>
		<li><b>CC 210</b> - Fundamental Computer Programming Concepts</li>
		<li><b>CC 310</b> - Data Structures & Algorithms I</li>
		<li><b>CC 315</b> - Data Structures & Algorithms II</li>
		<li><b>CC 410</b> - Advanced Programming</li>
	</ul>
</section>

This slide uses a custom style applied to the ul element, to reduce the text size of all list items a bit

Images with Sources

<section>
	<h2>Programming</h2>
	<img class="plain" style="height: 40%;" src="/images/java_logo_wiki.svg">
	<img class="plain stretch" src="/images/python_logo_wiki.svg">
	<p class="imagecredit">Image Credit: <a href="https://commons.wikimedia.org/w/index.php?title=File:Python_logo_and_wordmark.svg&oldid=164598673">Wikimedia</a> <a href="https://en.wikipedia.org/w/index.php?title=File:Java_programming_language_logo.svg&oldid=872323259">Commons</a></p>
</section>

The stretch class applied to the image will stretch that image to fill all available space in the slide. Only one image may have the stretch class applied on any given slide. So, in this case, the height of one image is set manually to 40%, and the other is allowed to stretch and fill the remaining part of the slide.

The plain class simply removes any adornment (borders, shading, etc.) from the image. I prefer them that way.

There is a custom imagecredit class defined in the CSS that can be used to give credit for images in a way that is unobtrusive to the presentation.

Math (via MathJax)

<section>
	<div style="font-size: 2em">
	$$x^2 + 2x + 5 = 0$$
	</div>
</section>

Slides can also include inline LaTeX math, using MathJax.

Tables

<section>
	<table class="reveal">
		<tr>
			<th>A</th>
			<th>B</th>
			<th>A &#8897; B</th>
		</tr>
		<tr>
			<td>F</td>
			<td>F</td>
			<td>F</td>
		</tr>
		<tr>
			<td>F</td>
			<td>T</td>
			<td>T</td>
		</tr>
		<tr>
			<td>T</td>
			<td>F</td>
			<td>T</td>
		</tr>
		<tr>
			<td>T</td>
			<td>T</td>
			<td>T</td>
		</tr>
  </table>
</section>

Tables should use the special reveal class for formatting.

Code

Code can be included in slides using the <pre> and <code> tags. Code highlighting is controlled by the class attached to the <code> tag (or inferred from context), while the size of the text is best controlled by the style in the <pre> tag. The stretch class can also be used to ensure a code block fills the available space, avoiding the need for scrollbars.

Java

<section>
  <pre class="stretch" style="font-size: 0.5em;"><code class="java">// Load required classes
import java.util.Scanner;
import java.io.File;

public class Conditionals{
  public static void main(String[] args) throws Exception{
    // Scanner variable
    Scanner reader;

    // If an argument is present, we are reading from a file
    // specified in args[0]
    if(args.length > 0){
      reader = new Scanner(new File(args[0]));
    // If no argument, read from System.in
    }else{
      reader = new Scanner(System.in);
    }

    int x = reader.nextInt();
    System.out.println(x);
  }
}</code></pre>
</section>

Python

<section>
  <pre class="stretch" style="font-size: 0.7em;"><code class="python"># Load required modules
import sys

# If an argument is present,
# we are reading from a file
# specified in sys.argv[1]
if len(sys.argv) > 1:
  reader = open(sys.argv[1])
# If no argument, read from stdin
else:
  reader = sys.stdin

x = int(reader.readline())
print(x)</code></pre>
</section>

Multiple Divs

The slides can also include multiple <div> tags to separate content.

<section>
  <div style="float: right; width: 70%">
    <pre class="stretch" style="font-size: .37em"><code class="java">// Load required classes
import java.util.Scanner;
import java.io.File;

public class Example{
  public static void main(String[] args){
    // Scanner variable
    <mark>Scanner reader;</mark>

    // If an argument is present,
    // we are reading from a file
    // specified in args[0]
    <mark>if(args.length > 0){
      reader = new Scanner(new File(args[0]));</mark>
    // If no argument, read from System.in
    <mark>}else{
      reader = new Scanner(System.in);
    }</mark>

    /* -=-=-=-=- MORE CODE GOES HERE -=-=-=-=- */
  }
}</code></pre>
  </div>
  <div style="width: 30%">
  <p style="font-size: .7em">Write a program that accepts a positive integer that represents a year...</p>
  </div>
</section>

The example below includes a <div> of text that is shown to the left, and a <div> of code shown to the right. We use the attribute style="float: right; width: 70%" applied to the first div to move it to the right and give it a fixed width. The second div should also have a fixed width attached to it.

Note that the stretch class applied to the code in the rightmost div only stretches the code within that div. Pretty handy!

Marking Text

We can mark (highlight) text in our slides using the <mark> tag:

<section>
  <div style="float: right; width: 70%">
    <pre class="stretch" style="font-size: .5em"><code class="java">
    </code></pre>
  </div>
  <div style="width: 30%">
  <p style="font-size: .7em">Write a program that accepts a positive <mark>integer that represents a year</mark>...</p>
  </div>
</section>

<section>
  <div style="float: right; width: 70%">
    <pre class="stretch" style="font-size: .5em"><code class="java"><mark>int year = reader.nextInt();</mark>
    </code></pre>
  </div>
  <div style="width: 30%">
  <p style="font-size: .7em">Write a program that accepts a positive <mark>integer that represents a year</mark>...</p>
  </div>
</section>

<section>
  <div style="float: right; width: 70%">
    <pre class="stretch" style="font-size: .5em"><code class="java">int year = reader.nextInt();
    </code></pre>
  </div>
  <div style="width: 30%">
  <p style="font-size: .7em">Write a program that accepts a <mark>positive integer</mark> that represents a year...</p>
  </div>
</section>

The three slides listed above each mark a different part of the text and code. This allows us to incrementally build a program by marking parts of the code as we discuss them.

Chapter 1

Advanced Structures

More Complex File Patterns

Simple Page

This is a simple Hugo page. It supports all Markdown formatting.

Leaf Page

This is a leaf bundle. It is a folder with a file named index.md without an underscore. Other files under this folder are accessible to the page, but other HTML/Markdown pages will not be rendered in the output.

Branch Bundle

This is a branch bundle. It is a folder with a file named _index.md including the underscore. Other files under this folder are rendered like any other content folder.

Rendered

This page is included in the output since it is a branch bundle.

Chapter 2

Structural Patterns

Patterns we use for various things

Previous Versions

This is a pattern for managing previous versions of a page. It uses a branch bundle combined with a hidden folder and the children shortcode.

This page would be the current version of the page.

Click this link to access the Previous Versions

Video Content

This is a pattern for managing video content related to a page. It uses a branch bundle combined with a hidden folder.

This page would be the content of the page itself, complete with the YouTube embed.

Click this link to access the Video Materials

Chapter 3

Basic Markdown

Basic Markdown Structures

Frontmatter

Note

This content details additions to the the original version in the Hugo Relearn Theme Documentation.

Front Matter configuration

Instead of using LastModifierDisplayName and LastModifierEmail, this site is instead configured to use Hugo Git Info Variables to pull that content from the git repository storing this website.

This template adds one new Frontmatter option:

ordinal: this is used by the new chapter archetype to override the weight as the chapter’s index.

There are many other items that can be added. See Hugo Frontmatter for details. The Hugo Theme Relearn documentation also has an exhaustive list of frontmatter options for the base theme.

Reveal.js Slides

For Reveal.js slides, the frontmatter is as follows:

---
type: "reveal"
hidden: true
---

These items are used:

type: this tells Hugo to render this page as a Reveal.js page, which will use a different template
hidden: this will remove this item from the menu on the left. This can be added to any page.

Note

Yes, I realize that most pages are using the YAML format for frontmatter (as indicated by the --- surrounding the block as described in the Hugo documentation), but the chapter pages are using TOML (surrounded by +++ instead). I did this simply because the template pages were set that way, but not for any particular reason.

Text

Note

This page is originally a shameful copy of the great Grav original page.

The current version is borrowed from the Hugo Relearn Theme Documentation. Since the CSS on this site is slightly different, below gives a good overview of the formatting as rendered by this theme.

Let’s face it: Writing content for the web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.

Markdown is a better way to write HTML, without all the complexities and ugliness that usually accompanies it.

Some of the key benefits are:

Markdown is simple to learn, with minimal extra characters so it’s also quicker to write content.
Less chance of errors when writing in Markdown.
Produces valid HTML output.
Keeps the content and the visual display separate, so you cannot mess up the look of your site.
Write in any text editor or Markdown application you like.
Markdown is a joy to use!

John Gruber, the author of Markdown, puts it like this:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. John Gruber

Tip

Bookmark this page for easy future reference!

Standard and Extensions

If not otherwise noted, the showed examples adhere to the Commonmark standard. In addition the theme supports the following extensions:

GFM Extension on top of standard Markdown adhering to GitHub Flavored Markdown.
PHP Extension on top of standard Markdown adhering to PHP Markdown.
Pants Extension by John Gruber adhering to SmartyPants.
Relearn Extension specific to this theme.
HTML If the usage of HTML is allowed in your hugo.toml the theme supports styling for further elements not accessible using Markdown alone.

Paragraphs

In Markdown your content usually spans the whole available document width. This is called a block. Blocks are always separated by whitespace to their adjacent blocks in the resulting document.

Any text not starting with a special sign is written as normal, plain text paragraph block and must be separated to its adjacent blocks by empty lines.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Result

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Headings

A good idea is to structure your content using headings and subheadings. HTML-headings from h1 through h6 are constructed with a # for each level.

In Hugo you usually don’t use h1 as this is generated by your theme and you should only have one such element in a document.

# h1 Heading

## h2 Heading

### h3 Heading

#### h4 Heading

##### h5 Heading

###### h6 Heading

Result

h1 Heading

h2 Heading

h3 Heading

h4 Heading

h5 Heading

h6 Heading

Horizontal Rules

To further structure your content you can add horizontal rules. They create a “thematic break” between paragraph blocks. In Markdown, you can create it with three consecutive dashes ---.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

---

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Result

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Text Markers

Bold

You can show importance of a snippet of text with a heavier font-weight by enclosing it with two asterisks **.

I am rendered with **bold text**

Result

I am rendered with bold text

Italics

You can emphasize a snippet of text with italics by enclosing it with underscores _.

I am rendered with _italicized text_

Result

I am rendered with italicized text

Strikethrough

GFM You can do strikethroughs by enclosing text with two tildes ~~.

~~Strike through this text~~

Result

~~Strike through this text~~

Marked Text

HTML You can mark text in the predefined accent color of your stylesheet.

<mark>Parts</mark> of this text <mark>are marked!</mark>

Result

Parts of this text are marked!

Special Typesetting

Text Substitution

Pants You can combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code.

Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.

Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.

Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.

Three consecutive dots `...` are replaced by an ellipsis **...** entity.

Result

Double quotes " and single quotes ' of enclosed text are replaced by “double curly quotes” and ‘single curly quotes’.

Double dashes -- and triple dashes --- are replaced by en-dash – and em-dash — entities.

Double arrows pointing left << or right >> are replaced by arrow « and » entities.

Three consecutive dots ... are replaced by an ellipsis … entity.

Keyboard Shortcuts

HTML You can use the <kbd> element to style keyboard shortcuts.

Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> to end your shift early.

Result

Press STRG ALT DEL to end your shift early.

Sub and Super Script

HTML You can also use the <sub> and <sup> elements. For more complex stuff or if your configuration does not allow HTML, you can use the math shortcode.

How many liters H<sub>2</sub>O fit into 1dm<sup>3</sup>?

Result

How many liters H₂O fit into 1dm³?

Lists

Unordered

You can write a list of items in which the order of the items does not explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

You may use any of -, * or + to denote bullets for each list item but should not switch between those symbols inside one whole list.

- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
  - Vestibulum laoreet porttitor sem
  - Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
  - Phasellus iaculis neque
  - Purus sodales ultricies
- Faucibus porta lacus fringilla vel

Result

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
Faucibus porta lacus fringilla vel

Ordered

You can create a list of items in which the order of items does explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

Markdown will automatically number each of your items consecutively. This means, the order number you are providing is irrelevant.

1. Lorem ipsum dolor sit amet
3. Consectetur adipiscing elit
    1. Integer molestie lorem at massa
    7. Facilisis in pretium nisl aliquet
99. Nulla volutpat aliquam velit
    1. Faucibus porta lacus fringilla vel
    1. Aenean sit amet erat nunc
17. Eget porttitor lorem

Result

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
1. Integer molestie lorem at massa
2. Facilisis in pretium nisl aliquet
Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
2. Aenean sit amet erat nunc
Eget porttitor lorem

Tasks

GFM You can add task lists resulting in checked or unchecked non-clickable items

- [x] Basic Test
- [ ] More Tests
  - [x] View
  - [x] Hear
  - [ ] Smell

Definitions

PHP Definition lists are made of terms and definitions of these terms, much like in a dictionary.

A definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term. You can also associate more than one term to a definition.

If you add empty lines around the definition terms, additional vertical space will be generated. Also multiple paragraphs are possible

Apple
: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
: An American computer company.

Orange
: The fruit of an evergreen tree of the genus Citrus.

  You can make juice out of it.
: A telecommunication company.

  You can't make juice out of it.

Result

Apple: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.; An American computer company.
Orange: The fruit of an evergreen tree of the genus Citrus.
You can make juice out of it.; A telecommunication company.
You can’t make juice out of it.

Code

Inline Code

Inline snippets of code can be wrapped with backticks `.

In this example, `<div></div>` is marked as code.

Result

In this example, <div></div> is marked as code.

Indented Code Block

A simple code block can be generated by indenting several lines of code by at least two spaces.

Be impressed by my advanced code:

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code

Result

Be impressed by my advanced code:

// Some comments
line 1 of code
line 2 of code
line 3 of code

Fenced Code Block

If you want to gain more control of your code block you can enclose your code by at least three backticks ``` a so called fence.

GFM You can also add a language specifier directly after the opening fence, ```js, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML.

See Code Highlighting for additional documentation.

```js
{
    name: "Claus",
    surname: "Santa",
    profession: "courier",
    age: 666,
    address: {
        city: "North Pole",
        postalCode: 1,
        country: "Arctic"
    },
    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};
```

Result

{
    name: "Claus",
    surname: "Santa",
    profession: "courier",
    age: 666,
    address: {
        city: "North Pole",
        postalCode: 1,
        country: "Arctic"
    },
    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};

Tables

GFM You can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.

| Option | Description |
|--------|-------------|
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

Result

Option	Description
data	path to data files to supply the data that will be passed into templates.
engine	engine to be used for processing templates. Handlebars is the default.
ext	extension to be used for dest files.

Aligned Columns

Adding a colon on the left and/or right side of the dashes below any heading will align the text for that column accordingly.

| Option | Number | Description |
|-------:|:------:|:------------|
| data   | 1      | path to data files to supply the data that will be passed into templates. |
| engine | 2      | engine to be used for processing templates. Handlebars is the default. |
| ext    | 3      | extension to be used for dest files. |

Result

Option	Number	Description
data	1	path to data files to supply the data that will be passed into templates.
engine	2	engine to be used for processing templates. Handlebars is the default.
ext	3	extension to be used for dest files.

Blockquotes

For quoting blocks of content from another source within your document add > before any text you want to quote.

Blockquotes can also be nested.

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.

Result

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.

Links

Autolink

GFM Absolute URLs will automatically be converted into a link.

This is a link to https://example.com.

Result

This is a link to https://example.com.

Basic Link

You can explicitly define links in case you want to use non-absolute URLs or want to give different text.

[Assemble](http://assemble.io)

Result

Assemble

For even further information, you can add an additional text, displayed in a tooltip on hovering over the link.

[Upstage](https://github.com/upstage/ "Visit Upstage!")

Result

Upstage

Link References

Links can be simplyfied for recurring reuse by using a reference ID to later define the URL location. This simplyfies writing if you want to use a link more than once in a document.

[Example][somelinkID]

[somelinkID]: https://example.com "Go to example domain"

Result

Example

Footnotes

PHP Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes.

Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.

Footnotes can contain block elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items, just indent the following paragraphs by four spaces in the footnote definition.

That's some text with a footnote[^1]

[^1]: And that's the footnote.

That's some more text with a footnote.[^someid]

[^someid]:
    Anything of interest goes here.

    Blue light glows blue.

Result

That’s some text with a footnote¹

That’s some more text with a footnote.²

And that’s the footnote. ↩︎
Anything of interest goes here.
Blue light glows blue. ↩︎

Images

Basic Images

Images have a similar syntax to links but include a preceding exclamation mark.

![Spock](https://octodex.github.com/images/spocktocat.png)

Result

Like links, images can also be given a tooltip.

![Picard](https://octodex.github.com/images/jean-luc-picat.jpg "Jean Luc Picard")

Result

Image References

Images can also be linked by reference ID to later define the URL location. This simplyfies writing if you want to use an image more than once in a document.

![La Forge][laforge]

[laforge]: https://octodex.github.com/images/trekkie.jpg "Geordi La Forge"

Result

Image Effects

Relearn This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. The default behavior is configurable through your hugo.toml or frontmatter parameter.

Resizing

Add query parameter width and/or height to the link image to resize the image. Values are CSS values (default is auto).

![Minion](https://octodex.github.com/images/minion.png?width=20vw)

Result

![Minion](https://octodex.github.com/images/minion.png?height=50px)

Result

![Minion](https://octodex.github.com/images/minion.png?height=50px&width=40vw)

Result

CSS Classes

Add a query parameter classes to the link image to add CSS classes. Add some of the predefined values or even define your own in your CSS.

Shadow

![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=shadow)

Result

Border

![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=border)

Result

Left

![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=left)

Result

Right

![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=right)

Result

Inline

![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=inline)
![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=inline)
![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=inline)
![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=inline)

Result

Combination

![X-tocat](https://octodex.github.com/images/xtocat.jpg?classes=shadow,border,left)

Result

Add the query parameter lightbox=false to the image link to disable the lightbox.

![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)

Result

Homercat

Note

If you want to wrap an image in a link and lightbox=true is your default setting, you have to explicitly disable the lightbox to avoid it to hijacking your link like:

[![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)](https://octodex.github.com/#homercat)

Shortcodes

Note

Documentation on built-in shortcodes can be found on the Hugo Relearn Theme Documentation.

There are also many useful shortcodes built directly into Hugo

This page and its children demonstrate ones unique to this theme as well as ones we use often.

Notice

Updates to the Notice shortcode

Encrypt

Encrypt & Decrypt Page Content (Useful for Model Solutions)

Include

Updates to the Include shortcode

Links

(DEPRECATED) Link Helper Shortcode

No Render

(DEPRECATED) Shortcode to Disable Markdown Rendering

Static

(DEPRECATED) Shortcode to access Static Content

Quizdown

Self-Check Quizzes

Syllabus

Include Default K-State Syllabus Statements

Notice

The notice shortcode has been modified to make the following changes:

The colors for the note and info styles have been swapped to match the earlier template
A special noiframe type has been added, see below.

No Iframe

{{% notice noiframe %}}
A disclaimer that will not be visible on the embedded version of the page
{{% /notice %}}

renders as

Web Only

A disclaimer that will not be visible on the embedded version of the page

That item will not render on the embed version of this page.

Encrypt

A shortcode was created to enable the encryption and decryption of pages. This allows secured content to be posted on the web, with the password shared elsewhere, such as in an LMS. A person with the password can use it to decrypt the page and see the content.

Of course, care must be taken not to commit the secured content in its raw form to a public Git repository. To aid in editing, we recommend including a version of the original content in the encrypted content.

See sjcl.js and ecnrypt.js for details.

Encryption Example

Encrypt

Example File to be Encrypted

Password: testpassword

Sample Text

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus sit amet placerat risus. In hac habitasse platea dictumst. Etiam risus massa, finibus vitae felis non, hendrerit auctor nibh. Morbi ut odio posuere, pharetra metus vitae, venenatis turpis. Nullam interdum imperdiet orci, ut ultrices magna. Donec a odio eu tellus commodo venenatis a nec dolor. Nam dictum auctor enim ut consequat. Phasellus sit amet sapien ipsum. Aenean scelerisque mi orci, ut aliquam eros volutpat id. Proin interdum convallis nunc, vel mollis leo pellentesque interdum.

Donec mollis egestas lacus vitae suscipit. Vestibulum in varius massa. Nam quis velit ut dolor pellentesque molestie vel non massa. Morbi hendrerit consequat mollis. Cras ligula massa, mollis eu urna non, eleifend scelerisque nulla. Mauris vel magna aliquam arcu lobortis sollicitudin in aliquam tortor. Curabitur nec sapien felis. Etiam quis mattis mi. Phasellus leo tortor, rhoncus at viverra at, porta viverra turpis. Ut elementum tortor sit amet ex volutpat pellentesque. Integer posuere enim tortor, eget finibus dolor sodales eleifend. Phasellus at rutrum sapien, in faucibus enim. Praesent vel convallis orci.

Bold

Italics

some code

a longer code block

Source File (for Editing)


### Example File to be Encrypted

**Password:** testpassword

### Sample Text

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus sit amet placerat risus. In hac habitasse platea dictumst. Etiam risus massa, finibus vitae felis non, hendrerit auctor nibh. Morbi ut odio posuere, pharetra metus vitae, venenatis turpis. Nullam interdum imperdiet orci, ut ultrices magna. Donec a odio eu tellus commodo venenatis a nec dolor. Nam dictum auctor enim ut consequat. Phasellus sit amet sapien ipsum. Aenean scelerisque mi orci, ut aliquam eros volutpat id. Proin interdum convallis nunc, vel mollis leo pellentesque interdum.

Donec mollis egestas lacus vitae suscipit. Vestibulum in varius massa. Nam quis velit ut dolor pellentesque molestie vel non massa. Morbi hendrerit consequat mollis. Cras ligula massa, mollis eu urna non, eleifend scelerisque nulla. Mauris vel magna aliquam arcu lobortis sollicitudin in aliquam tortor. Curabitur nec sapien felis. Etiam quis mattis mi. Phasellus leo tortor, rhoncus at viverra at, porta viverra turpis. Ut elementum tortor sit amet ex volutpat pellentesque. Integer posuere enim tortor, eget finibus dolor sodales eleifend. Phasellus at rutrum sapien, in faucibus enim. Praesent vel convallis orci.

**Bold**

_Italics_

`some code`

```
a longer code block
```

Decryption Example

Decrypt

IntcIml2XCI6XCIzOC83eEpudnVXWHd4NkhYV01rSE53PT1cIixcInZcIjoxLFwiaXRlclwiOjEwMDAwLFwia3NcIjoxMjgsXCJ0c1wiOjY0LFwibW9kZVwiOlwiY2NtXCIsXCJhZGF0YVwiOlwiXCIsXCJjaXBoZXJcIjpcImFlc1wiLFwic2FsdFwiOlwiQUVIWHcraU1uQzQ9XCIsXCJjdFwiOlwiOEZweEtkWi8yL3Z6UU9sSWhEMy9acnd5NWs5Tm43RzFlb0UxRlJKU1BlcjFDVTc4Q1QxWGJaWWdrd2Y5Mk43STdCeGxZdzd6UGZJWVk3VGVISDM0OUwvL1FhUjBWRkpUcU5vTHpibVlPWUlOREdldmhla1U5TFBZVWpTUXdkNHVTWHkvSkcyR1hTNnllVk4xTk1KY1JVMGROM09uMjNFTXFYdFFZckFSMDVUcTZMMnNGK1pMZ2pUSGhwODhtcEJ6TGxMZjliTncxZndQTHZGU3lSSy9jczRlZ084dW9naGZLUno0eG8xV3pkMGZHNm1qRkZGMUJpVkpwL3d0dU5SY0t2TDhBNVNDWFZ2dXdvbnlxd3Q2ME1xUVZoWnVlRHhYSEo0ZkpzUzdPUkhNckdPUSs5MUlxMjl2Z3I4UTVPUktuWmtxdlpFNG1PcWoyWTZ6OFZQdHFWSXliK3hxQnVMRU9zSmpjbHV3eGRCMGNVdDlreE1ieGVKOTJyMFMvYXQ3SUhsVUVkV1RBMXRJYmlwbllIMWNLOUhDellPM1Q3OHlac3V1WmJyYVZydjNQK0JIM2xCZmNZWlBib28ySkFqQmQ1b1FrdEMvZjRrMWkzVHJ1cDF3cGtBd0ZQVVlQZVErY1E3dVNxUXhRVjZVVkRRVGNsK2ZacnV4RFdaSUMyTVB5WXhwcEc4a2IrZHd0UlQwUENBL0Z1VkN4aGw2UjJNMEtHTWdQenVJSlBHRnZ6RDU2ck1uaDR0QlNzMU9XdDNxRVVNN1VNR2RCNWkvelVNYWZLNlNIeGVwc1RST0tXcTAvcXVobThqYVVzYmV2bWlFZHVYc1dkTXZDL3p4Wis0QVpFY3c0L2QvWHRJbUMrZDRvUUxEN09TcnpINzB6U1dadk5zb1V5dEVkL2NiZXBKUXVMZjN2S1VISmVGWDFlR3puOHlpU0p1bWROZUJaVHd5dXM2Q0lrSEkvaEZSZURKcTc2aTJranFxRkNBTDlCQi9aMmtWOERSdmE4ODkxK2FsQlVBTEJDemNGTUpWTHZ3amR5LzJ3ZG90MGZZOVkvc0tTcWsrVUZDRVcvUTBNNFlkMGx2eGN1bmE1WkxwOUtNZ0hySFB2cDAySmNUL0VoM0dWRkUxMkpYdWFtY0ZDVktucEU3ckJZdHUwbTZZTzJBVWEvdmEzb21VTzVOU0t5VUhmREh4VTZEQ3phN1Z6NkZ3ei9VRi85QXFxYjVBTU9nTWFWQjZDRUZjbzRkRWp5TWtNQzJpOEcvcGxmOVFJUnN4MjVxek5QWWpIdm5ZYXdRTHhrWjZqUHcrVGNjeWp3R1I3enkzZFZWcDFQVDNDQWovMlVYanc1ZHUwV0xlTTZXTzk1Z3NOdGxOQ2hyT3NJeUFOUmFhbVRsY2xBendoc0hCaUlIaVdpNHdDUmJkUjB4aFdrOFJ3dlYzdmtzUzJqSmtJa2szZ1JLOTNyVUxQM3Y3dVkwcDkrT3JaT1A5S2JIQm50cEtVVVhlUkRqRUNDNHkrWmV2bmZSRzRQcG1uRUdocjdDQ0dhL29kelVnTy9yWlp1QXJWb21LVlNTWlFBdUFrVTdWZUxLTEpWVE16RmZvNE9ZTURaR1RJSjkySjRLQkljM0RIZTFNM3dKMFpWOUpIKzQyb1VHNnJBOHNaNGlSSFJLeEVUNndTb1dhdGxLYzA4bUMxeVc5MkovcFpaeS9wZDE4Mk1zM0dzTmgxaEg1K0xrL2tQT0dDN1VNSFc1R2ZJLzJiNjZBcUZnVyt4T1VjK0p5bWtSRTVsWjd6eUhsd0M3Q3MwcC9TS0ttMUZ1MTBHTm1yWmZ5cDlHUnROR0Z0T2xBQ084WG1Fem5zZHV4eHNJbHZPcENDWXZoREx2Y3Z2dVJ6OFBDU1Bpazh4R2lKeVNWU0c3ellWNEtoZ2sxWE1zb00vVFN1V3RqRGdLRDJzSGFGMzI5dTdYa29jRkhnd2pSZHVhYWNNUG90b0k1dzg5cHozakRzUlVxa0RGdHJGTFVzdE9KcUhpWHR0UzhKNHFhdjZoSXlJTjhtSm5CUENlbGtvZUNLRThjcnRzUXlqZEorVzVlcXg0ZjNDOFd0dlBaVERnS2lIZzc3U1Rwc05EUjZudmlVbnd0Vjh0VElqaE92MW4rMWE5WkNkYVk4VVhZSXpwREUyb3lPMmJmdFFxdTBqcC9YWFJvTXd1LzFPR01kV0VhZWtmVy9ZY3laUEZHbFppSldyZThiaUdKc1NuTDJDdFJMQ1hhTGRKN3VIRmttdHhhcFZsU3dJd0RibWNkVVRTQVUrKzhza1lRNUhjYWZRZjE0aDdMS0tjNkJJRVpxU054UGJtaXQ1RlcwS0VtbUtHdWlGVkRDcitKYnJwWUJEcTh4RHJZTllpdkk5UlFyMWdiN0JidnFDSjdtbFFUVzhuVGMxUDB0UFpkdXFvb2VhalZnOXc5RTBQSFBWTm5YVEZiMjU2UlA3NVZIQ0NtU1VoZlhpb1c1YmFIM3FxbG5tVm9iclB6OXNyWWp3cVpHNGNpMExOQkZGTDEvbGo5OG9XR0tEMloxQ1BlUlB5cGU2UkxnaGkxQlk4UmNxaERyTDg3ckpmV3NrTDc3MWxubkxlWGczMkRvOHU3MHY1VzB1NGl1dUdxWTJteWZ1RnVwUm14cTZ6c3FrSW9rTmFBQWRjdjgyWkpwei9ZT0NhTXpUdThWSjhyR1RKNkZYbEk3Qmxhczg2NDhiTnZPVDNlYUNBTUh6dHBJSkw5QzhTUldhNmlKN3d4UTV4b3BiVlhyVE5jOEl4bCtiVGNsaUhWQ2R2R2QrelRBRk9YU2pjNDlxOGp2WXJSSEcwanJHVmsrenRHYmlKQktJTmFDdlk0MGlna0RnaVJ5czkyR0h3djN2bUJMS0Fic0Z0ODkwcVdTRDhSQWlVWlNJM3p1SnZWZ3M1ZFlXd2Ivb3M0d2tLcXExSXkwbTh5YktpZGJQTjRLeUNLdmN0L0cxdWRmRm9MVVgycVpRZmVtUVl3L0d3YVFoSUVWL09wUGg0YWw5Sk5uNWtWa1E2ZmIyOU8velUrMGVqMUQ3Yk5lSEhuV0tUcERueW12MzJCSkcybklkUFEzU1JSTnBoYndNZG9VTVJaTzVLT0RFZDZPakNnNm13RjJIRksxMUpoTTJuQ1FjUVlZQ2JGb3ZqVjNFekFCM3lGVk03S2I5Wko4cHU1dUxTZSswR2JQVFZIejd1MmRpOXhDMUdJSUdnK2IycXN6Wld3bnovb3luZWZyellQamJjSTJ4eUxseFR0enV1K2ZQMlZMZmpZUEJ0RDlQWlI0eTVIYkNXV2hOajQzM0ZwWXBucEl0eVo0UWRpSVhTN3VHdXdnQlhyTk1BSXp6UGM1STdIbjRrc2dvay9KeWpZaGIxNUo5anlCUk02cCtqMkRZS1dBZFZNM3Vub1dybS9kQlYxZzIwd2VLb0dUNjJiV0cwdVlYTEkvVk5xZEZvbWtJTldoQXpyOWtuaXIwUEFoaEVLcDFLV2dHUFk2RUpOZEV0QXN6R2NEcVhGeEFNTXY1ZFFnOVlpRE1jeHRiMkxrd0ZoRjc3dnFpOFF1Qk00L3drdmpmREJlS0tBblM0aE1hWGZqdE9IL2h1ZldLRWxBYVZDQUJiRk1aZytTa01sbWFJNTUrczZzU0V2QjVLWmtxL1FkVTNPVXZRTlYxL0FpNEhaY3NPNkN2bDd6MXFYMGdDb1luK2x3cXBqcE4rbEN4MzFjVlkwRWpGZTJzbGI0YkZrbmxmTVc0Y1VrZHREUkJPSGtNVWpkblBQb3B6R3dtNVNtdEJ5OU5icU5VTW5DZGtBTkIycnRWdHFFbHVXRVlHNXZTOVBrWU0rRSsvUi95MkxIUkMzRDFkbjQ2TmcrTXhKMzRRMitTbXZZa2Z3bUlUeE15NlpicEk5NENPWHp3QXpnVDhZMW1MaWxQL216eXBGaTVscFF5TlNjaEhoaHlscndDWjZwSExpOWpVTWVFWC9FTTZuYUFxQ01oVnZ1Y2JjWnpVaDlDM3VRVE5laS85akRwN0xkU0JudC9aYldNNkpaenVsYVFMZytxQUFlTzlWY2FYQ09iSXQxTnhlbXRrR3crWjNoTFVLS0Jjcy93aFgwMFVMRUNPM3RvMHBQUnkzRVozWTI2aFh1cmNMdW5jOTA5eDZrVGprbVBkU2JubkZaNGNpWjQyckFQR2h0MkVvTHd5UU5MSDBkM1EvOGNHREpCZkxLMjN0Y0dObTBNcGw5R2RNUFhPdStLblBNaGp5ZVdaQlNZeXlhaURiZDdWOG84NUpxajFua2V6ZnZSaHY0bjBEREJHM2t5NzFKN1dmVUp5VGZkY0F5eGw2V3k4Zi90NVhvbHArVlNvNnFoRGNxb09sN1V6eGxDTGZMbEE0YnJsem9QcFJzQkk3dUt2SmVxRldPWnhJSFo1UVoyL2s1MVZ6K091Y3h1cVI1czVkK0RDZG55MmRISVdYcEY5aC80NE13QUFZV0gvSXVtblM4NHR3N2NZdnZzb0FYTENVZG5WQTY0MTU4TzZGeld1dERNcWtsQ3BHdlAwKzM0Z1dxK3NKSjhxTXZRL0VwaC8vRW5DVVpYY0gwNFZzVm4yWXJUb1p2NlM1YzgvS0xYb3dOeEE3dlIzc2NrVFBSak9pVUY5ZklYM0xZZEZmY2wvNG5SUnhBcVlRZlI4ZXdaajZNdFpMNHdGUWM4Z25BZ3d3cm5QOEh0RFkrOHNtRjhiM3JoUm1STHBzN0RXTDJJV1pXUFJReFhSWkZjcUt2Ri9IRzR5WTJOVGFlRVBScEcvV01iZzYyZUN3UzlHcHRGN1NNWmxRTHNoK1dlaXVtUE1NekZSM1l4ck5ZUHVHMWJWYkxpOUd4Nk9QZ09TZmk2VXVkS3k5cDFxQUFLa214RjZTNkV0cVVjVlMvSFZpMWo3RXBLamxnUGlYUGNGWU5QN3FHVllXaStmbG5aSlNjbWNOMGN1L09zdktRSnhGQ05DK21FRlpncGlrSy9Ld2tPeEpmbEdDM3dKZXR5WXlUS0dCU2xaenpOeEJ1dGh6VTd0M1RqemwxMTYxZlRQTG1Rc3J1elVXa1pHcFdIWWZ1Z1lQd2dqZnVuZStOMzl2ZkIxZnBaN3poaFVBWjBTMXJLU2xPMVBFY0lWS3VDSjRMZzBuRWVzaStsSkNNS3huQjZvRHJGR0NOczIxMnZvb0dYSVlzTGtiSmhCSW5jZlZBcHlZakdBVkoxN25oOGR6OVc1YnRXeGVRR0pOL0wrb3FXTGtHQ1E2cUtSM0FyK3Jpcmptd0x4akZMMU1oNks2VHBCOUEvNlRvaWZTRUxOTStUVTVRSGY5c21tNGtJcFdteHJGdktnVUs1dEd5MFBrRlhtcTgwTnI5Smw5MnQxTlZjMXoyWjUvM2lXbjcvRkxhVlV6Szd0NHVBeWwrZ2lDWXduNVVHMnMrb001QVRrTG5CMHlzRUJadkpKT0d5NmhTTjlPQUNzLzVnV0R6blNDVHpBR0Y1QUVmQXVFYW5uNVk0WXFOb0EyY1FuVTluL2NYRllXTEMwbFN0Uk43bjFFZTlaWVlrQUEyT3NUK2V0YlNaYTdmQ1JXNGxXWWZ3SkcwSFFTTmRvdWk5SjJHUGErbyt5Yk5heTlsTDdKSVhzOWY2Y1c3N3ZSL0ltMXFrMFZsWHBHUkdsM0hPTmpWVnBOeHBHV2toYld5VHpLdC9TMGhYbEwwaXg0OHdyNGxzR2g2ZUtBQTBHMVkyS3RJQzlHbjBUdE9Kbmx3c3FQSUY2OXk2eHVobXFwcW1zY2Z3UXRFY1ZVZjQrNUhWSzhxVThkQnVMYjM0ZFZsR1orUDdqcEFvM3BnWk93TWtyejNSNzNKeVpJb1hMaUtoYjF5c3I4NWp3MVlRMnRBbEZWUmZRVlZxbmUxK3k1ZXhYU25MbDYrSXRCeElIakY5dEZFSENUUXZFdkd1dVE5dVBEaDA4MEYzcXBHRFJ3ckpoQVhCd0ZrK3dBcUErR2ZEWVBiTThES1ZVUlVJSkloZHovQmZ4dzlGVTdGV085dUFjcHJDVkVGL2tiN0NZZm9Ed0FHOWNGYnZ2UFJUenZnVXhMOThpMklFWkdTMVM0dTE2eDZqdFZ6S1EwUXdxanlWVllQTmR6OEVCQlhXU1A0SUZUNW9NeGxFMGprU0JhVCtpL3AxZWxmelhTS3NiTVJ2QzFRYm1oRzVJVXY5aVBOWmJRb2RBTTI1WjNsTTc2VEZ0a2lyd29XKzJnbHA5SzY5VTVxNFdPKzdneVwifSI=

Include

A shortcode was created to enable the inclusion of other markdown files. This allows us to create modular websites that reuse pieces of content, such as standardized syllabus statements.

There are two forms of the include shortcode - one to include files relative to the project root, and one to include files relative to the current file.

Note

This should also now work with shortcodes! See this GitHub Issue for more information. The .markdownify function was substituted for safeHTML in the include shortcode.

Include Local

This will include a file relative to the current page’s file path.

{{< include-local "includes/01-include.md" >}}

renders as

Content from a local file

This content is included from a local file. It can include any valid markdown. This file is inside of a folder with an _index.md file with the hidden: true attribute set, so it isn’t included in the menu.

Note

Shortcodes are now working! See this issue on GitHub for details.

Include

This will include a file with the filepath relative to the project root. This takes advantage of Hugo’s Union File System so that directories from the theme module are also accessible at paths relative to the project root.

{{< include "data/syllabus/netiquette.md" >}}

renders as

Netiquette

Info

This is our personal policy and not a required syllabus statement from K-State. It has been adapted from this statement from K-State Global Campus, and theRecurse Center Manual. We have adapted their ideas to fit this course.

Online communication is inherently different than in-person communication. When speaking in person, many times we can take advantage of the context and body language of the person speaking to better understand what the speaker means, not just what is said. This information is not present when communicating online, so we must be much more careful about what we say and how we say it in order to get our meaning across.

Here are a few general rules to help us all communicate online in this course, especially while using tools such as Canvas or Discord:

Use a clear and meaningful subject line to announce your topic. Subject lines such as “Question” or “Problem” are not helpful. Subjects such as “Logic Question in Project 5, Part 1 in Java” or “Unexpected Exception when Opening Text File in Python” give plenty of information about your topic.
Use only one topic per message. If you have multiple topics, post multiple messages so each one can be discussed independently.
Be thorough, concise, and to the point. Ideally, each message should be a page or less.
Include exact error messages, code snippets, or screenshots, as well as any previous steps taken to fix the problem. It is much easier to solve a problem when the exact error message or screenshot is provided. If we know what you’ve tried so far, we can get to the root cause of the issue more quickly.
Consider carefully what you write before you post it. Once a message is posted, it becomes part of the permanent record of the course and can easily be found by others.
If you are lost, don’t know an answer, or don’t understand something, speak up! Email and Canvas both allow you to send a message privately to the instructors, so other students won’t see that you asked a question. Don’t be afraid to ask questions anytime, as you can choose to do so without any fear of being identified by your fellow students.
Class discussions are confidential. Do not share information from the course with anyone outside of the course without explicit permission.
Do not quote entire message chains; only include the relevant parts. When replying to a previous message, only quote the relevant lines in your response.
Do not use all caps. It makes it look like you are shouting. Use appropriate text markup (bold, italics, etc.) to highlight a point if needed.
No feigning surprise. If someone asks a question, saying things like “I can’t believe you don’t know that!” are not helpful, and only serve to make that person feel bad.
No “well-actually’s.” If someone makes a statement that is not entirely correct, resist the urge to offer a “well, actually…” correction, especially if it is not relevant to the discussion. If you can help solve their problem, feel free to provide correct information, but don’t post a correction just for the sake of being correct.
Do not correct someone’s grammar or spelling. Again, it is not helpful, and only serves to make that person feel bad. If there is a genuine mistake that may affect the meaning of the post, please contact the person privately or let the instructors know privately so it can be resolved.
Avoid subtle -isms and microaggressions. Avoid comments that could make others feel uncomfortable based on their personal identity. See the syllabus section on Diversity and Inclusion above for more information on this topic. If a comment makes you uncomfortable, please contact the instructor.
Avoid sarcasm, flaming, advertisements, lingo, trolling, doxxing, and other bad online habits. They have no place in an academic environment. Tasteful humor is fine, but sarcasm can be misunderstood.

As a participant in course discussions, you should also strive to honor the diversity of your classmates by adhering to the K-State Principles of Community.

No Render

The norender shortcode has been deprecated. It can be safely replaced with <pre> in Markdown without any issue.

Static

The static shortcode has been deprecated. All static content should be stored in the static folder outside of content, and with the canonifyURLs option set to true in the site config, they can be referenced directly at the root of the site.

For example, the file at /static/images/core-logo-on-white.svg can be referenced using:

![Core Logo](/images/core-logo-on-white.svg)

Quizdown

This theme also includes the Quizdown Plugin.

Quizdown quiz omitted from print view.

Syllabus

The syllabus shortcode can be used to include the default K-State syllabus statements that are embedded into the theme. The theme maintainer will update these statements each semester, so by using this shortcode and keeping your theme updated, your textbooks will always have the current statements.

The syllabus statements can be found in /themes/hugo-theme-learn/static/files/syllabus/. The text of nearly all of these statements can be found on the Provost’s Website.

Default Usage

{{< syllabus >}}

This will include all of the default syllabus statements on the page. Currently, the default syllabus statements are included in this order:

honesty
disabilities
conduct
respect
netiquette (this is a custom statement for K-State CS courses)
discrimination
freedom
safety
resources
creations
mentalhealth
absences
copyright

Available Statements

In addition to the default statements, the following optional statements are available:

safezone
facecoverings (deprecated as of Fall 2023)
weapons

Customizing

There are two ways to customize the syllabus statements:

Include

{{< syllabus include="honesty disabilities conduct respect" >}}

The include parameter is a space-delimited list of statements to include. They will be included in the order listed.

Exclude

{{< syllabus exclude="copyright honesty" >}}

The exclude parameter is a space-delimited list of statements to be excluded from the default list.

Example - All

This example page shows all current default syllabus statements.

Standard Syllabus Statements

Info

The statements below are standard syllabus statements from K-State and our program. The latest versions are available online here.

Academic Honesty

Kansas State University has an Honor and Integrity System based on personal integrity, which is presumed to be sufficient assurance that, in academic matters, one’s work is performed honestly and without unauthorized assistance. Undergraduate and graduate students, by registration, acknowledge the jurisdiction of the Honor and Integrity System. The policies and procedures of the Honor and Integrity System apply to all full and part-time students enrolled in undergraduate and graduate courses on-campus, off-campus, and via distance learning. A component vital to the Honor and Integrity System is the inclusion of the Honor Pledge which applies to all assignments, examinations, or other course work undertaken by students. The Honor Pledge is implied, whether or not it is stated: “On my honor, as a student, I have neither given nor received unauthorized aid on this academic work.” A grade of XF can result from a breach of academic honesty. The F indicates failure in the course; the X indicates the reason is an Honor Pledge violation.

For this course, a violation of the Honor Pledge will result in sanctions such as a 0 on the assignment or an XF in the course, depending on severity. Actively seeking unauthorized aid, such as posting lab assignments on sites such as Chegg or StackOverflow, or asking another person to complete your work, even if unsuccessful, will result in an immediate XF in the course.

This course assumes that all your course work will be done by you. Use of AI text and code generators such as ChatGPT and GitHub Copilot in any submission for this course is strictly forbidden unless explicitly allowed by your instructor. Any unauthorized use of these tools without proper attribution is a violation of the K-State Honor Pledge.

We reserve the right to use various platforms that can perform automatic plagiarism detection by tracking changes made to files and comparing submitted projects against other students’ submissions and known solutions. That information may be used to determine if plagiarism has taken place.

Students with Disabilities

At K-State it is important that every student has access to course content and the means to demonstrate course mastery. Students with disabilities may benefit from services including accommodations provided by the Student Access Center. Disabilities can include physical, learning, executive functions, and mental health. You may register at the Student Access Center or to learn more contact:

Manhattan/Olathe/Global Campus – Student Access Center
- accesscenter@k-state.edu
- 785-532-6441
K-State Salina Campus – Julie Rowe; Student Success Coordinator
- jarowe@k-state.edu
- 785-820-7908

Students already registered with the Student Access Center please request your Letters of Accommodation early in the semester to provide adequate time to arrange your approved academic accommodations. Once SAC approves your Letter of Accommodation it will be e-mailed to you, and your instructor(s) for this course. Please follow up with your instructor to discuss how best to implement the approved accommodations.

Expectations for Conduct

All student activities in the University, including this course, are governed by the Student Judicial Conduct Code as outlined in the Student Governing Association By Laws, Article V, Section 3, number 2. Students who engage in behavior that disrupts the learning environment may be asked to leave the class.

Mutual Respect and Inclusion in K-State Teaching & Learning Spaces

At K-State, faculty and staff are committed to creating and maintaining an inclusive and supportive learning environment for students from diverse backgrounds and perspectives. K-State courses, labs, and other virtual and physical learning spaces promote equitable opportunity to learn, participate, contribute, and succeed, regardless of age, race, color, ethnicity, nationality, genetic information, ancestry, disability, socioeconomic status, military or veteran status, immigration status, Indigenous identity, gender identity, gender expression, sexuality, religion, culture, as well as other social identities.

Faculty and staff are committed to promoting equity and believe the success of an inclusive learning environment relies on the participation, support, and understanding of all students. Students are encouraged to share their views and lived experiences as they relate to the course or their course experience, while recognizing they are doing so in a learning environment in which all are expected to engage with respect to honor the rights, safety, and dignity of others in keeping with the K-State Principles of Community.

If you feel uncomfortable because of comments or behavior encountered in this class, you may bring it to the attention of your instructor, advisors, and/or mentors. If you have questions about how to proceed with a confidential process to resolve concerns, please contact the Student Ombudsperson Office. Violations of the student code of conduct can be reported using the Code of Conduct Reporting Form. You can also report discrimination, harassment or sexual harassment, if needed.

Netiquette

Info

Here are a few general rules to help us all communicate online in this course, especially while using tools such as Canvas or Discord:

Use a clear and meaningful subject line to announce your topic. Subject lines such as “Question” or “Problem” are not helpful. Subjects such as “Logic Question in Project 5, Part 1 in Java” or “Unexpected Exception when Opening Text File in Python” give plenty of information about your topic.
Use only one topic per message. If you have multiple topics, post multiple messages so each one can be discussed independently.
Be thorough, concise, and to the point. Ideally, each message should be a page or less.
Include exact error messages, code snippets, or screenshots, as well as any previous steps taken to fix the problem. It is much easier to solve a problem when the exact error message or screenshot is provided. If we know what you’ve tried so far, we can get to the root cause of the issue more quickly.
Consider carefully what you write before you post it. Once a message is posted, it becomes part of the permanent record of the course and can easily be found by others.
If you are lost, don’t know an answer, or don’t understand something, speak up! Email and Canvas both allow you to send a message privately to the instructors, so other students won’t see that you asked a question. Don’t be afraid to ask questions anytime, as you can choose to do so without any fear of being identified by your fellow students.
Class discussions are confidential. Do not share information from the course with anyone outside of the course without explicit permission.
Do not quote entire message chains; only include the relevant parts. When replying to a previous message, only quote the relevant lines in your response.
Do not use all caps. It makes it look like you are shouting. Use appropriate text markup (bold, italics, etc.) to highlight a point if needed.
No feigning surprise. If someone asks a question, saying things like “I can’t believe you don’t know that!” are not helpful, and only serve to make that person feel bad.
No “well-actually’s.” If someone makes a statement that is not entirely correct, resist the urge to offer a “well, actually…” correction, especially if it is not relevant to the discussion. If you can help solve their problem, feel free to provide correct information, but don’t post a correction just for the sake of being correct.
Do not correct someone’s grammar or spelling. Again, it is not helpful, and only serves to make that person feel bad. If there is a genuine mistake that may affect the meaning of the post, please contact the person privately or let the instructors know privately so it can be resolved.
Avoid subtle -isms and microaggressions. Avoid comments that could make others feel uncomfortable based on their personal identity. See the syllabus section on Diversity and Inclusion above for more information on this topic. If a comment makes you uncomfortable, please contact the instructor.
Avoid sarcasm, flaming, advertisements, lingo, trolling, doxxing, and other bad online habits. They have no place in an academic environment. Tasteful humor is fine, but sarcasm can be misunderstood.

As a participant in course discussions, you should also strive to honor the diversity of your classmates by adhering to the K-State Principles of Community.

Discrimination, Harassment, and Sexual Harassment

Kansas State University is committed to maintaining academic, housing, and work environments that are free of discrimination, harassment, and sexual harassment. Instructors support the University’s commitment by creating a safe learning environment during this course, free of conduct that would interfere with your academic opportunities. Instructors also have a duty to report any behavior they become aware of that potentially violates the University’s policy prohibiting discrimination, harassment, and sexual harassment, as outlined by PPM 3010.

If a student is subjected to discrimination, harassment, or sexual harassment, they are encouraged to make a non-confidential report to the University’s Office for Institutional Equity (OIE) using the online reporting form. Incident disclosure is not required to receive resources at K-State. Reports that include domestic and dating violence, sexual assault, or stalking, should be considered for reporting by the complainant to the Kansas State University Police Department or the Riley County Police Department. Reports made to law enforcement are separate from reports made to OIE. A complainant can choose to report to one or both entities. Confidential support and advocacy can be found with the K-State Center for Advocacy, Response, and Education (CARE). Confidential mental health services can be found with Lafene Counseling and Psychological Services (CAPS). Academic support can be found with the Office of Student Life (OSL). OSL is a non-confidential resource. OIE also provides a comprehensive list of resources on their website. If you have questions about non-confidential and confidential resources, please contact OIE at equity@ksu.edu or (785) 532–6220.

Academic Freedom Statement

Kansas State University is a community of students, faculty, and staff who work together to discover new knowledge, create new ideas, and share the results of their scholarly inquiry with the wider public. Although new ideas or research results may be controversial or challenge established views, the health and growth of any society requires frank intellectual exchange. Academic freedom protects this type of free exchange and is thus essential to any university’s mission.

Moreover, academic freedom supports collaborative work in the pursuit of truth and the dissemination of knowledge in an environment of inquiry, respectful debate, and professionalism. Academic freedom is not limited to the classroom or to scientific and scholarly research, but extends to the life of the university as well as to larger social and political questions. It is the right and responsibility of the university community to engage with such issues.

Campus Safety

Kansas State University is committed to providing a safe teaching and learning environment for student and faculty members. In order to enhance your safety in the unlikely case of a campus emergency make sure that you know where and how to quickly exit your classroom and how to follow any emergency directives. Current Campus Emergency Information is available at the University’s Advisory webpage.

Student Resources

K-State has many resources to help contribute to student success. These resources include accommodations for academics, paying for college, student life, health and safety, and others. Check out the Student Guide to Help and Resources: One Stop Shop for more information.

Student Academic Creations

Student academic creations are subject to Kansas State University and Kansas Board of Regents Intellectual Property Policies. For courses in which students will be creating intellectual property, the K-State policy can be found at University Handbook, Appendix R: Intellectual Property Policy and Institutional Procedures (part I.E.). These policies address ownership and use of student academic creations.

Mental Health

Your mental health and good relationships are vital to your overall well-being. Symptoms of mental health issues may include excessive sadness or worry, thoughts of death or self-harm, inability to concentrate, lack of motivation, or substance abuse. Although problems can occur anytime for anyone, you should pay extra attention to your mental health if you are feeling academic or financial stress, discrimination, or have experienced a traumatic event, such as loss of a friend or family member, sexual assault or other physical or emotional abuse.

If you are struggling with these issues, do not wait to seek assistance.

Kansas State University Counseling and Psychological Services offers free and confidential services to assist you to meet these challenges.
Lafene Health Center has specialized nurse practitioners to assist with mental health.
The Office of Student Life can direct you to additional resources.
K-State Family Center offers individual, couple, and family counseling services on a sliding fee scale.
Center for Advocacy, Response, and Education (CARE) provides free and confidential assistance for those in our K-State community who have been victimized by violence.

For Kansas State Salina Campus:

Kansas State Salina Counseling Services offers free and confidential services to assist you to meet these challenges.
The Kansas State Salina Office of Student Life can direct you to additional resources.
The Kansas State Salina Campus offers several services for students, including health services, counseling, and academic assistance.

For Global Campus/K-State Online:

K-State Online students have free access to mental health counseling with My SSP - 24/7 support via chat and phone.
The Office of Student Life can direct you to additional resources.

University Excused Absences

K-State has a University Excused Absence policy (Section F62). Class absence(s) will be handled between the instructor and the student unless there are other university offices involved. For university excused absences, instructors shall provide the student the opportunity to make up missed assignments, activities, and/or attendance specific points that contribute to the course grade, unless they decide to excuse those missed assignments from the student’s course grade. Please see the policy for a complete list of university excused absences and how to obtain one. Students are encouraged to contact their instructor regarding their absences.

Copyright Notice

© The materials in this online course fall under the protection of all intellectual property, copyright and trademark laws of the U.S. The digital materials included here come with the legal permissions and releases of the copyright holders. These course materials should be used for educational purposes only; the contents should not be distributed electronically or otherwise beyond the confines of this online course. The URLs listed here do not suggest endorsement of either the site owners or the contents found at the sites. Likewise, mentioned brands (products and services) do not suggest endorsement. Students own copyright to what they create.

Example - Exclude

This example page shows all current default syllabus statements, except for the statement on academic honesty and copyright. This allows instructors to modify those sections in the syllabus as desired.

Standard Syllabus Statements

Info

The statements below are standard syllabus statements from K-State and our program. The latest versions are available online here.

Students with Disabilities

Manhattan/Olathe/Global Campus – Student Access Center
- accesscenter@k-state.edu
- 785-532-6441
K-State Salina Campus – Julie Rowe; Student Success Coordinator
- jarowe@k-state.edu
- 785-820-7908

Expectations for Conduct

Mutual Respect and Inclusion in K-State Teaching & Learning Spaces

Netiquette

Info

Here are a few general rules to help us all communicate online in this course, especially while using tools such as Canvas or Discord:

Use a clear and meaningful subject line to announce your topic. Subject lines such as “Question” or “Problem” are not helpful. Subjects such as “Logic Question in Project 5, Part 1 in Java” or “Unexpected Exception when Opening Text File in Python” give plenty of information about your topic.
Use only one topic per message. If you have multiple topics, post multiple messages so each one can be discussed independently.
Be thorough, concise, and to the point. Ideally, each message should be a page or less.
Include exact error messages, code snippets, or screenshots, as well as any previous steps taken to fix the problem. It is much easier to solve a problem when the exact error message or screenshot is provided. If we know what you’ve tried so far, we can get to the root cause of the issue more quickly.
Consider carefully what you write before you post it. Once a message is posted, it becomes part of the permanent record of the course and can easily be found by others.
If you are lost, don’t know an answer, or don’t understand something, speak up! Email and Canvas both allow you to send a message privately to the instructors, so other students won’t see that you asked a question. Don’t be afraid to ask questions anytime, as you can choose to do so without any fear of being identified by your fellow students.
Class discussions are confidential. Do not share information from the course with anyone outside of the course without explicit permission.
Do not quote entire message chains; only include the relevant parts. When replying to a previous message, only quote the relevant lines in your response.
Do not use all caps. It makes it look like you are shouting. Use appropriate text markup (bold, italics, etc.) to highlight a point if needed.
No feigning surprise. If someone asks a question, saying things like “I can’t believe you don’t know that!” are not helpful, and only serve to make that person feel bad.
No “well-actually’s.” If someone makes a statement that is not entirely correct, resist the urge to offer a “well, actually…” correction, especially if it is not relevant to the discussion. If you can help solve their problem, feel free to provide correct information, but don’t post a correction just for the sake of being correct.
Do not correct someone’s grammar or spelling. Again, it is not helpful, and only serves to make that person feel bad. If there is a genuine mistake that may affect the meaning of the post, please contact the person privately or let the instructors know privately so it can be resolved.
Avoid subtle -isms and microaggressions. Avoid comments that could make others feel uncomfortable based on their personal identity. See the syllabus section on Diversity and Inclusion above for more information on this topic. If a comment makes you uncomfortable, please contact the instructor.
Avoid sarcasm, flaming, advertisements, lingo, trolling, doxxing, and other bad online habits. They have no place in an academic environment. Tasteful humor is fine, but sarcasm can be misunderstood.

As a participant in course discussions, you should also strive to honor the diversity of your classmates by adhering to the K-State Principles of Community.

Discrimination, Harassment, and Sexual Harassment

Academic Freedom Statement

Campus Safety

Student Resources

Student Academic Creations

Mental Health

If you are struggling with these issues, do not wait to seek assistance.

Kansas State University Counseling and Psychological Services offers free and confidential services to assist you to meet these challenges.
Lafene Health Center has specialized nurse practitioners to assist with mental health.
The Office of Student Life can direct you to additional resources.
K-State Family Center offers individual, couple, and family counseling services on a sliding fee scale.
Center for Advocacy, Response, and Education (CARE) provides free and confidential assistance for those in our K-State community who have been victimized by violence.

For Kansas State Salina Campus:

Kansas State Salina Counseling Services offers free and confidential services to assist you to meet these challenges.
The Kansas State Salina Office of Student Life can direct you to additional resources.
The Kansas State Salina Campus offers several services for students, including health services, counseling, and academic assistance.

For Global Campus/K-State Online:

K-State Online students have free access to mental health counseling with My SSP - 24/7 support via chat and phone.
The Office of Student Life can direct you to additional resources.

University Excused Absences

Example - Include

This example page shows only a few selected syllabus statements. This allows instructors to control the order they are presented or only show selected items.

Standard Syllabus Statements

Info

The statements below are standard syllabus statements from K-State and our program. The latest versions are available online here.

Academic Honesty

Students with Disabilities

Manhattan/Olathe/Global Campus – Student Access Center
- accesscenter@k-state.edu
- 785-532-6441
K-State Salina Campus – Julie Rowe; Student Success Coordinator
- jarowe@k-state.edu
- 785-820-7908

Expectations for Conduct

Mutual Respect and Inclusion in K-State Teaching & Learning Spaces

Face Coverings

Kansas State University strongly encourages, but does not require, that everyone wear masks while indoors on university property, including while attending in-person classes. For additional information and the latest updates, see K-State’s face covering policy.

Discrimination, Harassment, and Sexual Harassment

Built-In Shortcodes

Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. You could use pure HTML to expand possibilities.

But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.

To avoid this limitations, Hugo created shortcodes. A shortcode is a simple snippet inside a page.

The Relearn theme provides multiple shortcodes on top of existing ones.

Badge

Marker badges to display in your text

Button

Clickable buttons

Children

List the child pages of a page

Expand

Expandable/collapsible sections of text

Highlight

Render code with a syntax highlighter

Icon

Nice icons for your page

Include

Displays content from other files

Math

Beautiful math and chemical formulae

Mermaid

Generate diagrams and flowcharts from text

Notice

Disclaimers to help you structure your page

OpenAPI

UI for your OpenAPI / Swagger specifications

Resources

List resources contained in a page bundle

SiteParam

Get value of site params

Tab

Show content in a single tab

Tabs

Show content in tabbed views

Badge

The badge shortcode displays little markers in your text with adjustable color, title and icon.

Important Version6.6.6 Captain InfoNew Awesome

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% badge %}}Important{{% /badge %}}
{{% badge style="primary" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}
{{% badge style="info" %}}New{{% /badge %}}
{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Awesome{{% /badge %}}

{{ partial "shortcodes/badge.html" (dict
    "page"    .
    "content" "Important"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "primary"
  "title" "Version"
  "content" "6.6.6"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "red"
  "icon"  "angle-double-up"
  "content" "Captain"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "style" "info"
  "content" "New"
)}}
{{ partial "shortcodes/badge.html" (dict
  "page"  .
  "color" "fuchsia"
  "icon"  "fab fa-hackerrank"
  "content" "Awesome"
)}}

Parameter

Name	Default	Notes
style	`default`	The style scheme used for the badge. - by severity: `info`, `note`, `tip`, `warning` - by brand color: `primary`, `secondary`, `accent` - by color: `blue`, `green`, `grey`, `orange`, `red` - by special color: `default`, `transparent`, `code`
color	see notes	The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default. - for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
title	see notes	Arbitrary text for the badge title. Depending on the style there may be a default title. Any given value will overwrite the default. - for severity styles: the matching title for the severity - for all other styles: <empty> If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
icon	see notes	Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default. - for severity styles: a nice matching icon for the severity - for all other styles: <empty> If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
<content>	<empty>	Arbitrary text for the badge.

Examples

Style

By Severity

{{% badge style="info" %}}New{{% /badge %}}
{{% badge style="note" %}}Change{{% /badge %}}
{{% badge style="tip" %}}Optional{{% /badge %}}
{{% badge style="warning" %}}Breaking{{% /badge %}}

InfoNew NoteChange TipOptional WarningBreaking

By Brand Colors

{{% badge style="primary" icon="bullhorn" title="Announcement" %}}Mandatory{{% /badge %}}
{{% badge style="secondary" icon="bullhorn" title="Announcement" %}}Optional{{% /badge %}}
{{% badge style="accent" icon="bullhorn" title="Announcement" %}}Special{{% /badge %}}

AnnouncementMandatory AnnouncementOptional AnnouncementSpecial

By Color

{{% badge style="blue" icon="palette" title="Color" %}}Blue{{% /badge %}}
{{% badge style="green" icon="palette" title="Color" %}}Green{{% /badge %}}
{{% badge style="grey" icon="palette" title="Color" %}}Grey{{% /badge %}}
{{% badge style="orange" icon="palette" title="Color" %}}Orange{{% /badge %}}
{{% badge style="red" icon="palette" title="Color" %}}Red{{% /badge %}}

ColorBlue ColorGreen ColorGrey ColorOrange ColorRed

By Special Color

{{% badge style="default" icon="palette" title="Color" %}}Default{{% /badge %}}
{{% badge style="transparent" icon="palette" title="Color" %}}Transparent{{% /badge %}}

ColorDefault ColorTransparent

Variants

Without Icon and Title Text

{{% badge %}}6.6.6{{% /badge %}}
{{% badge style="info" icon=" " title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" %}}Captain{{% /badge %}}

6.6.6 Awesome Captain

Without Icon

{{% badge title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="info" icon=" " %}}Awesome{{% /badge %}}
{{% badge style="red" title="Rank" %}}Captain{{% /badge %}}

Version6.6.6 InfoAwesome RankCaptain

Without Title Text

{{% badge icon="star" %}}6.6.6{{% /badge %}}
{{% badge style="info" title=" " %}}Awesome{{% /badge %}}
{{% badge style="red" icon="angle-double-up" %}}Captain{{% /badge %}}

6.6.6 Awesome Captain

All Set

{{% badge icon="star" title="Version" %}}6.6.6{{% /badge %}}
{{% badge style="info" %}}Awesome{{% /badge %}}
{{% badge style="red" icon="angle-double-up" title="Rank" %}}Captain{{% /badge %}}

Version6.6.6 InfoAwesome RankCaptain

Override for Severity

{{% badge style="info" icon="rocket" title="Feature" %}}Awesome{{% /badge %}}

FeatureAwesome

Other

With User-Defined Color, Font Awesome Brand Icon and Markdown Title and Content

{{% badge color="fuchsia" icon="fa-fw fab fa-hackerrank" title="**Font**" %}}**Awesome**{{% /badge %}}

FontAwesome

With Icon Content

You can combine the badge with the icon shortcode to create even more stunning visuals.

In this case you need to declare {{< badge >}} instead of {{% badge %}}. Note, that in this case it is not possible to put markdown in the content.

{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}  
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}}{{< /badge >}}  
{{< badge style="primary" icon="angle-double-up" title="Rank" >}}{{% icon skull-crossbones %}} Pirate{{< /badge >}}

Pirate
Rank
Rank Pirate
Rank
Rank Pirate

Inside of Text

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. {{% badge style="blue" icon="rocket" %}}Awesome{{% /badge %}} Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Awesome Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Button

The button shortcode displays a clickable button with adjustable color, title and icon.

Get Hugo Get Hugo

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% button href="https://gohugo.io/" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" icon="dragon" %}}Get Hugo{{% /button %}}

{{ partial "shortcodes/button.html" (dict
    "page" .
    "href" "https://gohugo.io/"
    "content" "Get Hugo"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "href" "https://gohugo.io/"
  "style" "warning"
  "icon" "dragon"
  "content" "Get Hugo"
)}}

Once the button is clicked, it opens another browser tab for the given URL.

Parameter

Name	Default	Notes
href	<empty>	Either the destination URL for the button or JavaScript code to be executed on click. If this parameter is not set, the button will do nothing but is still displayed as clickable. - if starting with `javascript:` all following text will be executed in your browser - every other string will be interpreted as URL
style	`transparent`	The style scheme used for the button. - by severity: `info`, `note`, `tip`, `warning` - by brand color: `primary`, `secondary`, `accent` - by color: `blue`, `green`, `grey`, `orange`, `red` - by special color: `default`, `transparent`, `code`
color	see notes	The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default. - for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
icon	see notes	Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default. - for severity styles: a nice matching icon for the severity - for all other styles: <empty> If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
iconposition	`left`	Places the icon to the `left` or `right` of the title.
target	see notes	The destination frame/window if href is an URL. Otherwise the parameter is not used. This behaves similar to normal links. If the parameter is not given it defaults to: - the setting of `externalLinkTarget` or `_blank` if not set, for any address starting with `http://` or `https://` - no specific value for all other links
type	see notes	The button type if href is JavaScript. Otherwise the parameter is not used. If the parameter is not given it defaults to `button`
<content>	see notes	Arbitrary text for the button title. Depending on the style there may be a default title. Any given value will overwrite the default. - for severity styles: the matching title for the severity - for all other styles: <empty> If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)

Examples

Style

By Severity

{{% button href="https://gohugo.io/" style="info" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="note" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="tip" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo Get Hugo

By Brand Colors

{{% button href="https://gohugo.io/" style="primary" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="secondary" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="accent" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo

By Color

{{% button href="https://gohugo.io/" style="blue" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="green" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="grey" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="orange" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="red" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo Get Hugo Get Hugo Get Hugo

By Special Color

{{% button href="https://gohugo.io/" style="default" %}}Get Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="transparent" %}}Get Hugo{{% /button %}}

Get Hugo Get Hugo

Icon

Empty

{{% button href="https://gohugo.io/" icon=" " %}}{{% /button %}}

Only

{{% button href="https://gohugo.io/" icon="download" %}}{{% /button %}}

To the Left

{{% button href="https://gohugo.io/" icon="download" %}}Get Hugo{{% /button %}}

Get Hugo

To the Right

{{% button href="https://gohugo.io/" icon="download" iconposition="right" %}}Get Hugo{{% /button %}}

Get Hugo

Override for Severity

{{% button href="https://gohugo.io/" icon="dragon" style="warning" %}}Get Hugo{{% /button %}}

Get Hugo

Target

{{% button href="https://gohugo.io/" target="_self" %}}Get Hugo in same window{{% /button %}}
{{% button href="https://gohugo.io/" %}}Get Hugo in new Window/Frame (default){{% /button %}}

Get Hugo in same Window/Frame Get Hugo in new Window/Frame (default)

Other

With User-Defined Color, Font Awesome Brand Icon and Markdown Title

{{% button href="https://gohugo.io/" color="fuchsia" icon="fa-fw fab fa-hackerrank" %}}Get **Hugo**{{% /button %}}

Get Hugo

Severity Style with All Defaults

{{% button href="https://gohugo.io/" style="tip" %}}{{% /button %}}

Tip

Button to Internal Page

{{% button href="/index.html" %}}Home{{% /button %}}

Home

Button with JavaScript Action

If your JavaScript action does not change the focus afterwards, make sure to call this.blur() in the end to unselect the button.

{{% button style="primary" icon="bullhorn" href="javascript:alert('Hello world!');this.blur();" %}}Shout it out{{% /button %}}

Button within a `form` Element

To use native HTML elements in your Markdown, add this in your hugo.toml

[markup.goldmark.renderer]
    unsafe = true

<form action="../../search.html" method="get">
  <input name="search-by-detail" class="search-by" type="search">
  {{% button type="submit" style="secondary" icon="search" %}}Search{{% /button %}}
</form>

Children

The children shortcode lists the child pages of the current page and its descendants.

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% children sort="weight" %}}

{{ partial "shortcodes/children.html" (dict
  "page" .
  "sort" "weight"
)}}

Parameter

Name	Default	Notes
containerstyle	`ul`	Choose the style used to group all children. It could be any HTML tag name.
style	`li`	Choose the style used to display each descendant. It could be any HTML tag name.
showhidden	`false`	When `true`, child pages hidden from the menu will be displayed as well.
description	`false`	When `true` shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - read more info about summaries on gohugo.io.
depth	`1`	The depth of descendants to display. For example, if the value is `2`, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. `999`.
sort	`auto`	The sort criteria of the displayed list. - `auto` defaults to `ordersectionsby` of the pages frontmatter or to `ordersectionsby` of the site configuration or to `weight` - `weight` - `title` - `linktitle` - `modifieddate` - `expirydate` - `publishdate` - `date` - `length` - `default` adhering to Hugo’s default sort criteria

Examples

All Default

{{% children  %}}

With Description

{{% children description="true" %}}

page X
This is a plain page test, and the beginning of a YAML multiline description...
page 1
This is a demo child page
page 2
This is a demo child page with no description. So its content is used as description.
page 3
This is a demo child page

Infinite Depth and Hidden Pages

{{% children depth="999" showhidden="true" %}}

page X
page 1
- page 1-1
  - page 1-1-1 (hidden)
    - page 1-1-1-1
      - page 1-1-1-1-1 (hidden)
        page 1-1-1-1-1-1
  - page 1-1-2 (headless)
    - page 1-1-2-1
    - page 1-1-2-2
  - page 1-1-3
page 2
page 3
- page 3-1
page 4 (hidden)

Heading Styles for Container and Elements

{{% children containerstyle="div" style="h2" depth="3" description="true" %}}

page X

This is a plain page test, and the beginning of a YAML multiline description...

page 1

This is a demo child page

page 1-1

This is a demo child page

page 1-1-2 (headless)

This is a demo child page

page 1-1-3

This is a demo child page

page 2

This is a demo child page with no description. So its content is used as description.

page 3

This is a demo child page

page 3-1

This is a plain page test nested in a parent

Divs for Group and Element Styles

{{% children containerstyle="div" style="div" depth="3" %}}

page X

page 1

page 1-1

page 1-1-2 (headless)

Children

page X

This is a plain demo child page.

page 1

This is a demo child page.

Subpages of this page

page 1-1

page 1-1

This is a demo child page with a hidden child. You can still access the hidden child directly or via the search.

Subpages of this page

page 1-1-1 (hidden)
page 1-1-2 (headless)
page 1-1-3

page 1-1-2 (headless)

page 1-1-2-1

This is a plain demo child page.

page 1-1-2-2

This is a plain demo child page.

page 1-1-3

This is a plain demo child page.

page 2

This is a demo child page with no description.

So its content is used as description.

page 3

This is a demo child page.

Subpages of this page

page 3-1

page 3-1

This is a plain demo child page.

Expand

The expand shortcode displays an expandable/collapsible section of text.

Expand me…

Thank you!

That’s some text with a footnote¹

That’s some more text with a footnote.²

And that’s the footnote. ↩︎
Anything of interest goes here.
Blue light glows blue. ↩︎

Usage

While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.

{{% expand title="Expand me..." %}}Thank you!{{% /expand %}}

{{% expand "Expand me..." %}}Thank you!{{% /expand %}}

{{ partial "shortcodes/expand.html" (dict
  "page"  .
  "title" "Expand me..."
  "content" "Thank you!"
)}}

Parameter

Name	Position	Default	Notes
title	1	`"Expand me..."`	Arbitrary text to appear next to the expand/collapse icon.
open	2	`false`	When `true` the content text will be initially shown as expanded.
<content>		<empty>	Arbitrary text to be displayed on expand.

Examples

All Defaults

{{% expand %}}Yes, you did it!{{% /expand %}}

Expand me…

Yes, you did it!

Initially Expanded

{{% expand title="Expand me..." open="true" %}}No need to press you!{{% /expand %}}

Expand me…

No need to press you!

Arbitrary Text

{{% expand title="Show me almost **endless** possibilities" %}}
You can add standard markdown syntax:

- multiple paragraphs
- bullet point lists
- _emphasized_, **bold** and even **_bold emphasized_** text
- [links](https://example.com)
- etc.

```plaintext
...and even source code
```

> the possibilities are endless (almost - including other shortcodes may or may not work)
{{% /expand %}}

Show me almost endless possibilities

You can add standard markdown syntax:

multiple paragraphs
bullet point lists
emphasized, bold and even bold emphasized text
links
etc.

...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work)

Highlight

The highlight shortcode renders your code with a syntax highlighter.

1print("Hello World!")

Usage

This shortcode is fully compatible with Hugo’s highlight shortcode but offers some extensions.

It is called interchangeably in the same way as Hugo’s own shortcode providing positional parameter or by simply using codefences.

You are free to also call this shortcode from your own partials. In this case it resembles Hugo’s highlight function syntax if you call this shortcode as a partial using compatibility syntax.

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports codefences (eg. GitHub) and so your markdown becomes more portable.

```py { lineNos="true" wrap="true" title="python" }
print("Hello World!")
```

{{< highlight lineNos="true" type="py" wrap="true" title="python" >}}
print("Hello World!")
{{< /highlight >}}

{{< highlight py "lineNos=true,wrap=true,title=python" >}}
print("Hello World!")
{{< /highlight >}}

{{ partial "shortcodes/highlight.html" (dict
  "page"    .
  "content" "print(\"Hello World!\")"
  "lineNos" "true"
  "type"    "py"
  "wrap"    "true"
  "title"   "python"
)}}

{{ partial "shortcodes/highlight.html" (dict
  "page"    .
  "content" "print(\"Hello World!\")"
  "options" "lineNos=true,wrap=true,title=python"
  "type"    "py"
)}}

Parameter

Name	Position	Default	Notes
type	1	<empty>	The language of the code to highlight. Choose from one of the supported languages. Case-insensitive.
title		<empty>	Extension. Arbitrary title for code. This displays the code like a single tab if `hl_inline=false` (which is Hugo’s default).
wrap		see notes	Extension. When `true` the content may wrap on long lines otherwise it will be scrollable. The default value can be set in your `hugo.toml` and overwritten via frontmatter. See below.
options	2	<empty>	An optional, comma-separated list of zero or more Hugo supported options as well as extension parameter from this table.
<option>		<empty>	Any of Hugo’s supported options.
<content>		<empty>	Your code to highlight.

Configuration

Default values for Hugo’s supported options can be set via goldmark settings in your hugo.toml

Default values for extension options can be set via params settings in your hugo.toml or be overwritten by frontmatter for each individual page.

Global Configuration File

You can configure the color style used for code blocks in your color variants stylesheet file.

Recommended Settings

hugo.

[markup]
  [markup.highlight]
    lineNumbersInTable = false
    noClasses = false

markup:
  highlight:
    lineNumbersInTable: false
    noClasses: false

{
   "markup": {
      "highlight": {
         "lineNumbersInTable": false,
         "noClasses": false
      }
   }
}

Optional Settings

hugo.

[params]
  highlightWrap = true

params:
  highlightWrap: true

{
   "params": {
      "highlightWrap": true
   }
}

Page’s Frontmatter

+++
highlightWrap = true
+++

---
highlightWrap: true
---

{
   "highlightWrap": true
}

Examples

Line Numbers with Starting Offset

As mentioned above, line numbers in a table layout will shift if code is wrapping, so better use inline. To make things easier for you, set lineNumbersInTable = false in your hugo.toml and add lineNos = true when calling the shortcode instead of the specific values table or inline.

{{< highlight lineNos="true" lineNoStart="666" type="py" >}}
# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
print("Hello")
print(" ")
print("World")
print("!")
{{< /highlight >}}

666# the hardest part is to start writing code; here's a kickstart; just copy and paste this; it's free; the next lines will cost you serious credits
667print("Hello")
668print(" ")
669print("World")
670print("!")

Codefence with Title

```py { title="python" }
# a bit shorter
print("Hello World!")
```

# a bit shorter
print("Hello World!")

With Wrap

{{< highlight type="py" wrap="true" hl_lines="2" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff

Without Wrap

{{< highlight type="py" wrap="false" hl_lines="2" >}}
# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff
{{< /highlight >}}

# Quicksort Python One-liner
lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])
# Some more stuff

Icon

The icon shortcode displays icons using the Font Awesome library.

Usage

While the examples are using shortcodes with positional parameter you are free to also call this shortcode from your own partials.

{{% icon icon="exclamation-triangle" %}}
{{% icon icon="angle-double-up" %}}
{{% icon icon="skull-crossbones" %}}

{{% icon exclamation-triangle %}}
{{% icon angle-double-up %}}
{{% icon skull-crossbones %}}

{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "exclamation-triangle"
)}}
{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "angle-double-up"
)}}
{{ partial "shortcodes/icon.html" (dict
    "page" .
    "icon" "skull-crossbones"
)}}

Parameter

Name	Position	Default	Notes
icon	1	<empty>	Font Awesome icon name to be displayed. It will be displayed in the text color of its according context.

Finding an icon

Browse through the available icons in the Font Awesome Gallery. Notice that the free filter is enabled, as only the free icons are available by default.

Once on the Font Awesome page for a specific icon, for example the page for the heart, copy the icon name and paste into the Markdown content.

Customising Icons

Font Awesome provides many ways to modify the icon

Change color (by default the icon will inherit the parent color)
Increase or decrease size
Rotate
Combine with other icons

Check the full documentation on web fonts with CSS for more.

Examples

Standard Usage

Built with {{% icon heart %}} by Relearn and Hugo

Built with by Relearn and Hugo

Advanced HTML Usage

While the shortcode simplifies using standard icons, the icon customization and other advanced features of the Font Awesome library require you to use HTML directly. Paste the <i> HTML into markup, and Font Awesome will load the relevant icon.

Built with <i class="fas fa-heart"></i> by Relearn and Hugo

Built with by Relearn and Hugo

To use these native HTML elements in your Markdown, add this in your hugo.toml:

[markup.goldmark.renderer]
    unsafe = true

Include

The include shortcode includes other files from your project inside of the current page.

Usage

While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.

{{% include file="shortcodes/include/INCLUDE_ME.md" %}}

{{% include "shortcodes/include/INCLUDE_ME.md" %}}

{{ partial "shortcodes/include .html" (dict
  "page" .
  "file" "shortcodes/include/INCLUDE_ME.md"
)}}

The included files can even contain Markdown and will be taken into account when generating the table of contents.

Parameter

Name	Position	Default	Notes
file	1	<empty>	The path to the file to be included. Path resolution adheres to Hugo’s build-in `readFile` function
hidefirstheading	2	`false`	When `true` and the included file contains headings, the first heading will be hidden. This comes in handy, eg. if you include otherwise standalone Markdown files.

Examples

Arbitrary Content

{{% include "shortcodes/include/INCLUDE_ME.md" %}}

You can add standard markdown syntax:

multiple paragraphs
bullet point lists
emphasized, bold and even bold emphasized text
links
etc.¹

...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work)

Et Cetera (English: /ɛtˈsɛtərə/), abbreviated to etc., etc, et cet., is a Latin expression that is used in English to mean “and other similar things”, or “and so forth” ↩︎

Math

The math shortcode generates beautiful formatted math and chemical formulae using the MathJax library.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Usage

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Math codefences (eg. GitHub) and so your markdown becomes more portable.

You are free to also call this shortcode from your own partials.

Math is also usable without enclosing it in a shortcode or codefence but requires configuration by you. In this case no parameter from the below table are available.

```math { align="center" }
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```

{{< math align="center" >}}
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
{{< /math >}}

{{ partial "shortcodes/math.html" (dict
  "page"    .
  "content" "$$left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$"
  "align"   "center"
)}}

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Parameter

Name	Default	Notes
align	`center`	Allowed values are `left`, `center` or `right`.
<content>	<empty>	Your formulae.

Configuration

MathJax is configured with default settings but you can customize MathJax’s default settings for all of your files through a JSON object in your hugo.toml or override these settings per page through your pages frontmatter.

The JSON object of your hugo.toml / frontmatter is forwarded into MathJax’s configuration object.

See MathJax documentation for all allowed settings.

Global Configuration File

This example reflects the default configuration also used if you don’t define mathJaxInitialize

hugo.

[params]
  mathJaxInitialize = '{ "tex": { "inlineMath": [["\(", "\)"], ["$", "$"]], displayMath: [["\[", "\]"], ["$$", "$$"]] }, "options": { "enableMenu": false }'

params:
  mathJaxInitialize: '{ "tex": { "inlineMath": [["\(", "\)"], ["$", "$"]], displayMath:
    [["\[", "\]"], ["$$", "$$"]] }, "options": { "enableMenu": false }'

{
   "params": {
      "mathJaxInitialize": "{ \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"$\", \"$\"]], displayMath: [[\"\\[\", \"\\]\"], [\"$$\", \"$$\"]] }, \"options\": { \"enableMenu\": false }"
   }
}

Page’s Frontmatter

Usually you don’t need to redefine the global initialization settings for a single page. But if you do, you have repeat all the values from your global configuration you want to keep for a single page as well.

Eg. If you have redefined the delimiters to something exotic like @ symbols in your global config, but want to additionally align your math to the left for a specific page, you have to put this to your frontmatter:

+++
mathJaxInitialize = '{ "chtml": { "displayAlign": "left" }, { "tex": { "inlineMath": [["\(", "\)"], ["@", "@"]], displayMath: [["\[", "\]"], ["@@", "@@"]] }, "options": { "enableMenu": false }'
+++

---
mathJaxInitialize: '{ "chtml": { "displayAlign": "left" }, { "tex": { "inlineMath":
  [["\(", "\)"], ["@", "@"]], displayMath: [["\[", "\]"], ["@@", "@@"]] }, "options":
  { "enableMenu": false }'
---

{
   "mathJaxInitialize": "{ \"chtml\": { \"displayAlign\": \"left\" }, { \"tex\": { \"inlineMath\": [[\"\\(\", \"\\)\"], [\"@\", \"@\"]], displayMath: [[\"\\[\", \"\\]\"], [\"@@\", \"@@\"]] }, \"options\": { \"enableMenu\": false }"
}

Passthrough Configuration

You can use your math without enclosing it in a shortcode or codefence by using a passthrough configuration in your hugo.toml:

hugo.

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true

        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)'], ['$', '$']]

markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
          - - $
            - $
        enable: true

{
   "markup": {
      "goldmark": {
         "extensions": {
            "passthrough": {
               "delimiters": {
                  "block": [
                     [
                        "\\[",
                        "\\]"
                     ],
                     [
                        "$$",
                        "$$"
                     ]
                  ],
                  "inline": [
                     [
                        "\\(",
                        "\\)"
                     ],
                     [
                        "$",
                        "$"
                     ]
                  ]
               },
               "enable": true
            }
         }
      }
   }
}

In this case you have to tell the theme that your page contains math by setting this in your page’s frontmatter:

+++
disableMathJax = false
+++

---
disableMathJax: false
---

{
   "disableMathJax": false
}

See the example on how it makes using math really easy.

Examples

Inline Math

Inline math is generated if you use a single `$` as a delimiter around your formulae: {{< math >}}$\sqrt{3}${{< /math >}}

Inline math is generated if you use a single $ as a delimiter around your formulae: $\sqrt{3}$

Blocklevel Math with Right Alignment

If you delimit your formulae by two consecutive `$$` it generates a new block.

{{< math align="right" >}}
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
{{< /math >}}

If you delimit your formulae by two consecutive $$ it generates a new block.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Codefence

You can also use codefences.

```math
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Passthrough

This works for block as well as inline math but is only available if you are using the passthrough configuration.

With passthrough configuration you can just drop your math without enclosed by shortcodes or codefences but no settings from the parameter table are available.

$$\left|
\begin{array}{cc}
a & b \\
c & d
\end{array}\right|$$

$$\left| \begin{array}{cc} a & b \ c & d \end{array}\right|$$

Chemical Formulae

{{< math >}}
$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
{{< /math >}}

$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$

Mermaid

The mermaid shortcode generates diagrams and flowcharts from text, in a similar manner as Markdown using the Mermaid library.

graph LR;
    If --> Then
    Then --> Else

Usage

While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports Mermaid codefences (eg. GitHub) and so your markdown becomes more portable.

You are free to also call this shortcode from your own partials.

```mermaid { align="center" zoom="true" }
graph LR;
    If --> Then
    Then --> Else
```

{{< mermaid align="center" zoom="true" >}}
graph LR;
    If --> Then
    Then --> Else
{{< /mermaid >}}

{{ partial "shortcodes/mermaid.html" (dict
  "page"    .
  "content" "graph LR;\nIf --> Then\nThen --> Else"
  "align"   "center"
  "zoom"    "true"
)}}

The generated graphs can be panned by dragging them and zoomed by using the mousewheel. On mobile devices you can use finger gestures.

Parameter

Name	Default	Notes
align	`center`	Allowed values are `left`, `center` or `right`.
zoom	see notes	Whether the graph is pan- and zoomable. If not set the value is determined by the `mermaidZoom` setting of the site or the pages frontmatter or `false` if not set at all. - `false`: no pan or zoom - `true`: pan and zoom active
<content>	<empty>	Your Mermaid graph.

Configuration

Mermaid is configured with default settings. You can customize Mermaid’s default settings for all of your files through a JSON object in your hugo.toml, override these settings per page through your pages frontmatter or override these setting per diagramm through diagram directives.

The JSON object of your hugo.toml / frontmatter is forwarded into Mermaid’s mermaid.initialize() function.

See Mermaid documentation for all allowed settings.

The theme setting can also be set by your used color variant. This will be the sitewide default and can - again - be overridden by your settings in hugo.toml, frontmatter or diagram directives.

Global Configuration File

hugo.

[params]
  mermaidInitialize = '{ "theme": "dark" }'
  mermaidZoom = true

params:
  mermaidInitialize: '{ "theme": "dark" }'
  mermaidZoom: true

{
   "params": {
      "mermaidInitialize": "{ \"theme\": \"dark\" }",
      "mermaidZoom": true
   }
}

Page’s Frontmatter

+++
mermaidInitialize = '{ "theme": "dark" }'
mermaidZoom = true
+++

---
mermaidInitialize: '{ "theme": "dark" }'
mermaidZoom: true
---

{
   "mermaidInitialize": "{ \"theme\": \"dark\" }",
   "mermaidZoom": true
}

Examples

Flowchart with YAML-Title

{{< mermaid >}}
---
title: Example Diagram
---
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{<strong>Decision</strong>}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{< /mermaid >}}

---
title: Example Diagram
---
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{<strong>Decision</strong>}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Sequence Diagram with Configuration Directive

{{< mermaid >}}
%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
{{< /mermaid >}}

%%{init:{"fontFamily":"monospace", "sequence":{"showSequenceNumbers":true}}}%%
sequenceDiagram
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Class Diagram with Codefence Syntax

```mermaid
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }
```

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

State Diagram Aligned to the Right

{{< mermaid align="right" >}}
stateDiagram-v2
    open: Open Door
    closed: Closed Door
    locked: Locked Door
    open   --> closed: Close
    closed --> locked: Lock
    locked --> closed: Unlock
    closed --> open: Open
{{< /mermaid >}}

stateDiagram-v2
  open: Open Door
  closed: Closed Door
  locked: Locked Door
  open   --> closed: Close
  closed --> locked: Lock
  locked --> closed: Unlock
  closed --> open: Open

Entity Relationship Model with Non-Default Mermaid Theme

{{< mermaid >}}
%%{init:{"theme":"forest"}}%%
erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"
{{< /mermaid >}}

%%{init:{"theme":"forest"}}%%
erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"

User Journey

{{< mermaid >}}
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me
{{< /mermaid >}}

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me

GANTT Chart

{{< mermaid >}}
gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to Mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2              :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to Mermaid                      :1d
{{< /mermaid >}}

gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to Mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2              :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to Mermaid                      :1d

Pie Chart without Zoom

{{< mermaid zoom="false" >}}
pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
{{< /mermaid >}}

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

Quadrant Chart

{{< mermaid >}}
pie title Pets adopted by volunteers
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]
{{< /mermaid >}}

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]

Requirement Diagram

{{< mermaid >}}
    requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req
{{< /mermaid >}}

    requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req

Git Graph

{{< mermaid >}}
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit
{{< /mermaid >}}

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

C4 Diagrams

{{< mermaid >}}
C4Context
    title System Context diagram for Internet Banking System
    Enterprise_Boundary(b0, "BankBoundary0") {
    Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
    Person(customerB, "Banking Customer B")
    Person_Ext(customerC, "Banking Customer C", "desc")

    Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

    System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

    Enterprise_Boundary(b1, "BankBoundary") {

        SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

        System_Boundary(b2, "BankBoundary2") {
        System(SystemA, "Banking System A")
        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
        }

        System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
        SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

        Boundary(b3, "BankBoundary3", "boundary") {
        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
        }
    }
    }

    BiRel(customerA, SystemAA, "Uses")
    BiRel(SystemAA, SystemE, "Uses")
    Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
    Rel(SystemC, customerA, "Sends e-mails to")

    UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
    UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
    UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
    UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
    UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
{{< /mermaid >}}

C4Context
    title System Context diagram for Internet Banking System
    Enterprise_Boundary(b0, "BankBoundary0") {
    Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
    Person(customerB, "Banking Customer B")
    Person_Ext(customerC, "Banking Customer C", "desc")

    Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

    System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

    Enterprise_Boundary(b1, "BankBoundary") {

        SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

        System_Boundary(b2, "BankBoundary2") {
        System(SystemA, "Banking System A")
        System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
        }

        System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
        SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

        Boundary(b3, "BankBoundary3", "boundary") {
        SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
        SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
        }
    }
    }

    BiRel(customerA, SystemAA, "Uses")
    BiRel(SystemAA, SystemE, "Uses")
    Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
    Rel(SystemC, customerA, "Sends e-mails to")

    UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
    UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
    UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
    UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
    UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Mindmaps

{{< mermaid >}}
mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid
{{< /mermaid >}}

mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

Timeline

{{< mermaid >}}
timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : Youtube
    2006 : Twitter
{{< /mermaid >}}

timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : Youtube
    2006 : Twitter

Sankey

{{< mermaid >}}
sankey-beta

%% source,target,value
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
{{< /mermaid >}}

sankey-beta

%% source,target,value
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14

XYChart

{{< mermaid >}}
xychart-beta
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
{{< /mermaid >}}

xychart-beta
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]

Block Diagram

{{< mermaid >}}
block-beta
columns 1
  db(("DB"))
  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
  block:ID
    A
    B["A wide one in the middle"]
    C
  end
  space
  D
  ID --> D
  C --> D
  style B fill:#969,stroke:#333,stroke-width:4px
{{< /mermaid >}}

block-beta
columns 1
  db(("DB"))
  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
  block:ID
    A
    B["A wide one in the middle"]
    C
  end
  space
  D
  ID --> D
  C --> D
  style B fill:#969,stroke:#333,stroke-width:4px

Notice

The notice shortcode shows various types of disclaimers with adjustable color, title and icon to help you structure your page.

There may be pirates

It is all about the boxes.

Usage

While the examples are using shortcodes with named parameter you are free to use positional as well or also call this shortcode from your own partials.

{{% notice style="primary" title="There may be pirates" icon="skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}

{{% notice primary "There may be pirates" "skull-crossbones" %}}
It is all about the boxes.
{{% /notice %}}

{{ partial "shortcodes/notice.html" (dict
  "page"  .
  "style" "primary"
  "title" "There may be pirates"
  "icon" "skull-crossbones"
  "content" "It is all about the boxes."
)}}

Parameter

Name	Position	Default	Notes
style	1	`default`	The style scheme used for the box. - by severity: `info`, `note`, `tip`, `warning` - by brand color: `primary`, `secondary`, `accent` - by color: `blue`, `green`, `grey`, `orange`, `red` - by special color: `default`, `transparent`, `code`
color		see notes	The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default. - for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
title	2	see notes	Arbitrary text for the box title. Depending on the style there may be a default title. Any given value will overwrite the default. - for severity styles: the matching title for the severity - for all other styles: <empty> If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
icon	3	see notes	Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default. - for severity styles: a nice matching icon for the severity - for all other styles: <empty> If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
<content>		<empty>	Arbitrary text to be displayed in box.

Examples

By Severity

Info with markup

{{% notice style="info" %}}
An **information** disclaimer

You can add standard markdown syntax:

- multiple paragraphs
- bullet point lists
- _emphasized_, **bold** and even ***bold emphasized*** text
- [links](https://example.com)
- etc.

```plaintext
...and even source code
```

> the possibilities are endless (almost - including other shortcodes may or may not work)
{{% /notice %}}

Info

An information disclaimer

You can add standard markdown syntax:

multiple paragraphs
bullet point lists
emphasized, bold and even bold emphasized text
links
etc.

...and even source code

the possibilities are endless (almost - including other shortcodes may or may not work)

Note

{{% notice style="note" %}}
A **notice** disclaimer
{{% /notice %}}

Note

A notice disclaimer

Tip

{{% notice style="tip" %}}
A **tip** disclaimer
{{% /notice %}}

Tip

A tip disclaimer

Warning

{{% notice style="warning" %}}
A **warning** disclaimer
{{% /notice %}}

Warning

A warning disclaimer

Warning with Non-Default Title and Icon

{{% notice style="warning" title="Here are dragons" icon="dragon" %}}
A **warning** disclaimer
{{% /notice %}}

Here are dragons

A warning disclaimer

Warning without a Title and Icon

{{% notice style="warning" title=" " icon=" " %}}
A **warning** disclaimer
{{% /notice %}}

A warning disclaimer

By Brand Colors

Primary with Title only

{{% notice style="primary" title="Primary" %}}
A **primary** disclaimer
{{% /notice %}}

Primary

A primary disclaimer

Secondary with Icon only

{{% notice style="secondary" icon="stopwatch" %}}
A **secondary** disclaimer
{{% /notice %}}

A secondary disclaimer

Accent

{{% notice style="accent" %}}
An **accent** disclaimer
{{% /notice %}}

An accent disclaimer

By Color

Blue without a Title and Icon

{{% notice style="blue" %}}
A **blue** disclaimer
{{% /notice %}}

A blue disclaimer

Green with Title only

{{% notice style="green" title="Green" %}}
A **green** disclaimer
{{% /notice %}}

Green

A green disclaimer

Grey with Icon only

{{% notice style="grey" icon="bug" %}}
A **grey** disclaimer
{{% /notice %}}

A grey disclaimer

Orange with Title and Icon

{{% notice style="orange" title="Orange" icon="bug" %}}
A **orange** disclaimer
{{% /notice %}}

Orange

A orange disclaimer

Red without a Title and Icon

{{% notice style="red" %}}
A **red** disclaimer
{{% /notice %}}

A red disclaimer

By Special Color

Default with Positional Parameter

{{% notice default "Pay Attention to this Note!" "skull-crossbones" %}}
Some serious information.
{{% /notice %}}

Pay Attention to this Note!

Some serious information.

Transparent with Title and Icon

{{% notice style="transparent" title="Pay Attention to this Note!" icon="skull-crossbones" %}}
Some serious information.
{{% /notice %}}

Pay Attention to this Note!

Some serious information.

With User-Defined Color, Font Awesome Brand Icon and Markdown Title

{{% notice color="fuchsia" title="**Hugo**" icon="fa-fw fab fa-hackerrank" %}}
Victor? Is it you?
{{% /notice %}}

Hugo

Victor? Is it you?

OpenAPI

The openapi shortcode uses the Swagger UI library to display your OpenAPI / Swagger specifications.

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{< openapi src="https://petstore3.openapi.io/api/v3/openapi.json" >}}

{{ partial "shortcodes/openapi.html" (dict
  "page" .
  "src"  "https://petstore3.openapi.io/api/v3/openapi.json"
)}}

Parameter

Name	Default	Notes
src	<empty>	The URL to the OpenAPI specification file. This can be relative to the URL of your page if it is a leaf or branch bundle.

Note

If you want to print out (or generate a PDF) from your OpenAPI documentation, don’t initiate printing directly from the page because the elements are optimized for interactive usage in a browser.

Instead, open the print preview in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.

Example

Using Local File

{{< openapi src="petstore.json" >}}

Resources

The resources shortcode displays the titles of resources contained in a page bundle.

Attachments

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% resources sort="asc" /%}}

{{ partial "shortcodes/resources.html" (dict
  "page" .
  "sort" "asc"
)}}

Multilanguage features are not supported directly by the shortcode but rely on Hugo’s handling for resource translations applied when the theme iterates over all available resources.

Parameter

Name	Default	Notes
style	`transparent`	The style scheme used for the box. - by severity: `info`, `note`, `tip`, `warning` - by brand color: `primary`, `secondary`, `accent` - by color: `blue`, `green`, `grey`, `orange`, `red` - by special color: `default`, `transparent`, `code`
color	see notes	The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default. - for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
title	see notes	Arbitrary text for the box title. Depending on the style there may be a default title. Any given value will overwrite the default. - for severity styles: the matching title for the severity - for all other styles: `Resources` If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
icon	see notes	Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default. - for severity styles: a nice matching icon for the severity - for all other styles: `paperclip` If you want no icon, you have to set this parameter to `" "` (a non empty d with spaces)
sort	`asc`	Sorting the output in `asc`ending or `desc`ending order.
pattern	`.*`	A regular expressions, used to filter the resources by name. For example: - to match a file suffix of ‘jpg’, use `.\.jpg` (not `.\.jpg`) - to match file names ending in `jpg` or `png`, use `.*\.(jpg\|png)`

Examples

Custom Title, List of Resources Ending in png, jpg or gif

{{% resources title="Related **files**" pattern=".*\.(png|jpg|gif)" /%}}

Related files

hugo.png (17 KB)

Info Styled Box, Descending Sort Order

{{% resources style="info" sort="desc" /%}}

Info

With User-Defined Color and Font Awesome Brand Icon

{{% resources color="fuchsia" icon="fa-fw fab fa-hackerrank" /%}}

Attachments

Style, Color, Title and Icons

For further examples for style, color, title and icon, see the notice shortcode documentation. The parameter are working the same way for both shortcodes, besides having different defaults.

SiteParam

The siteparam shortcode prints values of site params.

Usage

While the examples are using shortcodes with named parameter you are free to use positional as well or call this shortcode from your own partials.

{{% siteparam name="editURL" %}}

{{% siteparam "editURL" %}}

{{ partial "shortcodes/siteparam.html" (dict
  "page" .
  "name" "editURL"
)}}

Parameter

Name	Position	Default	Notes
name	1	<empty>	The name of the site param to be displayed.

Examples

`editURL` from `hugo.toml`

`editURL` value: {{% siteparam name="editURL" %}}

editURL value: https://github.com/russfeld/ksucs-hugo/edit/master/content/${FilePath}

Nested parameter with Markdown and HTML formatting

To use formatted parameter, add this in your hugo.toml:

hugo.

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

markup:
  goldmark:
    renderer:
      unsafe: true

{
   "markup": {
      "goldmark": {
         "renderer": {
            "unsafe": true
         }
      }
   }
}

Now values containing Markdown will be formatted correctly.

hugo.

[params]
  [params.siteparam]
    [params.siteparam.test]
      text = 'A **nested** parameter <b>with</b> formatting'

params:
  siteparam:
    test:
      text: A **nested** parameter <b>with</b> formatting

{
   "params": {
      "siteparam": {
         "test": {
            "text": "A **nested** parameter \u003cb\u003ewith\u003c/b\u003e formatting"
         }
      }
   }
}

Formatted parameter: {{% siteparam name="siteparam.test.text" %}}

Formatted parameter:

Tab

You can use a tab shortcode to display a single tab.

This is especially useful if you want to flag your code example with an explicit language.

If you want multiple tabs grouped together you can wrap your tabs into the tabs shortcode.

printf("Hello World!");

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

{{% tab title="c" %}}
```c
printf("Hello World!");
```
{{% /tab %}}

{{ partial "shortcodes/tab.html" (dict
  "page"  .
  "title" "c"
  "content" ("```c\nprintf(\"Hello World!\")\n```" | .RenderString)
)}}

Parameter

Name	Default	Notes
style	see notes	The style scheme used for the tab. If you don’t set a style and you display a single code block inside of the tab, its default styling will adapt to that of a `code` block. Otherwise `default` is used. - by severity: `info`, `note`, `tip`, `warning` - by brand color: `primary`, `secondary`, `accent` - by color: `blue`, `green`, `grey`, `orange`, `red` - by special color: `default`, `transparent`, `code`
color	see notes	The CSS color value to be used. If not set, the chosen color depends on the style. Any given value will overwrite the default. - for severity styles: a nice matching color for the severity - for all other styles: the corresponding color
title	see notes	Arbitrary title for the tab. Depending on the style there may be a default title. Any given value will overwrite the default. - for severity styles: the matching title for the severity - for all other styles: <empty> If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
icon	see notes	Font Awesome icon name set to the left of the title. Depending on the style there may be a default icon. Any given value will overwrite the default. - for severity styles: a nice matching icon for the severity - for all other styles: <empty> If you want no icon for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces)
<content>	<empty>	Arbitrary text to be displayed in the tab.

Examples

Single Code Block with Collapsed Margins

{{% tab title="Code" %}}
```python
printf("Hello World!");
```
{{% /tab %}}

printf("Hello World!");

Mixed Markdown Content

{{% tab title="_**Mixed**_" %}}
A tab can not only contain code but arbitrary text. In this case text **and** code will get a margin.
```python
printf("Hello World!");
```
{{% /tab %}}

A tab can not only contain code but arbitrary text. In this case text and code will get a margin.

printf("Hello World!");

Understanding `style` and `color` Behavior

The style parameter affects how the color parameter is applied.

{{< tabs >}}
{{% tab title="just colored style" style="blue" %}}
The `style` parameter is set to a color style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant.
{{% /tab %}}
{{% tab title="just color" color="blue" %}}
Only the `color` parameter is set.

This will set the background to a lighter version of the chosen CSS color value.
{{% /tab %}}
{{% tab title="default style and color" style="default" color="blue" %}}
The `style` parameter affects how the `color` parameter is applied.

The `default` style will set the background to your `--MAIN-BG-color` as configured for your theme variant resembling the default style but with different color.
{{% /tab %}}
{{% tab title="just severity style" style="info" %}}
The `style` parameter is set to a severity style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.
{{% /tab %}}
{{% tab title="severity style and color" style="info" color="blue" %}}
The `style` parameter affects how the `color` parameter is applied.

This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.
{{% /tab %}}
{{< /tabs >}}

The style parameter is set to a color style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant.

Only the color parameter is set.

This will set the background to a lighter version of the chosen CSS color value.

The style parameter affects how the color parameter is applied.

The default style will set the background to your --MAIN-BG-color as configured for your theme variant resembling the default style but with different color.

The style parameter is set to a severity style.

This will set the background to a lighter version of the chosen style color as configured in your theme variant and also affects the chosen icon.

The style parameter affects how the color parameter is applied.

This will set the background to a lighter version of the chosen CSS color value and also affects the chosen icon.

Tabs

The tabs shortcode displays arbitrary content in an unlimited number of tabs.

This comes in handy eg. for providing code snippets for multiple languages.

If you just want a single tab you can instead call the tab shortcode standalone.

hello.

print("Hello World!")

echo "Hello World!"

printf("Hello World!");

Usage

While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.

See the tab shortcode for a description of the parameter for nested tabs.

{{< tabs title="hello." >}}
{{% tab title="py" %}}
```python
print("Hello World!")
```
{{% /tab %}}
{{% tab title="sh" %}}
```bash
echo "Hello World!"
```
{{% /tab %}}
{{% tab title="c" %}}
```c
printf"Hello World!");
```
{{% /tab %}}
{{< /tabs >}}

{{ partial "shortcodes/tabs.html" (dict
  "page"  .
  "title" "hello."
  "content" (slice
    (dict
      "title" "py"
      "content" ("```python\nprint(\"Hello World!\")\n```" | .RenderString)
    )
    (dict
      "title" "sh"
      "content" ("```bash\necho \"Hello World!\"\n```" | .RenderString)
    )
    (dict
      "title" "c"
      "content" ("```c\nprintf(\"Hello World!\");\n```" | .RenderString)
    )
  )
)}}

Parameter

Name	Default	Notes
groupid	<random>	Arbitrary name of the group the tab view belongs to. Tab views with the same groupid sychronize their selected tab. The tab selection is restored automatically based on the `groupid` for tab view. If the selected tab can not be found in a tab group the first tab is selected instead. This sychronization applies to the whole site!
style	<empty>	Sets a default value for every contained tab. Can be overridden by each tab. See the `tab` shortcode for possible values.
color	<empty>	Sets a default value for every contained tab. Can be overridden by each tab. See the `tab` shortcode for possible values.
title	<empty>	Arbitrary title written in front of the tab view.
icon	<empty>	Font Awesome icon name set to the left of the title.
<content>	<empty>	Arbitrary number of tabs defined with the `tab` sub-shortcode.

Examples

Behavior of the `groupid`

See what happens to the tab views while you select different tabs.

While pressing a tab of Group A switches all tab views of Group A in sync (if the tab is available), the tabs of Group B are left untouched.

{{< tabs groupid="a" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="_**XML**_ stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab title="text" %}}
    Hello World
{{% /tab %}}
{{< /tabs >}}

{{< tabs groupid="a" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}

{{< tabs groupid="b" >}}
{{% tab title="json" %}}
{{< highlight json "linenos=true" >}}
{ "Hello": "World" }
{{< /highlight >}}
{{% /tab %}}
{{% tab title="XML stuff" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{< /tabs >}}

Group A, Tab View 1

1{ "Hello": "World" }

<Hello>World</Hello>

Hello World

Group A, Tab View 2

1{ "Hello": "World" }

<Hello>World</Hello>

Group B

1{ "Hello": "World" }

<Hello>World</Hello>

Nested Tab Views and Color

In case you want to nest tab views, the parent tab that contains nested tab views needs to be declared with {{< tab >}} instead of {{% tab %}}. Note, that in this case it is not possible to put markdown in the parent tab.

You can also set style and color parameter for all tabs and overwrite them on tab level. See the tab shortcode for possible values.

{{< tabs groupid="main" style="primary" title="Rationale" icon="thumbtack" >}}
{{< tab title="Text" >}}
  Simple text is possible here...
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab title="python" %}}
  Python is **super** easy.

  - most of the time.
  - if you don't want to output unicode
  {{% /tab %}}
  {{% tab title="bash" %}}
  Bash is for **hackers**.
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}

{{< tab title="Code" style="default" color="darkorchid" >}}
  ...but no markdown
  {{< tabs groupid="tabs-example-language" >}}
  {{% tab title="python" %}}
  ```python
  print("Hello World!")
  ```
  {{% /tab %}}
  {{% tab title="bash" %}}
  ```bash
  echo "Hello World!"
  ```
  {{% /tab %}}
  {{< /tabs >}}
{{< /tab >}}
{{< /tabs >}}

Rationale

Simple text is possible here...

Python is super easy.

most of the time.
if you don’t want to output unicode

Bash is for hackers.

...but no markdown

print("Hello World!")

echo "Hello World!"

Chapter 5

Features

Features of the KSUCS Hugo Theme

Dark Mode

This site supports a “dark mode” CSS feature. It is implemented through the variant selector in the menu to the left

Embed & Teleprompter

This site also creates two additional outputs of each page, also accessible from the upper toolbar:

- Teleprompter View (add tele.html to the URL)
- Embedded View (add embed.html to the URL)

Teleprompter View

The teleprompter view is intended to be used on a mirrored teleprompter. It uses some customized CSS in custom.css.

It also includes JavaScript code to handle automatically scrolling the page by clicking the mouse, and mirroring/unmirroring the output using the m button. Other buttons are programmed to match an IKAN bluetooth remote. See tele-scroll.js for details.

It also uses an override for the Hugo YouTube shortcode to hide any embedded YouTube videos. See /layouts/shortcodes/youtube.tele.html.

Embedded View

The embedded view renders the page without any additional navigation elements. This view is meant to be embedded in an <iframe> directly in another site, such as an LMS. It also removes any noiframe notices. See custom.css for details.

Line Numbers

Some code line numbering and highlighting can be enabled directly through the Highlight shortcode.

142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
function setAutoScroll(newValue) {
    if (newValue) {
        autoScrollSpeed = speedFactor * newValue;
    }
    if (autoScrollTimer) {
      clearInterval(autoScrollTimer);
    }
    autoScrollTimer = setInterval(function(){
        currentTime = Date.now();
        if (prevTime) {
            if (!isScrolling) {
                timeDiff = currentTime - prevTime;
                currentPos += autoScrollSpeed * timeDiff;
                if (Math.abs(currentPos - prevPos) >= minDelta) {
                    isScrolling = true;
                    elem = document.getElementById("body-inner");
                    elem.scrollTo(0, currentPos);
                    isScrolling = false;
                    prevPos = currentPos;
                    prevTime = currentTime;
                }
            }
        } else {
            prevTime = currentTime;
            isScrolling = false;
        }
    }, 1000 / fps);
}

Chapter 6

Playground

A folder for testing and publishing demo work.

Sample Script

Resources

Slides

Salutations! My name is Russell Feldhausen, and currently it is my honor to serve as the vice president of the All Souls Board of Trustees. At our October board meeting, we approved a plan to return to in-person services starting on November 7th. We also set a goal to clearly communicate about this process to the congregation. So, in that spirit, here is some information about our current plan for in-person services. As many of you know, I work in education, so please forgive me as I slip into “teacher mode” for a bit to share all of this information.

First, we are tracking the risk level metric for the Kansas City Metro Area on Covid Act Now as our metric for determining whether it is safe to hold in-person services. That metric includes data from 14 area counties, and aggregates many data points together in a single value. If the risk level is Low, Medium, or High, we will be open for in-person services. However, if the risk value increases to Very High or Severe, we will immediately cease in-person services. If that happens, we’ll send out a notice to everyone.

As part of this plan, we are taking several precautions to protect all of our members from unnecessary exposure and risk. This plan is still constantly evolving, and we’ll be making changes from time to time. In addition, we hope that many of these precautions will be temporary, and we can continue to reduce them as the risk level improves.

Current precautions:

Masks are required for anyone 3 and up
Proof of full vaccination required for anyone 12 and up. We will follow CDC recommendations, so if they update those recommendations to include booster shots, we’ll aim to comply with that.
No food or drink. We won’t be serving coffee or snacks, and we ask you not to bring your own. Save that coffee run for after service!
Anyone who feels ill or has symptoms associated with COVID-19 should stay home
We will have separate, designated spaces for various groups during service. More about that later
We will limit entry to the building to just the doors off the parking lot that lead into the lobby and Conover.
The facilities committees has worked to improve airflow and filtration in the building to reduce risk from airborne exposure
We’ll have plenty of masks and sanitizer available for anyone who needs it

Of course, there are some reasonable exceptions to these precautions for staff and persons participating from the stage during service.

Now, for the most important part - we will be requiring reservations to attend in-person Sunday services in Bragg, as well as to attend the in-person RE classes. This will help us maintain proper social distance and make sure we can set up proper seating and spaces for everyone. Again, we hope that this is a temporary restriction that can be relaxed as the risk level improves.

Each week, we’ll send out a link to an online form for reservations on the Monday prior to an in-person service. That form will allow you to choose from four different reservation types:

Assigned seating - each person or group will have assigned seats that are separated from other groups by 6 feet. This section will also be the furthest away from RE students and unmasked singers on the stage, so it is best for anyone who wishes to be more careful. This section is open to fully vaccinated adults and youth 12 and up.
Mingle seating - in this section, persons or groups will be able to move chairs around a bit to form new groups. By choosing this option, you indicate that you are OK with sitting next to other fully vaccinated people outside your household. This section is open to fully vaccinated adults and youth 12 and up.
Parents - parents who have regular contact with children under 12 will have their own section in Bragg. Those parents will enter the building through the Conover doors with the RE students, and should proceed directly to Bragg unless their child needs their presence in Conover. This will make it easy for RE teachers to locate parents if needed, and will minimize unnecessary exposure between sections
RE Students - RE students will sign up by age group. When they arrive through what I’ve been told will be an amazingly decorated door, they will meet their RE teachers in Conover. At the start of service, they will proceed as a group to Bragg and be present for the first part of the service. After that, they will follow their RE teachers back to other designated areas in the church.

You’ll also have the option to reserve a seat to watch the Forum. We’ll have a limited number of seats in a room set aside for watching Forum, but you’ll need to bring your own device if you want to ask questions via chat during Forum discussion.

We also understand that reservations will probably fill up, so our form will also have a waitlist option that you may choose. Persons on the waitlist will be notified if space becomes available throughout the week, and anyone remaining on the waitlist will be given priority and the first opportunity to make a reservation for the following week’s service.

All of this information will be posted to our website at http://allsoulskc.org/reservations. If you prefer to make your reservation via phone, you are welcome to call the church Monday through Friday between 10 AM and 3 PM and someone there would be happy to assist you.

As part of this process, we’ll need to verify full vaccination status for anyone 12 years and older who attends an in-person service. To simplify this process, there are a few ways to do this:

Online Form - we have an online form where you can upload a picture of your vaccination card. Once you’ve done that, we’ll have a record of it and can pre-print a nametag for your reservation that includes your vaccination status, so you’ll effectively have a fast-pass to enter the building when you arrive. You can find the online form on the Reservations website, or in the Flicker for the past several weeks.
In Person - you may bring your vaccination card, or a copy or picture of it, to church on Sunday and we’ll have someone there to verify it. Once we’ve done that once, again we’ll have a record of it for future services. If you plan to bring your card with you, we ask that you arrive before 11 AM to give us enough time to get everyone verified before service begins.
Privately - if you’d like to protect your information, we’ll also have a board member or other designated person on duty each Sunday that you can show your card to privately, and they’ll get you verified.

Any visitors who wish to join us are welcome to fill out the online reservation form as well. However, we will also reserve a few spaces for visitors to join us even without reservations. We want to be an open and welcoming church for all those who wish to join us so we can continue to grow. Of course, all visitors must also be masked and show proof of vaccination to enter the building.

Finally, we are in need of several volunteers to help us implement all of these precautions. As an incentive, volunteers will be able to attend most of the in-person service each week they are volunteering. If you’d like to volunteer, there is a form on our reservations page you can fill out, or feel free to contact a board member.

We understand that this is complex, and you may have questions that we haven’t answered yet. We are compiling a list of Frequently Asked Questions to be published to our website soon. So, if you have any questions at all, I invite you to email us at board@allsoulskc.org, or contact any board member. We’ll also be watching our Facebook page and group and participating in discussions there.

On behalf of the entire All Souls Board of Trustees, we thank you for your patience and support as we take this next step. It is truly a privilege to serve this community.

Chapter 7

Documentation

Helpful Documentation for K-State CS Textbooks

Textbook From Scratch

This gives the basic steps for creating a brand new Hugo textbook from scratch.

Basic Site Setup

The first steps come from the Hugo Quick Start Guide

Install Hugo from the Hugo Releases. You should have version 0.101.0 or higher.
Create a new site: hugo new site <sitename>.
Open the site’s directory: cd <sitename>.
Start a git repository: git init.
Add the theme: git submodule add https://github.com/ksu-cs-textbooks/hugo-theme-relearn themes/hugo-theme-relearn
Update the config.toml file:
1. Best way to start is simply to copy the config.toml file for the starter site. It is well documented.
2. Update the baseURL at the top to match the URL where the site will eventually be deployed.
3. Update the title to match the site’s name
4. Update the theme to be just theme = ["hugo-theme-relearn"] (remove the "plausible-hugo" part)
5. Under [params], update the following:
  1. editURL to match the location where files can be edited in GitLab or GitHub.
  2. author used for metadata
  3. description used for metadata
  4. commitURL to match the location where individual commits can be found.
  5. Most of the parameters are documented in the Hugo Theme Relearn Documentation
6. Remove the [params.plausible] section - it is not used by the textbooks site.
Preview the site using hugo serve. It will be available at the URL given in the output. If the site loads with default content, then it is working.

Additional Configuration

Perform a few additional steps to make things work smoothly.

Create a .gitignore file in the site’s base directory with the following content:

/public/
/resources/_gen
.hugo_build.lock

If you are using Visual Studio Code to edit the site, create a .vscode folder in the site’s base directory, and then a settings.json file inside of that directory with the following content to change the sort order of your editor’s file explorer:

{
    "explorer.sortOrder": "mixed"
}

GitLab Repository Setup

Once the site is working locally, set up a repository on the CS GitLab server to store the data.

We recommend storing the textbook in the CS Textbooks group. Contact another textbook author to get access.
Create a repository that matches your textbook name. Use the other repositories as a naming guide. Do not initialize the repository in GitLab by creating a README file.
1. You can choose to make your repository private (accessible only to the group), internal (accessible to anyone with a CS account), or public (accessible to anyone). Only those with permissions can update the repository (typically group members), but others may be able to view the content.
In the site directory on your local system, add the repository’s URL as a remote: git remote add origin <url>
Commit and push: git commit -m "Initial Commit" && git push -u origin main (substitute master for main if needed) 5. Make sure that you don’t commit the .hugo_build.lock file - it should be excluded via the .gitignore file created above.

Initial Content Creation

Now that the site is working, it is time to create some basic content.

Homepage

To create a home page, create a new _index.md file in the content directory. It should have at least the following content:

+++
archetype = "home"
title = "Homepage"
+++

Lorem Ipsum

You can also create this page using the command hugo new --kind home _index.md from the site’s directory and then modifying the content a bit.

See the Hugo Theme Relearn Documentation or Hugo Documentation for more on how to use the front matter of each page.

Chapter

To create a chapter, first create a folder with the chapter’s name in the content directory. We recommend including a number in front of the name to help with sorting, such as 01-introduction. Then, inside of that folder, create a new _index.md file with the following content:

+++
archetype = "chapter"
ordinal = "1"
title = "Introduction"
pre = "<b>1. </b>"
weight = 1
+++

Lorem Ipsum.

You can also create this page using the command hugo new --kind chapter 01-introduction/_index.md from the site’s directory and then modifying the content a bit.

Content Page

To create a content page, simply create a file inside of the desired directory with the .md file extension. Like chapters, we recommend adding a number in front of the file name to help with sorting, such as 01-welcome.md. Place the following content in the page:

---
title: "Welcome"
pre: "1. "
weight: 1
---

Lorem Ipsum.

You can also create this page using the command hugo new 01-introduction/01-welcome.md from the site’s directory and then modifying the content a bit.

Tip

Notice that the front matter for the homepage and chapters use plus symbols +++ as delimiters, while the content pages themselves use dashes --- instead. This is done by convention in this particular theme, and we follow that in this documentation. The plus symbols +++ indicate that the front matter is written in TOML while the dashes --- indicate that the front matter is written in YAML. The biggest difference is that TOML uses the equals symbol = for assignment, while YAML uses a colon : instead. See Front Matter Formats for more information.

Note

When creating this page using the command, it will add draft: true to the front matter. You’ll want to remove that so it appears on the site, or use hugo serve -D to include drafts files when previewing the site. It will also include the date, which can be safely removed - the theme will use the date of the latest commit to GitLab that includes this file instead.

Logo

The site right now uses a default logo based on the site’s title in config.toml. To override that, create a file at layouts/partials/logo.html in the site with the following content:

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
  Hugo Starter
</a>

Replace the text with the desired logo content. Alternatively, an image can be used. Place the image in the static/images/ folder and adapt the following HTML:

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
    <img src="/images/logo.png" alt="Logo" style="width: 100%">
</a>

The sidebar footer can also be overridden by creating a file at layouts/partials/menu-footer.html. It is best to simply copy the existing content in themes/hugo-theme-relearn/layouts/partials/menu-footer.html and edit it from that template.

Additional Content

From there, you can continue to create additional chapters and pages as needed. For more advanced content structures, look through the source code to this site. It includes examples for page bundles, leaf bundles, hidden pages, non-printable pages, syllabus pages, video content, historical content, and more.

Textbook From Starter

This gives the basic setup for a new textbook based on a starter repository.

Clone Starter Repository

Install Hugo from the Hugo Releases. You should have version 0.101.0 or higher.
Clone the Starter Repository on GitLab or GitHub to your local system: git clone <url> <directory>.
Open the site’s directory: cd <directory>.
Initialize git submodules: git submodule init.
Recursively pull submodules: git pull --recurse.
Update the config.toml file:
1. Update the baseURL at the top to match the URL where the site will eventually be deployed.
2. Update the title to match the site’s name
3. Under [params], update the following:
  1. editURL to match the location where files can be edited in GitLab or GitHub.
  2. author used for metadata
  3. description used for metadata
  4. commitURL to match the location where individual commits can be found.
  5. Most of the parameters are documented in the Hugo Theme Relearn Documentation
Preview the site using hugo serve. It will be available at the URL given in the output. If the site loads with default content, then it is working.

GitLab Repository Setup

Once the site is working locally, set up a repository on the CS GitLab server to store the data.

We recommend storing the textbook in the CS Textbooks group. Contact another textbook author to get access.
Create a repository that matches your textbook name. Use the other repositories as a naming guide. Do not initialize the repository in GitLab by creating a README file.
1. You can choose to make your repository private (accessible only to the group), internal (accessible to anyone with a CS account), or public (accessible to anyone). Only those with permissions can update the repository (typically group members), but others may be able to view the content.
In the site directory on your local system, add the repository’s URL as the new remote: git remote set-url origin <url>
Commit and push: git commit -m "Initial Commit" && git push -u origin main (substitute master for main if needed) 5. Make sure that you don’t commit the .hugo_build.lock file - it should be excluded via the .gitignore file in the initial repository.

Logo

The site right now uses a default logo based on the site’s title in config.toml. To override that, create a file at layouts/partials/logo.html in the site with the following content:

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
  Hugo Starter
</a>

Replace the text with the desired logo content. Alternatively, an image can be used. Place the image in the static/images/ folder and adapt the following HTML:

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
    <img src="/images/logo.png" alt="Logo" style="width: 100%">
</a>

Additional Content

The starter repository contains all of the basic content covered in the Textbook from Scratch page.

Deploying Textbook

This page gives the basic instructions for deploying a textbook to the server. It is mainly meant as a reference for the server’s administrators, but it is helpful for everyone to understand the process.

Clone Repository on Server

Log in to the server via SSH and switch to the textbooks account: sudo su textbooks.
Change directory to the textbooks user’s home directory: cd ~.
Clone the repository into this folder: git clone <url> <directory>.
Change directory to the textbook’s directory: cd <directory>.
Initialize submodules: git submodule init.
Recursively pull submodules: git pull --recurse.
Log out of the textbooks account: exit.

Set up Webhook on Server

Switch to the config account: sudo su config.
Change directory to the config user’s home directory: cd ~.
Edit the webhook/webhook.conf file to add a new webhook.
1. In general, just copy an existing webhook definition and edit to match the new site. Be Careful! The configuration file is JSON and is very picky about proper JSON syntax.
2. Webhook Documentation.
Save the file.
Log out of the config account: exit.
Restart webhook service: sudo systemctl restart webhook.

Example Webhook:

{
  "id": "hugo-starter",
  "execute-command": "/home/config/bin/deploy-101.sh",
  "command-working-directory": "/home/textbooks/hugo-starter/",
  "response-message": "Executing checkout script",
  "pass-arguments-to-command":
  [
    {
        "source": "string",
        "name": "hugo-starter"
    }
  ],
  "trigger-rule":
  {
    "match":
    {
      "type": "value",
      "value": "secret",
      "parameter":
      {
        "source": "header",
        "name": "X-Gitlab-Token"
      }
    }
  }
}

Items to configure:

id: this is the identifier for the webhook used in the URL
execute-command: see the scripts in the /home/config/bin directory.
command-working-directory: this is the directory where the textbook repository is stored.
- deploy.sh will use the default version of Hugo
- deploy-101.sh will use Hugo version 0.101.0
pass-arguments-to-command: this determines the folder where the content will be deployed. The name should match the URL desired (e.g. hugo-starter will deploy at https://textbooks.cs.ksu.edu/hugo-starter)
trigger-rule: is used to determine if the webhook request is valid. Change the value to match the key given when setting up the webhook in GitLab.

Set up Webhook on GitLab

Open the repository on GitLab and navigate to the Settings -> Webhooks menu.
Add a hook using the following settings:
URL: http://pacer.cs.ksu.edu:9000/hooks/<hook_id>
Secret Token: <secret>
Trigger: Push events
1. You can specify a specific branch; I typically leave this blank.
Uncheck SSL Verification - we currently don’t have an SSL certificate on the webhook server.
Click Add Webhook to save.
Once saved, click the Test option and choose Push Event to test it. It should quickly return HTTP 200 at the top of the page if it is working.

Update Permissions

After the first deployment, on the server, go to the web directory: cd /var/www/textbooks.cs.ksu.edu
Update the permissions on the new directory:
1. sudo chown -R textbooks:www-data <directory>
2. sudo chmod -R g+w <directory>

Update Homepage

Log in to the server via SSH and switch to the textbooks account: sudo su textbooks.
Edit the site’s homepage at /var/www/textbooks.cs.ksu.edu/index.html to include a link to the new site.
Save the file, and then log out of the textbooks account: exit.

Save Configuration

Switch to the config account: sudo su config.
Change directory to the config user’s home directory: cd ~.
Copy the updated index.html file to the nginx folder: cp /var/www/textbooks.cs.ksu.edu/index.html ~/nginx/.
Use git to commit and push the changes to the server configuration to GitLab.
1. The only files changed should be webhook/webhook.conf and nginx/index.html.
Log out of the config account: exit.

Notifications

Deployment notifications are sent to a Discord server. Contact one of the other textbook authors to get access to that Discord server. It is helpful if you want to see that your deployments are starting and completing correctly.

Debugging

Deployment logs are stored in the /home/textbooks/<name>.log file. This can be helpful for debugging.

Updating the Theme

From time to time, the underlying Hugo Theme Relearn clone may be updated. This page gives the directions for updating your textbook to the latest theme.

Save and commit any work done on the textbook and push to GitLab. Wait until the deployment completes before continuing.
In the site’s directory, open the themes/hugo-theme-relearn directory: cd themes/hugo-theme-relearn.
Check out the main branch of the theme if you haven’t already: git checkout main.
Pull the latest version of the theme: git pull.
Change directory back to the site’s directory: cd ../../.
Preview the changes: hugo serve.
If everything looks good, commit and push: git commit -m "Update Theme" && git push
1. It should show modified: themes/hugo-theme-relearn (new commits) when running git status to confirm that the theme is being updated.
The site should deploy with the new theme.

Setting Up Backups

To provide extra security, you can also set up a live backup of your textbook to be hosted on GitHub. This page gives the instructions for setting this up.

Create GitHub Repository

If you haven’t already, ask another textbook author to join the ksu-cs-textbooks organization on GitHub.
Create a new repository on the ksu-cs-textbooks organization on GitHub.
1. The name of the repository should match the desired URL for your textbook (e.g. https://ksu-cs-textbooks.github.io/<repo_name>)
2. Do not initialize the repository with a README file.
3. The repository itself should be private.

Mirror GitLab Repository to GitHub

On the CS GitLab Server, open the repository and go to the Settings -> Repository menu.
Expand the Mirroring Repositories section.
In the Git repository URL, enter the SSH URL for the GitHub repository in the box.
1. You must add ssh:// to the front of the repository, and also change the colon between the hostname and the organization name to a slash /.
2. For example, git@github.com:ksu-cs-textbooks/hugo-starter.git becomes ssh://git@github.com/ksu-cs-textbooks/hugo-starter.git
For Mirror Direction choose Push
Click the Detect Host Keys button. It should show a key fingerprint for GitHub in a few seconds. THIS IS IMPORTANT! There is no way to do this after the fact.
For Authentication Method choose SSH Public Key.
Do not check Keep divergent refs - since we don’t want to commit directly to GitHub, we don’t need this.
Checkmark Mirror only protected branches. Only the main or master branch will be mirrored.
Click Mirror Repository to save the settings.

Once that is done, you’ll need to add an SSH public key to your GitHub Account.

Click the Copy SSH Public Key button in the list of mirrored repositories on GitLab.

On GitHub, navigate to Settings -> SSH and GPG Keys
Click New SSH Key and paste that key. Give it a name like CS GitLab <Textbook> to help keep track of it.
Click Add SSH Key to save it.
Go back to GitLab, and click the Update Now button (right next to the Copy SSH Public Key button). That will try to mirror the repository. After a few seconds, you should see the content appear in GitHub.

Update the Website

In order to properly build the backup site on GitHub, several changes must be made to the existing website directory.

Create a folder .github to store GitHub specific configuration files.
Create the file .github/workflows/gh-pages.yml with the following content:

# https://github.com/peaceiris/actions-hugo

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.101.0'
          # extended: true

      - name: Build
        run: hugo -b "https://ksu-cs-textbooks.github.io/hugo-starter"

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Update the -b "https://ksu-cs-textbooks.github.io/hugo-starter" to match the URL where the site will be deployed (e.g. https://ksu-cs-textbooks.github.io/<repo_name>)

Update the two instances of main to master if needed to match your repository configuration. You can also update the value of the hugo-version variable to match your desired Hugo version.

Note

For more advanced configuration, copy config.toml to github.toml and then edit that file to update the baseURL and other settings. Update the command to hugo --config github.toml to use that configuration file for deployment on GitHub.

[Optional] Create the file .github/dependabot.yml with the following content:

version: 2
updates:
  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"
  # Git Submodules
  - package-ecosystem: "gitsubmodule"
    directory: "/"
    schedule:
      interval: "daily"

This will help keep any underlying GitHub actions updated, and it will also send emails when the theme has been updated.

Once these changes are made, commit and push them to GitLab. You should also see them mirrored to GitHub as well.

Configure GitHub Pages Environment

Now that the site has the required GitHub configuration, we need to set up GitHub Pages to deploy the rendered site.

Once the site is updated, GitHub should automatically run the gh-pages action. You can click the Actions tab on GitHub to see that the action completed successfully.
On the GitHub repository, click the Settings tab and navigate to the Pages option.
Under the Branch heading, choose the gh-pages branch and the / (root) folder, then click Save

After a minute or so, the GitHub Pages deployment should finish. On the main repository page, you should see is as an active environment on the right side.
Once that is done, you can click on the github-pages environment, and click View Deployment to see the live version of the site.

Add to Homepage

The textbook backups are listed on the homepage available at https://ksu-cs-textbooks.github.io/. That page can be updated by editing this index.html page in the base repository. Anyone who is an owner of the group should be able to edit it. When you commit an edit to that page, it will automatically deploy and update.

Switching to New Theme

Warning

This page gives instructions for switching an existing textbook using the previous theme to the new version of Hugo Theme Relearn. Only use these instructions once per textbook!

Update Hugo

The new theme requires Hugo version 0.101.0 or higher. Install Hugo from the Hugo Releases.

Installing the Theme

Install the new theme as a git submodule:

git submodule add https://github.com/ksu-cs-textbooks/hugo-theme-relearn.git themes/hugo-theme-relearn

Updating the Configuration

Copy config.toml to config.toml.bak as a backup.
Replace the content in config.toml with the content from the config.toml from the starter site.
Customize config.toml to match the desired site configuration (refer to the config.toml.bak as needed).
1. Update the baseURL at the top to match the URL where the site will eventually be deployed.
2. Update the title to match the site’s name
3. Under [params], update the following:
  1. editURL to match the location where files can be edited in GitLab or GitHub.
  2. author used for metadata
  3. description used for metadata
  4. commitURL to match the location where individual commits can be found.
  5. Most of the parameters are documented in the Hugo Theme Relearn Documentation
  6. Add any custom parameters used in the previous site.
Once all updates have been made, delete the config.toml.bak file.

Updating Other Configurations

Depending on how the site is used, the following other configuration updates must be made.

GitHub Backups

If the site is set up for GitHub backups, there are two options:

If github.toml is present, and you’d like to continue using multiple configuration files, replace it with the current contents of the config.toml file and update the baseURL to match what was previously in the github.toml file (e.g. https://ksu-cs-textbooks.github.io/<repo_name>). Ensure that the hugo command in .github/workflows/gh-pages.yml is hugo --config github.toml so that the correct file will be used.
If github.toml is not present, or you’d like to simplify the configuration, set the hugo command in the .github/workflows/gh-pages.yml file to be hugo -b "https://ksu-cs-textbooks.github.io/<repo_name>" and update <repo_name> to match the correct URL. This will use the config.toml file but override the baseURL when building it.

In addition, you should confirm that the hugo-version setting in .github/workflows/gh-pages.yml is set to 0.101.0.

Docker images

If the site is set up to build Docker images, there are two options:

If docker.toml is present, and you’d like to continue using multiple configuration files, replace it with the current contents of the config.toml file and update the baseURL to match what was previously in the docker.toml file (e.g. https://<name>.textbooks.cs.ksu.edu). Ensure that the hugo command in the Dockerfile is hugo --config docker.toml so that the correct file will be used.
If docker.toml is not present, or you’d like to simplify the configuration, set the hugo command in the Dockerfile to be hugo -b "https://<name>.textbooks.cs.ksu.edu" and update <name> to match the correct URL. This will use the config.toml file but override the baseURL when building it.

In addition, you should confirm that the HUGO_VERSION argument in the Dockerfile is set to 0.101.0.

Finally, since we aren’t currently using Docker images yet, you may wish to configure your textbook to only create a Docker image when a new tag is pushed, or disable this completely for the time being. See the Docker Container page for more information.

Updating layouts

If the site has overridden any layouts in the layouts folder, they should be reviewed and updated as needed.

layouts/partials/logo.html - the default logo will use the title from the config.toml file as a clickable link. If this is desired, then delete layouts/partials/logo.html. Otherwise, update it using the following templates as a guide:

Static Text

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
  Hugo Starter
</a>

Logo Image

<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
    <img src="/images/logo.png" alt="Logo" style="width: 100%">
</a>

layouts/partials/menu-footer.html - the default menu footer gives information about the site and the CC-BY-NC-SA license. If this is desired, then delete the layouts/partials/menu-footer.html from the site. Otherwise, update it using the following templates as a guide (change only the second paragraph to your desired license information).

Note

The footer works best with a bit of inline HTML to fix the design. I left it this way since it was easier to override than trying to adjust it in the base theme, since updates to the base theme’s CSS may cause issues.

Default Footer

<style>
#footer {
	font-size: 13px;
	margin-left: auto;
	margin-right: auto;
	padding: 2rem 1rem;
	min-width: 230px;
	max-width: 300px;
}
#footer p {
	margin: 0;
}
</style>

<p>Built using <a href="http://gohugo.io/">Hugo</a> and <a href="https://github.com/ksu-cs-textbooks/hugo-theme-relearn">Hugo Relearn Theme</a>.</p>
<p><a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0; margin: .5rem auto" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.</a></p>

CC Course Footer with License and Attribution Info

<style>
#footer {
    font-size: 13px;
    margin-left: auto;
    margin-right: auto;
    padding: 2rem 1rem;
    min-width: 230px;
    max-width: 300px;
}
#footer p {
    margin: 0;
}
</style>
    
<p>Built using <a href="http://gohugo.io/">Hugo</a> and <a href="https://github.com/ksu-cs-textbooks/hugo-theme-relearn">Hugo Relearn Theme</a>.</p>
<p><a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0; margin: .5rem auto" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.</a> See <a href="https://core.cs.ksu.edu/license">License & Attribution</a> for details.</p>

Front Matter Changes

By default, the site will now create a printable version of all pages. To remove a page or group of pages from the printed view (such as announcements or assignments pages), add noprint = true (TOML) or noprint: true (YAML) to the front matter of a page or chapter. Any pages beneath that page in the tree will not be included in the print view. By default, all hidden pages will also not be included (but they also won’t be visible in the sidebar menu).

The template no longer includes code for the section: true front matter option - it should be switched to chapter: true to get the chapter header formatting, otherwise it can be removed entirely.

The date option is no longer used. It can be deleted or ignored.

See the Hugo Theme Relearn Documentation or Hugo Documentation for more on how to use the front matter of each page.

Note

This may be an incomplete list of front matter changes - if you run into additional front matter issues when upgrading, let me know and I’ll update this document.

Content Changes

LaTeX Math

Hugo Theme Relearn changed the way that LaTeX math is handled in markdown. Now it is best to either include it in a shortcode or a code fence instead of just using dollar signs $ directly in the markdown. See the Hugo Theme Relearn Documentation for additional details.

In general, any inline LaTeX using single dollar signs $ should be wrapped with the new math shortcode, as in $e^x$.

For multiline LaTeX using two dollar signs $$, use the math codefence:

$$ e^{i \pi} + 1 = 0 $$ $$ sin^2(x) + cos^2(x) = tan^2(x) $$

Shortcode Changes

Click here for Complete Shortcode Documentation. The following shortcodes should be reviewed for updates:

New Shortcodes

syllabus - this is a new shortcode to replace the previous include shortcodes for default syllabus statements. See the Syllabus Shortcode Documentation for how to use it.
quizdown - this is an implementation of the Quizdown plugin to add short quizzes to the site.

Updated Shortcodes

include - this shortcode should now use the < > delimiters instead of % %. Using < > will prevent the Markdown renderer from rendering the content twice, resulting in extra spacing around URLs and other strange formatting issues. See Shortcodes for more information on the different shortcode delimiters. See Custom Include Shortcode Documentation and Default Include Shortcode Documentation for more details on the shortcode itself. It should now support other shortcodes in included files! I recommend running a quick search for something like {% include and {%include to catch most of these and review them on the rendered site before committing.

Note

If you are including files from the previous theme, such as the default syllabus statements, you should update the path to the new theme or consider using the new syllabus shortcode for this.

notice - this shortcode has many new features, and the syntax for it is slightly different (only if you were using custom titles or icons - the base notice shortcode hasn’t changed). See Noiframe Notice Shortcode Documentation and Notice Shortcode Documentation for more information.

Deprecated Shortcodes

link - the link shortcode has been removed. Now, the default HTML renderer is configured to have a link either open in the same tab if it is a local link (does not have http in the URL), otherwise it will open in a new tab if the link goes to an external site. See Link Shortcode for more information. All links can now be converted to standard Markdown syntax [Link Name](link_url) or replaced with an HTML <a href="link_url" target="_blank" rel="noopener">Link Name</a> tag. You may also want to review the relref function in Hugo to generate relative links to pages within the site that use the correct base URL.
norender - the norender shortcode has been removed. It can be replaced by enclosing the content in a <pre> </pre> HTML element.
static - the static shortcode has been removed. Any files in the /static folder within the site are now accessible using direct URLs. For example, a file at /static/images/logo.png can be included using ![Logo](/images/logo.png). As long as the baseURL and canonifyURLs settings in config.toml are correct, Hugo will automatically update these URLs to the correct path.

Note

This may be an incomplete list of shortcode changes - if you run into additional shortcode issues when upgrading, let me know and I’ll update this document.

Preview Content

At this point, you should preview the content in your site using hugo serve and ensure that it looks correct. If everything is working properly, then continue. If not, feel free to contact the theme maintainer for assistance.

Update Deployment

Warning

As of August 2022, the server has not been updated to use a newer version of Hugo by default. Therefore, before deploying an updated site, contact one of the server administrators to have your site’s webhook updated to use the deploy-101.sh deployment script, which uses the new version of Hugo.

Commit and Push to Test Deployment

If everything is working correctly, you should be able to commit and push. Make sure that everything has deployed and updated properly. You may have to clear your browser’s cache using CTRL+F5 or CMD+F5 to get the latest version of the CSS file.

If anything doesn’t look correct, contact the theme maintainer for assistance.

Removing the Old Theme

Once everything is working properly, you should remove the old theme from your repository using these commands:

git rm themes/ksucs-hugo-theme
rm -rf .git/modules/themes/ksucs-hugo-theme
git config --remove-section submodule.themes/ksucs-hugo-theme

After making those changes, commit and push.

Updating Other Copies of the Repository

After updating the textbook on one system, it is recommended to delete and re-clone the repository on any other systems that are using it. That will give the cleanest version of the updated repository without any residual files from the previous theme. Run these commands starting outside of the site’s directory, where <directory> is the directory containing the site.

rm -rvf <directory>
git clone <url> <directory>
cd <directory>
git submodule init
git pull --recurse

Cloning an Existing Textbook

The instructions to clone an existing textbook are simple, but require a few extra steps compared to a normal git repository setup.

The basic version is to run these commands, where <directory> is the directory where the site should be stored:

git clone <url> <directory>
cd <directory>
git submodule init
git pull --recurse

These commands do the following:

git clone <url> <directory> will clone the existing git repository at <url> into the local directory <directory>.
cd <directory> will change the current working directory to be the directory where the site is stored.
git submodule init will initialize the submodules for this repository. We use git submodules to keep track of the theme and make it easy to update the theme as needed.
git pull --recurse will pull the latest version of the repository AND the theme. The theme will be locked to a specific version unless you go through the steps to Update the Theme.

Creating a Docker Container

The Hugo textbooks can also be deployed into a Docker container.

Dockerfile

Create a file named Dockerfile in the site’s base directory with the following content:

FROM nginx:alpine as build

RUN apk add --update \
    wget git
    
ARG HUGO_VERSION="0.101.0"
RUN wget --quiet "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz" && \
    tar xzf hugo_${HUGO_VERSION}_Linux-64bit.tar.gz && \
    rm -r hugo_${HUGO_VERSION}_Linux-64bit.tar.gz && \
    mv hugo /usr/bin

COPY ./ /site
WORKDIR /site
RUN hugo -b "https://hugo-starter.textbooks.cs.ksu.edu"

#Copy static files to Nginx
FROM nginx:alpine
COPY --from=build /site/public /usr/share/nginx/html

WORKDIR /usr/share/nginx/html

Update the following items in this file to match your desired configuration:
1. The HUGO_VERSION argument should be set to the version of Hugo used for the site.
2. The RUN command should include the URL that the site will be deployed to after the -b flag. Alternatively, copy config.toml to docker.toml and update the baseURL setting (as well as any other settings as desired), and use RUN hugo --config docker.toml instead.

You can find more information on setting up a Dockerfile in the Dockerfile Reference.

Build Docker on GitLab

Docker images can be built using GitLab. The organization or repository on GitLab must be configured with a GitLab Runner. This has already been done in most GitLab organizations on the CS GitLab server that contain textbooks.

Create the file .gitlab-ci.yml in the site’s base directory with the following content:

image: docker:20.10.11

variables:
  # When using dind service, you must instruct docker to talk with the
  # daemon started inside of the service. The daemon is available with
  # a network connection instead of the default /var/run/docker.sock socket.
  #
  # The 'docker' hostname is the alias of the service container as described at
  # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services
  #
  # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier,
  # the variable must be set to tcp://localhost:2375 because of how the
  # Kubernetes executor connects services to the job container
  # DOCKER_HOST: tcp://localhost:2375
  #
  DOCKER_HOST: tcp://docker:2375
  #
  # This instructs Docker not to start over TLS.
  DOCKER_TLS_CERTDIR: ""
  # 
  # Checkout submodules recursively
  GIT_SUBMODULE_STRATEGY: recursive

services:
  - docker:20.10.11-dind

before_script:
  - docker info
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build-latest:
  stage: build
  only:
    - tags
  script:
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

# build-branches:
#   stage: build
#   except:
#     - master
#     - main
#   script:
#     - docker pull $CI_REGISTRY_IMAGE:$CI_COMMIT_BRANCH || true
#     - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_BRANCH .
#     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
#     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_BRANCH

Update the following items in this file to match your desired configuration:
1. Under the build-latest job, it uses - tags under the only heading. This will only build a Docker container when a new tag is pushed. This reduces the number of containers built, since it is a time-consuming job. You can change this to the following to have it build anytime changes are made to the main or master branches:

only:
  - main
  - master

You can also enable additional jobs:
1. The build-branches job is commented out. This will build a Docker container for each branch that is tagged using the branch name. This can be uncommented if you’d like to build Docker containers based on a branch. (Likewise, the except section can be replaced with an only section to target specific branches.)

More information on the GitLab CI file can be found in the GitLab Documentation

Warning

You should also enable package cleanup in GitLab by going to the Settings -> Packages and Registries menu in the repository and turning on Clean Up Image Tags. This will clean up all tags older than 90 days, except for the last 10 tags. The latest tag will be kept indefinitely until replaced by a new version. This will help save space on GitLab as images are built and replaced.

Build Docker on GitHub

Docker images can be built using GitHub.

Create a file .github/worflows/docker-image.yml with the following content:

name: Docker Image CI

on:
  push:
    tags:
      - "v*.*.*"

jobs:

  build:
    runs-on: ubuntu-latest
    steps:

    - uses: actions/checkout@v3
      with:
        submodules: recursive
        fetch-depth: 0
      
    - name: Login to GitHub Container Registry
      uses: docker/login-action@v1 
      with:
        registry: ghcr.io
        username: ${{ github.repository_owner }}
        password: ${{ secrets.GITHUB_TOKEN }}
    - name: Build and push
      uses: docker/build-push-action@v2
      with:
        context: .
        push: true
        tags: |
            ghcr.io/${{ github.repository}}:latest

Update the following items in this file to match your desired configuration:
1. Under the push heading, it is configured to run this only when a new tag is pushed that matches Semantic Versioning structure. You can change this to the following to have it build anytime changes are made to the main or master branches:

push:
    branches: [ master, main ]

This can also be configured to send notifications to Discord on a successful deployment, and it can also trigger a webhook after deployment. See this example for how to configure those options. It requires creation of GitHub Action Secrets for the Discord webhook and deployment webhook.

More information can be found on the GitHub Actions Documentation.

Warning

As of this writing, GitHub will store all previous versions of this package, and there is no automatic way to delete older packages outside of using another GitHub action. So, if you choose to go this route, you may have to deal with manually cleaning up old packages at some point in the future if you run out of space on GitHub.

Update 2023

In Summer 2023 this theme was updated to match version 5.18.0 of the base Hugo Relearn Theme

New Features

A full list of changes to the theme can be found on the What’s New page and in the Documentation.

Some notable feature updates:

New Shortcode - Badge
New Shortcode - Icon
New Shortcode - Tab
New Shortcode - Highlight
The theme now includes warnings for deprecated and unsupported features
Many shortcodes now color and icon configurable
Supports task lists, definition lists, and footnotes using GHFM
Search updates and a dedicated search page
Automatically detect theme variant based on OS
Swagger renamed to OpenAPI and now uses SwaggerUI instead of RapiDoc
Absolute links now open in separate browser tab, configurable (this was previously handled by a custom HTML renderer that is no longer used)
Supports Hugo up to version 0.114.0
Supports the VSCode Front Matter extension (admittedly I have not tried this yet)
JQuery completely removed from template

Warning

Currently the template will sometimes include hidden pages in the menu when using hugo serve locally, but this does not affect any deployed versions of the site. To resolve this problem, disable fast rendering using hugo serve --disableFastRender.

Upgrading

To upgrade to the new theme version, do the following:

Navigate to the themes/hugo-theme-relearn directory
Use git pull to pull the latest version of the theme
Navigate back to the root directory of your site.
Commit and push the site. It should see a new version of the themes/hugo-theme-relearn submodule.

Enable Search

To enable the new search features, update the [outputs] section of the config.toml (and other files like docker.toml and github.toml if present) to the following:

[outputs]
  home = ["HTML", "RSS", "PRINT", "SEARCH", "SEARCHPAGE"]
  section = ["HTML", "RSS", "PRINT", "TELE", "EMBED"]
  page = ["HTML", "RSS", "PRINT", "TELE", "EMBED"]

Enable Auto Theme Variants

To enable automatically detecting theme variants based on the user’s OS preferences, find the themeVariant item under [params] in the config.toml (and other files like docker.toml and github.toml if present) and replace that line with the following:

  themeVariant = ["auto", "light-theme", "dark-theme"]
  # The first element is the variant for light mode, the second for dark mode
  themeVariantAuto = ["light-theme", "dark-theme"]

Deprecated Chapter Features

Many of the previous textbooks use the old method for creating chapters by placing chapter = true in the frontmatter. This has been deprecated in favor of using the new archetype = "chapter" setting. See the documentation for details.

Unfortunately, the way that the new archetype system assigns chapter numbers is using the weight parameter. Many of our books use non-sequential weights to make it simpler to add pages later. This theme adds support for an ordinal value in the frontmatter to allow overriding this value.

To get rid of the deprecation warnings, find all pages that contain chapter = true and make the following updates:

Replace chapter = true with archetype = "chapter" in the page’s frontmatter
Remove the top-level headers. Typically these pages would include an h1 and h3 header. These are now generated by the archetype.
OPTIONAL: Add an ordinal = "X" line to the frontmatter, and replace the X with the chapter number.

For example, a chapter with the following content:

+++
title = "Basic Content"
weight = 5
chapter = true
pre = "<b>0. </b>"
+++

### Chapter 0

# Basic Content

The Basics of this Template

should be updated to match this format:

+++
title = "Basic Content"
weight = 5
ordinal = "0"
archetype = "chapter"
pre = "<b>0. </b>"
+++

The Basics of this Template

Update 2024

In Summer 2024 this theme was updated to match version 6.0.0 of the base Hugo Relearn Theme

New Features

A full list of changes to the theme can be found on the What’s New page and in the Documentation.

Some notable feature updates:

Swagger Shortcode now OpenAPI
Attachments Shortcode now Resources
Many Shortcodes & Markdown Items Throw Errors/Warnings on Missing Resources - Configurable
Math No Longer Requires Shortcodes if Passthrough Enabled
IE 11 Support Removed
FontAwesome Updated to 6.5.2
Frontmatter menuTitle now linkTitle
Configuration file moved from config.toml to hugo.toml to match Hugo changes
Lots of theme configuration options were added to hugo.toml

In addition, the theme now supports installation via Hugo Modules as well as Git Submodules. We plan to migrate all textbooks to a Hugo Modules setup since it is more portable and easy to configure. More Information.

Upgrading and Switching to Hugo Modules

To Upgrade the theme and switch from a Git Submodule to a Hugo Module, do the following:

Ensure that a recent version of Go and Git is installed.
Install Hugo v0.126.1 or later.
Initialize the Hugo Module system. The name of the module doesn’t matter since it won’t be used - just use the name of the repository, such as hugo mod init cis598-textbook. This should create a file go.mod listing the name of the module and the version of go used.
1. The module import is already defined at the bottom of the new hugo.toml file and doesn’t need to be configured.
In the textbook directory, remove the submodule using git rm themes/hugo-theme-relearn. This should remove that directory as well as update the .gitmodules file to remove the submodule. If desired, also delete the themes directory itself using rmdir themes.
Create a new file hugo.toml using this sample file as a template.
1. Look for items labelled # TODO changeme to see what settings should be updated for each site. Many settings can be carried over from the existing config.toml but some settings are new. Configuration Documentation.
2. One recommendation is to use the Todo Tree extension in VS Code, which will highlight comments containing TODO and other keywords, making them easy to find.
3. The theme has changed how URLs are handled for sites served in subdirectories (such as textbooks.cs.ksu.edu/cis598). The canonifyURLs setting is deprecated and should be set to false, along with the relativeURLs setting set to false. This may break some image links - see below.
Once the configuration is updated in hugo.toml, delete the existing config.toml as it is no longer needed.
Install the Hugo module using hugo mod get -u. This should install the module and create a file go.sum that includes the checksums of the module dependencies.
1. In the future, use hugo mod get to get the current version specified, or hugo mod get -u to update the version to the latest in GitHub.
2. Running hugo serve or hugo build will also install the module if needed.
Check for files such as Dockerfile, .github/workflows/gh_pages.yml, .gitlab-ci.yml or similar and update the version of Hugo to v0.126.1.
1. Sample Dockerfile that works with Hugo modules instead of git submodules.

Before testing the site, there are a few content changes that must be made.

Content Changes

Updates to `ref` and `relref` shortcode

In newer versions of Hugo, the ref and relref shortcode must be delimited using % % instead of < >. Many of our textbooks use the old delimiter. This will result in errors such as this when building the textbook:

ERROR "/home/russfeld/web/cis598-textbook/content/0-introduction/01-syllabus/_index.md": link 'HAAHUGOSHORTCODE14s0HBHB' is not a page
WARN  "/home/russfeld/web/cis598-textbook/content/b-schedule/01-fall2022.md": WARNING you must call the ref / relref shortcode with '% %' instead of '< >' to work correctly for the anchor target attribute

To fix this, the following regex find/replace can be used in VS Code:

Search:

\{\{<\s*(rel)?ref ([^>]*)\s*>\}\}

Replace:

{{% $1ref $2 %}}

These errors can be switched to warnings in hugo.toml but it is best to deal with them directly so they don’t cause problems in the future.

Updates to `youtube` shortcode

The youtube shortcode may also need to be updated as described above, but in the other direction.

To fix this, the following regex find/replace can be used in VS Code:

Search:

\{\{%\s*youtube (.*)\s*%\}\}

Replace:

{{< youtube $1 >}}

Updates to Images and Other Resources

Newer versions of Hugo can also verify the path of any images and resources included in the page. This is helpful for finding broken links or missing images. Unfortunately, it cannot verify any items stored in the static directory since it is not processed through the content pipeline. Many of our textbooks store all images and resources in the static folder, which is fine, but it means that the build process cannot verify that there aren’t any missing items or broken links.

To fix this, there are a few options:

In hugo.toml, the errors can be switched to warnings or disabled entirely. By default, all checks are set to error except for images, which are set to warning. Read the documentation in hugo.toml to determine what options are preferred.
Images and resources in the static folder can be moved to the assets folder. Ideally the links won’t need to be changed if the images are linked using an absolute reference path (e.g. images/1/image.png). This is the simplest fix
Images and resources in the static folder can be moved to the content folder near the page where they are used. It is recommended to convert any standalone pages to page bundles that contain the page and all associated resources.

For example, the CIS 598 textbook contains a page 01-fall2022.md that contains links to many images in the static folder:

To switch this to a page bundle, create a folder 01-fall2022 and then move the 01-fall2022.md file inside of that folder and rename it to index.md. Then, create an images folder within, and move all of the images from static to the new folder. The resulting layout should be:

Using this method, all image links on the page can be updated by a quick find and replace to replace /images/fall2022/ with just images/ - removing the leading slash / and the subfolder name used in the old static/images path.

Image Links in Reveal.js Slides

Disabling the canonifyURLs option will break all image links in any Reveal.js slides that are using the /images path prefix. The previous behavior would simply prepend the subdirectory in front of any URL starting with a /.

There are two workarounds:

A quick fix is to a find/replace for the /images/ path in the slides and prepend the subdirectory to the path, as in /cis598/images/. This works as long as the site baseURL is not changed. This requires the images to remain in the static folder unless they are referenced by other markdown files. Generally I just copy images from static to assets to fix the problem above but leave a copy in the static folder as well. Hugo will merge the two.
Another workaround would be to move the images into a page bundle as described above, and then convert the /images URLs to be ../images (or whatever relative path is correct). The ref and relref shortcodes cannot be used in this context. This works regardless of the site baseURL setting.

Image Link in Logo Template

If the site includes an image in the layouts/partials/logo.html page, you can suppress the error by loading the image as a resource from the assets directory instead of the static directory.

{{/* Place Logo Graphic or Text Here */}}
{{ $image := resources.Get "images/cc410logo.png" }}
<a id="logo" href="{{ .Site.Home.RelPermalink | default ("/" | relLangURL) }}">
    <img src="{{ $image.RelPermalink }}" alt="Computational Core Logo" style="width: 100%">
</a>

K-State CS Hugo Theme

Subsections of K-State CS Hugo Theme

Basic Content

Subsections of Basic Content

Section

Subsections of Section

Simple Page

Simple Page

Reveal.js Example

Resources

Info

Examples

Simple Title Slide

Slide with Bulleted List

Images with Sources

Math (via MathJax)

Tables

Code

Java

Python

Multiple Divs

Marking Text

Advanced Structures

Subsections of Advanced Structures

Simple Page

Leaf Page

Branch Bundle

Subsections of Branch Bundle

Rendered

Structural Patterns

Subsections of Structural Patterns

Previous Versions

Subsections of Previous Versions

Video Content

Subsections of Video Content

Basic Markdown

Subsections of Basic Markdown

Frontmatter

Front Matter configuration

Reveal.js Slides

Text

Standard and Extensions

Paragraphs

Headings

h1 Heading

h2 Heading

h3 Heading

h4 Heading

h5 Heading

h6 Heading

Horizontal Rules

Text Markers

Bold

Italics

Strikethrough

Marked Text

Special Typesetting

Text Substitution

Keyboard Shortcuts

Sub and Super Script

Lists

Unordered

Ordered

Tasks

Definitions

Code

Inline Code

Indented Code Block

Fenced Code Block

Tables

Aligned Columns

Blockquotes

Links

Autolink

Basic Link

Link with Tooltip

Link References

Footnotes

Images

Basic Images