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

Codebooks

Codebooks 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 codebooks in their lessons. Our aim is to support maintenance, future translatability, and flexible usability.

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

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

• Codebooks consist of the code + line comments only
• Headings and subheadings mirror those of the lesson to support readers' navigation
• Codebooks do not extend or replicate commentary from the lesson

Notes on Codebooks in ph-submissions:

• Hosted in our organisational Colab, which is part of our Google Workspace
• Uploaded to Colab + linked directly to ph-submissions in Phase 1 Submission (Charlotte and I fully manage this as part of the work we do to process new lesson materials)
• Located in /assets/lesson-slug alongside any other assets (as part of the work that Charlotte and I do to process new lesson materials)
• Links to the asset within draft lessons will take the form: https://github.com/programminghistorian/ph-submissions/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb

How to Link a Codebook in Colab to GitHub:

• File > Save a Copy in GitHub

• Enter the following into the dialogue box:

• Repository:
  programminghistorian/ph-submissions

• Branch:
  gh-pages

• File path:
  assets/lesson-slug/lesson-slug.ipynb

• Commit message:
  Create lesson-slug.ipynb

• Include a link to Colaboratory:
  [YES]

Notes on codebooks in Jekyll:

• 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 a live link to the rendered file in the lesson.
• 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

--