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 in the official icon directory (be sure the “Free” box on the right, below the search bar, is selected). If the “Web Awesome” code has a family name listed (e.g. if you click the “Web Awesome” 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)
  • Tip: if you use chemical formulae or other math expressions on a page, put this: {{%math%}}{{%/math%}} somewhere in that page (such as the very bottom) to make sure math/chemical formulae processing is initialized for that page.
• 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!

New pages

Typically you’ll want to have a new directory for each new 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 simple one:

---
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)

Be aware that the front matter section is picky about formatting and only allows a few settings to be made; and anything it doesn’t like in front matter in any page will break the build of all your pages until it’s fixed! And don’t forget the --- lines starting & ending the front matter.

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). Make sure there are no spaces in your image filenames (rename the image file before uploading to remove any spaces; if you’ve uploaded already with spaces, delete the file from this system, rename your local copy, and upload again). Image formats supported are (grouped in rough order of preference, #1 the most preferred, but all will work):

1. .webp
2. .jpeg/.jpg for photos;
   .png for graphics and screenshots;
   native (not converted) .svg for digital drawings
3. .gif, .tif/.tiff, .bmp

You can even use images you have uploaded to other directories: ![](labs/labimage.jpg) (for an image in the labs directory one level “down”(=contained within the current directory)) or ![](../imagefilename.png) (for an image in the directory one level “up”).

If a page is in a {{% children type="card" %}} (or childrenof) card listing, add an image in the child’s directory with the the word feature anywhere in its filename and the card for that child will display the featured image.

Tips

Good Practices

• Get content in first – just type text! – then add markdown for formatting later.
• Add/change a bit at a time; save (“Commit”) often and view the results right away.
• Only make changes to one file at a time (don’t have multiple tabs open trying to edit simultaneously).
• Browse & copy markdown/layout tricks freely from anyone — BUT NOT CONTENT!
• Need some markdown tips? See the HTGAA Editing Guide, which also links to a Markdown Cheat Sheet and Full (Markdown) Guide This is linked from every one of your generated pages: “Resources” (lower left) → “Editing Guide”
• ASK FOR HELP! in the Editing/Publishing category on forum.htgaa.org. Don’t spend days fighting a problem someone can help solve in minutes!

Common Symptoms & Solutions

• Not seeing the change you expected? Wait 5 secs, reload; then check the Build Failure log.
• Build is all-or-nothing – a breaking mistake on one page will prevent all your pages from being built/redeployed!
• Unexpected line break? Check for ≥2 trailing spaces on end of previous line.
• Icon not displaying? Be sure it’s from their Free collection, not any of the Pro (paid) collections. Does it need a second “family” name?
• Mysterious or ? You have an image link ![]() with an incorrect filename or path.
• On a markdown page in edit.htgaa.org is the pencil icon not clickable to edit / does it say “You must fork this repository to make or propose changes to this file”? You’re not logged in (or you’re trying to edit someone else’s pages).
• Stuck puzzling over how to format something using markdown? AIs (LLMs) are actually pretty good at markdown; tell them you’re using “hugo-theme-relearn” for targeted advice on formatting BUT NOT CONTENT!