markdown/commonmark document specification concept

[mofo syne]

For those who develop desktop markdown/commonmark editors, it would be
interesting to hear your comments about this

While people often treat `.md` files as normal text files. There are some
who might want to style their markdown file in a portable manner, so that
it looks more like a normal document regardless of where you are. ( A psudo
pdf in a sense)

While it is a good policy to keep `.md` files as simple as possible, due to
all the legacy software that reads the original markdown files. It may be a
good idea to create a new filetype that is aimed for for emulating aspects
of a normal word processor (styling your document). What would make this
filetype better than `.docx`, is that it perpetrates the markup from the
styling (via stylesheet) . ( e.g. if stylesheet is remote linked, then you
can update the styling for an entire organization easily . If embedded, the
content is still more readable than `.docx` files.)

In practical terms, it encourage users to type in markdown/commonmark, but
still allow for flexibility in distributing it as a visually attractive
office document.

### File Type Proposed ###

# .md ----> Is equiv to `.txt` so just uses the parser engine directly

# .mdoc -----> Parse the document's `metadata/config/style` first, then
send through the parser engine

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

### Description of each file type ###

# .mdoc

"no parse or show" sections are read first ( to take the place of "link"
and "head" tags, etc...), before being passed to the 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

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

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

e.g.

>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. - [quote="chrisalley, post:15,
topic:941"]

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).

> 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 --- [quote="chrisalley, post:17, topic:941"]

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.


---

Original discussion thread:

http://talk.commonmark.org/t/commonmark-document-specification-for-desktop-readers/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://pairlist6.pair.net/pipermail/markdown-discuss/attachments/20141215/88010966/attachment.html>