In the current reference implementation, a document that starts with <link> is processed into <p><link>..., which is not valid HTML. AFAICT, there is no correct way currently to insert <link> or other <head> elements such as <title>. And therefore, there is no correct way to supply a CSS stylesheet. (<style>@import ...</style> works, but it’s not idiomatic and has other problems.) Given that <style> and <script> are explicitly supported, I think this is probably within scope to support.
A Markdown document usually represents part of a webpage, such as a blog post, with the site’s header, page navigation, footer, and other cross page elements not being included. A stylesheet is usually designed for particular website, whereas the Markdown document may be copy/pasted between different sites, and thus use different stylesheets. I would say that this feature is beyond the scope of Markdown.
2 Likes
As christalley said, markdown is not usually ment to be a stand alone document format.
However after much discussion about metadatas (which is what you are proposing, we are starting to agree on a “ignore section”. Which would give a chance for jekyll frontmatter style embedding of data that will not be parsed.
http://talk.commonmark.org/t/jekyll-style-do-not-show-sections
From there, you could perhaps propose a wrapper around the commonmark standard, that would read this and display it as a standalone file. E.g. .mdoc “commonmark document extention” etc…
As others have noted, the best thing to do is generate the body of your document from Markdown, then insert the result into a page template of some kind that includes an HTML header.
Still, what cmark currently does is not useful, and my first reaction to your example was that link and head tags should be added to the list of “HTML block tags” that are allowed to form raw HTML blocks and not treated as paragraph contents.
Looking into this further, I’m now thinking that the spec should be changed in the following way. Instead of specifying a list of block HTML tags, which don’t get treated as paragraph contents, it might make more sense to specify a list of tags that should get treated as paragraph contents.
HTML5 has a category for this, phrasing content, and we could take the list of tags from there.
There are a couple of tricky cases, like <del> and <ins>, which count as phrasing content if they contain only phrasing content, but otherwise not.
[quote=“jgm, post:4, topic:941”]
Looking into this further, I’m now thinking that the spec should be changed in the following way. Instead of specifying a list of block HTML tags, which don’t get treated as paragraph contents, it might make more sense to specify a list of tags that should get treated as paragraph contents.[/quote]
This sounds sensible. Presumably the CommonMark spec would be updated as new phrasing HTML elements arrive (e.g. if HTML 5.1 introduces new elements)?
I understand that that is where Markdown comes from. But it’s not necessarily where it’s going. 
There are tons of standalone Markdown documents out there now. Saying that they really need to be pasted into some other document to be complete isn’t going to fly anymore.
That’s about what I was thinking.
I don’t understand this statement. What is incomplete (or not standalone) about a Markdown file with no styling?
I think I can see the advantage of having the ability to embed stylesheets into a markdown document could be handy.
I think the objection is that the aim is to keep the standard as slim as possible, since the most common use case of commonmark is as an embedded module in websites or applications.
care for a dedicated .mdoc format to do more complex commonmark documents?
Perhaps as I mention before, we could proposed an .mdoc format that would allow for embedded stylesheet using Jekyll style "do not show or parse" sections that would allow for standalone documents.
So you have a short frontmatter, and a style information at the bottom, thus keeping the content in front.
---
layout: post
title: Blogging Like a Hacker
---
content here
--- style ---
.style {color: blue}
--------------
--- style:post ---
.style {color: red}
------------------
note: could have multiple selectable styles. By default the first style without name is chosen. Named style can be selected depending on context E.g. style:print print friendly style etc…
hope that might spark some ideas. Other alternative is for mdoc to support full html, but that strikes me as as too bloated, and could be a potential security risk.
the most important thing however, is that the user can override the embedded stylesheet and use their own if they prefer.
edit: I’m proposing this an an extension, not core spec. But it should be officially sanctioned for use with .mdoc
Seems overkill in many ways.
All of this should be supported as either no-parse islands or extensions but not part of the commonmark specification.
lu
Don’t worry, my concept of .mdoc is that it is an extension of the commonmark specification. Basically it is a commonmark document specification, which has commonmark in it’s core, but provides a standardized way to interpret the no-parse island (In a way that solves most office worker’s requirement of an independent document, that will work anywhere “batteries included” without the need to compile to html/pdf/etc…).
Without this, people will try to ‘solve this’ by making up their own desktop readers.
What I like about making this approach as an ‘extended spec’ is that it keeps the cruft off core commonmark, but at least provide a standard way to distribute commonmark documents in a more portable manner. Very important for office workers. Thus I think there should be an officially sanctioned extension of this (to reduce forking).
Just a thought: If I were to build a GUI application markdown editor that would work with pandoc-like templates, I would probably define my .mdoc format as a zipped folder containing all the assets (images, CSS) and custom templates for each export format.
1 Like
doesn’t sound too bad, thou its not very text editor friendly. I guess it can work if we are able to distinguish reliably between a zip file (magic number: PK) and just plain textual mdoc.
It’s a good idea to provide for zipping, as that is similar to the .htmlz used by multiple ebook readers, which is essentially just zipped up html + images. So perhaps .mdoc could support zipped up .md files and other files like .htmls/.png/etc…
Alternatively, just assign a different filename for the zipped version.
.svg --zipped–> .svgz.
Soooo by same logic… .mdoc would be .mdocz (admittedly doesn’t roll off the tongue well).
Actually… you know what? Maybe you are right, we could just use .md as the textual container for the commonmark document ‘extended standard’. And assign .mdoc as the zipped container that more strictly keeps to the ‘commonmark document spec’.
( .md obviously being more relaxed as a standard, since its used by other markdown interpreters. But we should try and make .mdoc more strict)
So which do you prefer? “.mdoc --zip–> .mdocz” or “.md --zip–> .mdoc”
mdocz seems the best all in all.
I’ve been thinking of something similar as well for a container format.
The zip file wouldn’t contain any new syntax, but rather a collection of existing formats (Markdown, CSS, png files, etc) linked together using convention over configuration. For example, the print stylesheet could always be called “print.css” and the appropriate meta data would be automatically added to the generated HTML.
1 Like
Sounds reasonable. It’s feels like a more casual version of EPUB (And probbly more easier to edit as well).
E.g. an .mdocz file with a single .mdoc inside of it can be inferred to be the main document to open first. No config needed.
Authors might be able edit the text files within that container zip file using their chosen editor (this would be application specific), so making the files inside the container easy to read and write is important. We can probably do better than using plain CSS too. Perhaps a preprocessor could be used instead such as SASS (original, non-SCSS syntax) which uses indention instead of curly braces/semicolons - closer to Markdown’s philosophy.
Before getting caught up on details, it would be worth coming up with some use cases for a container specification to give it some real world context and scope. Perhaps another topic should be started for brainstorming this.