Welcome to the User’s Guide for EditionCrafter! This page describes how to use the EditionCrafter Command Line Interface (EditionCrafter CLI) to prepare your documents for publication. In order to use EditionCrafter, you need to include it in an existing website or create a new one. We provide two website templates to help you get started:
The video tutorials provided below will guide you through the process of creating your first edition with EditonCrafter. The first video makes use of FairCopy for creating your TEI/XML file. FairCopy is a free TEI editor that has EditionCrafter built in. The second video provides instructions on using the EditionCrafter CLI. Both of these tutorials produce the same example website.
The EditionCrafter CLI takes as input a TEI Document and produces the artifacts the EditionCrafter viewer requires to display your edition. These artifacts are a set of JSON, HTML, and XML files. 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 image URLs or from a IIIF Manifest. The EditionCrafter CLI will generate a TEI/XML file 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.
If you already have material in TEI/XML format, you may need to transform it to meet EditionCrafter’s requirements.
The EditionCrafter Viewer 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-cliTo 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 helpIf 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>Please note that using high resolution images will result in a page that loads slowly. To get around this problem, we recommend using IIIF format for high resolution images.
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.
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.
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.
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.
If you are including EditionCrafter in a React app, add this module to your project:
npm add @cu-mkp/editioncrafterThe 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'
/>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>The following props are available to the <EditionCrafter> viewer component:
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',
}
}}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).
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": "..."
},
...
}
}Required if no documentInfo prop specified.
The URL of the IIIF manifest for your document.
Optional. Provide a URL to a Markdown file (GitHub Flavored Markdown supported). This will add a “Notes” item to the layers dropdown in which the contents of the Markdown will be displayed.
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.
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).
EditionCrafter will work on a wide variety of document schemas, but requires certain elements to be in place to function. These mostly have to do with describing the images and relating them to the text(s). To see an example of the correct format, use the EditionCrafter CLI commands described above to create a TEI Document and then examine its structure.
EditionCrafter expects images to be encoded in a sequence using a top level <facsimile> element. The first such element encountered in the file is used. This element can contain one or more <surface> elements. Each of these should have a unique xml:id attribute. These are used to reference the images from the text.
The surface also contains a <graphic> element. The mimeType attribute of this element tells EditionCrafter whether to expect an IIIF Image API Image Information Request (when mimeType="application/json") or a web compatible image format. (all other types). EditionCrafter can also display <zone> elements defined here.
For a given <surface>, text can be provided in zero or more layers. Each layer is found in a top level <text> or <sourceDoc> element. These elements must have an xml:id. The xml:id is used by the transcriptionTypes prop of the EditionCrafter viewer to identify the 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>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"/>
EditionCrafter
Developed by the Making and Knowing Project at the Center for Science and Society at Columbia University and Performant Software Solutions LLC. Funded by Grant SES-2218218 from the National Science Foundation.
© 2025 The Making and Knowing Project. This is an open source project licensed under the MIT License.