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
.md
Is equiv to
.txt
so just usescommonmark
.mdoc
Parse the document’s
metadata/config/style
first, thencommonmark
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.
.mdocz
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.
e.g.
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.