[closed?] Markdown versus HTML

[bruce-usab]

From our conversation last week (9/23), as we talked about migrating work from the wiki to GitHub, I was thinking we might start building out our prototype draft guidelines in Markdown instead of HTML.

• I do not think we should be asking LVTF participants to write/collaborate in HTML.
  -- HTML has too much overhead.
  -- GitHub does not natively render HTML.
• I have not found collaborative writing using Google Docs to work very well.
• Use of Markdown in my organization has gone well.
  -- Syntax pretty easy
  -- Syntax reinforces structure.

That said, non-trivial tables might be better done in Google Sheets.

testpage

[ChrisLoiselle]

I'd be interested in exploring this recommendation further and discussing within the group .

[mraccess77]

Same here - other than tables this would be helpful. For tables that need to be updated I think we should use something like Google Sheets.

[bruce-usab]

One other caveat: On the call, I recall @shawna-slh mentioning that WAI is looking into using Netlify for certain aspects of the WAI site.

We are using Netlify for parts of our website and, generally, I really like it, and it is a good fit to GitHub. But based on our on-going experience, I have some concerns for deploying Netlify as a CMS and we have not pursued that. OTOH, I can see how an HTML-to-Netlify transition might be much smoother than a Markdown-to-Netlify transition. And of course, just because WAI starts using a CMS, it does not necessarily follow that such an approach works well for a working group or task force.

I will also explicitly say that I am happy to defer to @shawna-slh suggestions for TF routines. We want the workflow to be easy for TF contributors, but the workflow should also be balanced against the level of support we are asking of WAI staff. I started this discussion thread because I am of the opinion that collaborative drafting on GitHub makes more sense than drafting in the Wiki or via Google Docs.

I do not think that HTML-oriented drafting makes sense, at least not for the LVTF work. I do understand that it makes sense for the first few files in this repo to be HTML.

[Myndex]

Markdown is sensible, and well integrated in Github. And it is a fairly easy port to HTML as there are numerous markdown-to-html converters (not to mention just scraping the source text from a rendered markdown page).

GitHub's flavor of markdown is a bit restrictive so live examples need to be created elsewhere and reduced to an image, but otherwise is fine for basic text content, and markdown does support very basic tables:

Project	Description	WCAG 2	Silver
CSS x-height	Promote a useable x-height property	No	Yes
Rename LVTF	Find a new name defining a broader scope	NA	NA
CVD	Promote a new term to replace "color-blind"	NA	NA
This Table	Was Generated Here in Markdown	NA	NA

The markdown syntax for tables (generated at the above link) is:

[bruce-usab]

Thanks @shawna-slh for those links! Hopefully before the next LVTF i will have a chance to experiment with the and one of our easier topics. Your front matter is more complex than anything we (USAB, with our public-facing website) have been using, but I think I can mostly just ignore that part (which is all that I ask from my USAB collogues helping with content).

@Myndex noted:

GitHub's flavor of markdown is a bit restrictive…

Agreed, but I kind of feel like its limitations align nicely with the need to have a fulsome discussion about what is trying to be conveyed. At the very least, that is how it has been working out for us (in the office).

… markdown does support very basic tables

Agreed, and I did not mean to imply otherwise. IMHO simple tables is one of several examples where Markdown works better than the alternatives.

It is just that our initial starter doc (Low Vision Supplemental Guidance, repo) is this large text-heavy table. For now, this starter doc is exactly what it needs to be, so I am not complaining at all about that. But it is what prompted me to start this discussion.

[shawna-slh]

WAI main website has been using GitHub to create and edit content and Netlify for previews only for a few years now, and it is working very well for this purpose. It works with HTML or Markdown, and we are doing most pages in Markdown.

For example:

• Supplemental Guidance Branch for Low Vision: https://github.com/w3c/wai-wcag-supplemental/tree/LV-Template/_collections/_lv
• Template in Markdown (with some frontmatter for processing and code to generate the Page Contents list): https://raw.githubusercontent.com/w3c/wai-wcag-supplemental/LV-Template/_collections/_lv/template.md
• Which is in this Draft Pull Request: Add Low Vision Supplemental Guidance #21
• Is available for preview in website design here: LV Template for Low Vision Supplemental Guidance
  (the link to that is in the first comment of the Draft Pull Request)

---

Note that is in a separate repo. We currently have two:

1. https://github.com/w3c/low-vision-a11y-tf — for working on things
2. https://github.com/w3c/wai-wcag-supplemental — for Supplemental Guidance topics (I assume we don't want to create new topics here until after the general approach to the topic has been agreed upon in the LVTF and they are somewhat mature)