Publishing on rrchnm.org

A reference for content authors on the rrchnm.org website. You do not need to install anything. Everything happens in your browser at github.com/chnm/rrchnm.org.

How this site works
Where things live
Creating a new post
Front matter (the settings block)
Markdown formatting
Images
Post template — copy this
Saving your work (committing)
How your post gets published (deployment)
Scheduling a post to publish later
Publishing checklist
When something goes wrong

1. How this site works (30 seconds)

The RRCHNM website is built by a tool called Hugo. You write posts as plain text files (Markdown) and store them in GitHub. When your change is merged, the site rebuilds itself and your post appears at https://rrchnm.org/… a few minutes later.

For blog posts you only ever touch two folders: content/blog/ (your writing) and, occasionally, static/media/ (shared images). Everything else — themes, layouts, hugo.yaml, anything under layouts/ or data/ — is not your job. If you find yourself editing a file outside content/ or static/, stop and ask a developer.

Term	What it means to you
Repository (repo)	`chnm/rrchnm.org` — the folder that holds the whole website
Markdown (`.md`)	Plain text with simple formatting marks
Front matter	The settings block at the top of every post
Bundle	A folder holding one post’s `index.md` plus its images
Slug	The last part of the URL, set in front matter
Commit	Saving your change, with a note about what you did
Branch	A private draft copy of the site to work in
Pull request (PR)	A request to publish your branch to the live site
Build	Hugo turning your text into web pages

2. Where things live

content/
  blog/
    2026-04-18-spring-fundraiser/      ← one blog post = one folder
      index.md                         ← the post itself
      crowd.jpg                        ← images that belong to this post
    2025-08-25-graduate-reflections/
      index.md
  publications/                        ← not blog posts — leave to developers
  page/                                ← standalone pages (about, contact…)
static/
  media/                               ← shared images, organized by topic
    reports/
  img/                                 ← site assets (logos, default images)

On this site, every blog post is a “bundle”: a folder with an index.md inside it — even a post with no images. That is the house convention here. Do not create a loose my-post.md file directly in content/blog/.

Folder name: start with the date, then a short hyphenated summary: 2026-04-18-spring-fundraiser. Existing posts all follow this pattern.
The file inside is always named index.md.
Images for the post go in the same folder, next to index.md.

The URL does not come from the folder name. It comes from the slug: field in your front matter (see section 4). A post with slug: spring-fundraiser lives at:

https://rrchnm.org/blog/spring-fundraiser/

Keep the folder’s slug and the slug: field matching so nobody gets confused.

Naming rules for the folder and the slug:

All lowercase
Hyphens instead of spaces: spring-fundraiser, not Spring Fundraiser
No accents, apostrophes, or other punctuation
Never change the slug of a published post — it breaks the link. (If you must, ask a developer to set up a redirect in static/_redirects.)

3. Creating a new post

Go to github.com/chnm/rrchnm.org.
Click into the content folder, then blog.
Click Add file → Create new file.
In the filename box, type the folder and file together, using a /:
```
2026-04-18-spring-fundraiser/index.md
```
Typing the / creates the folder automatically.
Paste the template from section 7 into the big text box and edit it.
Scroll to the bottom to Commit (see section 8).

4. Front matter (the settings block)

Every post must start with front matter: a block fenced by three dashes, at the very top of the file, with nothing above it. Here is what this site uses:

---
title: "Our Spring Fundraiser Was a Huge Success"
authors:
- "Your Name"
date: 2026-04-18
draft: true
slug: spring-fundraiser
categories:
- news
tags:
- events
- fundraising
lede: "A one- or two-sentence summary shown under the headline and in link previews."
featured_image:
---

