Using Drupal and DITA OT to Create a PDF File

This post shows you how to use Drupal and DITA OpenToolkit to create a PDF file. It uses Views in Drupal and the REST UI to create a json file that will be used to create a bookmap and markdown files. These files will be used by Open Toolkit to create a PDF file.

Prerequisites: Drupal, DITA OT, Python

Make sure that the following modules are installed in Drupal:

For DITA Open Toolkit, you can use markdown files instead of DITA files. For this post we will use markdown files, which are much easier to work with. DITA files require that you are familiar with fairly complex tagging. Markdown is much easier to use. See the following website for a markdown cheatsheet:

https://www.markdownguide.org/cheat-sheet/

Creating  Dita Bookmap and Markdown Content Types

We will create a Dita bookmap and two markdown files. First, let's make two new Content Types in Drupal.

For the first content type, perform the following steps:

1. Select Structure > Content Types > Add Content Type from the Administrator menu.
2. For the Name, enter: markdown.
3. For Description, enter: "Use markdown for creating markdown file."
4. Add the fields as shown below. You can Re-use an existing field for Tags.
   
   
   
5. Edit the Body field and make sure Body is set to allow Plain text.
   
   
   

For the second content type, perform the following steps:

1. Select Structure > Content Types > Add Content Type from the Administrator menu.
2. For the Name enter Dita Bookmap.
3. For Description enter: "Use Dita Bookmap for creating a Dita bookmap."
4. Add the fields as shown below. You can Re-use an existing field for Tags.
   
   
   
   
   
   
   
5. Edit the Body field and make sure Body is set to allow Plain text.

Creating  Markdown Files in Drupal

Next, we will create the two markdown files. For the first file, perform the following steps:

1. Select Content > Add Content > markdown.
2. For the Name, enter: Test markdown page 1
3. Enter the following information:

For the second file, perform the following steps:

1. Select Content > Add Content > markdown.
2. For the Name, enter: Test markdown page 2
3. Enter the following information:

Creating Bookmap File in Drupal

Let's create the bookmap file next.

1. Select Content > Add Content > Dita Bookmap..
2. For the Name, enter: Test Bookmap
3. Enter the following information:

For Body field, enter the following information:

<?xml version='1.0' encoding='utf-8'?><!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "../dtd/bookmap/dtd/bookmap.dtd">
<bookmap id="test1">
<booktitle>
<booklibrary>Test Document</booklibrary>
<mainbooktitle>Test Document</mainbooktitle>
<booktitlealt>By: Eric Strausbaugh</booktitlealt></booktitle>
<frontmatter>
<booklists><toc/></booklists>
</frontmatter>
<chapter href="test1.md" format="markdown">
 <topicref href="test_page2.md" format="markdown"></topicref>
</chapter>
</bookmap>

Creating a  Drupal View and Saving View as a JSON File
The following step shows how to make a view using the dita_test tags that we applied above.

Select Structure > Views > Add View.
Enter dita_test for the View Name.
Select Create Page and use the default settings.
Click on Provide a Rest Export and chose api/dita_test as the Rest Export Path.
Click Save and Edit.
Click on the Edit button for the dita_test view.
Click on Add under Filter Criteria.
Click on Tags (field_tags).
Click Apply.
Click Apply and Continue.
For Operator, select Is one of and enter dita_test.
For Access > Access restrictions: select Role
For Access > Access options: select Authenticated User
Click Apply.
Click on the Rest export display.
Under Formats, click on Settings.
Select json as the Accepted request formats and click Apply.
Under Authentication, choose Basic_Auth
Click Save.
The Preview should look similar to the following:

To save the view as a JSON file: 
Navigate to the view that you created (e.g., http://localhost/api/dita_test). NOTE: You may need to open the view as New Incognito Window. 
Login with your admin login and password. 
In the view, right click and select Save As… (choosing dita_test.json as filename).
Creating Bookmap File and Markdown Files 
The following steps will create the bookmap file and markdown files from the dita_test.json file by using a Python script:
Create a directory (e.g., python_drupal).
Change directory to the directory that you created.
Copy the dita_test.json file to this directory.
Create a file named json_to_dita.py.
Paste the following contents into the file.
import json
import requests
import os
 
with open('dita_test.json', 'r') as file:
    data = json.load(file)
 
length= len(data)
print(length)
 
directory_name = "out"
# Create the directory
try:
    os.mkdir(directory_name)
    print(f"Directory '{directory_name}' created successfully.")
except FileExistsError:
    print(f"Directory '{directory_name}' already exists.")
except PermissionError:
    print(f"Permission denied: Unable to create '{directory_name}'.")
except Exception as e:
    print(f"An error occurred: {e}")
 
for x in range(length):
    if data[x]['field_tags'][0]['target_id'] is not None:
        file1 = open(directory_name + "/" + data[x]['field_name'][0]['value'], "w")
        file1.write(data[x]['body'][0]['value'])
        print(data[x]['vid'][0]['value'])
        print(data[x]['body'][0]['value'])
        print(data[x]['field_name'][0]['value'])
        file1.close()  
Run python3 json_to_dita.py
This creates the bookmap and markdown files that you created in previous steps in the out directory.
Creating PDF File or HTML5 Files 
Within the directory with the bookmap and markdown files, run:
~/dita-ot-x.x/bin/dita --input=test_bookmap.ditamap --format=pdf --output=out
        or

      ~/dita-ot-x.x/bin/dita --input=test_bookmap.ditamap --format=html5 --output=out 
  
           NOTE: DITA-OT must be installed to run the commands above. See https://www.dita-ot.org/dev/topics/installing for installation insuctions.