Thanks for coming to InDesignSecrets.com, the world's #1 resource for all things InDesign!

Formatting Text With XML in InDesign

by Andrej Balaz

The first time I learned about the XML workflow in InDesign was when I was confronted with the massive task of designing a new edition of the Mobile Developer’s Guide to the Galaxy every few months.

The Mobile Developer’s Guide to the Galaxy is a beautiful community publication project initiated by Enough Software, a German cross-platform mobile development agency. It features the voluntary work of more than dozen experts, who write about topics ranging from general introductions to all mobile platforms to specific technical topics, such as Near-Field-Communication (NFC) or UX design.

The book is in its 14th Edition now with 256 pages full of content. It has spun off two companion publications focusing on mobile design and marketing. It is published in printed editions, as well as web-optimized PDF, EPUB and MOBI formats and features over 500 hyperlinks.

As you can guess, producing each book would consume significant amount of time if parts of the process weren’t automated. Before I describe how to approach the XML-based formatting process, I would like to quickly list the steps that each edition has to go through in order to land in the hands (or on devices) of its readers.

  1. Authors write the content: We use a Wiki to collect the work from every author, make corrections and finalize the editing. Authors are working here.
  2. Transform Wiki to XML: The Wiki content magically transforms into an XML document. I would like to write a future article on how the magic works.
  3. Import XML to InDesign: The content enters InDesign and is correctly formatted. This is what you will find about in a second.
  4. Finalize formatting: Some things cannot be defined via XML in InDesign, such as hyperlinks and footnotes. I wrote a few scripts to circumvent these shortcomings. Illustrations are also added in this step.
  5. Export to all formats: This process is still largely manual as each of the export file formats has its quirks.

Let’s take a look at how to prepare your file for automatic formatting.

How To Create An XML File That InDesign Understands

Even though our XML file for the Guide is generated automatically from Wiki HTML, you can easily write your own tags that InDesign will understand in any text editor of your choice. Let’s say we want to create a headline and a paragraph of body text that is automatically formatted upon import. Something like this:

Do cool stuff headline

This is just a normal paragraph describing how to do cool stuff with XML in InDesign. By reading this you will achieve InDesign mastery and earn your black belt in formatting.

Our XML for this text would look like this:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>

<root>

<Story>

<headlineChapter>Do cool stuff headline</headlineChapter>

<body>This is just a normal paragraph describing how to do cool stuff with XML in InDesign. By reading this you will achieve InDesign mastery and earn your black belt in formatting.</body>

</Story>

</root>

If you are familiar with HTML, this might look familiar to you. So what is happening?

In order to tell InDesign which paragraph, character or any other style is assigned to each piece of content, you need to enclose the content in an XML tag. The tags are defined by <> brackets. Each opening tag has to be closed by a closing tag that is marked by the </ opening bracket. For example: <tag>some content</tag>. To find out more, check out Adobe’s Technical Reference document on InDesign and XML. Later you will tell which tag belongs to which style using the Map Tags to Styles menu that can be found in the flyout menu of the Tags palette in InDesign.

Let’s have a look at our example again. The blue tag <headlineChapter> will assign the Headline Chapter paragraph style to the text enclosed by it. The <body> tag assigns the Body paragraph style. As you have probably guessed, you can name your tags any way you want. I suggest creating easily readable tags that correspond to your style definitions in InDesign.

The green tag <?xmlversion=”1.0″encoding=”UTF-8″standalone=”yes”?> is mandatory and can be copied as is. It simply tells InDesign that it’s reading an XML document.

The <root> tag just defines the scope of your document and could be omitted. The <Story> tag defines an InDesign story. It is helpful when dragging and dropping content from the Story pane into a series of linked text frames in InDesign.

Important note: Unfortunately, InDesign imports line breaks in your code into your imported content. Therefore, make sure to delete all line breaks and returns that you used to format your code before importing into InDesign.

Setting Up Tags in InDesign

Now that we have our XML document, we can use it to import its content into an InDesign document.

  1. Create a new document and place a text frame in it to hold your content.
  2. Set up two Paragraph Styles called Headline Chapter and Body. You can choose any type of styling you want.
  3. To see what happens next, open the Tags panel from Window > Utilities > Tags. Here is where you can define Tags manually. We will let InDesign list them automatically upon import.
  4. Open the Structure pane by going to View > Structure > Show Structure. You might need to drag it out from the left of your document window. The XML structure of your document is shown here. There shouldn’t be anything listed yet.

    Figure 1: This is how your workspace should look

    Figure 1: This is how your workspace should look

  5. Import your XML file into InDesign via File > Import XML… Choose Append Content in the dialog box that pops up2. You should see a root tag pop up in the Structure pane. You can open the tag to see your structure reflecting the syntax of your XML file. The tags should also appear in the Tags panel.
  6. Now go to the flyout menu of the Tags palette and choose Map Tags to Styles. A menu will pop up that allows you to assign each tag a Style. If we had named our styles the same as our tags, we could have chosen the Map by Name button to let InDesign do the mapping work, as well.

    Figure 2: The Map Tags to Styles menu

    Figure 2: The Map Tags to Styles menu

  7. Now that our tags are mapped to styles, drag and drop content from the Structure pane into the text frame you previously created. It should be automatically formatted correctly – magic! You can dynamically change the tag to style assignment any time, even after you placed the content in your document.

To read more about the process described here, read the corresponding page in the InDesign manual.

Tables, Hyperlinks, Footnotes, or the Advanced Stuff

While it is completely possible to format tables with XML in InDesign, automation for hyperlinks and footnotes is not fully implemented. But there are some simple workarounds to circumvent these shortcomings.

