Developer Portal - Extend markdown functionality of x-embedded-doc in Product and API definitions

The ability to define additional documentation pages using x-embedded-doc object in API or Product definitions is already a nice feature, but it can be better. What we love about it is that it makes it very easy to have the Product specific documentation be versioned together with the Product.

Currently we struggle with the following limitations:

• Images
  No images can be directly inserted into the resulting page. Images that are either uploaded to the portal beforehand or externally hosted can be referenced via the markdown  syntax.
• Document Structure
  The docs object cannot be nested indefinetly. From our testing we noticed that if the relation went deeper than 2 links, it would no longer be shown on the developer portal.

x-embedded-doc:
  # Folder on root
  - name: 📁-guides
    title: 📁 Guides
    docs:
      # Folder in folder
      - name: 📁-opening-a-file
        title: 📁 Opening a File
        docs:
          # Folder in folder in folder, will be shown as empty
          - name: 📁-assets
            title: 📁 Assets
            format: md
            docs: 
              # Will not be shown
              - name: creating-assets
                title: Creating Assets
                fornmat: md
                content: "Something about assets"
          - name: file-opening
            title: File Opening
            format: md
            content: "Some content"

• Relative Links
  Links cannot be created to other docs. Though links to external resources can be created with the [IBM Ideas](https://ideas.ibm.com) syntax, it is not possible to reference other documents. Though there is no "official markdown way to create links", the most common one is the Github style based on Jekyll, which could be leveraged here.
• Support for Markdown extensions
  The main request by one of our teams is the ability to use Mermaid diagrams directly in their defined markdown files.

The Drupal markdown editor in the developer portal also mentions (in a page that is shipped with the developer portal by default: <devportal>/filter/tips/ghmarkdown) more features that aren't fully supported: Daring Fireball Markdown Syntax and PHP Markdown Extra. Though I do not know if the translation of the x-embedded-doc object leverages this.

Most if not all of our developers and analysts are already familiar with the markdown syntax and like the capability to have this be properly combined with their Product/API. It also doesn't create a mess where multiple people would have to create Drupal objects on the portal to publish and maintain their documentation. It also allows documentation to easily be promoted to higher environments together with the Product and API, instead of having to maintain Drupal objects across multiple environments.

Kind regards,
Xander