How to Prepare OBS Projects for Publishing
Posted by: Mark


This article is one in a series of articles describing how to get a GL project ready to publish so that others can benefit from it. This article deals with Open Bible Stories (OBS) projects created in translationStudio. A complete OBS project uploaded from tS consists of 700+ text files. These files must be compiled together into 53 Markdown files, one for each story, plus these three:

  • front/
  • front/
  • back/


  • The stories have been translated in tS and checked to level 3.
  • The reader knows how to copy files between Door43 and a file system on a computer.

Upload to Door43

If you haven’t already, upload your project from tS to Door43.
The uploaded data will be plain text files with UTF-8 character encoding.
The .txt files reside in 50 numbered story folders plus a single front folder.

  • One .txt file per OBS chunk, multiple chunks per story, 50 stories
  • One reference.txt file per story
  • One title.txt file per story and one in the front folder.
  • Normally each text file contains one paragraph.

Compile to story files

Copy the entire collection of OBS files to a computer for processing.
I do this by using git clone* commands. For example,

git clone

The conversion process will convert and combine the text files for each numbered story to a corresponding, numbered .md file in a content folder under the target directory. The resulting folder structure and format must look like that found in

The contents of title.txt becomes a level 1 heading in the output Markdown file. The contents of references.txt becomes a footnote at the bottom of the output file. The contents of the numbered .txt files become paragraphs in the output file. References to OBS images are added before each paragraph in the output file.

The script can do this conversion. If you use this script, or any other script found in 1, you will first have to adapt it to your computing environment.

Copy or generate files in front and back folders

You may have to ask for translations of these files if they were not generated/uploaded by tS.

  • front/
  • front/
  • back/

Verify the .md files, and make corrections

You should perform as many of these steps as you reasonably can, before requesting publication of the OBS project.

  • Delete empty .md files.
  • The .md file must use UTF-8 character encoding, with no Byte Order Mark (BOM).
  • Each numbered .md file must:
    • begin with a valid level 1 <h1> heading, which means a single hash symbol at the beginning of the first line, followed by a space, followed by the story number and title.
    • Blank line after the first heading.
    • Third line is an OBS image link in this form ![OBS Image]( The example is for story 1, image 1.
    • A plain text paragraph follows each image link. No lists, headings, nor special formats are wanted.
    • Blank lines separating heading, image links and paragraphs from each other.
  • No HTML code, such as comments <!-- -->, <b>, <br>, and &nbsp;

Create a manifest.yaml file for the OBS project

  • Borrow a known good manifest.yaml file from another project as a template, but review every line in it.
  • Follow the specifications in .
  • Must use UTF-8 character encoding, with no BOM.
  • Copy contributor names from the manifest.json file and any other source of names that you have.
  • Ensure quotes around version number strings.
  • Update the issued and modified dates when any content changes.
  • Modify only the modified date if just metadata (manifest) changes. If it is just a cosmetic change of no value to end users, do not even modify the modified date.
  • Increment the version string whenever the issued date changes.
  • The language|title should be localized if possible.
  • The subject field must say “Open Bible Stories”.
  • With the exception of the English resources, the publisher field should not say “unfoldingWord”.
  • The projects section should look like this, with the title translated into the target language:
  • categories:
    identifier: obs
    path: ‘./content’
    sort: 0
    title: ‘Open Bible Stories’
  • Validate yaml syntax with an online checker, like

Upload to Door43

Create a repository in Door43. The repository name should include the language code, an underscore, and “obs”. The name may also include other identifying information, such as the checking level. Upload your OBS directory structure and files to this repository.

As a final verification step, check the rendering on Door43 by using the Preview button on the repository where you stored the OBS project. Look for presence of images between paragraphs, check the index, and read the warnings that were generated. Address whatever doesn’t look right.

Submit a Source Text Request (STR)

Notify the UnfoldingWord team to publish the material by creating a Source Text Request (STR) form: Once your form is submitted, the unfoldingWord team will verify the license release forms, and will perform all the checks and corrections described above. Any issues requiring translator intervention will be noted in the STR, and will block publication until resolved. Check back often on your STRs to monitor their progress.

Update Options

There are four options to choose from when updating. NOTE: Updating requires an Internet connection. Update List of Available Source Texts Click on this option to upload a list of the available source texts. NOTE: this update will only update the list of available...

Where Can I Find the PDF Version of the ULB for this Language?

ULB (Unlocked Literal Bible) resources are available at

How to Build and Run a V-MAST Server (V-MAST Series 3)

Helpful Links: 7zip Balena Etcher  

How to Prepare tS Translation Notes Projects for Publishing

Note: This article is one in a series of articles describing how to get a GL project ready to publish so that others can benefit from it. This article deals with Translation Notes (tN) projects created in translationStudio. A complete Bible tN project consists of...


e-Visa was not fast. provided no support, and we got our visas through the intervention of our local contact. Visa payment is made in cash at entry to the country. Officially, the visa is paid in Euros or FCFA — I was quoted $110 to pay in US currency. Two...

How to Create a New Release

This document is intended to provide a Content Release Structure checklist.  The goal is that each release is clearly identified in a consistent manner.  The versioning scheme used across the Door43 ecosystem is defined at

Electrical Plugs

Indonesian Adapter


In an earlier workflow we used USB thumb/pen drives to collect the translated output from translators. This was collected on one computer, where it was put together, missing pieces were discovered, and the whole project was eventually uploaded to Door43. One of the...

Booklet example from Pacific

The pacific team put together this booklet to help with one of their training events.    I post it here for safekeeping and for others to view.     The pluses of having training material printed and bound are numerous from what I observed: 1.) participants just like...

MAST Tech Workflow

  MAST Tech Workflow Export or Back Up the Project (Step 1) When you are called to collect or "harvest" a chapter from a translator, you can do it from within the translationStudio program. Without stopping them or quitting the program or closing the project,...