Each GRE garden article is stored in a single Markdown file which starts with front matter, and may also contain Hugo shortcodes. Each of these components are described below.

Front matter

Front matter is the metadata that appears at the top of the source file for each page. Specifically, GRE uses YAML-formatted front matter, and it looks something like this:

---
gre_id: "ac3df48e02"
aliases: [/id/ac3df48e02]
type: garden
title: "Grove at the shrine of Aiakos"
latlon: [ 37.739227, 23.518981 ]
author: Maureen Carroll
contributor: Jane Millar, Amartya Shri
date: 2021-04-21
modified: 2025-06-29
draft: false
---

The front matter must appear at the very top of the file. It starts with a line containing three hyphens --- and ends with the same. Each line in the front matter defines a metadata value for the page, as described here:

• gre_id (automatically generated) is an internal ID for the article
• aliases (automatically generated) defines any links that will point to this article, such as a "permalink" containing the ID
• type defines whether the page describes a garden, place, or person
• title is the name of the garden, place, or person being described
• latlon defines a point location for a garden (when known)
• author is the main author of the text of the page If multiple names, separate with a comma followed by a space ,
• contributor is anyone who contributed significantly to the article, such as the editor of the file. If multiple names, separate with a comma followed by a space ,
• date (automatically generated) is the date the file was created
• modified is the date of the latest modification to the file, and should be updated whenever the file is significantly updated
• draft indicates whether the article is still a draft, not yet ready for publication

Markdown

Markdown is a lightweight syntax for creating formatted text using plaintext. It supports things like headers, lists, emphasized text, links, and images.

When we are editing the source of a GRE article using Markdown, we only see the plaintext, not the final formatting that will appear on the GRE website. However, VSCode will automatically add some color-coding, which helps to visually distinguish various elements:

On the GRE website, this would be transformed into:

Shortcodes

For the GRE project, we have created some custom Hugo "shortcodes" to help normalize the entry of keywords, images, and linked IDs. When generating the website, Hugo will process these shortcodes to generate more complex displays of the data.

All shortcodes begin with {{< and end with >}} so that Hugo will recognize them.

The gre repo has been customized to enable keyboard shortcuts for adding these shortcodes. Simply type image, keyword (or just kw), or id then press CTRL-SPACE and press enter.

Images

Image shortcodes look like this (with a linebreak added for readability):

{{< image file="agora1.png" caption="Fig. 1: Agora of the Italians, reconstructed plan"
    credit="Drawing by M. Trümper." alt="" >}}

To add a new image shortcode, add a blank line, type image, then press CTRL-SPACE and press enter.

The image shortcode uses the following parameters:

• file is the name of the image file (usually .jpg or .png) that is stored in the separate gre-images repository on GitHub.
• caption is the image caption that will appear below the image.
• credit appears after the caption, and gives credit to the image photographer, drawing artist, etc.
• alt is usually blank, since the basic information should already be stated in the caption. However, alt text could contain additional information that would helpful to someone who cannot view the image.

When Hugo builds the website, it will convert this into more complex HTML and Javascript code that will display a smaller version of the image (with caption and credit) that can be clicked to view the larger image.

Keywords

Keywords are terms from a controlled vocabulary that can be used to describe features of a garden. GRE has chosen Getty's Art and Architecture Thesaurus (AAT) as its primary vocabulary for these terms, but also uses Kew Garden's Plants of the World Online (POWO) for plant names, and Getty's Union List of Artist Names (ULAN) for historical personal names.

Lists of keyword shortcodes look like this:

- {{< keyword "mosaics" >}}
- {{< keyword "olive trees" >}}
- {{< keyword "porticoes" >}}
- {{< keyword "Marcus Aurelius" >}}

To add a new keyword shortcode, add a blank line, type keyword (or just kw), then press CTRL-SPACE and press enter.

GRE uses Hugo to convert these shortcodes into links, automatically figuring out which vocabulary and ID to link to:

Notice that, while the full AAT term is "mosaics (visual works)", it is not necessary to add the parenthetical in the source code of the page, unless there are multiple terms listed in keyword.csv that have the same root (currently, just "exedrae", "podiums", and "triclinia"). In general, AAT uses the plural form of a term, but it is always good to check the current list of GRE keywords.

(Changes to the list of GRE keywords can be made by carefully editing the keyword.csv file.)

Linked IDs

In addition to keywords, GRE uses IDs to link to placename gazetteers Pleiades and Getty's Thesaurus of Geographic Names (TGN):

- {{< id vocab="Pleiades" id="579885" name="Athenae" >}}
- {{< id vocab="TGN" id="7001393" name="Athens (inhabited place)" >}}

Additionally, GRE people pages (for contributors to the project) uses IDs to link to ORCID (Open Researcher and Contributor ID) and WorldCat Entities:

- {{< id vocab="ORCID" id="0000-0002-1628-615X" name="AMINA-AICHA MALEK" >}}
- {{< id vocab="WorldCat" id="E39PBJv8CFc7mdbWrDBjtVPfbd" name="Amina-Aïcha Malek" >}}

To add a new id shortcode, add a blank line, type id, then press CTRL-SPACE and press enter.

When creating an id shortcode, the name should be the form of the name used by the linked website. (If you are wondering why the "id" shortcode requires more parameters that keywords, that's because the place and people ids are relatively unique, representing a single garden or person, and thus appearing on just a single page within all of GRE. Whereas a keyword might be applied across many different gardens.)