docs: Fix compatibility issues with opentelemetry.io

[arielvalentin]

The changes I submitted in #930 were optimized for a GitHub markdown, however when I integrated them into opentelemetry.io I ran into issues with navigation, duplicate headers, and some odd rendering issues.

The changes included in this PR update the Markdown to work better with Hugo and opentelemetry.io:

[ahayworth]

I have not the tiniest clue how these changes actually fix the visual problems, but I absolutely trust that they do. 😄 😄 😄 😄

[arielvalentin]

@ahayworth The main problem was I reused the same description on every page with an image of a Ruby. I thought it was a "meta" description but no it was included as a header on every page.

[ahayworth]

@ahayworth The main problem was I reused the same description on every page with an image of a Ruby. I thought it was a "meta" description but no it was included as a header on every page.

Ah that makes sense!

[arielvalentin]

Oh also navigation is busted because the io site processes the MD to generate static HTML. I had to sacrifice MD navigation as a result.

[fbogsany]

It's fine to break MD navigation - these files are intended purely for opentelemetry.io.