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: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20161006/589bf9a9/attachment.html>