ZOOKEEPER-3807: fix the bad format when website pages build due to bash marker

[maoling]

• more details in ZOOKEEPER-3807

[ctubbsii]

This says more details are on the issue, but there are zero details on the issue at all.

What is the nature of the breakage?

Also, this change seems to switch from explicit fenced code blocks to the more basic ones that are whitespace sensitive. In my experience, the fenced code blocks are better, and less prone to breakage due to improper spacing.

Can this PR be updated to a more minimal change that does a targeted fix of whatever is broken, leaving the existing fenced code blocks in place, rather than switch to the basic code blocks, which seems unrelated?

[maoling]

@ctubbsii

• fenced code blocks can also cause the bad formats in the website page. Look at this
  http://zookeeper.apache.org/doc/r3.6.0/zookeeperAdmin.html#Quorum+TLS
  And the basic code block works well
  http://zookeeper.apache.org/doc/r3.6.0/zookeeperTools.html#zkTxnLogToolkit
• Although the change is not small, from the diff to see: just a housekeeping.
  I also fix a few other obvious bad formats in the webpage.
• mvn clean install -DskipTests to recheck the generated HTML files under zookeeper-docs/target/html
• In essence, do we have an alternative way to twist some makedown build parameters to handler it gracefully without any changes(compatible for all kinds of block code grammar)? @tamaashu Do you have any insight?

[ctubbsii]

@maoling From what I can tell, the bad formatting has absolutely nothing to do with the markdown at all, but the markdown-page-generator-plugin, which generates different HTML for the two kinds of code blocks. The basic block generates <pre><code>content here</code></pre>, whereas the fenced code block is generated as <p><code>content here</code></p>.

This difference matters, because the profile.css stylesheet styles <pre> blocks, but not <code> blocks. A much simpler change (pretty trivial, actually), that retains use of the (IMO superior) fenced code block style is to simply add the appropriate CSS for the <code> to zookeeper-docs/src/main/resources/markdown/skin/profile.css

Long-term, I think the build should be changed to stop rendering static HTML in a Maven build with a Java plugin and a non-standard Markdown parser, and instead use a better tool designed for the job (such as Jekyll, with the widely popular Kramdown).

[symat]

simply add the appropriate CSS for the <code> to zookeeper-docs/src/main/resources/markdown/skin/profile.css

this would make a lot of sense. Also it would make the PR easier to backport to older branches (as I am sure the current approach will resulting a lot of merge conflicts).

Still, I saw other smaller improvements in the PR (unrelated to the code blocks), I would keep those.

[ztzg]

Closing this (valiant) attempt in favor of #1741 (review), as acknowledged by @maoling. Fenced code blocks are specified by CommonMark, so I don't feel retaining them locks us into a specific rendering engine.