Markdown in Tabularia

1. Markdown is a way in and out

Tabularia does not keep your manuscript in Markdown. The page you write on holds real formatting — a heading is a heading, a quotation is a quotation — and the markers never stay in the text. Markdown is how that formatting gets typed quickly, brought in from other writing apps, and handed on to tools that read plain text.

It meets Markdown in four places, and each understands a slightly different amount:

• Typing shortcuts turn markers into formatting as you write.
• Importing a file reads a whole .md file into a manuscript, chapters and all.
• Pasting reads Markdown someone copied out of another app.
• Exporting and copying writes your manuscript back out as Markdown.

2. What each syntax does

In the first three columns, a dash means the characters stay on the page as ordinary text. The sections after the table explain the rows that need more than a word.

Code, tables, task lists, footnotes, and ==highlight== have no row because no place turns them into formatting. An import keeps their words as plain text.

3. Scene breaks and dividers are different things

Most Markdown apps treat every horizontal rule alike. Tabularia does not, because a book has two kinds of gap. A scene break is structure: it ends one Scene and opens the next in the Outline, and your book decoration draws it. A divider is an ornament that sits on the page and starts nothing.

Asterisks mean a scene break — *** or * * *, which is also what Tabularia writes when it exports one. Dashes, underscores, and four or more asterisks mean a divider. Typing, importing, and pasting all read rules this way, and either kind you paste wears the same design as one you type, even a rule pasted on its own. Importing a file follows one more convention some writers use: a line holding nothing but # is a scene break too.

4. Typing shortcuts

Shortcuts are off until you switch on Markdown shortcuts in Writing Tools. The switch belongs to the browser rather than the manuscript, so turning it on at your desk leaves your laptop as it was, and a collaborator sees the formatting you made whether their own switch is on or not. The list of triggers is in Writing and formatting; what follows is how they behave.

• Block markers — headings, >, and numbered lists — only count at the very start of a paragraph, and convert on the space.
• A bullet waits one character longer. - and a space stay as typed until you type the first word, so that * * * can still become a scene break.
• Bold, italic, and strikethrough apply the moment you type the closing marker.
• Scene breaks and dividers convert when you press Return on a line holding only the rule.
• A numbered list starts at one whatever number you typed. Task boxes like - [ ] are left alone.

One Undo puts the markers back exactly as you typed them. To keep a marker without converting it, type a backslash first: \# and a space leaves # on the page, and the backslash disappears. In a paragraph under review, a shortcut becomes a pending Review Change like any other edit. Shortcuts do nothing while text is selected, in a scene break or divider, or while you are previewing a Snapshot.

5. Importing a Markdown file

A .md or .markdown file becomes a manuscript. Chapters come from headings: Tabularia finds the shallowest heading level the file uses more than once and starts a chapter at each of those. A single title above them opens the first chapter rather than taking one of its own. A file that begins without a heading gets a chapter title made from its file name. Insert a file as a scene or as prose and every heading stays a heading, with no chapters started. Acts and books are never inferred from Markdown; add them in the Outline afterwards.

Front matter at the top of the file can name the manuscript: title becomes its title and author its author. Other keys are set aside with a note in the import review. Consecutive > lines become one quotation, and a blank > line between paragraphs keeps them in the same one.

Anything Tabularia has no shape for keeps its words and loses its structure, and the import review lists it:

• A quotation inside a quotation becomes a separate quotation.
• A list inside a list is flattened to one level.
• A line break inside a paragraph splits it into two paragraphs.
• A table arrives as its pipe-separated text in one paragraph.
• An image reference becomes the placeholder text [Image: …] where it stood.

Code blocks come in line by line as plain paragraphs, and a link keeps its words without its address. Neither shows up in the review, so check for them if your file has any.

Two kinds of comment come across as Tabularia comments: an HTML comment <!-- like this -->, and CriticMarkup's comment forms, {>>a note<<} at a point or {==a phrase==}{>>a note<<} across a phrase. CriticMarkup's insertions, deletions, and substitutions are not read and stay as typed. Files from Obsidian, Joplin, iA Writer, and Bear get extra handling of their own, described in Importing an existing manuscript.

6. Pasting Markdown

Paste text that looks like Markdown and Tabularia formats it. Pasting reads more loosely than importing a file: every line becomes its own paragraph, and there are no chapters, front matter, or comments. It does understand underline, written ++like this++ or with <u>, which neither typing nor import does.

A single Markdown line is enough for Tabularia to read the whole paste that way, and a rule on a line of its own counts. So if you paste plain prose that has a --- between sections, words wrapped in underscores or asterisks elsewhere in it turn italic or bold. To keep the text exactly as it was, choose Paste without formatting from the right-click menu instead.

Copying from one Tabularia manuscript into another never goes through Markdown at all. The copy carries Tabularia's own format alongside it, so alignment, quotation details, footnotes, and formatting Markdown cannot express survive the trip; the rest is in Copying and pasting.

7. Exporting and copying to Markdown

Export to Markdown writes a file that opens with the manuscript's title in front matter. If the manuscript has pictures, the download is a zip holding manuscript.md and an images folder, with each picture linked just after the paragraph it sits beside. Copying text from the canvas also puts a Markdown version on the clipboard, for any app that asks for one.

Paragraphs that happen to begin with a character Markdown treats as structure, like # or -, are escaped with a backslash so they stay paragraphs when the file is read again. Footnotes are written as small pieces of HTML at the end of each book, because plain Markdown has no footnotes.

Markdown has nowhere to put some of what Tabularia holds, so an export leaves out:

• underline, highlight, text color, typeface, size, and letter spacing
• alignment and drop caps
• dividers and ornaments
• a quotation's attribution link and category
• scene labels, anchors, and comments

Export to DOCX, EPUB, or HTML when those need to travel.

8. A round trip through Markdown

Export a manuscript to Markdown, edit it elsewhere, and import it again, and this much comes back unchanged: headings, bold, italic, strikethrough, quotations and how they are grouped, bullet and numbered lists, scene breaks, and the title. Chapters return too, found again by the heading rule rather than remembered.

Everything in the export's leave-out list stays lost, and pictures return only as their [Image: …] placeholders. Footnotes come back as literal HTML, so tidy them by hand or keep the Tabularia manuscript as the copy you work from.

9. Continue reading

• Previous: Writing and formatting
• Next: Navigating a long manuscript
• All guide articles