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

[Hung, Jonathan]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20161005/896f0439/attachment.htm>