To boldly go where no tech writer has gone before (one can dream, right?)

The World’s Smallest DITA Project Part 1: Installing the tools

(This post is part of the Learn DITA on Your Own series.)

Before you can start having fun with DITA, you need to install the following tools:

  • A DITA editor
  • The DITA Open Toolkit

You use a DITA editor to write your topics, create your maps, and add your topics to maps. To generate your DITA content into the output format of your choice (PDF, .chm, HTML, etc.), you use the DITA Open Toolkit publishing engine, as shown in the following diagram:

DITA editor

An ideal DITA editor has the following features:

  • It includes a visual interface that lets you enter content without having to worry about tags. While it’s very useful to understand the DITA tags and be able to work with them, you don’t want to worry about the mechanics when you are writing your content.
  • It also includes a text interface that lets you work in the DITA code. This is very useful when you perform more complex operations such as applying conditions, adding cross-references, setting variables, etc. I work in the visual interface about 80% of the time and in the text interface 20% of the time.
  • It checks the syntax of your DITA code. Even when you’re working in a visual interface that does most of the job for you, you may still make mistakes. A good DITA editor will check your syntax as you type and will let you know when you make mistakes.

I’ve spent a few hours searching for a free XML editor that provides these features, but none seems available (and if I’m wrong, please, please let me know!). Many products provide a 30-day free trial, such as oXygen (which I use and love), and I’ll discuss this option when planning your DITA training.

For the World’s Smallest DITA Project, we will use Notepad++. It’s free, easy to use, and will work fine for what we want to do. Yes, when using Notepad++ you will be working with the tags, but as Sarah O’Keefe from Scriptorium said: “If you don’t understand the underlying DITA structure, you’re just going to continue to create badly structured information that is technically valid.”

Downloading and installing Notepad++

Notepad++ is a very common editor, and you may already have it installed on your computer.

If you don’t, follow these instructions:

  1. Go to the following URL:
  2. Click the DOWNLOAD button.
  3. When the file is downloaded, run the installer.
  4. Follow the instructions, using the default selections.
    Note: If you get errors indicating that a file is moved to the “disable” directory, simply ignore them and click OK.
  5. When the installation is completed, click Finish.

DITA Open Toolkit

The DITA Open Toolkit (also called the DITA-OT) is an open source publishing tool that converts DITA content into various output formats such as PDF, XHTML, Eclipse Help, HTML Help, etc. To generate the output of a DITA map or topic, you run a command-line DITA-OT script that takes the map or topic as input and generates the content.

To download and install the DITA Open Toolkit:

  1. Go to the DITA Open Toolkit download website:
  2. Click the button for your operating system.
    The file is downloaded to your system. The Open Toolkit is packaged as a .zip (Windows) or .tar.gz (Unix, Mac) file.
  3. Extract the file to the C:\ directory (Windows).
    The DITA OT is now installed in the C:\DITA-OT1.8.M2 directory.

The next step is to run the demo project provided with the DITA-OT to test your installation. To build the demo project, you run a script that asks for the DITA map that you want to build, the directory where you will store the output, and the type of output you want to create. For this test, we’ll accept the default answers to all questions.

  1. In the  C:\DITA-OT1.8.M2 directory, double-click startcmd.bat (Windows) or run (Linux, Mac).
  2. At the prompt, enter the following command to build the demo project:
    ant -f build_demo.xml

    The following message is displayed:

    [echo] Please enter the filename for the DITA map that you
    [echo] want to build including the directory path (if any).
    [echo] The filename must have the .ditamap extension.
    [echo] Note that relative paths that climb (..) are not supported yet.
    [echo] To build the sample, press return without entering anything.
    [input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]

    Note: If you get the following error message instead:

    "java.exe"' is not recognized as an internal or external command...

    You need to update your system PATH variable with the location of your Java bin directory (for example, C:\Program Files\Java\jre7\) before you can try again. See these Java instructions for more information.

  3. Press Enter to use the default DITA map filename.
    The following message is displayed:

     [echo] Please enter the name of the output directory or press return
     [echo] to accept the default.
     [input] The output directory (out): [out]
  4. Press Enter to use the default output directory.
    The following message is displayed:

     [echo] Please enter the type of output to generate.
     [echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web
     [echo] Use lowercase letters.
     [input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)
  5. Press Enter to generate the map to XHTML.
    The following message is displayed:

     [echo] Ready to build C:\DITA-OT1.6.M5\samples\hierarchy.ditamap
     [echo] for web in out
     [input] Continue? (Y, [y], N, n)
  6. Press Enter.
    The DITA OT converts the DITA map to XHTML. After a few minutes, the following message is displayed:

    Total time: 2 minutes 54 seconds

    Note: If you do not get this message, see the DITA OT user documentation at the following location:

    If you can’t make this work by following the documentation, please post your error in the comments section below and I’ll try to help you fix the issue.

  7. To look at your newly generated output, double-click the index.html file in the following directory:

If you want, you can run this procedure again, this time choosing a different output type.

What’s Next?

You are now ready to write your first DITA document! This will be the subject of the next post.  I will be off snowshoeing during the holidays and will come back with part 2 of the World’s Smallest DITA Project in 2014.

Until then…Happy Holidays, be safe, and be happy. :)

For the curious:

  • To lean more about the features that you need in a DITA editor, read this article from the April 2008 STC intercom issue. It’s five years old, so the list of tools is out of date, but the article still provides very useful information.
  • The DITA Writer has compiled a list of DITA optimized editors, which are XML editors best suited for producing DITA content.

Share this article:
Facebook Twitter Email Linkedin

