Moving away from Markdown to straight HTML for Inclusive Design Guide site

Harnum, Alan aharnum at ocadu.ca
Thu Oct 6 15:42:49 UTC 2016


Here’s a quick spike as a concrete example of more complex block helpers: https://github.com/waharnum/guide.inclusivedesign.ca/tree/blockhelper-spike

The two most relevant files are:
https://github.com/waharnum/guide.inclusivedesign.ca/blob/blockhelper-spike/helpers/fluidHelpers.js - new helper that returns a figure
https://github.com/waharnum/guide.inclusivedesign.ca/blob/blockhelper-spike/src/documents/activities/InclusiveDesignMapping.html.md.handlebars - example of using the new helper

So under this system we reduce our need to copy and paste large blocks of structurally identical HTML with helpers.

We write this in the document source:

{{{fluidHelpers_figure
    src="/images/InclusiveDesignMappingTool05.png"
    caption="*Figure 5:* Inclusive Design Mapping Tool - Proposing the Desired State"
    alt="A diagram showing a new mapping with a positive gap"
}}}

The helper + docpad’s Markdown system eventually produce the following rendered markup:

<figure>
    <a href="/images/InclusiveDesignMappingTool05.png">
        <img src="/images/InclusiveDesignMappingTool05.png" alt="A diagram showing a new mapping with a positive gap">
    </a>
    <figcaption>
        <em>Figure 5:</em> Inclusive Design Mapping Tool - Proposing the Desired State
    </figcaption>
</figure>

The general pattern can be extended to let us store markup blocks that are structurally the same but require different parameters in a single place, which should make maintaining consistent styling and formatting easier.

Does this seem comprehensible, provided our custom helpers have good documentation?

On Oct 6, 2016, at 10:07 AM, Harnum, Alan <aharnum at ocadu.ca<mailto:aharnum at ocadu.ca>> wrote:

I like the direction of Tony’s thinking here - having some well-documented custom block helpers for our common use cases (like the icon list, and the figure/figcaption you mention below) could simplify the page maintenance and the creation of new pages, and let us avoid some of the current need to hand-roll largely identical blocks of HTML.

Looking at the markup on https://guide.inclusivedesign.ca/activities/InclusiveDesignMapping.html we’d probably have something like the following:

