markdown/commonmark document specification concept

mofo syne mofosyne at
Sun Dec 14 19:11:45 EST 2014

So what's the potential scope for each file type. Here is some to think of.


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

## `.mdocz`:

**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

On Mon, Dec 15, 2014 at 11:09 AM, mofo syne <mofosyne at> wrote:
> 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:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the Markdown-Discuss mailing list