create and add content to index pages

[njr2128]

Follow-up to #21, each index page now needs to be populated with descriptive content (e.g., info about the semester's theme).

All index files are listed in blank-fill-log.xlsx. For tracking purposes, this file has been made into a googlesheet under M&K's account (Digital> Digital Admin > Field Notes)

[njr2128]

General language for Semester index pages

Fall 2014 was the very first offering of the Laboratory Seminar <i>HIST GR8906: Craft and Science: Objects and Their Making in the Early Modern World</i> at Columbia University by the Making and Knowing Project. The course contributed to the collective production of <i><a href="https://edition640.makingandknowing.org/#/">Secrets of Craft and Nature in Renaissance France. A Digital Critical Edition and English Translation of BnF Ms. Fr. 640</a></i>. The yearly theme was Moldmaking and Metalworking, and students in the course explored processes related to this theme and conducted hands-on reconstructions of related entries in BnF Ms. Fr. 640. The results of their skill building work from the beginning of the semester are recorded in Fieldnotes. As students worked towards composing critical commentary for <i>Secrets of Craft and Nature</i> in the form of <a href="https://edition640.makingandknowing.org/#/essays">Research Essays</a>, they kept "Annotation" fieldnotes to document their research process, reconstructions, and hands-on work in the laboratory. Profiles were a way for students to introduce themselves to each other and the instructors. Other select course materials, such as collective notes and reference documents, are found in the Reference pages.

[njr2128]

General Language for fld pages

Each student (or group of students) kept detailed fieldnotes for all skill building activities each semester.

General Language for ann pages

Annotation fieldnotes record planning, research, and hands-on work for the students' explorations of specific entries or processes in BnF Ms. Fr. 640. The results of this work are the <a href="https://edition640.makingandknowing.org/#/essays">Research Essays</a> in <i>Secrets of Craft and Nature in Renaissance France. A Digital Critical Edition and English Translation of BnF Ms. Fr. 640</i>.

General language for profiles

Students introduced themselves and their backgrounds to the instructors and each other in these profiles. They were asked to include as much or as little information as they liked.

[njr2128]

Questions that arose while I did this, with answers/comments by @gschare below:

• Can the descriptions handle basic markdown or html styling? e.g., hrefs, italics

gschare: HTML styling should work.

• In the fieldnote.html template pages, do I need to manually create the "pages" listings? i.e., do I need to write out each title and its corresponding link?
  • Perhaps we can automate part of this process - like to grab a listing of the files in that directory and put them as the links? Then I can add the titles

gschare: I can try to autofill some of the page listings, but we should also remember that some students may have fieldnotes which were collaborations that wouldn't be in their own folder.

• I have just edited all index pages in fa14 EXCEPT the fieldnote.html template ones (the ones that list each students' individual pages -- lowest level): a1f71c4
  Before I do the rest, can we test these pages?

gschare: will do later today

[njr2128]

Greg has created a pages.md file with the listings for each index.md pre-filled with the content of the directory, which simply has to be copied and pasted, as per f01fd81. This needs to be done recursively through each directory, and double-checked by eye for any errors to be corrected or manual revisions we desire

[gschare]

I created a Python script which runs the Pandoc command to generate the index.html files in every subdirectory.

How to run

1. Open terminal
2. Navigate to the fieldnotes-content repo
3. Ensure your repo is up to date by running git pull
4. cd content
5. python3 run_pandoc.py

This will generate a ton of index.html files. If everything runs without errors, you should see nothing printed to terminal. If there are problems, they will appear in terminal so you can look at them and fix them.

Common errors and how to fix them

The most common errors will be:

Missing fields

The error looks like:

[WARNING] This document format requires a nonempty <title> element.
  Defaulting to 'index' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

e.g. the index.md file has a blank value for title, like title: ""

You can fix this by giving the necessary fields a value, like title: "Fall 2014 Field Notes".

Malformed fields

The error looks like:

YAML parse exception at line 8, column 201,
while parsing a block mapping:
did not find expected key

This can be many things, like unescaped characters. Often this is because the fields are surrounded in double quotes ("), so they cannot contain double quotes or else Pandoc will get confused.

There is a relatively easy fix. Here's an example:

Bad

intro: "My favorite song is "Shape of You" by Ed Sheeran."
title: "Shape of You"
author: "Ed Sheeran"

Good

Escape the double quotes.

intro: "My favorite song is \"Shape of You\" by Ed Sheeran."
title: "Shape of You"
author: "Ed Sheeran"

Great

Put a > after intro and then prefix every line after intro with two or more spaces.

intro: >
  My favorite song is "Shape of You" by Ed Sheeran.
title: "Shape of You"
author: "Ed Sheeran"

Another advantage of using > is it makes it easy to have multiple lines:

intro: >
  Line 1.
  Another line...
  So many new lines!
another_field: "Another value."

Missing file

The error looks like:

pandoc: index.md: openBinaryFile: does not exist (No such file or directory)

This just means that my script is trying to compile an index.md file where there isn't one. This is most likely a bug in my script, not a mistake in the index.md files.

[njr2128]

Just realized that for any semesters with "reference" directories (like fa14), we did not generate index pages or include them in the various listings. This can be done manually, however.
--> moved to #32

For now, I am going to wait on making those pages (perhaps doing them all in one fell swoop) as I work on updating the other index pages

[njr2128]

Reference docs for YAML:

• https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
• https://yaml.org/spec/1.2.2/#chapter-2-language-overview
• https://yaml.org/spec/1.2-old/spec.html#id2776092

[njr2128]

Summary of what needs to be done

write script to check the following across all subfolders:

• pages.md exists
• index.md exists
• index.md info matches information contained in folder name
• index.md does not contain itself or pages.md in the page listing
• in index.md, automatically populate with the correct pages if not there already

Then,

• index.html is being generated by the build script
• for each index.html, add backlinks to the parent folder's index.html

Then,

• (not MVP) subfolders like reference are being handled - create and populate index pages for "reference", etc. directories #32
  • also, "assignments" folder