{{{figcaptionHelper “/images/InclusiveDesignMappingTool01.png” “<em>Figure 1:</em> Inclusive Design Mapping Tool - Choosing the Facets" }}}

That helper would then generate the appropriate block of markup using the image URL plus the caption text.

Given docpad’s architecture we should be able to create something like a “fluid-helpers” plugin that could be shared between various docpad-based projects.

On Oct 6, 2016, at 9:50 AM, Hung, Jonathan <jhung at ocadu.ca<mailto:jhung at ocadu.ca>> wrote:

Thanks Tony, this is really insightful.

Any idea how we might handle the <figure><img></img><figcaption></figcaption></figure> scenario in Markdown?

- Jon.

---
Jonathan Hung, Inclusive Designer
Email: jhung at ocadu.ca<mailto:jhung at ocadu.ca>
OCAD University
Inclusive Design Research Centre

From: Tony Atkins <tony at raisingthefloor.org><mailto:tony at raisingthefloor.org>
Date: October 6, 2016 at 8:05:18 AM
To: Hung, Jonathan <jhung at ocadu.ca><mailto:jhung at ocadu.ca>
Cc: Fluid Work <fluid-work at fluidproject.org><mailto:fluid-work at fluidproject.org>
Subject:  Re: Moving away from Markdown to straight HTML for Inclusive Design Guide site

Hi, Jonathan:

I agree with a lot of Alan's points, moving to pure HTML seems like a step we should only consider once we have reasonably exhausted the remaining options.  Thankfully, I can already think of a few options off the top of my head that would get us back to more pure markdown.

Let's start with the markup from the "Cause and Effect" page<https://github.com/inclusive-design/guide.inclusivedesign.ca/blob/master/src/documents/activities/CauseAndEffect.html.md.handlebars#L35>:

<ul class="idg-articleContentUseWhyHow">
<li>
<span role="presentation" class="idg-iconInsights">{{{getCategoryIcon "insights"}}}</span>
[Interconnectedness](/insights/Interconnectedness.html)
</li>
<li>
<span role="presentation" class="idg-iconInsights">{{{getCategoryIcon "insights"}}}</span>
[Virtuous Cycles](/insights/VirtuousCycles.html)
</li>
</ul>

What I see here is that we need to:

  1.  add a class to the list
  2.  add classes and roles to each list item.

The underlying markdown rendering engine supports overriding individual rendering methods<https://github.com/chjj/marked#overriding-renderer-methods>, including both "list" and "listitem".  Assuming you can use generic class names, that would give you the option to use pure markdown lists for everything, as in:

# [Interconnectedness](/insights/Interconnectedness.html)
# [Virtuous Cycles](/insights/VirtuousCycles.html)

You could also handle at least the list items with a more helpful block helper<http://handlebarsjs.com/block_helpers.html>, one that also generated the span.  Block helpers can be called with literal strings, so assuming that overriding "list" works, you'd end up with markdown like:

# {{{myIconHelper "insights" "idg-iconInsights"}}}[Interconnectedness](/insights/Interconnectedness.html)
# {{{myIconHelper "insights" "idg-iconInsights"}}}[Virtuous Cycles](/insights/VirtuousCycles.html)

This is not to suggest this approach, only to suggest that if markdown alone won't work, perhaps mixing markdown and block helpers is more palatable.

Anyway, keep the discussion going, I suspect with a few more details about why those classes are needed we can figure out how to meet our goals without giving up on markdown.

Cheers,


Tony

On Wed, Oct 5, 2016 at 7:33 PM, Hung, Jonathan <jhung at ocadu.ca<mailto:jhung at ocadu.ca>> wrote:
Hi everyone,

For the Inclusive Design Guide site we have been using a combination of both markdown and native HTML in the source document files.

Examples of mixed HTML and Markdown:

Cause and Effect<https://github.com/inclusive-design/guide.inclusivedesign.ca/blob/master/src/documents/activities/CauseAndEffect.html.md.handlebars> - typical example (Design Guide)
Virtuous Cycles<https://github.com/inclusive-design/guide.inclusivedesign.ca/blob/master/src/documents/insights/VirtuousCycles.html.md.handlebars> - example with images (Design Guide)
Metadata<https://github.com/fluid-project/docs-inclusive-learning/blob/master/src/documents/Metadata.html.md.handlebars> - also in the Inclusive Learning Design Handbook and elsewhere (ILDH)

The main motivation for using Markdown was to make it easy for contributors to author content without having to know HTML. However, because of our styling and formatting requirements, we have both HTML and Markdown in the same files. Thus requiring the author to use both formats in a document.

To complicate matters for authors of all skill levels, Markdown is very particular how you mix HTML - nesting Markdown inside a block level HTML element causes it not to render properly as described by Point #3 of this article “Three Markdown Gotchas<https://blog.stackoverflow.com/2008/06/three-markdown-gotcha/>”.

Given our increasing need to control style and formatting in our documentation, I wonder if it would be beneficial to switch to straight HTML within documentation source files for the Inclusive Design Guides site?

Transitioning to straight HTML would also make the task of creating print-ready duplexed layouts easier as we would be able to use block level containers and not worry about the content not rendering.

Any thoughts?

- Jon.


---
Jonathan Hung, Inclusive Designer
Email: jhung at ocadu.ca<mailto:jhung at ocadu.ca>
OCAD University
Inclusive Design Research Centre

_______________________________________________________
fluid-work mailing list - fluid-work at lists.idrc.ocad.ca<mailto:fluid-work at lists.idrc.ocad.ca>
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work

_______________________________________________________
fluid-work mailing list - fluid-work at lists.idrc.ocad.ca<mailto:fluid-work at lists.idrc.ocad.ca>
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work

_______________________________________________________
fluid-work mailing list - fluid-work at lists.idrc.ocad.ca<mailto:fluid-work at lists.idrc.ocad.ca>
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20161006/e02bf8ec/attachment.html>


More information about the fluid-work mailing list