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.)
- 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.)
- 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.
- 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.