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.
- 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.
- 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.
- Import XML to InDesign: The content enters InDesign and is correctly formatted. This is what you will find about in a second.
- 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.
- 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.
- Create a new document and place a text frame in it to hold your content.
- Set up two Paragraph Styles called Headline Chapter and Body. You can choose any type of styling you want.
- 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.
- 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
- 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.
- 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
- 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=“https://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
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:
<hyperlink>URL|name</hyperlink>
The URL part simply defines the link’s target, whereas the name can be anything which the hyperlink will be connected to.
Example:
<hyperlink>https://www.balaz.de|Check out my work</hyperlink>
will result in
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.
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.
Find out about my work and connect via Twitter at @Designamyte.
 |
If you want to understand XML in InDesign, this is a great way to start! Thanks, Andrej!
Thanks David. Nice to see it published. Let me know if I can write about other details of the process or something else. :)
In my opinion the XML Feature in InDesign is broken due to the unfeasible Whitespace Handling. Long time ago I wrote a Script to optimize this.
https://www.indesignblog.com/2009/11/xml-und-indesign-%E2%80%93-es-konnte-so-einfach-sein/
Sorry it’s german and the Script isn’t up to date, but should work.
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 “https://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
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.
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.
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 Alexeys,
I just wrote a little Example on the Whitespace Management via Processing Instruction
https://gist.github.com/grefel/26fef91ce1f00318693c
Nice, but still no solution without XSLT or programming Knowledge.
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…
Great article! I just got finished creating two product catalogues where I was able to make great use of indesigns XML capabilities.
It can be daunting and often frustrating, but you can do some really cool things that would otherwise be too time consuming to do otherwise. I’d advise anyone working in indesign to take a good look at what you can achieve.
This book is also excellent https://www.amazon.co.uk/Designers-Guide-Adobe-InDesign-XML/dp/0321503554
What a fantastic writing! Opened a door to a entire new world of layouting to me ;)
I’m glad it could help you. There are some pitfalls but it certainly is a feature that is not known to many, yet still comprehensible and powerful.
We started of using XML pulls with CS2 and for the life of me I haven’t been able to convert it to any of the new CC. Do you know what the problem could be. I actually have CS2 still on an old machine and have import into it and then reopen in CC2015 inorder for it to work. Any help would be great… thanks.
Unfortunately, I haven’t really used CS2 for any of the described work. I think this is something to ask in the InDesign development forum on Adobe’s site.
Hi Andrej,
Great article, thank you! I was just wondering if you had any tips for importing multiple records? I’m trying to create a catalogue in InDesign, with about 7 tags in XML to be assigned to their own text box (title, publication date, etc). There are multiple records and I’d like one title to show per page. I can only seem to import the XML and view the first record though, and I’m struggling to get InDesign to automatically drop in the remaining records on subsequent pages.
Thanks in advance!
Helen.
HI ,
I want to import a paragraph <p style=”color:red;”>hello world</p>
I code a XML file that have all the element are tagged as and differentiate with attribute example check and check ,without XSLT just import XML option in indesign we can able to map the style tag
Hi Andrej,
I’ve found this article by chance. It cleared the basics for me.
I would really like to see your grep pattern for footnotes as I appear to have come to a dead-end in my experimenting with the ReFoot script.
Thank in advance,
Miha.
Hi,
Can you post a link to the script you used for the hyperlinks?
Thanks,
Craig
Hi @Andrej @David
It seems that Adobe is no longer maintaining the XML namespace at https://ns.adobe.com/AdobeInDesign/5.0
Is that correct? Do you know any way around this? I am trying to bring in to InDesign pre-formatted tables using the aid5 spec which is still clearly shown on the Adobe site: https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/products/indesign/pdfs/indesign_and_xml_technical_reference.pdf
Am I missing something? Or has the world moved on but Adobe not clarified how we should now do this?
Thanks!
Dean