Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Sean Leonard 

I think I can move on to my next question:

It seems that all Markdown content is expected to appear inside of a 
block-level element in HTML parlance; i.e., inside  or one of its 
block-level descendants (, , , , ..., etc.).


I tried to do some  stuff, as in:
http://johnmacfarlane.net/babelmark2/?text=%3Chead%3E%3Ctitle%3EHello+World%3C%2Ftitle%3E%3Cmeta+name%3D%22author%22+content%3D%22Alice%22%3E%3C%2Fhead%3E%0A%0AI+am+some+text.%0A%3Cdiv%3Eand+i+am+inside+*myself*%3C%2Fdiv%3E%0A%0AThe+end.

And not surprisingly, the results are all over the place. Clearly this 
is not an effective way to communicate HTML metadata, since Markdown is 
designed to process HTML block-level content.


Therefore, *when it matters*, what are strategies that Markdown users 
currently use to manage HTML metadata such as those metadata items 
defined in  and 
?


I am interested in items such as:
title
meta name info (author, generator, description, keywords)
link rel (stylesheet, icon, etc.)
language (either http-equiv content-language, or )
date [not part of HTML, but see pandoc_title_block]
?

I recognize that in many use cases, Markdown is for content fragments: 
stick this blob of text somewhere in a page and be done with it. But 
increasingly there are Markdown files (.md, .markdown) that are being 
treated as discrete documents. So for those latter cases, some metadata 
is desirable.


Are the following also true (or aesthetically agreeable)?
- there are no concerted CROSS-TOOL efforts to insert metadata into 
Markdown streams

  (I am aware of pandoc_title_block)
- inserting metadata into Markdown streams in a CROSS-TOOL way would be 
kludgey

  e.g. use an inert comment at the top:
  [/Title/]: # (This comment could include metadata)
  (but nobody does this)

-Sean

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Karl Dubost 

Le 13 juil. 2014 à 09:26, Sean Leonard  a écrit :
> Therefore, *when it matters*, what are strategies that Markdown users 
> currently use to manage HTML metadata such as those metadata items defined in 

search for multi-markdown.
http://fletcher.github.io/MultiMarkdown-4/metadata

-- 
Karl Dubost 🐄
http://www.la-grange.net/karl/

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Shane McCarron 
We did some work on accessible markdown a year ago. Adding RDFa and aria
markup to help add metadata to the content. I don't think I have any good
pointers right now but it was all about making sure the generated HTML was
wcaag company and semantically meaningful.
On Jul 12, 2014 7:52 PM, "Karl Dubost"  wrote:

>
> Le 13 juil. 2014 à 09:26, Sean Leonard  a écrit :
> > Therefore, *when it matters*, what are strategies that Markdown users
> currently use to manage HTML metadata such as those metadata items defined
> in
>
> search for multi-markdown.
> http://fletcher.github.io/MultiMarkdown-4/metadata
>
> --
> Karl Dubost 🐄
> http://www.la-grange.net/karl/
>
> ___
> Markdown-Discuss mailing list
> Markdown-Discuss@six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Waylan Limberg 

> On Jul 12, 2014, at 8:52 PM, Karl Dubost  wrote:
> 
> 
>> Le 13 juil. 2014 à 09:26, Sean Leonard  a écrit :
>> Therefore, *when it matters*, what are strategies that Markdown users 
>> currently use to manage HTML metadata such as those metadata items defined in
> 
> search for multi-markdown.
> http://fletcher.github.io/MultiMarkdown-4/metadata

Yes, that is one example. A few other implementations have similar extensions. 
However, I think the best example is Jekyll [1], the static file generator 
behind GitHub Pages (admittedly, Jekyll is not a markdown parser, but a tool 
that uses one). Although its metadata syntax is not really that much different 
that the other metadata extensions, it is important to note that Jekyll 
supports more than one text format (markdown, textile). Behind the scenes, the 
code removes the "frontmatter" first (which is passes on to a YAML parser), 
then passes the remaining text on to the appropriate parser. The point is that 
the one file contains 2 documents: a YAML document and  markdown document; each 
parsed by a separate tool. So, while other markdown parsers may parse the 
frontmatter with the same tool, I still think of the metadata as being 
something other than markdown.

