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.

Workflow Using SmartGit

Forking/Branching Workflow Before beginning this procedure, it is a good idea to remove all copies of the repository from your computer. If you are concerned you might lose something, you can alternately move all copies of the repository to a backup location where...

Manual Solving Pull-Request Conflicts

There are instances where a DCS github user submits a Pull-Request from their Fork of the repository which cannot be Merged automatically. The steps below will identify one approach for a repository administrator to solve this problem. This approach requires that that...

Installing translationStudio on Windows

Windows Installation: Please note that Wycliffe Associates does not currently endorse any version of translationStudio greater than 11.1. Go to: Latest Releases of translationDesktop Installation Files  Click on the appropriate file for your computer.  Allow the file...

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...

VMAST Keywords Fix

What to do when you can't move beyond reconciling keywords.  How to delete hidden keywords in a v-mast server

WACS – the Wycliffe Associates Content Service

You may have already heard about WACS, and that we want all of our translated texts to be uploaded to WACS. This article is intended to tell you how to access WACS, and what you can do there. WACS, the Wycliffe Associates Content Service, is a storehouse for written...

Upload or Export

There are four options to choose from when exporting from translationStudio. Upload to Door43 This requires an Internet connection. PLEASE NOTE that by uploading the project to your Door43 account, the content is available to be downloaded by other translators, merged...

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...

Tanzania Travel

Check with the CDC (link) for immunizations, etc. They are very serious about Yellow Fever, so if you think they might worry about you, get your shot at home. I don't recommend getting the inoculation at the airport in Dar. Visa is easy to get at the airport in Dar es...

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...