Design: Outline indentation and Markdown?

The puzzle

  • The user enters a Markdown document in an outline.
  • How to interpret indentation?

Necessary background

  • This is a design puzzle for content management.
  • To solve the puzzle you need to have a design-level understanding of three things:

1st approach — flatten everything

  • In the first approach we ignore indentation.
  • As we generate Markdown text from the outline, we go into sub-heads, but we don’t indent with tabs, add any Markdown syntax, or HTML syntax.
  • Consider this example:
    • To-do list
      • Walk the dogs.
      • Get coffee.
        • Two shot-in-the-dark coffees.
        • One tall latte.
      • Go to a movie.
  • What we would generate, in Markdown, is this:
    • To-do list
    • Walk the dogs.
    • Get coffee.
    • Two shot-in-the-dark coffees.
    • One tall latte.
    • Go to a movie.
  • This is the approach I take in the software I’m working on, but have not released. It’s the most conservative approach. It says outline indentation is a writing aid, but has no effect on the rendering. It may be possible to add interpretation for structure in the future, but if we do it we would break existing users.

2nd approach — ignore Markdown

  • Note: This approach is pure fiction. I don’t think it’s possible in Markdown. 🙂
  • Having used an outline-based CMS for many years, the approach I like best is the one that you’re reading right now. The structure is reflected in an HTML outline with wedges that can be used to collapse or re-expand the text.
  • This way I can organize my writing and have that organization reflected in the readers’ experience.
  • So in the example we’re using the to-do list would look like this:
    • To-do list
      • Walk the dogs.
      • Get coffee.
        • Two shot-in-the-dark coffees.
        • One tall latte.
      • Go to a movie.

3rd approach — a compromise between the two

  • Use Markdown syntax to indicate list structure.
  • We might render the list as follows:
    • To-do list
    • * Walk the dogs.
    • * Get coffee.
    • – Two shot-in-the-dark coffees.
    • – One tall latte.
    • * Go to a movie.
  • However, unless I’m missing something, Markdown sees one flat list, not a list with a second item containing its own sub-list with two items. In other words, there’s no concept of nested lists in Markdown?
    • I see that at least one Markdown processor has innovated here.
  • Or we might render it thus, to give emphasis to the main head:
    • ### To-do list
    • * Walk the dogs.
    • * Get coffee.
    • – Two shot-in-the-dark coffees.
    • – One tall latte.
    • * Go to a movie.
  • This approach is needed to help the eye pick up the structure when looking at a long list, each with a lot of subs.

Other approaches?

  • I wanted to put this out for comment, because I want to make the best use of outlining and Markdown, and my experience with Markdown is very limited.
Advertisements

About Dave Winer

Dave Winer, 54, pioneered the development of weblogs, syndication (RSS), podcasting, outlining, and web content management software; former contributing editor at Wired Magazine, research fellow at Harvard Law School, entrepreneur, and investor in web media companies. A native New Yorker, he received a Master's in Computer Science from the University of Wisconsin, a Bachelor's in Mathematics from Tulane University and currently lives in Berkeley, California.
This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s