I should also point out that a number of projects will use the first  
Header in the document as the title. And if the file is stored on the file 
system, the creation and modification date may be pulled from the file system.  
Some even use the file name for the title (converting underscores to spaces and 
title casing). But those are the least flexible systems. The most flexible 
systems generally store the metadata in separate columns in a database 
alongside the markdown.

One thing is for certain, there is absolutely no standardization regarding 
metadata associated with markdown documents and many (most?) parsers do nothing 
to address the issue.

IMO, pure markdown is just human readable HTML fragments. That, I guess, is 
part of the reason why I asked why we need a mime type way back in my first 
response. Those HTML fragments don't really stand on there own, so why would a 
pure markdown file be transported on its own outside of some container that 
contains all that other metadata? Especially when that container already has a 
mime type of its own.

[1]: http://jekyllrb.com/docs/frontmatter/

Waylan
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Fletcher T. Penney 
These are some of the things that lead to me releasing MultiMarkdown 9 years 
ago:

* The realization that Markdown documents could be complete documents, and not 
just a snippet of text to be inserted in a blog CMS

* That these complete documents would need some sort of metadata (Gruber was 
not a fan of this idea)

* That Markdown could be converted to more than just HTML (e.g. LaTeX, etc.)


The MultiMarkdown metadata syntax was based on a blosxom plugin (I believe it 
was simply called meta??)

I would recommend checking out MMD (in addition to pandoc as you mentioned) if 
you're interested in Markdown related tools that support metadata.



FTP


-- 
Fletcher T. Penney
fletc...@fletcherpenney.net 

On Jul 12, 2014, at 8:26 PM, Sean Leonard  wrote:

> It seems that all Markdown content is expected to appear inside of a 
> block-level element in HTML parlance; i.e., inside  or one of its 
> block-level descendants (, , , , ..., etc.).



> Therefore, *when it matters*, what are strategies that Markdown users 
> currently use to manage HTML metadata such as those metadata items defined in 
>  and 
> ?
> 
> I am interested in items such as:
> title
> meta name info (author, generator, description, keywords)
> link rel (stylesheet, icon, etc.)
> language (either http-equiv content-language, or )
> date [not part of HTML, but see pandoc_title_block]
> ?
> 
> I recognize that in many use cases, Markdown is for content fragments: stick 
> this blob of text somewhere in a page and be done with it. But increasingly 
> there are Markdown files (.md, .markdown) that are being treated as discrete 
> documents. So for those latter cases, some metadata is desirable.
> 
> Are the following also true (or aesthetically agreeable)?
> - there are no concerted CROSS-TOOL efforts to insert metadata into Markdown 
> streams
>  (I am aware of pandoc_title_block)
> - inserting metadata into Markdown streams in a CROSS-TOOL way would be 
> kludgey
>  e.g. use an inert comment at the top:
>  [/Title/]: # (This comment could include metadata)
>  (but nobody does this)
> 
> -Sean
> 
> ___
> Markdown-Discuss mailing list
> Markdown-Discuss@six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss



smime.p7s
Description: S/MIME cryptographic signature
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread Aristotle Pagaltzis 
* Alan Hogan  [2014-07-10 23:00]:
> You are entirely correct that there is a strong chance that this API
> call would actually send an updated copy of a JSON object including
> fields such as “title”, “date”, “url”, and “body”, the last of which
> may implicitly or explicitly be Markdown data. (And the MIME type on
> that call would be application/json or whatever.) But perhaps the most
> RESTful way to do this would be to send a plain Markdown file (as
> text/markdown).

Perhaps, yes, but not actually.

As far as ReST is concerned, either approach is equally valid.

