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:
![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:
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).