hugo-theme-ncsu #

Example / documentation page for the Bootstrap 5 version of the unofficial hugo-theme-ncsu.

Config #

General config options for hugo are listed here: https://gohugo.io/getting-started/configuration/

1
2
3
4

baseURL = "" # Set by deploy script
languageCode = "en-us"
title = "NCSU Theme Documentation"
theme = "hugo-theme-ncsu"

• baseURL: Base URL for the site, (often?) set by deploy platform. Affects how relative links are handled (and might cause broken CSS / JS if not set correctly). Needs to be set to base URL of course website when manually deploying the html, e.g., baseURL = "courseXX.example.org"
• languageCode: Displayed in the website header as lang attribute, likely not very relevant except for search engines.
• title: Default website title displayed in the tab and search engines if no specific page title is set.
• theme: Name of theme to use from the themes folder (this theme).

Parameters #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[params]
	# Theme specific setting
	showToC = true # ToC on the right
	showSidebar = true # Sidebar on the left
	showWIP	= true # 'Work in progress' message on every page
	showFooter = true  # Site footer with some lecture info
	# Course variables
	iteration = "Fall 2024"
	year = "2024"
	cshort = "CSC XXX"
	clong = "Example Lecture"
	cfull = "CSC XXX - Example Lecture"
	cdesc = "Some longer course description"
	time = "Monday, Wednesday 6:00pm -- 7:15pm"
	location = "1226 Engineering Building 2 (EB 2)"

Theme-specific #

Theme settings. Can be overwritten for individual pages in their front matter.

• showToC = true: Show (autogenerated) Table of Content (ToC) based on markdown headings on the right
• showSidebar = true: Show sidebar on the left. Sidebar content generated from /layouts/partials/sidebar.html.
• showWIP = true: Show ‘work in progress’ message at top of every page. Content generated from /layouts/partials/wip.html.
• showFooter = true: Site footer with some lecture info. Content generated from /layouts/partials/footer.html.

Show Sidebar #

Display left sidebar if showSidebar = true. Set in a /layouts/partials/sidebar.html file.

Show Table of Contents #

Display right table of content if showToC = true. Auto-generated from markdown headings, included levels can be modified in hugo.toml.

Show WIP #

Display following info box towards the top off every page if showWIP = true:

Can be overwitten with a /layouts/partials/wip.html file.

Show Footer #

Display footer at bottom of each page if showFooter = true. Generated from some of the course variables, can be overwritten woth a /layouts/partials/footer.html file.

Course Variables #

Course-specific variables.

• Display in html file in the form of {{ .Site.Params.cshort }}
• Display in markdown file with the param shortcode {{< param "cshort" >}}

Menu #

Menu displayed on the top right of every page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Menu
sectionPagesMenu = "main"
[menu]
	[[menu.main]]
		identifier = "about"
		name = "About"
		URL = "/"
		weight = 1
	[[menu.main]]
		identifier = "schedule"
		name = "Schedule"
		URL = "/schedule/"
		weight = 2
	[[menu.main]]
		identifier = "syllabus"
		name = "Syllabus"
		URL = "/syllabus/"
		weight = 3

Bootstrap Shortcodes #

Shortcodes that wrap some Bootstrap elements and classes for easier use in Markdown files. Note that HTML code with Bootstrap classes is also valid Markdown and will render.

Alert #

Bootstrap alert text box with customizable markdown content. First parameter is passed as class (for setting color).

• Bootstrap documentation: https://getbootstrap.com/docs/5.3/components/alerts/
• Example parameters: alert-primary (red), alert-secondary (grey), alert-success (green), …

Usage:

1
2
3

{{< alert "alert-primary" >}}
**Alert**: some markdown text to display.
{{< /alert >}}

Examples:

Badge #

Bootstrap badge span with customizable markdown content.

• Bootstrap documentation: https://getbootstrap.com/docs/5.3/components/badge/
• Example parameters: alert-primary (red), alert-secondary (grey), alert-success (green), …

1
2
3

{{< badge "text-bg-primary" >}}
Primary
{{< /badge >}}

