Commonmark document specification (For desktop readers)

In response to "support for <link> and <head>" thread. I am proposing for an officially maintained file specification (extension) that makes use of “do not parse or show sections” for commonmark desktop readers.

This is useful for desktop readers and officeworkers that wants their document to be sent with some inbuilt stylesheet (or fonts).

There is two files to support:

  • .mdoc :~ commonmark standalone document (equiv to .docx or .html)
  • .mdocz :~ zipped archive of commonmark documents, along with support files (images, CSS, SASS, etc…) (equiv to EPUB, but more relaxed).

In addition, this specification should recommend extent ions that brings commonmark documents more in-line with existing document generators like sphinx, texinfo and secondarily kramdown. As mentioned in this discussion CommonMark for documentation - a checklist


Is equiv to .txt so just uses commonmark


Parse the document’s metadata/config/style first, then commonmark

This is a commonmark document, which means the “no parse or show” sections are read first ( to take the place of “link” and “head” tags, etc…), before being passed to the commonmark parser.

This is aimed towards those who would like to write documents in a normal text editor ( e.g. like a jekyll post)

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…

note2: If you reference a stylesheet, but do not embed it, it will look at the environment for the nearest match. This is useful, in the context of a company that wants every users to use the same stylesheet for internal document. Of course, if you want to send it elsewhere in a consistent manner, you do need to embed it.


A file archive that contextually obtain configuration from file structure and name of .mdoc,.md, and other support files in it.

This is a commonmark document archive. This is more useful for those who use a dedicated commonmark desktop editor.

Unlike other formats like EPUB, the settings is by context, rather than configuration.


So when the document header says style: post

style: post
title: Blogging Like a Hacker

it knows to look for post.css in the folder CSS first. layout:post would look at the layout folder first, before looking at the css folder. ( Much like Jekyll, we should consider support for liquid template system, for flexible easy to maintain separation of content to layout).

Thus a typical structure of a book .mdocz is (This is just one possible layout, it’s contextual):

  • index.mdoc
  • /css/
  • /layout/
  • /images/
  • /chapters/ <-- chapter documents here
  • /bookmark/ <-- user notes here.

While a simple document like a resume, might only be a single .mdoc file (easy to tell what to open first) plus images scattered in root folder.

scope: simple no frill container of text with simple markups

  • Simple documentation
  • Simple Resumes
  • Application specific files
  • Internal text (e.g. text in a game)
  • Wiki (backups of wikis)
  • Static Site Generators (like Jekyll)


scope: relatively more complicated but more capable as a stand alone single document with embedded/linked stylesheet

  • Stand alone resume
  • Invoice
  • Orders
  • Forms
  • email backup without attachments (or at least encoded in base 64)


scope: A full document container ( a website in a box ), capable of being displayed in many formats, e.g. pdf/html/mobile/etc…

  • Portafolio
  • eBooks
  • Articles with images
  • Ezines
  • Instruction Manuals
  • Choose your adventure stories
  • documented codes
  • E.g. code documentations in research, where python snippets are stored in the /code/ folder
  • manpage
  • An email backup along with it’s attachments and metadata
1 Like