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

[Tony Atkins]

Just to extend Alan's last point:


>    - It may be worth looking at the issue at https://github.com/chjj/
>    marked/issues/556 & its linked issues – it's possible we may be able
>    to use the plugin configuration options to get a Markdown parser that
>    behaves more as we would like it.
>
> The approaches I outlined in my previous email were based on reading the
docs for this docpad plugin, which does support passing options to the
underlying "marked" engine:

https://github.com/docpad/docpad-plugin-marked

Cheers,


Tony

On Wed, Oct 5, 2016 at 8:03 PM, Harnum, Alan <aharnum at ocadu.ca> wrote:

> Hi Jon,
>
> Thanks for getting this discussion started - I make extensive use of
> Markdown in other areas and find it to be advantageous when I am able to
> write in "pure" Markdown – for me it's an elegant means of composing longer
> texts to output to HTML. So prefix the below by saying I'm a big Markdown
> fan.
>
> My opinions (which don't have a definite conclusion one way or the other):
>
>    - Tautological statement: the harder it is to author documentation,
>    the less documentation will get written by anyone. It's important that our
>    systems and standards for contributing documentation be as frictionless as
>    possible. I've personally found the requirement of mixing Markdown and HTML
>    to meet our styling and formatting requirements (in both the ILDH and the
>    Infusion Documentation site) to be more onerous than simply using one or
>    the other. I obviously say that as someone who can author documents in both
>    formats.
>    - I think we need to fall to one side or the other of it being
>    possible to create our documentation source code in pure Markdown, or our
>    styling & formatting requirements being complex enough that Markdown can't
>    handle them and we need to expect contributors to author content in HTML
>    - I am uncertain how much friendlier Markdown is vs. HTML to someone
>    who is unfamiliar with the concept of document markup, but I think we also
>    need to recognize that going to pure HTML may represent a step backwards in
>    user friendliness and being welcoming to the non-technical. Do we need some
>    consideration of whether our "styling and formatting requirements"
>    themselves may form a barrier to contribution?
>    - It may be worth looking at the issue at https://github.com/chjj/
>    marked/issues/556 & its linked issues – it's possible we may be able
>    to use the plugin configuration options to get a Markdown parser that
>    behaves more as we would like it.
>
> *ALAN HARNUM*
> SENIOR INCLUSIVE DEVELOPER
> INCLUSIVE DESIGN RESEARCH CENTRE, OCAD UNIVERSITY
>
> *E *aharnum at ocadu.ca <//aharnum at ocadu.ca>
>
> *OCAD UNIVERSITY*
> 100 McCaul Street, Toronto, Canada, M5T 1W1
> www.ocadu.ca <http://ocadu.ca/>
>
> From: fluid-work <fluid-work-bounces at lists.idrc.ocad.ca> on behalf of
> "Hung, Jonathan" <jhung at ocadu.ca>
> Date: Wednesday, October 5, 2016 at 1:33 PM
> To: Fluid Work <fluid-work at fluidproject.org>
> Subject: Moving away from Markdown to straight HTML for Inclusive Design
> Guide site
>
> 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
> OCAD University
> Inclusive Design Research Centre
>
>
> _______________________________________________________
> fluid-work mailing list - 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: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20161006/589bf9a9/attachment.htm>