Home

Welcome to the Riddle Project wiki. This guide helps illustrate how to add information to the site, including blog posts and new story maps. It also explains the layout and functionality of the different pieces of the site.

Introduction

riddleproject.github.io is powered by Jekyll, which serves the site from this repository onto the web. Jekyll makes it simple to test and build up content for the Riddle Project and check if formatting agrees. Much of this documentation will match Jekyll's own documentation, so for performing tasks like setting up a local server and editing styles, using the Jekyll documentation in tandem with this wiki would be useful. This site is powered by the Minima theme, so reading about that theme would also be useful. There is significant documentation there that will help with any extra questions on maintaining the site.

Generally, to maintain this site, only a basic understanding of markup is necessary. Adding new blog posts is as simple as uploading a correctly formatted file, and adding new story maps is a matter of matching the syntax of existing story maps. The site is designed so that building it up just means using the existing Jekyll templates alongside some simple (and mostly predefined) markup, HTML, and Javascript. It might sound intimidating, but it's really accessible!

Adding new blog posts

All of the blog posts for this page are written in Markdown. Markdown is incredibly simple to use—even this wiki is written in markdown. The link above references a quick guide to syntax, which will be useful for writing blog posts. Essentially, markdown allows you to use plain text in order to define more complex formatting. For instance, adding *s around a word (like *this*) will make it italics. Checking out the source of the existing blog posts (by opening them in a text editor like Sublime) will offer a good set of examples that show how the formatting works.

Writing a blog post in Markdown is simple. Let's take this post as an example. The document is structured like this:

---
layout: post
title: "New SSHRC Funding for The Riddle Project"
categories: Announcements
author: " Jacquelyn Sundberg "
---

The Social Sciences and Humanities Research Council...

You can see that the "layout" is defined as a post (because this is a blog post) and the title is written in quotes. Any categories for the post can be added, separated by commas. Here, the only category is Announcements. You can add new ones on the fly. The last piece of metadata is the author, again written in quotes. From there, just write out the blog post in markdown syntax. (If you want to get fancy, you can also write in HTML, so really anything is possible with this format. You can add images, links, colors, whatever!)

Once the post is written, save it in the file format "YEAR-MONTH-DAY-SHORTTITLE.md. In this example, the file name is 2019-07-25-SSHRC-funding.md. You must save it in this format, otherwise the post won't be registered by the server, and won't appear online. The date will automatically be tagged in the article based on the filename.

Upload your newly saved markdown document to the _posts folder in the Github repository using either Github online, Github desktop, or by pushing the file directly from the command line.

The rest will be handled automatically: All of this metadata will be transformed and updated automatically in any place the blog post is referenced across the site. Same goes for the content, which will fill itself in.

Adding new Story Maps

Although story maps are slightly more complicated, they are built in a similar manner to blog posts. All of the story maps for the website are stored in the folder visualizations. That being said, it's also totally fine to make a new folder for a special set of story maps, or to move the current ones around. Just make sure link references reflect the location of the story map in the repository! (More on that later).

We'll take one of the story maps from Story Maps tab as an example. To build one, just make a new HTML document in a text editor (like Sublime). Once that's done, set the metadata, similarly to setting the metadata for a blog post:

---
title: Holiday Riddles
layout: story-layout
---

The story map will need a title, and the layout will need to be set as story-layout so that the server knows that the new file is a story map (and can add the necessary components to make the story map work).

From there, add in the slides using HTML. Here's the first slide of an example story map:

<div id='features'>
    <section id='introduction' class='active'>
        <h3>How do holidays play into riddling practices?</h3>
            <p>Many of the riddles in this exhibition originated in 18th-19th century Britain. These were known as Enigmatic Bills of Fare (EBoFs). Enigmatic Bills of Fare were riddling menus which guests would be expected to solve before ordering their meals!</p>
    </section>
</div

This may look intimidating at first, but it's really quite simple. You'll need an ID for the slide (that way you can set a map image later on). Here, the ID is introduction. Because this is the first slide, the class is active. It isn't necessary to add this attribute to later slides. Inside the h3 tag is the slide title. The title for this slide is How do holidays play into riddling practices?. In the p tag is a description. Once that's done, close the p tag and close the section tag. All of the chapters are built in this style and are contained within features div. The text is now ready to go!

To add a map visual for each slide, you'll need to add in some basic Javascript. Let's use this story map as an example and write up the map metadata for the slide:

<script> 
var chapters = {
  "introduction": {
    bearing: 0,
    center: [-62.88620, 48.62161],
    zoom: .8,
    pitch: 0,
    filter: null,
  },
}
</script>

First, you'll need to add in a script tag. This tells the browser that you're using Javascript now, not HTML. Then, you set up a list of chapters named chapters. The first chapter (the one we built above) is introduction. Inside the brackets for that chapter, you'll set the bearing (which is the rotation of the camera), the center point in (longitude, latitude), the zoom, and the pitch. If you want to add in a filter for the slide, that can also be added (use the existing filter settings for reference). To set the camera, the Mapbox helper tool is perfect. It will allow you to orient the camera perfectly for the visual you want.

Each additional slide can be added into the chapters variable, with commas between each chapter. Make sure that the chapter titles are the same as the titles you wrote for each section.

To get a better sense of how this all fits together, take a look at some of the already-built visualizations. They're accessible in the visualizations folder of this repository. Although it may look intimidating, once you get the basic idea down, building up more story maps is really easy. The hard part is writing the content for them.

Now that a story map is built, it needs to be embedded in the website somewhere. The best way to do this is using iframe. The new map is located on the website at the path where it's saved--for example, this holiday story map is saved at riddleproject.github.com/visualizations/holiday-riddles.html. That link is for the "full screen" version of the app, which is technically just its full representation. To embed the app in another page, just wrap the link in an iframe html element:

<iframe src="visualizations/holiday-riddles"
        width="100%" height="500px" frameBorder="0">
</iframe>

The src tag points to the location of the map in the repository or its true url, and the width and height just specify how big the map should be. What will this look like once it's actually embedded? Check out the Story Map section of the website.

Now you have a new story map that you can put into a blog post, special page, or anywhere else!