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.

Autographa Lite

Autographa Lite is a translation assistance tool with an emphasis on simplicity and usability. It is still in an early state of development, which means that it has some rough edges, but also that we can be involved in making it better. One of the areas that is...

Installing SyncThing on a Windows 10 computer

Follow these simple instructions on installing SyncThing on a Windows 10 machine for MAST data collection. Notes: Install SyncTrazor

Installing MAST Apps on a tablet Part Deux

  I didn't know that we had separate apps for ULB and UDB, as well as Autographa Go and unfoldingWord. I suspect only one of these four is necessary, since both Autographa Go and unfoldingWord can load the ULB and UDB. Although I really like the interface on...

VMAST Hardware Recommendations (V-MAST Series 2)

How to create a standalone V-MAST server Links

Why Does translationStudio stop me at Story 17?

In this situation, the translator was unable to load any Story beyond Story 17 in Open Bible Stories. The Solution was to update the source text for Open Bible Stories in translationStudio.


Here is an example of a normal DOT Kit

Ocen Audio Computer Specs

Ocen Audio : which is used to edit audio files for tR projects does not have any official computer specifications for hardware at this time.  I did find this from .  This is what I received for Ocenaudio's support: Hello Mark,...

What To Pack?

Tools to bring - A multi-purpose tool such as a Leatherman Skeletool or the REV Multi-Tool. Chris Jarka ~$60US. It has a bit driver, but you'll probably need your own selection of bits. John Wood   A personal water...

translationWords – How to Translate into a Gateway Language

It is important that translators understand all of the words that they are translating. But some of the words in the Bible are not used in everyday life in our time or in our cultures, and so the translator may not be familiar with them. Other words are used in...

Images for Open Bible Stories

The link in translationStudio to download images for Open Bible Stories is broken. As a result, you will not be able to print OBS from translationStudio until you manually update the pictures. The pictures can be downloaded...