Support languages other than puppet within @example blocks

Use Case

Be able to provide examples in other languages in particular YAML.
Currently all @example blocks are assumed to be puppet language.

Describe the Solution You Would Like

Don't really know yardoc so guessing what a syntax might be

@example(yaml) Specify a Yum repo
---
yum::repos:
    base:
        baseurl: 'https://repos.example.com/CentOS/base/'
        mirrorlist: '--'

A clear and concise description of what you want to happen.

Should be rendered as the following with pretty yaml.

# Example - Specify a yumrepo
---
yum::repos:
    base:
        baseurl: 'https://repos.example.com/CentOS/base/'
        mirrorlist: '--'

Describe Alternatives You've Considered

Folk have tried nesting a yaml code block but it turns weird.
(have used ' rather than ``` for the inner code block)

@example an example
'''yaml
---
foo:bar
'''

however this results in nonsense output.

Additional Context

Stems on from this merge request to clean up some previous attempts to render yaml.

https://github.com/voxpupuli/puppet-yum/pull/171

which resulted a completely broken markdown result.

Start by tracing how @example blocks are parsed and rendered, then inspect the existing handling of Puppet examples and the markdown output. Use the YAML example and the linked puppet-yum pull request as reproduction material; done means a language-qualified example renders as readable YAML without breaking existing examples.