Oral History (as) Data

Analyze and publish coded oral history and qualitative interviews

How To Configure Your Website

Below are a few quick steps to help you begin configuring your GitHub site for use with Oral Histories as Data (OHD).

Making a Filter

Step 1: Make a Template of OHD

picture of the button that enables user to create a new template in github
  • Name your repository.
image of the field users must fill out in order to create a name for their new template
  • Click the “Create Repository From Template” button – this will copy all the files (but not the history!) of the Oral History as Data repository into your own repository.
picture of the create repository button located at the bottom of the page

Step 2: Upload Your Transcript

Go to the _data/transcripts/ directory:
  • Click on the _data folder, which will take you to a new page.
  • Then click into the transcripts folder.
Drag your transcript(s) onto the webpage to upload them:
  • Find the transcript spreadsheet/CSV file or files you created and downloaded in the Prepare Your Data Section.
    • Make sure the transcript CSV is titled something simple, and that it’s all lowercase and has no spaces or special characters. E.G. doe_john.csv (And make sure it has a .csv extension!)
  • Drag the file or files onto the web page – the page will change when you drag it onto the webpage to say “Drop to Upload Your Files”. Drop the file to upload it!
    • Alternatively, you can push the “Add File” dropdown button at the top right of your screen, and then select the file(s) you’d like to upload.
Commit your upload/changes to add the file(s):
  • Once it’s uploaded, you’ll need to commit your change to make it permanent. Commit your upload at bottom of page by scrolling to the bottom of the page and clicking “commit new file”.
  • Below is what the CSV should look like after you’ve committed it into your GitHub repository.
complete and committed csv in github
This is how the CSV should look after you paste it into the new file and commit it.

NOTE: If the CSV has a problem, GitHub will show you an error message that will say: “We can make this file beautiful and searchable if this error is corrected:” After that phrase, they will also point out a line number that is causing the problem. Open the file up by clicking on the pencil icon in the top right of the file area. Go to the line indicated and see if there’s an obvious error. If you can’t get it fixed, go back to your Google Sheet and see if there’s anything to clean up. Even if there is nothing wrong, re-download the file as a CSV, rename it to the new title, then drag it back to the page as you did above. Hopefully one of these steps clears up the problem.

Creating a .MD File

Step 3: Upload Your Filters.CSV file

Much like the step before, you will:

  • Go to the _data folder.
  • Upload your filters.csv file into the folder by dragging it onto the webpage
    • This will replace the file that is currently there.
  • Commit your changes.

Step 4: Creating a Markdown File

Go to the _transcripts/ directory:
  • Navigate back to the root of your repository by clicking on <> Code at the top left of the page.
  • Click on the folder that says “_transcripts”
_transcipts button
Make a copy of one of the Markdown files in the directory:
  • Open up any of the .md file examples that are in this folder
  • Navigate to the button that says “raw” and click it
raw file button
  • Copy the text inside of the file you opened
raw file text
Create a new Markdown file for your transcript by pasting and then editing your copied text:
  • Go back to your _transcripts directory by clicking back two pages in your browser.
  • Click the “Create New File” button
create new file button
  • Name this file the same name you named your transcript file, but be sure to put .md rather than .csv, as it’s extension.
name field in new markdown file

You are creating a markdown file; more on Markdown here. Jekyll uses the markdown file as the basis for creating web pages. All the information stored between the two --- at the top and then down a bit is called frontmatter. This frontmatter is written in a language called YAML, which is a a human-readable language for writing/storing data variables. (You’ll work with some .yml files later as well)

  • Paste the text you copied from the raw file you opened earlier into this new file.
pasted text in new .md file
Pasted text before editing
  • Edit the variables in the frontmatter between the --- lines ) to fit your data – be sure that the object-id option is the same as the filename (without the extension) of your transcript.
new .md file text after being edited for new file
File after being edited for new file

NOTE: if the “object-id” field is different than the name of your transcript CSV file in the _data/transcripts folder, the tool will not work. The transcript file will have an extension (.csv) but the object-id should not have an extension. So if the transcript is called doe_john.csv, then the object-id for the corresponding Markdown file should be doe_john.

Commit your changes:
  • Write a commit message, briefly describing the changes you made and then commit them at the bottom.
  • Once you are done, navigate to your new file, it should look like the example below
the newly created md file

Optional: Connect the transcript to an audio or video file using av_source

You may want to connect transcript to a audio or video recording. The tool has built in connections to YouTube, Vimeo, Soundcloud, and plain mp3 files. You’ll need to incorporate some simple information in the header of your markdown file to make these connections possible. To provide users navigation to certain moments in the recording, you’ll also need to provide timestamps in the data file.

  • Look in the header of your markdown file. You’ll see that there is a space for av_source. Here you have four options, using OHD: mp3, youtube, soundcloud, or vimeo.

Using all lowercase letters, type the platform’s name where your file is uploaded.

opened file, ready for editing
  • Below av_source, you’ll see a space for your file’s audiovideo-id. Fill in this information.
opened file, ready for editing
  • Below are pictures indicating the location of various audiovideo-id locations on different platforms.
opened file, ready for editing
location of your youtube audiovideo-id
opened file, ready for editing
location of your vimeo audiovideo-id
opened file, ready for editing
location of your the URL path

NOTE: if you want to utilize an mp3 file, you can create also create a webpage to house your file and link the URL, in quotation marks, in the audiovideo-id. You can store mp3s in your GitHub repository, but be aware that GitHub only allows a small amount of space to each repository. It’s probably best practice to link them from elsewhere. You will also need to change av_source to “mp3”. Follow the visualizations below for instruction.

  • If you have a page for your mp3 file copy the URL.
mp3 page URL
  • Copy and paste URL with quotation marks included.
Included URL for mp3 feature
  • Change av_source to “mp3”.
av_source edited to include mp3 file
s

Step 4: Setting up the visualization(s)

OHD offers a way to categorize your transcripts using tags. This is done through two locations: the “tag” column cells in your transcript’s CSV and the filters.csv file, which is already provided for you in the structure of OHD. If you are not aware of either of these files, first visit our steps on “How To Prepare Your Data.”

Creating Filters
  • Open the filters.csv file you created in your text editor.
  • Navigate to the “_data” folder
  • Open the “_data” folder and click the pencil icon to edit the file
  • Copy and paste the filters.csv you created in the Prepare Your Data tutorial over into the existing content.
  • Alternatively, you can simply edit the CSV file here. (Below is how the file looks when opened with the pencil icon.)
opened file, ready for editing
Filters.csv as it looks in a text editor
filters.csv copied into GitHub
filters.csv copied into GitHub
  • Commit the change at the bottom of the page by clicking the commit button (be sure to write a commit message so you can track your changes)
picture of the commit button at bottom of page
  • However you edited it, the finished CSV should look like the example below (with your new tags and descriptions) in GitHub
finished csv after being transferred to github
CSV after being transferred to GitHub
  • Below is a slightly more robust example of what your visualization will look like.
picture of finished visualization
finished OHD visual

Next Step - Deploy your site

Previous Step: Prepare Your Data