https://cu-mkp.github.io/research-teaching-companion/
Webpage content and navigation for the Making and Knowing Project's Research and Teaching Companion (RTC), built on the Hugo framework.
For Making and Knowing Editors, see also Publishing to the RTC.
Content pages are stored in the content/
directory. Each content page is a Goldmark-flavored Markdown (.md
) file. To contribute to the site content, you may edit the Markdown files directly, or add new ones. The page's URL will be determined by its location in the folder structure.
At the top of each Markdown file is metadata called "front matter", separated from the rest of the file by three dashes (---
) on either side. The following front matter information will be used by the site:
title
populates the heading/banner at the top of the page, and if the page will appear in the top navigation, this value will appear there as well.menu
indicates which, if any, menu(s) the page should appear in.- Currently, the only supported values are
"main"
(the top navigation that appears on every page) and"resources"
(the buttons that appear on the homepage and the Resources page to link to the available resources).
- Currently, the only supported values are
weight
determines the order of the page in a menu.- Higher values are "more" weight, which means the item "falls" to the bottom of the list, and lower values are "less" weight, which means the item "floats" to the top of the list. A bit counter-intuitive, but the items that should appear first should have lower numbers.
draft
indicates whether or not this page should be public (false
) or hidden (true
).slug
determines the page's URL, but this will be generated automatically so there is no need to provide it unless you wish to override the generated URL.
Other front matter metadata, such as tags
, date
, and author
, may be used in the future, but will currently be ignored.
After the front matter, the rest of the page must be formatted as Goldmark-flavored Markdown. Markdown Guide provides a handy guide for the Markdown syntax supported by Goldmark.
Headings of levels ## Two
and ### Three
will populate the table of contents on the left side of each document. Headings of level two will also have a thin horizontal rule beneath them.
To link to other pages on the site, use the To link to both external and internal locations, use typical Markdown link syntax.ref
tag surrounded by double brackets;
For an example using both internal and external links:
Similar to M&K's [Fieldnotes](https://fieldnotes.makingandknowing.org/), these
portfolios document the students' hands-on activities, which included
[Stucco for Molding](/resources/activity-sheets/stucco-assignment), "Keeping Dry Flowers
in the Same State all Year" from the bottom of [folio 120v in BnF Ms. Fr. 640](https://edition640.makingandknowing.org/#/folios/120v/f/120v/tl),
and making and painting [cochineal lake](/resources/activity-sheets/pigment-cochineal-lake_assignment)
and [verdigris](resources/activity-sheets/verdigris-assignment) pigments.
Note that you do not need to give the entire path for ref
tags, unless there are multiple Markdown files with the same name. You also do not need to include the .md
. All of the following will work, but the first is much simpler!
Use "absolute" paths in ref links; that is starting with /resources/
followed with the path to the file, excluding file extension
[Stucco for Molding](/resources/activity-sheets/stucco-assignment)
For more information about internal links, see the Hugo documentation on Links and Cross References.
All non-markdown media should be placed in the static/
directory. For ease of use, it is currently structured as two folders: img
for images, and documents
for all other media (e.g. docx
, pptx
, pdf
).
These work differently from the other internal links. Instead of the ref
tag, just use normal Markdown link or image syntax, treating static/
as the base of the URL. It is important that each URL includes a leading slash. For example:
![stucco-molded](/images/stucco-molded.jpg)
[PDF (student handout)](/documents/activity-sheets/stucco_assignment_student-handout.pdf)
There is a special kind of page at the root of each subfolder called _index.md
. This represents the category root and can be used to list all the subpages. In RTC, we use them for three purposes:
- Display the homepage (
content/_index.md
) - List the subpages of the "Resources" page (
content/resources/_index.md
) and indicate where the "Resources" page should appear in the main menu - Display content that should appear at the root of the "Activity Sheets" and "Student Projects" folders (the
_index.md
in each of those folders)
To achieve the RTC structure, there is a rule in place that these pages will only show a list of their subpages if:
- they are not the homepage AND
- they are a top-level category
In other words, only the "Resources" page currently matches that description. A developer may change this rule in the file themes/rtc/layouts/_default/list.html
.
Every time changes are pushed to the main
branch, a GitHub action will execute and publish content to the gh-pages
branch. Make sure not to modify or remove this branch.
- Hugo v0.104.2+
Run this command to serve the site over localhost, with hot-reloading.
Run this command to build the static site and output into the public/
directory.
The custom theme is based on the Edition 640 theme and is composed of Go Templates HTML and SASS-flavored CSS. It can be edited in themes/rtc/
, under layouts/
for Go Templates/HTML and assets/scss/
for CSS. See Hugo documentation on templating for more information.