Formatting preferences and options

[briandominick]

Tell me if I'm stepping on any toes, or if you have a better place for this discussion, but I was thinking maybe we could just use a thread to list some things we may or may not consider less-than-optimal about the current formatting, and maybe a wishlist of changes? We can spin issue tickets off for the ones we want to implement, if we want...

\s before *?
The first thing I noticed is you put spaces before list markup (ordered and unordered).

So:

 * item
 * item

Instead of:

* item
* item

Is there a reason for this convention? I find it really awkward.

Blank lines before lists?
The conversions are also missing blank lines between the preceding line and the list (ordered or unordered).

So:
This kind of thing:

• Item 1
• Item 2

Parses to:

*This kind of thing:*
 * Item 1
 * Item 2

I think a blank line is required. This just dumps the asterisks and text inline.

Extraneous ==
Sometimes I'm getting == on a line on its own. I haven't investigated, but I'm guessing it's maybe from deleted headings or something? We could probably stand to clean up stray ^\=\=\n or something. I don't think this was intentional, right?

I'll leave it there for now. Let me know if this is helpful, and create tickets (or I will) to implement these? I'll gladly take some on :-)

[ggrossetie]

Wow thanks for this detailed issue! 👍

Tell me if I'm stepping on any toes, or if you have a better place for this discussion, but I was thinking maybe we could just use a thread to list some things we may or may not consider less-than-optimal about the current formatting, and maybe a wishlist of changes? We can spin issue tickets off for the ones we want to implement, if we want...

Not at all, thanks for your ideas! I'm sure we can make this addon better and better 😄
I think it's better to create a dedicated ticket for each feature. Even if we end up not considering a feature we can later see the discussion on the dedicated ticket.

\s before *?

No this is a personal preference but we should avoid the extra space because Asciidoctor lists don't need space before *: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#lists
Please create a new ticket to track this issue.

Blank lines before lists?

Indeed a blank line is required, this need to be fixed.
Could you please create a new ticket ?

Extraneous ==

If you check your document you should see a blank line with an heading 2 format.
But I think we can be more user friendly and remove titles if there's no text.
👍 for a ticket!

[briandominick]

Yeah I didn't want to spam you with tickets ;-) I'll make some new tickets tonight!