Code listing titles could be styled in HTML output

[skalee]

AsciiDoc allows code listings to have titles (typically file name). However, they look ugly and confusing in YARD documentation. In particular, they are difficult to distinguish from regular paragraphs.

Obviously, using a custom template may help a lot. However, this issue should be addressed in a default template IMO.

I am not sure if this issue belongs to this repository or rather to https://github.com/docmeta/rubydoc.info.

Steps to reproduce

Following AsciiDoc document was used to illustrate the issue:

== In AsciiDoc...

This is a lead paragraph.  Code listing starts right below.

.test.rb
----
two = 1 + 1
eleven = "1" + "1"
raise if Failure.problem
----

This is the second paragraph.  Code listing has just ended.

With default settings, YARD translates it to a following piece of HTML:

<div class="sect1">
<h2 id="_in_asciidoc">In AsciiDoc&#8230;&#8203;</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="title">test.rb</div>
<div class="content">
<pre>two = 1 + 1
eleven = "1" + "1"
raise if Failure.problem</pre>
</div>
</div>
<div class="listingblock">
<div class="title">test2.rb</div>
<div class="content">
<pre class="highlight"><code class="language-ruby" data-lang="ruby">two = 2 + 2
eleven = "2" + "2"
raise if Failure.problem</code></pre>
</div>
</div>
</div>
</div>

Actual Output



## Expected Output Something of similar quality like:



---- I can prepare CSS updates if this is non-controversial. I have read the [Contributing Guide][contrib]. [contrib]: https://github.com/lsegal/yard/blob/master/CONTRIBUTING.md

[skalee]

@lsegal How about this one? Can I implement such feature, or is it something what doesn't fit to YARD for some reason?

[skalee]

@lsegal Few more ideas with different background colors:

Using background color #efeff1 (which is exactly 3% darker than listings' background, i.e. #f7f7f9):



Using background color #eeeeee (which is widely used in the default theme):



Using background color #e1e1e8 (same as border color):



Achieved by adding a few lines to templates/default/fulldoc/html/css/style.css:

/* code block titles (supported in AsciiDoc) */
#filecontents .listingblock .title {
  padding: 9px 14px 9px 14px;
  margin-top: 4px;
  border: 1px solid #e1e1e8;
  background: #e1e1e8;
  border-radius: 4px;
  font-size: 1em;
  overflow-x: auto;
  line-height: 1.2em;
  margin-bottom: -9px;
}