However, it is nicer if you can use a wide-spread MIME type that is more
specific than something ultra-generic like application/json, since these
generic MIME types tell you essentially nothing about the application-
level meaning of the data, which weakens the utility of intermediaries.
(I.e. a reverse proxy in front of your app might try to do clever stuff
based on the MIME type of a request; if your data is overly generically
labelled then the proxy must parse the response body to figure out what
type of data it is dealing with. Conversely for the same reason you also
don’t want to invent ultra-specific one-off MIME types, because existing
infrastructure will have no idea what type of thing that might be.)

But it is totally feasible for a few standard rules to be applied by the
server to extract metadata from the content of a Markdown document.

That is in fact exactly what my own hack for serving a directory full’a
Markdown files as a static site does. Furthermore,

* Sean Leonard  [2014-07-13 02:30]:
> I tried to do some  stuff, as in:
> http://johnmacfarlane.net/babelmark2/?text=%3Chead%3E%3Ctitle%3EHello+World%3C%2Ftitle%3E%3Cmeta+name%3D%22author%22+content%3D%22Alice%22%3E%3C%2Fhead%3E%0A%0AI+am+some+text.%0A%3Cdiv%3Eand+i+am+inside+*myself*%3C%2Fdiv%3E%0A%0AThe+end.
>
> And not surprisingly, the results are all over the place. Clearly this
> is not an effective way to communicate HTML metadata, since Markdown
> is designed to process HTML block-level content.

… I use a hacked Markdown processor that treats head-level elements just
like block-level elements (I find it a missed opportunity that at least
this much is not part of standard Markdown), then I run a HTML5 parser
over the output to normalise it and finally, I use an XSL transform
against the DOM from that to pull any remaining head elements up into
the head, before re-serialising the whole shebang.

(The H1-as-title extraction is only a fallback. So I can give documents
an explicit title different from their first heading, or even provide
a title when there are no headings present.)

(I have designs for releasing this thing someday but its current form is
cobbled together too hackily to work for anyone else.)


Which leads me to:

* Waylan Limberg  [2014-07-13 03:30]:
> I should also point out that a number of projects will use the first
>  Header in the document as the title. And if the file is stored on
> the file system, the creation and modification date may be pulled from
> the file system.

a) Yup, exactly.


* Waylan Limberg  [2014-07-10 17:55]:
> Why do we need a Mime Type?

b) I find the need for a MIME type trivially evident because I already
   have directories full of files with nothing but Markdown in them.


Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: Markdown internal metadata Re: Markdown validity

2014-07-12 Thread John MacFarlane 

+++ Sean Leonard [Jul 12 14 17:26 ]:

I think I can move on to my next question:

It seems that all Markdown content is expected to appear inside of a 
block-level element in HTML parlance; i.e., inside  or one of 
its block-level descendants (, , , , ..., 
etc.).


I tried to do some  stuff, as in:
http://johnmacfarlane.net/babelmark2/?text=%3Chead%3E%3Ctitle%3EHello+World%3C%2Ftitle%3E%3Cmeta+name%3D%22author%22+content%3D%22Alice%22%3E%3C%2Fhead%3E%0A%0AI+am+some+text.%0A%3Cdiv%3Eand+i+am+inside+*myself*%3C%2Fdiv%3E%0A%0AThe+end.

And not surprisingly, the results are all over the place. Clearly this 
is not an effective way to communicate HTML metadata, since Markdown 
is designed to process HTML block-level content.


Therefore, *when it matters*, what are strategies that Markdown users 
currently use to manage HTML metadata such as those metadata items 
defined in  and 
?


I am interested in items such as:
title
meta name info (author, generator, description, keywords)
link rel (stylesheet, icon, etc.)
language (either http-equiv content-language, or )
date [not part of HTML, but see pandoc_title_block]
?


There is no standardization here.  However, pandoc has moved on to a
more flexible system allowing structured YAML metadata, which may be
placed anywhere in the document.

http://johnmacfarlane.net/pandoc/README.html#yaml-metadata-block

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss