Guide for students
How to add your work
You do not need to know how to code. You will copy a template, fill in the blanks, and save. This page walks you through it.
Before you start
You need:
- A free GitHub account.
- An invitation to this project from your instructor. Accept it by email.
- Your pictures, saved as
.jpgfiles under 1 MB each, with names in lowercase and hyphens (grandmothers-suitcase.jpg).
Step 1. Open the editor
- Go to the project page on GitHub (your instructor will give you the link).
- Press the
.(full stop) key on your keyboard. A code editor opens in your browser.
You will see a list of folders on the left. The two you care about are objects and essays.
Step 2. Copy the template
To add an object
- Open the
objectsfolder. - Right-click the
_templatefolder and choose Copy, then right-clickobjectsand choose Paste. - Right-click the new copy and choose Rename. Give it a short name in lowercase with hyphens, like
grandmothers-suitcase. This name becomes part of the web address.
To add an essay, do the same thing in the essays folder.
Step 3. Fill in the blanks
- Open
index.mdinside your new folder. - At the top, between the two lines of
---, are the “front matter” lines. Change the words after each colon. - Below that is the writing. Replace the sample text with your own.
- Grey text inside
<!-- -->is a note to you. You can delete it.
Object fields
| Field | What to write | Required |
|---|---|---|
title |
The name of the object | Yes |
author |
Your name | Yes |
thumbnail |
The picture file, like images/suitcase.jpg |
Yes |
summary |
One or two sentences about the object | Yes |
image-alt |
A description of the picture for people who cannot see it | Yes |
image-credit |
Where the picture came from | Yes |
maker, object-date, placename, medium, dimensions, collection, accession |
Facts for the label. Delete a line if you do not know it. | No |
year |
One number that places your object on the timeline. Use a minus sign for BCE (-500). |
Yes |
region |
Africa, Asia, Americas, Europe or Middle East. Used by the filters. | Yes |
tags |
One to three themes. Reuse tags other students have used so the filters work. | No |
published |
false hides your page. Delete the line when you are done. |
No |
Essay fields
| Field | What to write | Required |
|---|---|---|
title |
Your headline | Yes |
author |
Your name | Yes |
kicker |
A short label above the title | No |
summary |
One sentence that makes your argument | Yes |
lead-image, lead-image-alt, lead-image-caption |
The big picture at the top | Yes |
thumbnail |
The picture for your card | Yes |
objects |
The objects your essay is about (use the folder name as slug) |
No |
position |
Order on the Essays page. Leave it, your instructor will set it. | No |
Step 4. Add pictures
- In the editor, open your folder’s
imagesfolder. - Drag your picture files from your computer into it.
- Use the file name in the blanks:
images/suitcase.jpg.
Always write alt text and a credit. If you did not take the picture, say who did and link to the source.
Step 5. Use the special blocks
You can copy these blocks into your writing. Change only the words inside the quotation marks.
A picture with caption
{% include essay/figure.html
image="images/suitcase.jpg"
alt="Describe the picture"
caption="What it shows and where it came from."
size="wide"
%}
size can be small, normal, wide, or full.
A feature card for an object
{% include essay/object.html slug="bowl-with-dragons" note="Why it matters." %}
A “look closer” box readers can open
{% include essay/look-closer.html title="Look closer: a detail" text="Explain it." %}
A pull quote
{% include typography/pullquote.html text="One memorable sentence." %}
Writing tips
| Part | Length |
|---|---|
| Object description | 150 to 300 words |
| Essay | 800 to 1,500 words |
| Essay opening paragraph | 60 to 100 words |
| Essay sections | 2 to 4, each with a short heading |
Use ## Heading for a section heading and *word* for italics. Leave a blank line between paragraphs.
Step 6. Save and send
- Click the Source Control icon on the left (a branch symbol).
- Type a short message, like “Add suitcase object”.
- Click Commit & Push. Choose Create a new branch if asked, then name it after yourself.
- Tell your instructor. They will review and publish your work.
The site updates a couple of minutes after your instructor approves it.
Troubleshooting
| Problem | Try this |
|---|---|
| My page does not appear | Check that published: false has been removed and that the folder name has no spaces or capital letters. |
| My picture is missing | Check the file name matches exactly, including .jpg. Check it is in your images folder. |
| The page is blank or broken | Check the --- lines are at the top and after the front matter, and that every quotation mark has a partner. |
| A colon in my title breaks things | Put the title in quotation marks: title: "Trade: A Story". |
| My block shows as text | Check it starts with {% include and ends with %}. |
Still stuck? Ask your instructor and share the page name.
Editing the museum entrance
In index.md, change the hero title and introduction at the top. Set
spotlight to an object’s folder name. Below the front matter, edit the
headings and paragraphs as Markdown. The include lines assemble the displays;
you can move whole section pairs to change their order.
Exhibition pages work the same way: write the introduction in Markdown and
list object folder names and notes under objects in the front matter.