I was reading What’s Wrong with Markdown by Adam Hyde this morning.  Coincidentally, I’ve been researching and weighing my options for a simplified markup syntax for a Test Case Management system I’m working on.

While I agree with most of what he said, the thing that really struck home (and rang false) is that Markdown is meant as a way to visually markup text — not a shorthand syntax to translate into HTML.

When editing test cases (or comments, or really any simple form of documentation, you don’t want to get too fancy.  You don’t want to hide complexity, you want to eliminate it.  So, here is my proposal for a complete structured text format designed to be read as is … or translated into HTML or other inputs.

Text styles:

Forget about all those weenies who think they’re hip talking about semantic markup (which is really just semantics) nobody ever said, I wish I could tell people my text has emphasis or “strong”.  People want text that is bold, italic, and underlined.

*bold*

/italic/

_underline_

~strikethrough~

No further explanation needed.

Headings:

The same goes for headings. Who cares what an H6 is?  What you really care about is font size.  But, here, a little bit of semantics is useful for creating an outline or table of contents — or just a tiny bit for SEO.

= Heading 3 =

== Heading 2 ==

=== Heading 1 ===

Which heading is bigger? I bet you can tell.  A document really only has one main heading, and several nested under that.  So you should spend less time typing the headings you use more often.  Let the parser figure out which heading level is biggest and adjust accordingly.  HTML got the way headings are numbered wrong, but that’s not my problem.

And I don’t think you need more than 3 levels.  But you can make it bigger for more emphasis if you want:

================= You’ll really notice this heading (but you shouldn’t have to count dashes =================

Lists

This one isn’t hard.  But so many parsers screw it up — so does MS Word, but what’s your excuse?

Bulleted lists

* item a

* item b

* item c

Numbered lists

1. item 1

2. item 2

3. item 3

Indentation creates nesting.  That is all.

Indentation

Four spaces or a tab.  I’d restrict it to only tabs, but textareas can’t handle tabs (unless you paste them.)

indented

Links

If it looks like a url, it’s a link.  Too bad if the parser makes a mistake.  But you can create links with labels, and use anchors

[link:label]

[#anchor]

A footnote would look (surprisingly) like a footnote

see footnote [1]

[#1] This is my footnote

Images

Images (and why not, even flash or an HTML canvas if you really want) can be embedded with curly braces.  If a link looks like an image, you could embed it by default.

{embeded url}

Preformatted text and code

This is important, and github’s triple tilde is a good solution, but how about just a triple dash?

—single-line preformatted—

—
multi-line
prefomatted
text
—

You could also just use a HTML-like tag

<code>

This is a code block.

</code>

Tables

Why not?  If you’re willing to draw it, render it.  Along with alignment like github markdown uses

+------------+-----------+--------+
| :left      | :center:  | right: |
+============+===========+========+
| the above rows are headers      |
+---------------------------------+
| don't | worry | about | cells   |
+-------+-------+-------+---------+

Number of dashes determines width in ems — or just default to 100% — or something like that.

Do you really need anything else?  Especially because this should be a simple text block.  I’m not sure that embedding images or rendering tables is even called for.

Let me know what you think.