Markdown formatting in LinkML documentation

[cmungall]

I like to have contextual examples embedded in documentation. I have started using newline-preserving yaml line blocks (|-), with meaningful white space, and using markdown.

For example:

https://github.com/berkeleybop/kgviz-model/blob/1003fa95b6dd931b58d4df6a0505a88d2108bbb3/model/schema/kgviz.yaml#L59-L84

 RelationConfiguration:
    is_a: ElementConfiguration
    description: |-
      style for a particular relation (for example, BFO:0000050 or rdfs:subClassOf).

      Example of usage, where [relationProperties](relationProperties.md)
      specifies a collection of RelationConfigurations keyed by property.

      ```json
      {
          "relationProperties": {
              "rdfs:subClassOf": {
                  "color": "black",
                  "penwith": 3,
                  "arrowhead": "open",
                  "label": ""
              },
              "BFO:0000050": {
                  "arrowhead": "tee",
                  "color": "blue"
              }
          }
      }
      ```

this renders as:

https://berkeleybop.github.io/kgviz-model/RelationConfiguration/

which is exactly what I intend and is IMHO quite nice.

This also works in the header section, e.g.

https://cmungall.github.io/semantic-sql/relation_graph_index/

I want to check:

• Is this good practice
• Should we make more formal guarantees about how markdown rendering is preserved when running markdowngen
• Should we allow more control over how this works. For example, the start of the block could include a hint that the formatting is markdown, leaving us the option to having other formats

[hsolbrig]

Wholeheartedly agree. We need a couple of good test cases so we can be sure that the markdown is preserved across the entire process.

[cmungall]

should we preserve it in pythongen? convert to ReST?