AsciiDoc lists have extra space (when compared to Markdown output)

[sgilda]

I am converting Markdown files to Asciidoc. Simple lists render strangely using Asciidoctor.

This is the source:

This is a list:

• Item 1
• Item 2
• Item 3

Asciidoctor renders list items with a <p></p> tag and the resulting list has blank lines between
list items, resulting in a very spread out list.

The resulting HTML rendered by Asciidoctor:

            <div>
                <p>This is a list:</p>
            </div>
            <div>
                <ul>
                    <li>
                        <p>Item 1</p>
                    </li>
                    <li>
                        <p>Item 2</p>
                    </li>
                    <li>
                        <p>Item 3</p>
                    </li>
                </ul>
            </div>

Markdown files render more compactly like this:

            <ul>
                <li>Item 1</li>
                <li>Item 2</li>
                <li>Item 3</li>
            </ul>

[lordofthejars]

Can you provide with an example of your source? I have never heard this
problem before.

2014-09-11 22:52 GMT+02:00 sgilda notifications@github.com:

I am converting Markdown files to Asciidoc. Simple lists render strangely
using Asciidoctor.

This is the source:

This is a list:

• Item 1
• Item 2
• Item 3

Asciidoctor renders list items with a

tag and the resulting list
has blank lines between
list items, resulting in a very spread out list.

The resultng HTML rendered by Asciidoctor:

This is a list:

Item 1

Item 2

Item 3

Markdown files render more compactly like this:

• Item 1
• Item 2
• Item 3

—
Reply to this email directly or view it on GitHub
#1087.

+----------------------------------------------------------+
Alex Soto Bueno - Computer Engineer
www.lordofthejars.com
+----------------------------------------------------------+

[sgilda]

Sure. For a comparison, see how the following files render on Github:

https://github.com/sgilda/playground/blob/master/file-asciidoc.asciidoc

https://github.com/sgilda/playground/blob/master/file-markdown.md

[mojavelinux]

It just so happens we've been discussing this topic this week on the
AsciiDoc discussion list. There's a reasonable explanation for why AsciiDoc
Python (and in turn Asciidoctor) uses

tags around list item text.

See https://groups.google.com/forum/#!topic/asciidoc/BF9HlACuNjE

Note that I did something slightly different in the EPUB3 converter, which
I consider to have much more semantic HTML5 output.

https://github.com/asciidoctor/asciidoctor-epub3/blob/master/lib/asciidoctor-epub3/converter.rb#L610

I wrap the item's "principal" text in a instead of a

. The text
has to be wrapped in something or it becomes very difficult to style when
used alongside list items with complex content. However, the
prevents it from being styled by default. We'll likely want to take this
approach on GitHub.

[mojavelinux]

The fact that they look different on GitHub is a slightly different issue. AsciiDoc relies on a stylesheet to fill in some features. GitHub renders AsciiDoc without any help from the stylesheet, so we fall back to the default styling of HTML tags. This is something we still need to address with AsciiDoc support on GitHub.

[mojavelinux]

I've updated the issue title so it better reflects the discussion.

[sgilda]

@mojavelinux : Thanks for following up on this and providing this information. It's not an urgent issue. Just an observation. :-)

[mojavelinux]

Some additional insight:

What I discovered when implementing clean room HTML5 for the EPUB3 converter is that if we simply remove the <p> element, it becomes extremely difficult to style both simple and complex lists. We still need some wrapper element around the list item text in order to control spacing. As suggested above, instead of a <p> element, we can use a <span> element so that it does not impact spacing when a dedicated stylesheet is absent (as it is on GitHub).

[mojavelinux]

I was thinking there is one other way around this problem that would possibly allow us to drop the <span> around the list item text. We could flag compound lists with the compound class (or, vice versa, simple lists with the simple class) so we could control the spacing on the <li> element accordingly. CSS doesn't give us enough power (yet) to handle both lists with compound content and lists with simple content using element selectors alone.

In other words, a simple list might look like:

<div class="ulist">
  <ul class="simple">
    <li>Item 1</li>
    <li>item 2</li>
    <li>item 3</li>
  </ul>
</div>

I'll need to play around with the CSS to determine if it's better to flag the simple or compound list (or both).

To clarify, we'd be passing a hint to CSS about what type of content the list contains.

[mojavelinux]

Oh yeah, I remember another reason why I needed the <span> in the EPUB3. It allowed us to control the font settings (e.g., legibility) without having to add the font family directly on the <li> element (which slows down rendering on the EPUB3 devices). Maybe not as much a concern on the web.

[gAmUssA]

@mojavelinux What's min required css should be included to fix this "bug"?

[old-o]

I noticed the same issue when migrating my READMEs from md to adoc. Any idea when you will start using span instead of p ?

[mojavelinux]

