FLUID-6324: patch for 6.82.5 release of DocPad

[waharnum]

This is a patch to allow us to build and deploy the documentation under a version of DocPad compatible with Node 10.

It makes the following substantive changes:

• bumps the DocPad version to 6.82.5
• adds the serve plugin to maintain static server support (DocPad made this a plugin rather than a built-in for the 6.8 line)
• uses my forked and built version of the handlebars plugin, updated for compatibility with the 6.8 line: https://github.com/waharnum/docpad-plugin-handlebars/tree/fixFor6.8-build - I've had an outstanding pull request on the fix for this plugin since last December, but it has yet to be merged (v2.5.1 - update plugin for 6.82.x line of DocPad docpad/docpad-plugin-handlebars#13)

This should allow us to build and deploy the documentation in our usual way, in the immediate term.

[waharnum]

@simonbates, would you be able to review this for merge when you have a chance? You should now be able to check out a clean copy of my branch, run npm install, and be able to build and work on the Infusion docs in the usual way.

@jhung Assuming this approach works for Simon we should be able to use it on the Guide site and other places DocPad is used.

[waharnum]

@simonbates It looks like the reason for commenting out / removing the ghpages plugin was because that plugin is also currently broken and not updated for the most recent version of DocPad compatible with Node 10. So I think the current situation is now as follows:

• this patch will produce the expected site in the out directory
• the contents of the out directory needs to be committed to the deploy branch of the repo by some means; previously this was handled by the ghpages plugin, but that plugin is no longer working.

Options for moving forward that I see:

1. Patch the ghpages plugin like we did for the handlebars one (I don't consider this preferable, given how little this plugin is actually doing)
2. Use another means of committing the out directory to the deploy branch (Grunt task, or maybe do manually for the moment)

The Docker support that was being worked on in #138 would make the separate deploy step unnecessary by using a builder container, but it isn't in yet (due to being blocked by the errors this mean PR is meant to fix).

I'd recommend we go with the need to make a manual commit of out to the deploy branch for the moment, given how infrequently we update the docs. Longer-term, we'll work on getting the Docker support in. Let me know your thoughts.

[simonbates]

I agree with your proposal to manually copy out to the deploy branch. I think the Docker work would be a better task to spend time on, rather than getting the ghpages plugin to work, or automating the committing to the deploy branch.

[simonbates]

I see that we are also changing from docpad-plugin-markit to docpad-plugin-marked. I will do some testing, but I was wondering: do we anticipate changes as a result? I'm thinking of details like automatically generated heading anchors?

[waharnum]

I'm uncertain as to what changes we might see - I believe the change was made because docpad-plugin-markit hadn't been updated in three years, but it was made by @jobara.

I didn't see obvious issues but haven't tested extensively - automatically generated heading anchors seem to still be working.

[jhung]

I'm uncertain as to what changes we might see - I believe the change was made because docpad-plugin-markit hadn't been updated in three years, but it was made by @jobara.

I didn't see obvious issues but haven't tested extensively - automatically generated heading anchors seem to still be working.

Sorry I'm late to conversation @waharnum and @simonbates. There was a change from marked to mark-it a while ago as discussed in FLUID-6205. That conversation may shed some light into the possible effects of reverting back to Marked.

If I recall correctly, Marked is still being used on our other docpad sites. Fluid docs is the only one using Mark-it. I will need to verify that.

[simonbates]

I've generated the upstream master docs with Node 8 and generated the docs for this branch with Node 10. And then compared the generated output using a diff program (Beyond Compare). I'm seeing some differences:

• "." is handled differently in generated anchors
  • master: <h3 id="fluiddefaultsgradename-options">fluid.defaults(gradeName[, options])</h3>
  • FLUID-6324: <h3 id="fluid-defaults-gradename-options-">fluid.defaults(gradeName[, options])</h3>
• Some minor typographical: ' instead of '
• src/documents/UserInterfaceOptionsAPI.md has changes on master not on this branch (I think it's fine to leave this -- I note it here for completeness)

The only one I've found so far that is significant is the change in anchors. This will break related links, such as (fluid.hasGrade in https://github.com/fluid-project/infusion-docs/blob/master/src/documents/CoreAPI.md): ([defaults](#fluiddefaultsgradename-options))

[waharnum]

@simonbates @jhung It's odd that the generated anchors would be different since they're both using Mark-it - it look like the anchor-generating plugin allows for a custom slug function (https://github.com/valeriangalliat/markdown-it-anchor) - I'll look into this.

[simonbates]

I was trying to generate the master docs with Node 8 again today but was having trouble (error related to the ghpages plugin). And with Alan's help we were able to determine that the issue was that I had the latest version of DocPad installed globally (6.82.5). I was able to generate the docs with Node 8 and DocPad version 6.79.4, which can be installed with:

npm install -g docpad@6.79.4

[waharnum]

As discussed in-channel and in-person, I am going to close this in favour of this pull request that uses Docker containers pinned to Node Version 8.