Field	Required?	Example	Notes
`title`	Yes	`"American Religious Ecologies Team Completes Digitization"`	Always in double quotes. The headline shown on the page.
`authors`	Yes	`- "Paige Magoto"`	One name per line, each starting with `-` and in quotes. Use the name as it should appear.
`date`	Yes	`2025-12-08`	Use `YYYY-MM-DD`. A future date means the post will not appear until that day.
`draft`	Yes	`true` or `false`	The only two values. `true` = invisible on the live site; `false` = published.
`slug`	Yes	`graduate-student-reflections-sustainability-summer`	Lowercase-with-hyphens. Becomes the URL: `/blog/<slug>/`. Match it to the folder name.
`categories`	Recommended	`news` or `post`	These two cover almost every post — `news` for announcements, `post` for regular articles. One per line, lowercase.
`tags`	Optional	`- teaching + learning` `- research + tools` `- events`	Freeform topic labels, one per line, lowercase. Reuse existing tags where you can.
`lede`	Recommended	`"Congratulations to Envisioning Seneca Village!"`	1–2 sentences. Shows as a subtitle under the headline and as the search/social summary.
`featured_image`	Optional	`viele-map-1.jpg`	A filename in the post’s bundle folder, or blank for the site’s default banner. See section 6.
`publishDate`	Optional	`2026-04-20`	A future date (same `YYYY-MM-DD` format) that keeps the post hidden until then, and lets the site publish it automatically. Only add this when scheduling — see section 10.
`aliases`	Not recommended	`- /news/envisioning-the-legacy-of-seneca-village/`	Old URLs that redirect to this post. Leave redirects to a developer — the better fix is usually to not change a published `slug` in the first place.
`crossposted`	Optional	`- name: "Sustainable DH"` `  url: "https://sustainabledh.org/…"`	If the post also appears elsewhere, adds an “Also published at” notice. A list of entries, each with a `name` and `url` (see below).

House style: lists use one item per line

authors, categories, and tags are lists. Write each item on its own line, indented, starting with - :

categories:
- news
tags:
- events
- fundraising

Redirects and cross-posts (only if you need them)

Redirects (aliases) — leave these to a developer. The best practice is to never change a published post’s slug, so you rarely need one. If a post really must move, ask a developer to handle the redirect (via aliases or static/_redirects) so old links don’t break. You may see an aliases block in existing posts — that’s what it is:

aliases:
- /news/mills-kelly-named-executive-director/

If the post is also published somewhere else, add a crossposted list — each entry is a name and a url, and the page shows an “Also published at” notice:

crossposted:
- name: "Sustainable DH"
  url: "https://sustainabledh.org/blog/example/"

Front matter rules that break the site if ignored

The --- lines must be exactly three dashes, on their own line, with no spaces.
Nothing goes above the opening --- — no blank line, no heading, no text.
If a title contains a colon, quotes are mandatory: title: "Q&A: Meet the Team"
If a title contains double quotes, use single quotes on the outside: title: 'The "Best" Year Yet'
Never use tabs for indentation. Spaces only (two spaces is fine).

The `draft` flag

Set draft: true while you write. When you’re ready to publish, change it to draft: false and commit again. A post with draft: true will not appear on the live site, no matter what else you do.

5. Markdown formatting

Leave a blank line between paragraphs. A single line break is ignored by Hugo — two lines of text with no blank line between them become one paragraph.

Headings

## Section heading
### Sub-heading
#### Smaller sub-heading

Start at ##. Do not use a single # — the post’s title is already the top-level heading, and using # gives the page two competing headlines.

Emphasis and links

**bold text**
*italic text*

