How Lighthouse ticket-tracking currently uses Markdown for lists

We are gradually switching from Mantis to Lighthouse for ticket tracking at work because it's a great ticketing system, and more customer-friendly than Mantis because it's simpler. Lighthouse uses Markdown as its text-formatting "language". But we've had some problems getting text formatting to work well, partly because we're habituated to writing content in Textile-format in Basecamp, partly because we do lots of structured lists in our tickets, and partly because Lighthouse's implementation of Markdown lists is currently a bit idiosyncratic.

So here are some rules of thumb for making lists work in Lighthouse. As the developers improve it, I'll come back and edit this post. (I hope this also helps the developers updating the documentation and, preferably, the code: Lighthouse is a great product but we'd love to see a less brittle and more consistent implementation of Markdown lists.)

1. Every list must have a blank line above it and one beneath it. Else, your list will break horribly. (Also don't do a numbered list, then have a blank line, then do another list: it'll continue your first list.)
2. Nested/hierarchic lists work slightly differently for numbers and bullets:
   • To do a second-level bullet (a "child") you do space-space-*
   • To do a second-level number (a "child") you do space-space-space-1. That it's different from the way bullets are handled is probably a bug.
   • To do a third-level bullet (a "grand-child") you do tab-*
   • To do a third-level number (a "grand-child") you do tab-tab-1.
   • To do a fourth-level bullet (a "great grand-child") you do tab-tab-*
   • To do a fourth-level number (a "great grand-child") you do tab-tab-tab-1.
3. Mix numbers and bullets very carefully in nested lists: numbers should not contain bullets as children because the bullets tend to kill the number order of the parents...

Some examples. A list of bullets that works:

* parent
  * child (space-space-bullet)
    * grandchild (tab-bullet)
        * great-grandchild (tab-tab-bullet)
* parent
  * child (space-space-bullet)
    * grandchild (tab-bullet)
        * great-grandchild (tab-tab-bullet)
    * grandchild (tab-bullet)
  * child (space-space-bullet)
* parent

A list of numbers that works:

1. parent
   1. child (space-space-space-number) - nb, here it's a triple-space, not the double-space you'd do for a child bullet
   1. child (space-space-space-number)
        1. grandchild (tab-tab-number) - again, not the same as it is with bullets. And nb now you can't do a fourth, great-grandchild, level of numbers.
1. parent
   1. child (space-space-space-number)
   1. child (space-space-space-number)
        1. grandchild (tab-tab-number)
   1. child (space-space-space-number)
1. parent

And a list with both bullets and numbers that doesn't work in Lighthouse:

1. parent
   1. child (space-space-space-number)
   1. child (space-space-space-number)
    * grandchild (tab-bullet)
        * great-grandchild (tab-tab-bullet)
   1. child (space-space-space-number) - here the number order has been broken by the preceding bullet
        1. grandchild (tab-tab-number)
        1. grandchild (tab-tab-number)
   1. child (space-space-space-number)
    * grandchild (tab-bullet)
    * grandchild (tab-bullet)
   1. child (space-space-space-number) - again number order broken by preceding bullet
        1. grandchild (tab-tab-number)
        1. grandchild (tab-tab-number)
1. parent
   1. child (space-space-space-number)

There may be a better/more robust way to do nested lists, but I haven't found it yet. (Nested lists seem to work quite differently in Markdown, but to be fair to Lighthouse here, it does all seem a bit arbitrary in Markdown. Markdown seems more powerful than Textile, but also more complex, so maybe I don't understand it well enough yet.)

See also: Lighthouse commits to Markdown over Textile; Markdown syntax and testing doobry; a Lighthouse ticket discussing this very matter.

Comments

[Tom Armitage]

I really, really love Markdown for writing long-form documents - but am never convinced it's the appropriate choice for rich-text-ifying simple text fields. It prioritises the look of the pure text version over markuppy simplicity, which, for most of the time, is the correct approach imho... but not for just *filing a ticket*.

That said: the Ruby textile/markdown library isn't super-consistent in its interpretation of either spec. There have been some recent attempts at overhauling it (http://tomayko.com/writings/ruby-markdown-libraries-real-cheap-for-you-two-for-price-of-one), but I'm not sure how many retail products these are making it into.

I found Lighthouse good-but-not-great, but it appears to be improving at a rate of knots. I am very glad, however, both for you and your customers, that you're moving off Mantis. It terrified me ;)

[rodcorp]

"prioritises the look of the pure text version over markuppy simplicity" - is exactly the experience I've had, and I'm not sure it's better. Mind you, I've been using Textile for three years so I'm habituated...

Also Markdown (or perhaps it's just Lighthouse's implementation) seems quite unforgiving. When you render text, it either works or fails utterly. Textile seems a bit better at simply ignoring stuff it doesn't understand. I assume this is because Markdown is a lot more powerful.

A (very non-technical) thought: can my browser not perform this kind of processing for me? Then I could write whatever markup I wanted into it and it could output what the website in question expects. (Maybe that's stupid.)

And as for Mantis... it was so intimidating enough to customers that they all ignored it and used email instead.

[Tom Armitage]

""prioritises the look of the pure text version over markuppy simplicity" - is exactly the experience I've had, and I'm not sure it's better."

I'm definitely not sure it's better for writing fragments - comments, ticket updates. I'm pretty convinced it's nicer for writing documents; eg, if you look at John Gruber's markdown versions of his blogposts, for instance:

http://daringfireball.net/2008/08/raining_on_the_openclip_parade.text

it makes total sense; I like how footnotes are possible, and I like how it handles quotations.

When you're writing a single paragraph, or a swift comment, I don't know that it makes as much sense. It is, however, a pure markup language - Textile tends to assume you know HTML to begin with, wheras Markdown could feasibly be converted into anything.

[rodcorp]

Given that example, I see what you mean. So it would be nice to be able to try Markdown as a format but still inject it successfully into Basecamp - but as Basecamp doesn't support it, that's what I want the browser to do for me...

Anyway, stop commenting on posts about markup Armitage. Haven't you got a post on games, or frankly a game, to be writing?!

[Chris Cera]

I found your blog by searching for 'mantis lighthouse'

The 37signals guys had a discussion on their forum about how they believe Textile was a mistake in Basecamp, and they decided not to add it to Highrise.

http://forum.37signals.com/highrise/forums/9/topics/802

I'm currently using Mantis, and thinking about switching to Lighthouse. Are you aware of any import tools.

[rodcorp]

Thanks for the comment and link Chris. That there isn't consistency across 37Signals's products seems a bit weird, though I understand that customer service is a valid concern for them. I'm persuaded by Tom Armitage's comments that Markdown is better for marking up long form content (though I do think that Textile looks easier to learn).

Anyway, it all reinforces my (no doubt unfeasible) desire to separate the way the website expects to receive content from the way the user might be used to writing the content, perhaps in a browser plugin or something...

As for migrating Mantis to Lighthouse, we're currently taking the coward's route and making the switch at the start of new projects, so we're not yet dealing with importing legacy tickets. If you find a useful tool, do come back at let me know!

So far, we're liking the simplicity and user-friendliness of Lighthouse compared to Mantis, and its use of milestones etc.

[fiona]

so comparing lighthouse with highrise? woul dlove to know your thoughts. tender supoort seems a great online ticket and community center, but using is that then over kill with lighthouse?