23 Responses to “The World’s Smallest DITA Project Part 1: Installing the tools”

  1. Jeanne says:

    Happy new year, Nathalie! Thanks for this. I am all set. The instructions worked great – I just needed to update my system PATH variable with the location of my Java bin directory.

  2. Nathalie says:

    Thanks Jeanne! I updated the procedure to add these instructions.

    Happy new year to you too, and thanks for your feedback!

    The next blog post will be available this Friday :)

  3. Excellent start-up instructions. Would be better with the Java path example you sent me via email, though. I had to press Enter a few more times in the cmd prompt, but that might be a peculiarity of my machine.

    How about a link to the next part in the series at the end of the page? I am a very lazy man!

  4. Frank Ralf says:

    Hi Nathalie,

    Thanks for this instructive blog post. I agree that using a simple text editor while learning is a good thing and Notepad++ is also my favorite editor. However, you can make editing DITA files a bit more comfortable by using some of the many plugins available for Notepad++. Especially I’d recommend the “XML Tools”, available from


  5. Salala says:

    Thanks Nathalie! The demo project runs successfully in my computer.

    An unknown reason occured at the first time, but I found out how to solve it. There is a suggestion for Windows 7 or later users:
    If you do not have the Administrator right of your PC, but your DITA_OT was installed in a directory that you do not have the right to edit, to run the demo project successfully, you must modify [input] line in Step 3:
    [input] The output directory (out): [out](you must type the target directory you have the right to edit, for example, D:\DITA-OT\Output\)

    I hope this can help those who may have this “right” problem.

  6. Jeana says:

    Looks like a lot of this is out of date. Running into all sorts of problems in the current version of dita-ot (2.1.1). I think the package has changed too drastically for this to work anymore :(

    I’m guessing you probably don’t have a lot of free time to update this document (it seems like it would be a lot of work!), but does anyone here know a more recent getting started guide?

    • Nathalie says:

      Hi Jea
      na! You are right, now that DITA-OT 2.x is out, I need to update my posts… I get enough feedback and email on them that I think it’s worth taking the time to update this series. I’ll do this within the next few weeks. Thanks for your feedback!

  7. Jeanine says:

    Hi Nathalie, I also tried (and failed) with DITA-OT-2.1.1. An update will be great!

  8. Jamie Eby says:

    Thanks so much for this helpful tutorial. I couldn’t get it working with the latest version of DITA-OT, but after I downloaded DITA-OT1.8.M2, it worked fine.

  9. Gabriel says:

    Thanks Nathalie for this post.
    I also have to thank you guys for comments that helped me to almost achieve.

    Now, here is where I’m stuck :
    – I upgraded my Java configuration to solve the “can’t find Tools.jar” problem. It seemed that I needed the JDK (Java Development Kit) instead of the JRE.
    – I updated variable locations PATH, CLASS_PATH & JAVA_HOME
    – I used version 1.8.M2 version of DITA OT
    – I tried to write the file into a file with full acces

    And here is my final error message :
    C:\Program Files (x86)\DITA-OT1.8.M2\build_demo.xml:311: The following error occured while executing this line:
    C:\Program Files (x86)\DITA-OT1.8.M2\build_demo.xml:78 Directory C:\Program Files (x86)\DITA-OT1.8.M2\temp\temp20160115102416010 creation was not successful for unknown reason

    Anyone would have an idea to solve this?

    • Nathalie says:

      Hi Gabriel,

      Thanks for your message! I just spent some time researching this issue. It seems to be related to a command-line interface issue, and I think that it’s probably solved with the new DITA-OT. I’m now updating my posts to the new DITA-OT version and will have an updated post by early next week. If you want, email me at nathlaroche at gmail dot com and I’ll let you know when I’m done. :) Thanks!

      • Gabriel says:

        Hi Nathalie and all DITA writers/publishers wannabes,

        I finaly found what made DitaOT not working on my computer : DitaOT was installed in a folder with a name containg blank space (spacebar) : “C:\Program Files (x86)\…”
        I re-instalred DitaOT in a folder without blank space in its name (as indicated in this tutorial actualy), and voilà!

        So happy that my new toy finaly works!

        Thanks for assistance.

  10. Alex says:

    Hi, Nathalie, thanks for this tutorial. I have not figured out how to get it to work on a Mac unfortunately. When I try to run, I get this error: “The has been deprecated, use the ‘dita’ command instead.” Any idea what this might be?

  11. Erin Grace says:

    Thanks for this great post! However, I’m very stuck and can’t build the demo (probably because of the new version).

    When I follow the instructions here and type
    ant -f build_demo.xml
    it says that the file doesn’t exist. I looked into the folder itself, and found that the file is indeed missing. However, there is one called build_template.xml. I tried the same command but with the different filename, but get the error “BUILD FAILED, C:\dita-ot-2.3.1/build_template.xml:23: path doesn’t support the nested ‘extension’ element.”

    Any suggestions? I’ve tried researching the error elsewhere but can’t find anything of use. Thank you!

  12. Elane.bian says:

    Hello Gabriel:
    Thank you for your message, but I cannot load the The DITA Open Toolkit. Would you please send this back to my email?
    Best regards

  13. Tomas says:


    Thanks for awesome howto!
    Very small and easy to get started and to put more thing there.

    I was able to create this template document with latest dita-ot.

    I used: dita-ot-2.3.3

    All you need to do is create the two files in guide in your separate direcotory.

    Open windows shell in your directory where you created the two files from guide.
    and then use command:
    DITA_EXTRACT_DIR\bin\dita -input worlds_smallest_dita_project.ditamap -format pdf

    • Tomas says:

      oh and one more thing :)
      dtd files I used:



  14. Maria says:

    Hi I downloaded the latest DITA OT version and it kept saying the build failed. Should I download an older version?I have Windows 10.

Leave a Reply

Your email address will not be published. Required fields are marked *