I have it scheduled for 1.6.0. The default Asciidoctor stylesheet provides the CSS necessary to make it render more compact. However, it's going to look expanded on GitHub until the HTML changes because GitHub doesn't (and won't likely) provide the necessary styles. But hey, they could surprise us :)

[wimdeblauwe]

+1 for this. I also find the lists too "spread out" when converting to HTML.

[mojavelinux]

Also related to #1221.

[old-o]

I don't want to nag, but is there any progress on this issue? :)

[nfrankel]

@89z If you're unhappy with a design decision of a product you're using for free, I've great news for you. Asciidoctor is Open Source. Nothing prevents you from forking it and making the changes you deem necessary.

[Frizlab]

@89z Of course not…

The maintainers do not wish to remove the <p> from <li>, and that’s fine; I don’t really think they should either. The generator is customizable though.

I simply asked GitHub to either tweak the CSS they generate (to simply remove padding for first p in li in generated) or tweak the generator options to avoid the <p> in <li>.
Both are relatively easy to do.

[nfrankel]

@89z I surely know nobody forces you to use GitHub or Asciidoctor. I surelly know that @mojavelinux already commented on the issue in detail. I surely know bad attitude when I see it.

[mojavelinux]

Please stop this argument. It's off the rails, distracting, and not productive. I never said I wasn't going to implement the solution previously agreed on. I merely pointed out that this is a display issue. I stated that to emphasize that it's not something that is controlled by the AsciiDoc source, but rather by the output Asciidoctor produces and how that output is styled. That output can be controlled by CSS where CSS can be controlled.

GitHub happens to style <p> elements inside an <li> in a way that is outside of our control. We already know that. The only option for controlling the display on GitHub is to change the element used. This is not a shortcoming of the Asciidoctor processor. And it's neither correct nor incorrect to use a <p> element in this case. But we know that GitHub won't change its styles. So it's a reality we have to face. We're willing to make the change for the benefit of our users. I've already scheduled that change as indicated by the milestone. So further punching on Asciidoctor is not welcome and will only succeed in delaying a fix.

[ggrossetie]

If you are using Refined GitHub (if not, you should!), you can define the following styles to remove margins:

.markdown-body li>p {
  margin-top: 0;
  margin-bottom: 0;
}

Open the extension options and copy-paste the above styles in the "Custom CSS" text area:

And here's the result:

Before	After

https://github.com/opendevise/asciidoc-samples/blob/master/demo.adoc#1-first-steps-with-asciidoc

[sskras]

Folks, a lot of comments here.

So, how on GitHub can I achieve compact spacing in bulleted lists for any popular browser (without using the extension) using .adoc?
What's the consensus?

[ggrossetie]

@sskras you can open a support ticket at https://support.github.com/. Hopefully, if enough people ask for this, they will do something.

[toastal]

@sskras you can open a support ticket at https://support.github.com/. Hopefully, if enough people ask for this, they will do something.

I and others are waiting for the <p> → <span> migration. People use AsciiDoc on other Git forges (GitLab for instance renders it natively), and personal webpages. The current state as a paragraph does indeed feel like bug because everyone needs to include a special stylesheet to deal with this issue. Hacking just GitHub does not solve the problem. Additionally screen readers have tools to skip paragraphs, but this content doesn't match the normal conception of a paragraph.

---

Personally, I'm working on a Soupault plugin to clean up all of the issues I'm finding with AsciiDoc output. Currently this list includes:

• unparagraphing list items
• strikethroughs using <span> instead of <del>
• the entire body is listed as a the article when I want my article to be an <article> inside the body.

Maybe I'll report back once it's more stable

[toastal]

Reporting back tangentially...

https://git.sr.ht/~toastal/sourcehut-asciidoc-renderer

I've made a Nix script to help do READMEs or other docs in on Sourcehut. This script include stripping these extra <p>s on list items and tables because Sourcehut has similar issues with misrendering like GitHub because of the output with <p>s (though it does still feel like a bug in Asciidoctor to begin with as many times list items don't need to be complex enough to contain paragraphs).

[mojavelinux]

The question is not whether it is a bug. The output is the way it is because it was developed initially to be consistent with the output that AsciiDoc.py generated. Changing that structure years after the fact would affect every single user of Asciidoctor in some way, and I'm just not going to do that to this community. It's too late to change the markup in the existing built-in converter. That's why we are changing it in the new HTML converter. See #242.

[toastal]

Ah, I did not consider that this would break AsciiDoc (:snake: version). This is a fair consideration and I don't disagree with your plan. There are two problems though:

• It's often not the correct/semantic markup
• In embedded cases, there's not much anyone here can do to fix or augment the host's rendering pipeline. Sure this will always be the way and until broader adoption, platforms like GitHub will neglect this.

I subscribed to the #242 issue though. It will be cool to see what comes of it.

[positron96]

Hi, I'd like to express my interest in this feature. I agree that changing stylesheets would be a proper solution, but too often these days we do not control the styling, e.g. I use asciidoc on github, gitlab, vscode preview extension and so on. Particularly, now I experience this problem with jekyll SSG and a custom theme, but, fortunately, there I have some control over CSS files.

By the way, to retain backward-compatibility, an extra list modifier can be introduced, like the one suggested earlier by @tringuyen-yw :

[compact-interline-spacing]
* Item1
* Item2

[mojavelinux]

As I've already stated:

That's why we are changing it in the new HTML converter.

Btw, you are free to add a compact role on the list, then modify the CSS accordingly. You have all the control you need to achieve the appearance you want. The main issue here is whether the principal text is wrapped in a paragraph by default. In the new HTML converter, it will not be. It will instead be wrapped in a span, making it easier to get compact by default with the option to add more space using targeted CSS.