Editing Guide

Markdown

In your _index.md files you mainly write “Markdown”, which is an easy way to add simple formatting to a document just by typing. If you just write text it will get displayed as text (without any special formatting). By adding simple punctuation you can mark portions of text as bold, italic, highlighted, quoted, lists, headings of a half dozen levels, inlined images, web links, and more.

• You can copy-paste into your markdown any emoji (😁) or type its name (:grin: ) from the official emoji list
• Icons can be included via {{% icon <icon-name> %}} using <icon-name>s which you can search for (be sure to click on the “Free” box on the right below the search bar). If the “Web Awesome” code has a family name listed (e.g. if you click the “Web Aweome” tab for this icon you see the family name is brands), enter that after the icon name, e.g. {{% icon google brands %}}.
• See a basic markdown cheat sheet
• Or refer to a more complete markdown guide with many more advanced features (navigate using the Table of Contents by clicking the icon at top on the left side)

Tools

The markdown you write is processed using the Hugo Relearn Theme.¹ For advanced layout of your pages you can use their many “shortcodes” – a few to call out are:

• For layout & formatting, use cards and notices; also buttons can provide colorful links.
• For organization, you can group related pages into directories and use children to automatically display titles & optional descriptions of all pages below in various formats. We also provide a custom version of it, {{< childrenof path="/projects" ... >}} which takes all the same parameters as children but only lists children which are underneath your specified path.
• To guide the reader’s focus, use expand/collapse and tabs.
• You might have occasion to write chemical formulae (part of the math package)
• mermaid makes it easy to create all sorts of diagrams. (Very detailed documentation is also in the official docs – find your desired diagram type in the left nav bar)
  Mermaid diagram inside too small a box? Expand this.

  If the diagram the box is in is too small, here is a markdown snippet to make it larger (put your diagram inside the mermaid section, and pick your own scale factor):

  <div style="text-align:center; scale: 200%;"><!-- next line must be blank! -->
  
  ```mermaid {zoom="true"}
  graph LR
  a-->b-->c
  ```
  </div>

  Be aware that Hugo only leaves room for the original size, so you might need to arrange for enough blank space around your diagram if you don’t want the diagram spilling over onto other content.

For even more advanced customization you can define your own shortcodes, define your own formatting, and more!

Your project structure

Typically you’ll want to have a directory for each page, and put the markdown you write for that page in _index.md in that directory. The index.md files should all start with a simple header which looks something like this:

---
title: 'Title for This Page'
---

Hugo calls this “front matter” and on lines between the --- markers it can contain other customizations including:

• type = chapter for an intermediate page which groups others (like Homework or Weeks), type = home for your top-level homepage
• weight = 100 if you want to set the ordering of this page relative to its peer pages (sorted by the values each page has) in a {{< children sort="weight" >}} list (ditto childrenof list, see above)
• description = "Brief blurb about the page" will display that description attached to the page title in {{< children description="true" >}} (and childrenof)

Images

You can upload images for a page to use into its directory and include them inside a page by filename: ![Accessibility text](my-image.webp). You can even use images in other directories: ![](labs/labimage.jpg) or ![](../imagefilename.png).

If a page is in a {{< children type="card" >}} (or childrenof) card listing, add the string feature to an image filename in the child’s directory and the card for that child will display the featured image (otherwise, the system will just pick one of the image files in that directory).