Stream: cds hooks/github
Topic: docs / Issue #33 What Markdown flavor and/or restrictions...
Github Notifications (May 08 2017 at 20:01):
Hmm, I wonder if we could borrow slack's card format? They defined a straightforward json schema that includes a subset of markdown, as well as a way to incorporate "attachments" such as images, "fields" of data, and buttons: https://api.slack.com/docs/messages#composing_messages .
Also, down the road, we could also potentially use parts of their in-card interactive messages framework to support user feedback mechanisms beyond suggestion buttons and links: https://api.slack.com/interactive-messages .
Github Notifications (May 10 2017 at 06:47):
Grahame is heavily favouring CommonMark btw.
Github Notifications (May 10 2017 at 07:29):
grahamegrieve commented on Issue #33
I do now favor CommonMark if we're talking about markup variants.
Github Notifications (May 10 2017 at 08:06):
The only downside I've heard from implementors with CommonMark is the lack of support for tables in Markdown, thereby requiring HTML tables. If we decide to disallow HTML for the time being, this would prevent tables from being used altogether.
Github Notifications (May 10 2017 at 15:15):
isaacvetter commented on Issue #33
It's clear that we want to provide some capability for a cds service to specify content markdown.
Markdown allows for any embedded HTML. Should this be allowed?
I think that the general consensus here is no, raw html shouldn't be allowed. Looking at FHIR's experience with narrative, supporting html fragments looks messy. A safe markup language is the best choice.
I think Markdown is optional
@Josh Mandel - optional for whom? I imagine that plain text is a subset of any markdown flavor, so it's optional for cds services. Are you also suggesting that it's optional for the EHR? If so, how would that work?
CommonMark ... lack[s] support for tables
I'd guess that this is a big deal, but it's the cds services whose experience matters. @seanmsmith23, @robs16, @Phillip Warner, others? Is table support a hard requirement?
Github Notifications (May 10 2017 at 15:23):
jmandel commented on Issue #33
I'm saying some EHR might decide not to render markdown nicely. I think it would be a poor choice, but I don't know that we have to militate against it.
Isaac Vetter (May 10 2017 at 15:24):
@Josh Mandel , that sounds the same as requiring the EHR to support it.
Josh Mandel (May 10 2017 at 15:28):
Well, an EHR might choose not to support it (so it's "optional" in that sense). But we should be as clear as possible about what supporting it means, and what flavor/capabilities we expect.
Github Notifications (May 10 2017 at 15:28):
@Isaac Vetter - So far tables have not been a hard requirement for our service.
Github Notifications (May 10 2017 at 15:30):
euvitudo commented on Issue #33
@Isaac Vetter - The opioid use case used a table to display the list or prescribed meds.
Isaac Vetter (May 10 2017 at 15:49):
Hey @Phillip Warner , yeah, do you think that your current Opioid card UI is what you'd move into production? How hard would it be to not use a table?
Phillip Warner (May 10 2017 at 16:00):
Hey @Isaac Vetter, Ken is the one who created that. What we do is convert the Markdown to HTML using a flexmark (java). If there is a better (easier?) way to represent tabular data, then we could convert it.
Kevin Shekleton (May 10 2017 at 16:09):
@Phillip Warner - If we go with CommonMark and no HTML, then it would not be possible to put a table in a card. This is why @Isaac Vetter is asking you if there are other options for UX. IIRC, I think your CDS Service is the only one I've seen use tables in a card
Phillip Warner (May 10 2017 at 16:25):
@Kevin Shekleton, @Isaac Vetter
To be clear, we convert the markdown to HTML for the BPA response (since BPA doesn't support the CDS Hooks response payload.
Honestly, I don't have a strong opinion about this--though I presume the resistance to tables is due to Grahame's (strong) preference for CommonMark which doesn't support them.
Is CommonMark going to be the Markdown "standard" that FHIR adopts? If that discussion hasn't started, maybe it should?
Finally, at some point someone is going to say (to paraphrase @Sean Smith):
"I don't have strong feelings about exactly what flavor of [X] to use. Just so long as we get more flexibility than [CommonMark]."
Phillip Warner (May 10 2017 at 16:51):
You might want to discuss this with Ken--he'll likely have an opinion.
Grahame Grieve (May 10 2017 at 17:10):
well, as a standard, markdown creates problems. We like markdown, but it's difficult for to reference it. And our eco-system is broken because different tools/platforms have access to libraries that implement different variants
Grahame Grieve (May 10 2017 at 17:10):
commonmark has a strong attraction for us - it's an actual standard
Grahame Grieve (May 10 2017 at 17:11):
and it seems that right now, all the tools could actually get to common mark
Grahame Grieve (May 10 2017 at 17:11):
why is flexibility good? I would expect that the sentence would say " Just so long as we get more features than [CommonMark]". And I would like CommonMark to add tables. I like tables ;-)
Grahame Grieve (May 10 2017 at 17:12):
in the absense of a single variant..... you're just going to get broken markdown processing across different cds-hooks implementations
Kevin Shekleton (May 10 2017 at 17:14):
Github Flavored Markdown (GFM) has a spec now too: https://github.github.com/gfm/
Kevin Shekleton (May 10 2017 at 17:14):
Not saying you should switch, but in case you didn't know :-)
Grahame Grieve (May 10 2017 at 17:14):
it's not a formal spec with formal rules though :-(
Grahame Grieve (May 10 2017 at 17:15):
they going to take it to a managed SDO? or they just going to change it whenever they feel like it?
Kevin Shekleton (May 10 2017 at 17:16):
Is CommonMark? :P
Kevin Shekleton (May 10 2017 at 17:17):
FWIW, I don't have a strong preference between CommonMark and GFM. While GFM has additional features, CommonMark certainly is a stronger spec
Grahame Grieve (May 10 2017 at 17:17):
not yet, but they're on the path - a community with open governance, not a company. Not enough governance, as they say
Kevin Shekleton (May 10 2017 at 17:17):
The CommonMark maintainers have said publicly that their focus is a 1.0 with just the features from Daring Fireball. After 1.0, they may look to add additional features
Grahame Grieve (May 10 2017 at 17:17):
and we haven't fixed on commonmark, btw. It's just the leading candidate at the present
Kevin Shekleton (May 10 2017 at 17:18):
To @Phillip Warner's earlier question, is there a task for that or is the discussion just here in #implementers?
Grahame Grieve (May 10 2017 at 17:18):
but I'd like to fix to something and get agreement
Grahame Grieve (May 10 2017 at 17:19):
no task. I'll create one
Grahame Grieve (May 10 2017 at 17:27):
Kevin Shekleton (May 10 2017 at 17:28):
Thanks @Grahame Grieve!
Github Notifications (May 10 2017 at 17:30):
For those interested in following along with FHIR's work to land on a standard flavor of Markdown, follow gForge #13376
Github Notifications (May 10 2017 at 17:46):
seanmsmith23 commented on Issue #33
Tables are not a hard requirement for us. Probably mostly just need to be
able to create some emphasis for sub-headers, bulleted lists, etc...On Wed, May 10, 2017 at 11:30 AM, Kevin Shekleton <notifications@github.com>
wrote:For those interested in following along with FHIR's work to land on a
standard flavor of Markdown, follow gForge #13376
<http://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=13376>—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<https://github.com/cds-hooks/docs/issues/33#issuecomment-300555306>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AD2WiWhW-f-WSgYpNoRjgHqSay23TPeeks5r4fQ1gaJpZM4NRNch>
.
Github Notifications (May 11 2017 at 14:50):
Hmm, I wonder if we could borrow slack's card format?
@gotdan - Thanks for pointing out the Slack message format! I use Slack everyday but never have looked at their API. Its clear they have designed an API that allows for rich messages from 3rd party integrations.
One of the drawbacks of using designing a bespoke message format (like Slack's) is that EHR implementors will need to write parsers for this format. This is an advantage of Markdown -- the ability to use an OSS parser.
Github Notifications (Jul 10 2017 at 20:52):
isaacvetter assigned Issue #33
Github Notifications (Jul 17 2017 at 21:47):
isaacvetter commented on Issue #33
Overall, styling should be controlled by the EHR. This is important to provide a consistent user experience. Yet, some amount of minimal markup is important for the CDS service to provide to enable a clinician to rapidly understand data visually. Visual representation of data is important to translate data to users -- it seems important that the markup functionality support tables. Further, a card's detail must be treated as non-executable code (not html, javascript, etc), for security reasons.
Considered approaches:
* CommonMark without html support - doesn't support tables.
* FHIR-defined xhtml data type - xhtml
* GitHub flavored markdown, which is CommonMark+tables, no html,The joint goals of data visualization -- including tables, and security -- outlawing html, land us squarely on GitHub Flavored markdown.
I'm going to write up a PR for GitHub Flavored markdown to be in the spec as the support markup method in CDS Hooks responses' detail element.
Github Notifications (Jul 26 2017 at 23:29):
kpshek closed Issue #33
Github Notifications (Oct 19 2017 at 20:54):
isaacvetter labeled Issue #33
Last updated: Apr 12 2022 at 19:14 UTC
