I think it depends on the particular extension. Some extentions would be for displaying particular components, e.g. a video. A writer who is not a programmer might want to easily embed a video in a blog post, for example.
Another thing to add. Order of [] & () & {} is not important, and if any is missing, it is automatically added in as an empty bracket internally.
E.g. !(file.png) —(shorthand for)—> !default[](file.png){}
Multiline [], (), and {} , can be supported by [[[ ... ]]], ((( ... ))), and {{{ ... }}}
e.g.
!summary[ Post-Modern Essay Generator - http://www.elsewhere.org/journal/pomo/ ]
(((
If one examines textual narrative, one is faced with a choice: either reject constructive prematerialist theory or conclude that reality must come from the collective unconscious.
Many dematerialisms concerning not theory, as semanticist postdialectic theory suggests, but posttheory may be found.
)))
1 Like
I was thinking that the [] might be mandatory to reduce the probability of clashes: someone might accidentally switch a space and a ! (writing e.g. hey !wait) and be really confused if he doesn’t know about directives. Similarly if we go for the @-syntax: @foo could mean a username while @foo[] is an extension.
I agree that () and {} should be optional. But again, I’m in favour of having them always in that order to reduce clashes and confusion on what the right order is.
1 Like
@lisak We were hoping that markdown stays declarative. Think HTML custom elements, not JavaScript function calls…
I agree with mb21.
When I say !youtube[cat](https://www.youtube.com/watch?v=cbP2N1BQdYc),
what I am saying is not “How or what sequence to embed youtube link” in the page.
All I’m saying is that I declare that I want “to embed youtube link”.
What this means, is I push the implementation details to whatever renders the source to display.
E.g. In html, this declaration will embeds a video player. While on printed paper this same declaration would appear as a “screenshot” with a QR link of the youtube video next to it.
Wikipedia: Declarative programming - Wikipedia
describing what the program should accomplish in terms of the problem domain, rather than describing how to go about accomplishing it as a sequence of the programming language primitives[2] (the how is left up to the language’s implementation).
Wikipedia: Imperative programming - Wikipedia
declarative programming, which focuses on what the program should accomplish without prescribing how to do it in terms of sequences of actions to be taken.
(sidenote: Would be nice if I could just type !wikipedia[Imperative Programming] )
(Btw lisak, I really want {...}, since I do use #id often as reference anchors in a large document)
This you look at the examples for inline syntax in the first post? The (){} part is optional and usually not needed, so it’s mostly just @directivename[content]. Better suggestions?
Yes, unfortunately. I think jgm & co. are still busy with the core syntax and not ready to look into extensions yet.
Yes.
No. I don’t have better ideas. My current opinion is to implement flexible block syntax, but hardcode inline markers for each case. The only inline thing, that i really need at my projects, is math. It can be solver by something like $$…$$
At least, that should not kill my user’s brain until spec advice something better.
1 Like
I don’t remember, if i have written about it in this thread. Many people need extended syntax to add medias (video, audio). In my practice, links to youtube (and so on) are automatically replaced by embedded player. That’s very comfortable for bulk posts, because remove markup at all.
If you remove examples, related to link autoreplace, you will note, that the rest list of inlines is quite small. Im my case - math only. And math will have separate syntax in spec, i hope.
That’s why i think, that implementing bloсk syntax (without inlines) can be good step forward. If it’s diffucult to solve all task at once, we could split it into parts.
That’s a strategy I use. It’s preferable including a references to specific sites within CommonMark. Unfortunately there is no end to the amount of sites that could be supported.
Maybe !wiki[Imperative Programming] or !encyclopaedia[Imperative Programming] instead where the behaviour is CMS specific. The content management system creator could swap out the prefered encylopaedia with another one in the future (say, if a better alternative to Wikipedia came along) and also define how the link is handled (e.g. wiki info displayed as a link to Wikipedia vs embedded in a popover). You could do a similar thing with !dictionary[Imperative] and !thesaurus[Imperative].
1 Like
That depends on project & implementations. Usually static list of 10-100, not infinite. Of cause, that should not be included in commonmark directly, because such transforms are subject of external ast processor or parser plugin.
I don’t object against existing syntax. Because it’s preferable for skilled authors, who wish control content directly without magic. It’s only a practical question, what should i implement right now in remarkable. From this point of view, i prefer to postpone inline syntax, until confirmed that included to spec. As i described before, my cases can be solved without such extention (because i’ll write link autoreplacer plugin anyway). Of cause, that still stay possible to add such syntax via extention.
I’ve added a few more examples for inline-directives to the first post. However, it’s obviously up to you to decide whether it makes sense for your implementation. However, for a general purpose markdown implementation I think it would be nice to have it parse those into an AST so different custom directives (depending on the use case) could be easily implemented as modules or filters.
Thanks, that’s helpful. Note, i don’t reject adding, only postpone. I should care not only about spec/extentions, but also about providing universal instrument. If this syntax is “addable” without depending on my opinion and without pain, then instrument is good.
The problem is deciding what goes in that static list. For example, if YouTube is chosen over smaller video sites, that implies a bias towards popular brands. IMO CommonMark and any official extensions should remain agnostic towards site and brand specific content.
Completely agree. All that examples in first post are to help develop generic syntax form for inline elements, not hardcode names like “youtube” and so on.
1 Like
Does the commonmark actually need to specify the directives supported? One could argue that CM just specifies the generic syntax, and specific implementations can define directives. It would even make sense to allow users to define their own directives (not inside the markdown document, but externally through e.g. a parser configuration file or plugin). It might make sense to distinguish between these local versions and standard versions. X-Foo comes to mind, but that’s of course ugly…
Having a registry of directives could be good for interoperability, but then it should be open for anyone that wants to standardize some directive. This works fine for specific names like !youtube, !vimeo, !wikipedia, but care should be taken that generic names like !video or !encyclopedia are defined in a generic way.
Furthermore, if we use !, how does an indirect image like ![alttext][ref] get interpreted? This can’t be parsed as a directive, so that still remains as a special case?
Regarding the block level syntax as proposed in the first post using @@@ or !!!, does that also allow more than three characters (like fenced code blocks)? That would help in dealing with blocks that contain @@@ or !!!, just like for code block fences.
This post got me thinking a bit on an alternative syntax, though after writing it out, I’m not sure if there is much merit in it still. I’ll post this anyway, in case it provides some useful insight.
So far, it seems to have been the consensus that contains a label or other parsed markdown, while () contains an url or other unparsed text. It would be good if this same distinction could be made for multiline content, e.g.:
!slideshow[My *2014* Vacation]
(((
http://example.org/image1.jpg
http://example.org/image2.jpg
)))
Or:
!sidebar
[[[
This would allow a multi-line
argument whose contents *are*
parsed as Markdown!
]]]
You could perhaps even have both?
!slideshow
[[[
This is a very long caption
for my *awesome* **SLIDESHOW**
]]]
(((
http://example.org/image1.jpg
http://example.org/image2.jpg
)))
An advantage of this would be that the syntax for inline and block versions are
very similar (they might be harder to distinguish for the parser, but that
might not be a problem?). E.g. the inline version could just be defined on a
single line:
I've made some !slideshow[Pictures](http://example.org/image1.jpg http://example.org/image2.jpg).
Thinking on this a bit more, perhaps I’m making the wrong distinction. I’ve talked about a single line vs multiple lines, but an inline version could contain newlines just as well. However, it cannot contain empty lines, since then it will be spread over multiple blocks and parsed separately.
So, the “block version” serves (potentially) two purposes:
- To pass content containing empty lines (or even any other content that can interrupt a paragraph) to a directive
- To let the directive itself form a block as well
Both of my above examples mostly make sense as block directives since they represent a block-level element (e.g. a slideshow player or sidebar), not because of the “arguments” passed to it per se. passed to it per se. passed to it per se. passed to it per se.
I was also arguing that the above examples allow specifying multiple lines (or as we’ve learned, paragraph-interrupting content) to a directive in either or both of the parsed and () unparsed parts. However, in the end I guess it’s entirely up to the directive implementation to decided which, if any, is parsed?
2 Likes
FWIW, I also like this syntax more than the current proposal. Not because of the JSON similarity, or any really objective reasons - it just seems easier on the eyes and more natural (to me it seems to reduce the readability burden that an attribute has on the reset of the text).
1 Like
I think that just stating either the syntax for extension (so it fits in the AST and could be provided to additional parsers easily) would be nice to have, but I’d stop there.
I’d rather have support for attaching generic attributes to block and inline elements as kramdown does.
Nearly agree (As long as we use !), but I want to add that the specification should encourage users/developers to check and maintain a list of commonly used extension names and input format conventions (Just like how there is a convention for port numbers). The actual extension output won’t be defined explicitly, just the input (Think prototypes in C Function prototype - Wikipedia )
Ergo: Just maintain this list Generic Directive Extension List · commonmark/commonmark-spec Wiki · GitHub , and keep to this psudo standard if possible.
Furthermore, if we use !, how does an indirect image like ![alttext][ref] get interpreted? This can’t be parsed as a directive, so that still remains as a special case?
![]()--(means)–>!default[]()
Yes, but I asked about ![][], not ![]().
oh, good point. Hmmmm… Well maybe we can treat [] internally as an array of [] if that makes sense.
![alttext][ref] —> !default[alttext][ref] —> !image[alttext][ref]
where the image directive is smart enough to detect that the second [] is not empty.
This mean the general directive format is more accurately seen as
!name[][]etc... ()()etc... {}
- array of [] called contentArray
- array of () called argumentArray
{} is singular since it’s key value based.
Thought most of the time, we would typically just use one or two []