File Management

Publishing Tasks: Phase 1 Submission

File Management

---

Contents of this page:

• 1. Markdown files
• 2. Images
• 3. Assets

---

Lesson materials are saved in the following directories on ph-submissions:

1. Markdown files

EN:

/en
/en/drafts
/en/drafts/originals
/en/drafts/translations
/en/published
/en/published/originals
/en/published/translations

ES:

/es
/es/borradores
/es/borradores/originales
/es/borradores/traducciones
/es/publicadas
/es/publicadas/originales
/es/publicadas/traducciones

FR:

/fr
/fr/en-cours
/fr/en-cours/originales
/fr/en-cours/traductions
/fr/publiees
/fr/publiees/originales
/fr/publiees/traductions

PT:

/pt
/pt/esbocos
/pt/esbocos/originais
/pt/esbocos/traducoes
/pt/publicadas
/pt/publicadas/originais
/pt/publicadas/traducoes

2. Images

As part of our commitment to global accessibility, we keep content on our site 'light' to avoid slow-loading for readers with lower internet speeds or less computing power. We've agreed on a maximum image size of 840 pixels on the longest edge.

Originals

• Create an images directory named to match the lesson-slug exactly
• Note of the order of images in the lesson, rename each one in sequence following our Image Naming Conventions
• Check image sizes, resize if necessary (max. 840px on longest edge)
• Upload directory to /images
• Return to the Markdown file, update filenames in liquid syntax as necessary

Translations

• Navigate to the original lesson's /images directory (named to match the original-lesson-slug)
• Note any new images created for the translation, rename each one in sequence following our Image Naming Conventions
• Check any new image sizes, resize if necessary (max. 840px on longest edge)
• Upload new images to the original lesson's /images directory
• Return to the Markdown file, update filenames in liquid syntax as necessary

3. Assets

Sub-directories should be named to match the lesson-file-name (slug:) exactly.

Datasets include for example a CSV file, or a directory of images for analysis. The maximum size of data assets hosted on our GitHub repository is 25 MB.

/assets

Notebooks

If authors choose, they may create a notebook as a supplementary resource to support teaching and learning, after Phase 4 Open Peer Review is complete. Notebooks associated with lessons are hosted within our infrastructure so that we can manage them as assets and ensure their sustainability.

To support this, we’ve developed some guidelines for authors who choose to integrate notebooks in their lessons. Our aim is to ensure effective maintenance, future translatability, and flexible usability.

These guidelines are based on a key understanding that we want our readers to be able to make the choice to work either in Google Colab, in their preferred alternative cloud-based development environment, or opt to run the code locally.

If authors provide notebooks to accompany their lesson, we ask that notebooks:

• Consist of the code + essential line comments only (do not replicate nor extend commentary from the lesson)
• Mirror the headings and subheadings of the lesson, to support readers' navigation

Notebooks in ph-submissions:

• Authors may share with us an .ipynb file or a link to their notebook in Google Colab. If the latter, we download it from Google Colab as an .ipynb file. Authors should ensure they have cleared all cell outputs before preparing their file.
• We upload this file to the lesson's assets folder by copy and pasting the raw code from a local text editor (TextEdit on Mac, Atom...), and name the file lesson-slug.ipynb.
• Before committing this first upload, we insert a snippet of code which will generate the Open in Colab button at the top of the file:

{
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "view-in-github"
   },
   "source": [
    "<a href=\"https://colab.research.google.com/github/programminghistorian/ph-submissions/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
   ]
  },

Remember to change the lesson-slug placeholder in the link!

• The snippet of code above should be pasted in directly after the first two lines of raw code of the original notebook, which should look like this:

{
  "cells": [

• If the code appears different in a particular notebook, we may need to experiment with the positioning of the Button code. In all cases, it can be helpful to paste the code into a JSON validator to ensure everything is formatted correctly.
• The notebook can then be committed to /assets/lesson-slug alongside any other assets (as part of the work that the Publishing Assistant and Publishing Manager do to process new lesson materials)
• Links to the notebook within draft lessons will take the form: https://github.com/programminghistorian/ph-submissions/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb

Editing notebooks in ph-submissions

• Although it's possible to edit the notebooks' raw code directly in GitHub by clicking Edit File (or the pen icon), this is not intuitive or easily navigable. This option should be reserved for small changes that can be searched through using control + F (e.g. typos, single words, etc.).
• For complex edits, authors are encouraged to either download the .ipynb file from the assets or click the Open in Colab button, make their changes in their preferred environment, and send a new copy of the .ipynb file to the Publishing Assistant via email.
• The Publishing Assistant can upload the new file by copy and pasting the raw code: this will ensure the changes are visible through GitHub's 'rich diff' function.

Notebooks in Jekyll:

• The .ipynb file is uploaded to /assets/lesson-slug in a PR that precedes the PR to publish the lesson. This is important, because we want to be able to include an external, live link to this file in the lesson: so the notebook must already be published before that build.
• During this first PR, the link in the Open in Colab button must be edited slightly to replace ph-submissions with jekyll.
• The live link is rendered using https://nbviewer.org/: links to the notebook within published lessons will take the form:https://nbviewer.org/github/programminghistorian/jekyll/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb. This must be edited throughout the lesson during the second PR to publish the lesson and its other associated files.

--