Primary

Examples:

Pill Badge #

With .rounded-pill class.

1
2
3

{{< badge "text-bg-primary rounded-pill" >}}
Primary
{{< /badge >}}

Button #

Bootstrap button with customizable markdown content.

• Bootstrap documentation: https://getbootstrap.com/docs/5.3/components/buttons/

1
2
3

{{< button "btn-primary" >}}
Primary
{{< /button >}}

Primary

Examples:

Outline Buttons #

With .btn-outline-* classes:

1
2
3

{{< button "btn-outline-primary" >}}
Primary
{{< /button >}}

Primary

Examples:

Card #

Generic bootstrap card that displays content as body text. No additional parameters.

Usage:

1
2
3

{{< card >}}
**Card**: some markdown text to display.
{{< /card >}}

Examples:

Also plays well with the columns short code:

Col & Row #

Bootstrap column & row class wrappers.

• Bootstrap documentation: https://getbootstrap.com/docs/5.3/layout/grid/
• Bootstrap grid works with 12 vertical, i.e., col-8 will leave 4 vertical slots for remaining columns.

1
2
3
4
5
6
7
8

{{< row >}}
{{< col >}}
Column 1
{{< /col >}}
{{< col "col-6" >}}
Column 2 (Larger)
{{< /col >}}
{{< /row >}}

Columns #

Shortcode to generate two columns.

• width as optional parameter to set maximum width for each column in px (will wrap if wider).
• split as optional parameter to set split ratio between columns (i.e. split = "2/1" for 66% and 33%). Overwrites any width parameter.

The two columns are split by <--->.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{< columns >}}

#### Left Column
Text that will appear in the left column.

<--->

#### Right Column
Text that will appear in the right column

{{< /columns >}}

Also works for more than 2 columns:

With different split ratios:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{< columns split="2/1" >}}

#### Left Column
66% column.

<--->

#### Right Column
33% column.

{{< /columns >}}

Splits also work for multiple columns

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{{< columns split="1/1/3" >}}

#### First Column
20% column.

<--->

#### Second Column
20% column.

<--->

#### Third Column
60% column.

{{< /columns >}}

Details #

Shortcode for the HTML “details” built-in to show/hide longer content adapted for Bootstrap 5. Takes up to 2 parameters and inner content:

• pos 0, “title”: Title shown for the summary
• pos 1, “open”: Whether the detail starts expanded
• inner: Text hidden / displayed by the summary

Usage:

1
2
3

{{< details title="Title of the Detail" >}}
Some inner text
{{< /details >}}

1
2
3

{{< details title="Detail that starts open" open=true >}}
Some inner text that starts visible
{{< /details >}}

Examples:

Table #

Wrapper shortcode to use bootstrap table classes for markdown tables. Pass classes as parameters, markdown table as inner content.

• Modified from: https://stackoverflow.com/questions/64609165/how-to-give-a-hugo-markdown-table-a-class-when-the-table-contains-shortcodes

Usage:

1
2
3
4
5
6
7
8
9

{{< table "table-striped col-auto" >}}
|  |  |
|-------------------|-----------------------------------------|
| Format            | In-person, recorded|
| Credits           | 3 |
| Meeting Times	    | 6:00 am |
| Meeting Location  | Earth |
| Instructor        | Dr. Doe |
{{< /table >}}

Example:

Custom Shortcodes #

Custom shortcodes for this theme (mostly focused around class schedules).

Assignment #

Assignment shortcode with multiple displays of assignment data from /data/assignments.toml. Real-world examples on the assignments page.

Example data entry:

1
2
3
4
5
6
7
8

[a1]
id 			= "a1"
name	 	= "Assignment 01"
short_name 	= "A01"
url 		= "/schedule#a1"
page		= "/assignments/a1"
date 		= "2024-07-21T13:59:59"
color		= "bg-secondary"

Shortcode parameters:

• pos 0, “id”: Specific assignment selected by id field from /data/assignments.toml.
• pos 1, “type”: optional type to control what data is displayed (see examples below for all options).