Tables

Tables can be described by XML, however the tag <table> has to be outfitted with several properties to ensure a correct layout later on. Basically a table is a stack of <cell> tags that is divided into rows and columns, headers and so forth by applying specific attributes to them, enclosed by the <table> tag. Review the Technical Reference to learn more about the syntax details of tables.

A simple table with a header row and one normal cell might look like this:

<?xml version=“1.0″encoding=“UTF-8″?>

<table xmlns:aid=“http://ns.adobe.com/AdobeInDesign/4.0/” aid:table=“table” aid:trows=“2″ aid:tcols=“1″>

<cell aid:table=“cell”aid:theader=“”aid:crows=“1″aid:ccols=“1″ aid:ccolwidth=“81″>

</cell>

<cell aid:table=“cell” aid:crows=“1″ aid:ccols=“1″ aid:ccolwidth=“81″>

</cell>

</table>

Figure 3: A simple table generated from XML

Figure 3: A simple table generated from XML

Notes:

The number of rows and columns is defined in the <table> tag. InDesign simply places cells from left to right, you define the number or rows and columns by manipulating the aid:trows and aid:tcols attributes.

The header row is defined by the presence of the aid:theader attribute, normal cells do not require it.

You can place content in the cells by placing it between the <cell></cell> tags. Example:

<cell aid:table=“cell” aid:theader=“”aid:crows=“1″ aid:ccols=“1″ aid:ccolwidth=“81″>

<body>

I am inside of a cell

</body>

</cell>

Footnotes

Unfortunately InDesign does not support simple, automatic conversion of XML tags into functional hyperlinks and footnotes. We solved this by using scripts. These scripts recognize custom tags inside of the placed text after it was imported into the document.

For footnotes we modified the amazing Refoot.jsscript from Indiscripts.com and created a script that recognizes this pattern in imported text:

{{footnote}}This is a footnote{{/footnote}}

When run, the script recognizes the tags and creates InDesign footnotes from the content between them.

Hyperlinks

For hyperlinks the approach is similar. This time, the syntax looks like this:

<hyperlink>URL|name</hyperlink>

If you want to generate this syntax in your imported text in InDesign, you need to escape the angled brackets, so that InDesign does not mistake the tags for XML.

In your XML document the hyperlink syntax would look like this:

&lt;hyperlink&gt;URL|name&lt;/hyperlink&gt;

The URL part simply defines the link’s target, whereas the name can be anything which the hyperlink will be connected to.

Example:

<hyperlink>http://www.balaz.de|Check out my work</hyperlink>

will result in

Check out my work.

in InDesign.

Final Thoughts

I hope this article is helpful in introducing you into the specifics of preparing XML files for automated formatting, and showing you how to deal with InDesign’s shortcomings with footnotes and hyperlinks.

I am happy to hear your feedback and encourage you to modify the scripts and correct any mistakes I might have made. I am also happy to clarify any of your questions and await your feedback on Twitter. My handle is @Designamyte.

Andrej is an UI & UX designer currently living in Berlin. He also works as freelance graphic designer and illustrator. Graduated with M.A. in Digital Media design at the University of the Arts Bremen, Andrej loves to experiment with all kinds of interactive media and has a strong interest in digital publishing. You can find out more about his work by visiting his portfolio at www.balaz.de.

Sources

Adobe InDesign and XML Technical Reference

This document shows you how to write XML that InDesign understands.

InDesign help: Importing XML

It’s always good to start with the program’s help, right?

Adobe InDesign Developer Documentation

For those who want to take an in-depth look on how to script for InDesign, this is the page to go.

Adobe InDesign Automation Page

This is where you find all kinds of helpful information about automating publishing in InDesign.

Mobile Developer’s Guide to the Galaxy

Get the Mobile Developer’s Guide to the Galaxy, learn about mobile development and see the book in all editions. See the illustrations here.

Andrej Balaz Portfolio

Find out about my work and connect via Twitter at @Designamyte.

Tags
Related Articles
Comments

12 Comments on “Formatting Text With XML in InDesign

    • Hey, thanks for the helpful script. You’re right about XML being a bit difficult when it comes to whitespacing. As I’ve written above, whitespacing used to format code for better readability needs to be stripped as it is treated as content in InDesign. That’s a big shortcoming from Adobe’s side, unfortunately.

      • Thanks, Andrej.
        As for whitespace handling – it’s possible to use XML processing instruction

        With this instruction InDesign will stripe all line breaks and tabs from imported XML. To get “tabs” and “paragraph breaks” in the content tegs and can be used.
        But this works only in “http://ns.adobe.com/AdobeInDesign/3.0/” namespace.
        This feature isn’t well documented, has some side effects, but can be good work-around in some circumstances.

      • …it deletes xml-code…
        instruction:
        whitespace-handling use-tags
        and tegs:
        aid:tab, aid:br

  1. Great introduction — thanks! I produce a newspaper using XML generated from the MySQL database that drives our website. InDesign’s capabilities offer a powerful way to create a database- and web-based workflow.

  2. I am only just learning InDesign, and have messed with a very small amount of XML while doing form design in LiveCycle, but I got to say this is a very nice article. I had no idea that InDesign could do all this stuff.

  3. As we are talking about XML can anyone suggest a way to export XML from Excel 2011 on a Mac? I think there is a great gap there…
    Oh… I shouldn’t forget to thank the author for this article. Thanks Andrej!

    • Hey Gregor,
      I agree, this is very limited solution. It’s only useful if you don’t need tabs and paragraphs (e.g. XML used to fill placeholders) or with very simple “hand-made” XML.
      Otherwise only scripts or XSLT…

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>