Markdown to InDesign, Simplified

If a Microsoft Word user employs styles reliably and consistently, placing their Word doc into an InDesign publication can go smoothly. We congratulate the several people who enjoy this workflow. The rest of us wrangle unformatted or erratically formatted text.

But then, it’s not fair to ask writers to find formatting tools and apply styling. Their eyes and mnds are on the words, fingers forming les mots justes. Markdown is a way for a writer to easily add a few characters here and there so a designer doing layout with that text can recognize an intended header from a subhead and what should be bold and italic.

The writer should leave it to those of us doing the design to prettify their finely formed words. To understand how Markdown can help in that process, let’s review what markup is.

Markdown is Markup

In the days of “typewriters” (machines you can find in museums and trendy cafés), a writer would create a manuscript that someone later would “mark up,” indicating what a given chunk of text is, whether a header, a regular paragraph, or some phrase that should be emphasized. A typesetter would consult a style guide to know how each marked-up element should be formatted.

In modern times, we have other markup like HTML, a markup “code” that a web browser can interpret and format appropriately. But HTML is a bit hard to type. Consider the title of a manuscript. In HTML, we might write:

<h1>Pride and Prejudice</h1>

Try typing that quickly! Some “tags” on either side of an element can be verbose, like the <strong> tag, which usually yields bold type.

Markdown is Efficient and Succinct Markup

About two decades ago, John Gruber and Aaron Swartz invented Markdown, an easier-to-type markup that could be converted to HTML if desired. Using Markdown, that title becomes:

# Pride and Prejudice

Instead of surrounding a phrase in a <strong> tag, we use two underscores or asterisks (e.g., **this becomes bold later** as does __this phrase__).

This is wrist-saving and easy to learn and so more likely to be used by writers. That’s why it’s so popular. All that’s been missing is an easy way to convert this code to actual formatting in InDesign, the topic of this article.

The basic syntax of Markdown can be found here:https://www.markdownguide.org/basic-syntax/. Much of it assumes conversion to HTML (the original intent of Markdown). Fortunately, those parts may be ignored for use in InDesign.

Since Markdown text isn’t formatted per se, it can be written in any text editor: Notepad, TextEdit, Scrivener, Ulysses, BBEdit, Word, Apple Pages, and many more. Some apps even provide a formatted preview. But the file that’s delivered to an InDesign user can really be just a plain text file (.TXT).

Styling Markdown in InDesign

There are many ways to convert Markdown to HTML. For other formats, we could use a computer’s command line (Terminal in macOS, for example) to use a utility known as PANDOC, which converts a huge number of formats to almost any other, including Word and InCopy documents. But the conversion from Markdown to InCopy sadly misses some common elements and the conversion to Word requires too much prep.

So, we’ll use an InDesign script and support files we made for you!

Get them here: https://luminousworks.com/resources#markdown

The download includes styles that the script applies to Markdown elementsThe download contains:

• A folder called FindChangeSupport containing a text file called FindChangeListMarkdown.txt

• The script (called FindChangeByListMarkdown.jsx) that uses that text file to perform many Find/Change operations

• An InDesign File (called MarkdownStyles.indd) which houses the styles that are applied (provisionally) to Markdown content.

• And, importantly, a PDF with some background on the process that the script uses as well as how to use the script itself.

Add the Script to InDesign

Follow the steps below to add the script to InDesign’s Scripts panel. Put the Snippet (MarkdownStyles.idms) in a handy spot of your choosing.

1. Get InDesign’s Scripts panel (Window > Utilities > Scripts)

2. In that panel, note the User folder. Right-click on it (or Control+click on macOS), and choose Show in Finder (macOS) or Show in Explorer (Windows). Now you’re in the operating system viewing a folder called Scripts Panel (weirdly, not “User”).

3. Copy both the script (FindChangeByListMarkdown.jsx) and the FindChangeSupport folder then paste into that Scripts Panel folder (or drag and drop). Those items show up immediately in the Scripts panel!

Save your InDesign document. If the script goes wrong, it will require a great many undos to remedy it. But if you save before running a script, you can use File > Revert as “undo.”

Run the Script

If there is other content in your document besides the Markdown text, you should insert the text cursor into the Markdown text to control the scope of the script.

Then double-click FindChangeByListMarkdown.jsx in the Scripts panel to run it. Tell it where the styles document is and specify the “Search Range,” and the text is styled.

Map Your Own Styles to Ours

If you’ve already got styles in the InDesign document to format this kind of content, it’s actually easy to replace our styles with yours and eliminate unneeded styles at the same time.

1. Make sure nothing is selected

2. Highlight the folder (Style Group) called “markdown” in the Table Styles panel. Then click the small trashcan at the bottom of that panel.

3. You’ll be asked if you want to delete that Style Group. The answer is Yes.

4. If my style is actually used, you may choose a replacement from your own styles that weren’t in the group being deleted.

5. Highlight the folder (Style Group) called “markdown” in the Cell Styles panel. Then click the small trashcan at the bottom of that panel. If any are used, choose a substitute.

6. Highlight the folder (Style Group) called “markdown” in the Paragraph Styles panel. Then click the small trashcan at the bottom of that panel.

7. You’ll be asked if you want to delete that Style Group. The answer is Yes.

8. For each of the styles that are actually used, such as the one called “Paragraph”, you’ll choose a replacement from styles that weren’t in the group being deleted. In the case of the style “Paragraph,” choose whatever you’re using for body text. Do NOT tick the box to Apply to All!

9. Do the same for the Character Styles “markdown” group, replacing our Bold and Italic with yours, if you wish.

If your Markdown text used only four Paragraph Styles from that group, you need choose only four substitutes. The unused styles will be deleted without comment.

Summary

1. Place Markdown text with no formatting

2. Add (then delete) the Snippet MarkdownStyles.idms

3. If other text is in the doc, select the Markdown text or put the text cursor in its story

4. Double-click the script FindChangeByListMarkdown.jsx

5. Locate and select the Styles InDesign document. To replace our supplied styles with your own, delete each Style Group and choose a substitue style for each being deleted

With all the assets in place, this process really takes about a minute! Enjoy!