Default #

Without any type just renders assignment title with link to assignment page if provided:

1

{{< assignment "a1" >}}

badge #

type=badge renders as badge with link to assignment url if provided.

• Different badge color optionally set by a color variable in the data file. Color options follow the Bootstrap 5 badge format, e.g., bg-primary, bg-info, etc.
• Theme has custom additional badge classes for more colors; bg-blue, bg-purple etc.
• Color class can be combined with text classes for hard to read text colors, e.g. color = "bg-warning text-dark"

1
2

{{< assignment "a1" "badge" >}}
{{< assignment "a2" "badge" >}}

A01
A02

date #

type=date renders due date and time:

1

{{< assignment "a1" "date" >}}

countdown #

type=countdown renders a countdown for the time in the date field. Should be timezone aware using the moments.js library (not extensively tested), assumes EST (America/NewYork) time for the provided date data:

1
2

{{< assignment "a1" "countdown" >}}
{{< assignment "a2" "countdown" >}}

Chart #

Wrapper shortcode to render a chart.js chart directly in markdown. Automatically includes the chart.js library. Optional parameters:

• pos 0: width in percent
• pos 1: height in pixels

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{{< chart "80%" 100 >}}
{
    type: 'doughnut',
    data: {
        labels: ['Assignments', 'Exams', 'Reading / Participation'],
        datasets: [{
            label: 'Percent',
            data: [60, 30, 10],
        }]
    },
    options: {
		indexAxis: 'y',
        maintainAspectRatio: false,
		plugins: {
			legend: {
				display: false
			}
		}
    }
}
{{< /chart >}}

Example:

Schedule #

Collection of 3 mostly independent shortcodes week, happening, and lecture to render a schedule using Bootstrap 5 cards (see schedule for real-world examples).

• All 3 shortcodes can automatically compute and display dates if a startDate = 2024-08-19 (first Monday of the semester) variable is set in the page frontmatter. Otherwise they will fall back to not showing specific dates.
• Note that all schedule shortcodes need to be initiated with {{% %}}, not the usual {{< >}} because the week shortcode needs to appear early in the rendering pipeline to show up in the ToC and the other shortcodes need to appear in the same context for shared variables.

A combined use of the three shortcodes in a schedule could look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Start of the first week
{{% schedule/week title="First Week" %}}

// No class on Monday
{{% schedule/happening "mon" "noclass" %}}
Labor Day - **No Classes**, University Closed
{{% /schedule/happening %}}

// Lecture "lec-intro" on Tuesday
{{% schedule/lecture "tue" "lec-intro" %}}

// Lecture "lec-hcs" on Thursday
{{% schedule/lecture "thu" "lec-hcs" %}}