[Link text](https://example.com)
[Link to another post on this site](/blog/my-other-post/)

Internal links start with / and end with /. For your own pages, use the short form (/blog/some-slug/) rather than pasting the full https://rrchnm.org/....

Lists

- First item
- Second item
  - Indented sub-item (two spaces)

1. First step
2. Second step

Leave a blank line before and after a list.

Quotes, dividers, code

> A pull quote or a quotation from someone.

---

Use `backticks` for a word that's a filename or a button label.

Tables

| Name | Role |
|------|------|
| Ada  | Lead |
| Grace| Ops  |

6. Images

On this site you insert images with the figure shortcode, not with plain Markdown. It gives you captions, credits, and a click-to-enlarge lightbox for free.

Uploading an image that belongs to one post

Open your post’s folder (e.g. content/blog/2026-04-18-spring-fundraiser/).
Click Add file → Upload files.
Drag the image in, then commit.

Before uploading: rename the file to lowercase-with-hyphens (fundraiser-crowd.jpg, not IMG_4471 (1).JPG), keep it under ~500 KB, and no wider than about 2000 pixels. Huge photos straight from a phone make pages slow.

Inserting it

Because the image sits next to index.md, refer to it by bare filename:

{{< figure src="fundraiser-crowd.jpg" alt="Volunteers setting up tables in the hall" caption="Setting up before doors opened." >}}

src — the filename (for a post image) or an absolute path (for a shared image, below).
alt — alt text: a description for screen readers and for when the image fails to load. Describe what’s in the photo; don’t write “image” or “photo of”.
caption — optional text shown under the image.
Optional: align="left", align="right", or align="center"; attr="Photo: Jane Doe" with attrlink="https://…" for a credit.

Shared images (used across several posts)

Put them under static/media/<topic>/ (organized by topic, e.g. reports/, not by date), then reference them with an absolute path starting with / and dropping static:

{{< figure src="/media/reports/annual-report-cover.jpg" alt="Cover of the 2026 annual report" >}}

To set the post’s banner image

Put the image in the post folder and name it in front matter:

featured_image: banner.jpg

Leave it blank and the site uses its default banner.

Other shortcodes available on this site

Only these shortcodes exist here. Anything else will fail the build and your post won’t publish.

{{< gallery cols="2" >}}
  {{< figure src="photo-1.jpg" alt="…" caption="…" >}}
  {{< figure src="photo-2.jpg" alt="…" caption="…" >}}
{{< /gallery >}}

{{< youtube "dQw4w9WgXcQ" >}}

{{< button href="https://example.com" text="Read the report" >}}

{{< support-btn >}}

gallery — arranges several figures in a grid (cols can be 2, 3, or 4).
youtube — embeds a video; give it the video ID or the full URL.
button — a red call-to-action button; add external="false" for links within rrchnm.org.
support-btn — the standard “Support Our Work” donate button (no parameters needed).

7. Post template — copy this

---
title: "Your Headline Here"
authors:
- "Your Name"
date: 2026-07-13
draft: true
slug: your-headline-here
categories:
- news
tags:
- tag-one
- tag-two
lede: "One or two sentences summarising the post, shown under the headline."
featured_image:
---

Open with a short paragraph that says what this post is about. Along with the
`lede` above, this sets the scene for readers arriving from the homepage.

## First section

Body text goes here. Leave a blank line between paragraphs.

{{< figure src="example.jpg" alt="Description of the image" caption="An optional caption." >}}

## Second section

- A point
- Another point

> An optional quote.

Closing paragraph, with a [link somewhere useful](https://example.com).

8. Saving your work (committing)

At the bottom of the GitHub editor:

Write a short commit message: “Add spring fundraiser post” or “Fix typo in fundraiser post”.
Choose “Create a new branch for this commit and start a pull request.”
Name the branch something like post/spring-fundraiser.
Click Propose changes, then Create pull request.

Working on a branch means the live site is untouched until the pull request is reviewed and merged.

What happens next on this site: a developer reviews your pull request. When they merge it into main, the site rebuilds automatically and your post goes live at https://rrchnm.org/blog/<slug>/ within a few minutes. There is no automatic per-pull-request preview — if you want to see it staged before it’s live, ask a maintainer to push your branch to the preview branch.

Committing directly to main publishes immediately with no review. Only do this if you’ve been told it’s the accepted workflow, and only for small fixes.

Editing an existing post

Open content/blog/<the-post-folder>/index.md on GitHub, click the pencil icon (top right of the file), make your edits, and commit the same way.

9. How your post gets published (deployment)

You never publish the site by hand — it’s automated. Here is the whole pipeline, start to finish:

Your pull request is reviewed and merged into main (section 8).
Merging automatically starts a build on GitHub Actions: a tool called Hugo turns all the Markdown into web pages, packages them, and deploys them to rrchnm.org.
A few minutes later (usually under five), your post is live at https://rrchnm.org/blog/<your-slug>/.

That’s it — no button to press, no files to upload to a server. Merge, wait a few minutes, refresh.

Where the build happens. Every merge, push, and scheduled run appears on the Actions page:

https://github.com/chnm/rrchnm.org/actions

Each run shows a status: a spinning amber dot (building), a green check (built and deployed successfully), or a red X (something failed and the site did not update).

Two related paths use the same pipeline: pushing to the preview branch deploys to the staging site (hugo.chnm.gmu.edu) instead of production (see section 8), and scheduled posts publish themselves on a timer (see section 10).

If something looks wrong

Give it a few minutes first — builds are not instant. If, after roughly ten minutes, your post still isn’t live, or you see a red X on your pull request or on the Actions page, the build failed.

You are not expected to diagnose or fix it. Build failures are almost always technical (a template, a setting, a dependency) and are the web team’s job, not yours. Instead:

Open https://github.com/chnm/rrchnm.org/actions and find the failed run (the red X) for your change.
Copy its link.
Post a short note in the #rrchnm-website Slack channel — say what you were publishing and paste the link to the failed run. The web team will take it from there.

The live site is never in danger from a failed build: a build that errors simply doesn’t deploy, so rrchnm.org keeps serving the last good version until the problem is fixed.

10. Scheduling a post to publish later

Sometimes you want to finish a post now but have it appear on a specific future day — an embargoed announcement, or a post timed to an event. This site can do that automatically; you don’t have to come back and flip a switch.

How it works. The site rebuilds itself on a timer: an automated job runs every weekday (Monday–Friday) morning. The exact time isn’t guaranteed — it usually runs in the morning but can slip toward midday — so don’t count on a post appearing at a precise moment. Each run scans content/blog/ for any post whose publishDate has just arrived and, if it finds one, rebuilds and deploys the site. Hugo keeps a post hidden until its publishDate has passed, so the post stays invisible until that build runs and then appears on its own.

The one field that matters: publishDate. Add it to your front matter with a future date:

---
title: "Big Announcement"
authors:
- "Your Name"
date: 2026-04-15
publishDate: 2026-04-20
draft: false
slug: big-announcement
categories:
- news
lede: "A one- or two-sentence summary."
---

Write publishDate as a plain date (2026-04-20), the same YYYY-MM-DD format as date.
draft must be false. A draft never publishes, scheduled or not.
Keep date as when the post was written and set publishDate to when it should go live. date is what readers see as the post’s date and what controls ordering; publishDate only controls when it becomes visible.

What you do: write the post with draft: false and a future publishDate, open your pull request as usual, and have a developer merge it to main ahead of time. Merging rebuilds the site immediately, but because publishDate is still in the future the post is built as hidden. On the first weekday build at or after your publishDate, it goes live automatically — no further action needed.

Things to know:

Use publishDate, not just a future date. Only publishDate triggers the automatic build. A post with just a future date stays hidden but won’t reliably appear on its own — it would only show up the next time someone else happens to cause a build.
The timer only runs on weekdays. A publishDate that lands on a Saturday or Sunday won’t appear until Monday morning’s build. (The job looks back a few days, so weekend dates are never missed — just held until Monday.)
It appears when the build runs, not at a precise time. The weekday build happens in the morning, but the exact time varies (it can slip toward midday). Expect the post to appear sometime that morning, on or after your publishDate — not on the dot. If precise timing matters, ask a developer to publish it manually instead.
It must be merged to main first. The timer only sees posts already on the live branch, so don’t leave a scheduled post sitting in an open pull request.

11. Publishing checklist

Before you set draft: false:

12. When something goes wrong

Symptom	Most likely cause
Post doesn’t appear at all	`draft: true`, or a `date` in the future
Post is at the wrong URL	`slug` differs from what you expected — the URL is `/blog/<slug>/`, not the folder name
Whole page shows as one blob of text	Missing blank lines between paragraphs
Raw `---` and `title:` visible on the page	Front matter isn’t at the very top, or a dash line is malformed
Build fails (red X), or post still not live after ~10 min	Often a bad shortcode or broken front matter (a colon in an unquoted `title`, a tab used for indenting) — but you’re not expected to fix it. Check the Actions page and relay the failed run link to #rrchnm-website Slack (see section 9).
Image is a broken icon	Wrong `src`, the file wasn’t uploaded, or the filename case doesn’t match (`Photo.JPG` ≠ `photo.jpg`)
Page is blank after publishing	Unquoted colon in the `title`
Scheduled post didn’t publish on its day	Used a future `date` instead of `publishDate`; still `draft: true`; the date fell on a weekend (publishes Monday); or the post was never merged to `main`

Nothing you do is permanent. Every change is recorded and can be undone. If a pull request looks wrong, close it and start again — you can’t break the live site from a branch.