Introduce configuration value for mounts

Problem to solve

We need a way of resolving the full path of images referenced in a page’s source. For example:

https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/8c405278e6e9882fd242de4a50c3bb78671ba2dd/sites/handbook/source/handbook/business-ops/data-team/platform/periscope/index.html.md#L146

![discovery](/handbook/business-ops/data-team/platform/periscope/discovery.png)

When middleman resolves this absolute path, it uses /sites/handbook/source/ as the content root source directory.

We must also account for the fact that some static site generators and site configurations (including Gitlab's own middleman monorepo structure) may have images compiled from multiple different content root source directories in the same repo, but being served under the same target path URL.

Proposal

This config value takes inspiration from the approach Hugo ended up with in their module/mounts approach:

• The configuration is an array, with entries consisting of source + target value pairs.
• The source value of an entry is the path relative to the project root.
• The target value is where the content relative to the source should considered to be mounted, relative to the web root.
• Other relevant links on the Hugo virtual filesystem and modules/mounts:
  • https://gohugo.io/news/0.56.0-relnotes/
  • https://gohugo.io/hugo-modules/
  • https://gohugo.io/content-management/organization/

So, using an examples from our current repo where we have can have two or more different content roots for Middleman in our monorepo structure, it would be something like this (using the Hugo "mounts" terminology):

mounts:
  - source: sites/handbook/source
    target: ''
  - source: source/images
    target: images

So, to solve the image-display problem, the logic would be that when the SSE encounters an image tag, it would look at the first part of the path, and try to match it to the target of an entry. If a match was found, the source would be prepended the WYSIWYG image tag to make a valid relative URL.

This does present potential complexity/performance problems in first entry, where there is a blank target value. A "blank" value essentially means "use this entry if the path didn't match any other target". That's why having images scattered among the content templates rather than under an images root is an anti-pattern.

This approach also offers us at least some degree of future-proofing and flexibility for handling this same type of issue for non-image files, e.g. layouts or partials which may be included from various directories at build-time.

See further discussion of this approach in this thread below

Config File Entry Syntax Details

Types:

mounts:
  - source: <string>
    target: <string>
  - ...

Default Values:

• Ideally, the default value should be determined based on the static_site_generator config value, and be a single array entry with the source and target following the out-of-the box defaults for the corresponding tool (middleman, hugo, etc).