// A Deadline on Friday
{{% schedule/happening "fri" "deadline" "11:59pm" %}}
**Deadline**: [Assignment 1](/#example) (11:59pm)
{{% /schedule/happening %}}

Week #

Displays a week heading (also shows up in ToC).

• Automatically counts up from Week 1. Manually set week with a week = "XX" shortcode parameter, will continue counting automatically from set value.
• Optionally set a title variabel to show up in the week title and ToC.
• Optionally with specific week dates (in grey) if startDate variable is set on page.

Usage:

1
2
3
4

{{% schedule/week %}}
{{% schedule/week title="Example" %}}
{{% schedule/week "20" %}}
{{% schedule/week %}}

Examples:

Week 1 #

Monday, 2024-08-19 - Friday, 2024-08-23

Week 2 - Example #

Monday, 2024-08-26 - Friday, 2024-08-30

Week 20 #

Monday, 2024-12-30 - Friday, 2025-01-03

Week 21 #

Monday, 2025-01-06 - Friday, 2025-01-10

Happening #

Generic happening schedule shortcode with a number of display options. Date is derived from the day parameter and last week shortcode used. Short code parameters:

• pos 0, day: Day of the happening (3 letter lower), e.g., day = "mon", tue, etc.
• pos 1, type: optional type of the happening (different display, see below for examples)
• pos 2, time: optional time argument, shown on the right side of the header if provided (useful for, e.g., exams)
• Inner content rendered as markdown

Default #

No type, generic grey, single line happening

1
2
3

{{% schedule/happening "mon" %}}
Something is **happening** today.
{{% /schedule/happening %}}

noclass #

type=noclass, green background, single line, e.g. used for no class happening.

1
2
3

{{% schedule/happening "tue" "noclass" %}}
Labor Day - **No Classes**, University Closed
{{% /schedule/happening %}}

deadline #

type=deadline, red outline, deadline events. Takes optional time parameter.

1
2
3

{{% schedule/happening "wed" "deadline" "11:59pm" %}}
**Deadline**: [Assignment 1](/#example) (11:59pm)
{{% /schedule/happening %}}

Mostly works well with the assignment shortcode (minus the countdown type currently):

1
2
3

{{% schedule/happening "wed" "deadline" %}}
{{% assignment "a3" "badge" %}} **Deadline**: {{% assignment "a3" %}}, due {{% assignment "a3" "date" %}}
{{% /schedule/happening %}}

exam #

type=exam, red background, multi-line exam event. Takes optional exam time.

1
2
3
4
5

{{% schedule/happening "fri" "exam" "7:00pm" %}}
### Final Exam (7:00pm -- 9:30pm)
- Some extra info
- Link [test](#example)
{{% /schedule/happening %}}

Lecture #

The lecture shortcode renders lecture data from /data/lectures.toml by provided id.

Example lecture entry with optional parameters commented out:

1
2
3
4
5
6
7
8
9

[intro]
id			= "lec-intro"
title		= "Course Introduction"
# label		    = "lec-xyz"
# description	= "Included in recording of Lec00"
# short		    = "Guest Lecture"
# time		    = "3 pm"
# slides		= "https://drive.google.com/..."
# recording	    = "https://ncsu.hosted.panopto.com/..."

• id: ID to retrive this lecture by from the shortcode (e.g. {{% schedule/lecture "mon" "lec-intro" %}} for the id lec-intro).
• title: Lecture title
• label: Optional label to directly reference lecture on page (link id) and displayed in header. ID is used if not set.
• description: Optional description text displayed for the lecture. Supports markdown.
• short: Optional text displayed before the lecture title (e.g., “Guest Lecture”). Defaults to “Lecture X” with automatically incrementing counter.
• time: Optional parameter to overwrite the lecture time displayed in the header. Defaults to page variable lectureTime or no display if the page variable is not set.
• slides: Link to lecture slides.
• recording: Link to lecture recording.

Optionally, discussion, mentioned, and additional subtables can be provided to display additional resources (including some icons based on the type):

[intro.additional]
a1 = {authors="BD Payne, WK Edwards", title="A Brief Introduction to Usable Security", url="https://faculty.cc.gatech.edu/~keith/pubs/ieee-intro-usable-security.pdf", venue="IEEE Internet Computing", date="2008", type = "paper"}
[intro.mentioned]
m1 = {title="ACM SIGSOFT Empirical Standards for Software Engineering", url="https://www2.sigsoft.org/EmpiricalStandards/tools/", type="website"}

Automatic settings:

• Displays specific dates based on last week shortcode and passed weekday parameter, requires startDate to be set on the page.
• Displays lecture times in the header if a page frontmatter variable is set: lectureTime = "6:00pm-7:15pm"
• Automatically counts up lecture counter (“Lecture 1: …”), can be overwritten for each lecture in the toml, e.g., short = "Guest Lecture".

Short code parameters:

• pos 0, day: Day of the lecture (3 letter lower), e.g., mon, tue, etc.
• pos 1, id: ID of the lecture to display from the toml file, can be alphanumeric, e.g., lec-intro.
• pos 2, recorded: optional, for pre-recorded lectures, replaces lecture time and adds warning that this lecture won’t be in person

Examples:

1

{{% schedule/lecture "mon" "lec-intro" %}}

With recorded = true set in shortcode:

1

{{% schedule/lecture "tue" "lec-intro" "true" %}}