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.

/assets

Notebooks

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 + line comments only
• Headings and subheadings mirror those of the lesson, to support readers' navigation
• Notebooks do not replicate nor extend commentary from the lesson

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 IDE (VSCode, Atom...).
• 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>"
   ]
  },

• 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 the file in the lesson: so the notebook must already be published before that build.
• This link is rendered using https://nbviewer.org/: links to the asset within published lessons will take the form:https://nbviewer.org/github/programminghistorian/jekyll/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb

--