After a day of intense debugging I found the solution to my Partial problems, which failed when I upgraded from V3.4 to V4.1. I like to summarize the Gotchas.
GOTCHA 1. Content files that used to be built properly are now ignored.
V3
about.md builds to about.html or /about/index.html
V4
about.md builds to about
also no layout is wrapped around it.
V3-to-V4: Rename all the content files in V3 according to this scheme
about.html.md (target is html with layout, source is md)
about.html.md.erb (target is html with layout is chain erb to md)
I see this is by design in V4. I think it is a mistake to break V3 compatibility.
If the target has no html extension then it gets no layout wrapped.
This is not good, whatabout targets that are JS and PHP?
If this is by design it can be done better with code in configuration.
GOTCHA 2. Partials behaviour is changed.
V3
= partial “myheader”
includes a file called _myheader(.md, .html, .erb, etc) from a directory /partials
and this default location is changeable with set :partials_dir
V4
= partial “partials/myheader.erb” (fully write out the subdirectory).
set :partial_dir is dropped.
This change from V3 to V4 breaks the project with no sensible error or warning message during build
Not documented correctly in the info page for partials either.
GOTCHA 3:
I have to rant about the horrible syntax of specifying a complex file specification in a string which then gets cut up without rhyme and logic.
= partial “THEPARTIALFILE”
the string part gets cut up into DIRECTORY part and FILENAME part
-
FILENAME part gets an underscore prefix
-
FILENAME part file extension is left out, so the template engine chooses from the files it find
-
Then everything is recombined into the target filename for inclusion.
E.g. = partial “mydir/header”
actual file included is “mydir/_header.haml”
if the file that Middleman thinks should be used could not be found, no error is raised, just blanks are included.
At the very least there should be a debug mode that shows the source and destination transformation, so when content goes missing we can at least know what files Middleman was tracking.