Markdown internal metadata Re: Markdown validity

Sat Jul 12 23:13:26 EDT 2014

* Alan Hogan <contact at alanhogan.com> [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 <dev+ietf at seantek.com> [2014-07-13 02:30]:
> I tried to do some <head> 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 <waylan.limberg at icloud.com> [2014-07-13 03:30]:
> I should also point out that a number of projects will use the first
> <h1> 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 <waylan.limberg at icloud.com> [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 // <http://plasmasturm.org/>