Getting Started Guide

Welcome to the “Getting Started Guide” for EditionCrafter. This guide describes how to include EditionCrafter in your website. In order to do so, you must first create the artifacts EditionCrafter needs to work. These artifacts are a set of JSON, HTML, and XML files generated from a TEI Document that you supply. You can use the EditionCrafter CLI to create all of these artifacts and a starting TEI Document in the correct format, based on a IIIF Manifest.

If you don’t have a TEI Document yet, don’t worry, the command line tool can help you create one. You can create a TEI Document from a list of images or from a IIIF Manifest. The EditionCrafter CLI will generate a TEI Document that includes all of the images in the IIIF Manifest you provide. You can even provide plain text transcriptions to include in your TEI Document.

In order to use EditionCrafter, you will also need to publish the EditionCrafter artifacts online, either on your edition website or on a separate data site. GitHub Pages is a no-cost way to accomplish this. However, documenting the use of git and GitHub Pages is beyond the scope of this guide. You can see examples of this pattern here.

You will also need a website where EditionCrafter will display your edition. We provide instructions for how to install EditionCrafter in a React app and in a HTML website. Lastly, the page images of your text need to be available online on a IIIF Image server. You can often obtain a link to your page images from the institution that is holding the originals. Here’s a good place to start.

Installing the EditionCrafter CLI

EditionCrafter has an accompanying command line interface (CLI) that is used to generate the artifacts it displays. This software is written in Javascript, so you will need to have Node.js installed on your computer. Once Node.js is installed, run the following command to install the tool:

npm install -g @cu-mkp/editioncrafter-cli

To test it out, try the command below, which displays the CLI documentation in the console. Note that you may need to restart your terminal window to get EditionCrafter CLI on your path.

editioncrafter help

Creating a TEI Document from a List of Images

If you are starting with a list of images, you can use the EditionCrafter CLI to generate a TEI Document for you based on your images. To do this, create a CSV file that lists the images in your document. You can generate a CSV file from an Excel spreadsheet or a Google Sheet.

The CSV file should have the following columns: url, label, and xml_id. The url column should contain the URL of the image, the label column should contain a label for the image, and the xml_id column should contain a unique identifier for the image. This ID will be used as the xml:id attribute for each surface and can be referenced when adding plain text transcriptions.

Once you have created this file, you can generate a TEI Document by running the following command:

editioncrafter images -i <images.csv> -o <output.xml>

Creating a TEI Document from your IIIF Manifest

If you are starting with a IIIF Manifest, you can use the EditionCrafter CLI to generate a TEI Document for you based on your IIIF Manifest:

editioncrafter iiif -i <iiif_url> -o <output.xml>

This creates an XML file on your computer at the output file path based on the IIIF Manifest that you point to in the <iiif_url>. In a separate section below, we will describe how to edit this structure to fill in the textual content of your edition. Before we do that, let’s finish setting things up.

In iiif mode, the XML ID for each generated surface will be f000 for the first surface, f001 for the second, and so on. This ID will be used as the xml:id for each surface and can also be referenced when adding plain text transcriptions.

Adding Plain Text transcriptions

If you have plain text transcriptions of your document, you can include them in the TEI Document that you are creating. To do this, create a folder on your computer that contains a text file for each page of your document. The text files should be named in the following format: <xml_id>.txt. For example, if you have a transcription for page 3 of your document and it has the ID of f003, the file should be named f003.txt. Once you have created these files, you can include them in the TEI Document by running the following command:

editioncrafter iiif -i <iiif_url> -o <output.xml> -t <transcription_folder_path>

Note: The -t flag works with both the iiif and images commands.

Processing a TEI Document to create EditionCrafter artifacts

Once you have a TEI Document in the correct format, the next step is to generate the EditionCrafter artifacts needed to display the document on the web. We do that with this command:

editioncrafter process -i <tei_file> -o <output_path> -u <base_url>

This creates the necessary artifacts at the <output_path>. These artifacts include a new IIIF Manifest that is now annotated with web annotations that link each page of the text with the corresponding HTML and XML renderings of that page. You will want to point to this manifest from the EditionCrafter viewer component. Once you have published these files online at the <base_url>, you are ready for the next step.

Publishing a Document

EditionCrafter can be included in a React app or a HTML website. EditionCrafter should work on any content management system (CMS) where you can edit the HTML of your page. We have tested it on Hugo CMS, Astro Framework, and Scalar CMS. We also have an example Hugo website that you can fork. Please see that website’s README for more information.

EditionCrafter in a React App

If you are including EditionCrafter in a React app, add this module to your project:

npm add @cu-mkp/editioncrafter

The reference section below details all of the props of the EditionCrafter component. Here is an example of use:

import EditionCrafter from '@cu-mkp/editioncrafter'

<EditionCrafter
  documentName='BnF Ms. Fr. 640'
  transcriptionTypes={{
    tc: 'Diplomatic (FR)',
    tcn: 'Normalized (FR)',
    tl: 'Translation (EN)'
  }}
  iiifManifest='https://cu-mkp.github.io/editioncrafter-data/fr640_3r-3v-example/iiif/manifest.json'
/>

EditionCrafter in an HTML Website

To include EditionCrafter in your HTML website, you need to create a div somewhere on your page, assign it an ID and then pass that ID to EditionCrafter. The reference section details the options for EditionCrafter, which are otherwise the same as the React component. Here is an example of use:

 <div id="ec"></div>

 <script type="text/javascript" src="https://www.unpkg.com/@cu-mkp/editioncrafter-umd" ></script>

 <script type="text/javascript">

     EditionCrafter.viewer({
         id: 'ec',
         documentName: 'BnF Ms. Fr. 640',
         iiifManifest='https://cu-mkp.github.io/editioncrafter-data/fr640_3r-3v-example/iiif/manifest.json',
         transcriptionTypes: {
           tc: 'Diplomatic (FR)',
           tcn: 'Normalized (FR)',
           tl: 'Translation (EN)'
         }
     });

 </script>

Editing a Document

Once you have generated a TEI Document with the EditionCrafter CLI, you can start to edit it and add material. Whenever you want to see your changes on your website, simply run the editioncrafter process command again and upload the new artifacts. If you are using a GitHub-based workflow like the one described in the example Hugo site, at this point you would simply commit your changes to GitHub and push them.

While editing a document, there are two things to consider related to display in EditionCrafter. First, the text can be provided in one or more layers. Each layer is found in a top level <text> element. The <text> element must have an xml:id. This xml:id is used to identify this layer. For example, to create two layers, one for the transcription and another for a translation, the code would look like this:

<text xml:id="transcription">

  ... my transcription ...

</text>

<text xml:id="translation">

  ... my translation ...

</text>

The other thing to consider is how the text is paired with the page images. In each layer, add a <pb/> element whenever a new page begins. This element should have a @facs attribute that references the @xml:id of the corresponding <surface> element. The surfaces are found in the <facsimile> element that was automatically generated by the EditionCrafter CLI. So for example, if you have a <facsimile> that looks like this:

<facsimile
  sameAs="https://gallica.bnf.fr/iiif/ark:/12148/btv1b10500001g/manifest.json" 
  xml:id="BnF.DépartementdesManuscrits.Français640" 
>

  <surface
    xml:id="f010" 
    ulx="0" 
    uly="0" 
    lrx="3369" 
    lry="5417" 
    sameAs="https://gallica.bnf.fr/iiif/ark:/12148/btv1b10500001g/canvas/f11"
  >

    <label>
      3r
    </label>

    <graphic 
      mimeType="application/json" 
      url="https:/gallica.bnf.fr/iiif/ark:/12148/btv1b10500001g/f11"
    />

  </surface>

</facsimile>

You could begin page 3r in your text like this:

<pb facs="#f010"/>

Additional functionality can be triggered by specific elements and attributes. See the TEI reference section for more information.

EditionCrafter Viewer Reference

The following props are available to the <EditionCrafter> viewer component:

documentInfo

Optional; used only in the case that you wish to load multiple documents in the same viewer for easy comparison.

An object whose keys are unique document IDs for each document you wish to include, and whose values are objects specifying the documentName, transcriptionTypes, and iiifManifest for each document as described below. For example:

documentInfo={{
    FHL_007548733_TAOS_BAPTISMS_BATCH_2: {
        documentName: 'Taos Baptisms Batch 2',
        transcriptionTypes: {
            translation: 'Translation',
            transcription: 'Transcription',
        },
        iiifManifest: 'https://editioncrafter.org/taos-baptisms-example/iiif/manifest.json',
    },
    eng_415_145a: {
        documentName: 'Eng 415-145a',
        transcriptionTypes: {
            'eng-415-145a': 'Transcription',
        },
        iiifManifest: 'https://cu-mkp.github.io/bic-editioncrafter-data/eng-415-145a/iiif/manifest.json',
    }
}}

documentName

Required. (Note: This is required even in the case that you have also included a documentInfo prop.)

A string giving the name of the document(s).

glossaryURL

Optional. A URL pointing to a JSON file containing glossary information. The glossary should have the following format:

{
  "title": "[a subheader, written in markdown]",
  "citation": "[information on how to cite the glossary, written in markdown]",
  "entries": {
    "[Term]": {
      "headword": "...",
      "alternateSpellings": "...",
      "meanings": [
        {
          "partOfSpeech": "...",
          "meaning": "...",
          "references": "..."
        }
        ...
      ],
      "modernSpelling": "...",
      "antonym": "...",
      "synonym": "...",
      "seeAlso": "..."
    },
    ...
  }
}

iiifManifest

Required if no documentInfo prop specified.

The URL of the IIIF manifest for your document.

threePanel

Optional. (Defaults to false.)

A boolean flag, which when set to true adds a third pane to the viewer. The third pane starts collapsed on the righthand side of the viewer and can be expanded by clicking and dragging the divider. This pane operates independently from the other throw; for example Book Mode is disabled in the third pane.

transcriptionTypes

Required if no documentInfo prop specified.

An object providing a dictionary of the different transciption types provided in your TEI document. The keys of this object should correspond to the xml:id values of the different <text> layers of your document. For example, suppose you have the following text layers in your document:

<text xml:id="transcription">

  ... my transcription ...

</text>

<text xml:id="translation">

  ... my translation ...

</text>

In this case the transcriptionTypes object might have the form:

transcriptionTypes = {
    transcription: 'Transcription',
    translation: 'Translation'
}

The value for each transcription type should be a string that will be displayed in the selection menu within the viewer. These need not correspond precisely to the keys. For instance in the example above, you could add more information to the display strings, e.g. 'Transcription (FR)' and Translation (EN).