re: serving markdown directly : any suggestions?

converting light-markup to .html ain't rocket-science.  really.

you can use any language to do it.  specifically including perl.

and besides, i think it's kinda cute that some perl people would
"look down on" php, ruby, and python.  good for the gander, eh?

but if i had to place a bet, it would be on client-side javascript...


Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net
Mayuresh Kathe | 4 Feb 09:27 2015

serving markdown directly : any suggestions?


have been tinkering with markdown for a few hours now, so am still a 

would like to use it for a documentation project which will be served 
over the web.

need to know if there's any way to transform markdown content to (x)html 
on the fly at the web server level?

use case:
a web server with the above capabilities would have the document root 
folder holding a bunch of markdown files and a 'css' file.
on visiting that web server's address over 'http', the index.md file 
would get transformed into (x)html, pick-up the 'css' and show a 
beautiful page to the visitor.
all this, while i would be busy writing plain old markdown.

i am sorry if this has been asked out here before, but i couldn't find 
any such queries, perhaps my googling skills are bad.  :)


Sean Leonard | 21 Jan 10:49 2015

IETF text/markdown draft-05

Hi Markdown world,

A month ago, the fifth draft of the IETF text/markdown work, 
"draft-ietf-appsawg-text-markdown-05", was published.

Additionally, a companion document regarding text/markdown use cases 
(including how to label Markdown variants when the text/markdown media 
type is not in use, e.g., by using filenames) was published about three 
weeks ago. See "draft-seantek-text-markdown-use-cases-01".

If you are interested, please comment here or on the IETF apps-discuss 
mailing list. I am monitoring both.

Overall the volume of comments dropped precipitously on the IETF mailing 
list, indicating (to me) that people don't have many nits with it. The 
text in both cases has been drastically simplified, so it's much shorter 
and more straightforward.



-------- Forwarded Message --------
Subject: 	[apps-discuss] I-D Action: 
Date: 	Mon, 22 Dec 2014 15:01:49 -0800
From: 	internet-drafts <at> ietf.org
To: 	i-d-announce <at> ietf.org
CC: 	apps-discuss <at> ietf.org

A New Internet-Draft is available from the on-line Internet-Drafts directories.
  This draft is a work item of the Applications Area Working Group Working Group of the IETF.

         Title           : The text/markdown Media Type
         Author          : Sean Leonard
	Filename        : draft-ietf-appsawg-text-markdown-05.txt
	Pages           : 14
	Date            : 2014-12-22

    This document registers the text/markdown media type for use with
    Markdown, a family of plain text formatting syntaxes that optionally
    can be converted to formal markup languages such as HTML.

The IETF datatracker status page for this draft is:

There's also a htmlized version available at:

A diff from the previous version is available at:

-------- Forwarded Message --------
Subject:     New Version Notification for 
Date:     Sun, 28 Dec 2014 15:24:09 -0800
From: internet-drafts <at> ietf.org

A new version of I-D, draft-seantek-text-markdown-use-cases-01.txt
has been successfully submitted by Sean Leonard and posted to the
IETF repository.

Name:        draft-seantek-text-markdown-use-cases
Revision:    01
Title:        text/markdown Use Cases
Document date:    2014-12-28
Group:        Individual Submission
Pages:        18


    This document elaborates upon the text/markdown media type for use
    with Markdown, a family of plain text formatting syntaxes that
    optionally can be converted to formal markup languages such as HTML.
    Background information, local storage strategies, and additional
    syntax registrations are supplied.
Benoit Perdu | 6 Jan 06:10 2015

Re: Markdown-Discuss Digest, Vol 142, Issue 1

> Two approaches I've seen:
> 1.  On stack exchange they have an editor that makes you type markdown in
> one field, and it shows it formatted in another field.  This works fairly
> well.
> 2.  There is an extension, "Markdown Here" available for both Chrome and
> Firefox that allows you to type MD and there is a toggle that switches
> between marked up verson and fancy text.  Works quite well in gmail/chrome.
> Respectfully,
> Sherwood of Sherwood's Forests

I was unaware of the latter, and am now trying it, it is a great
addition to the browser.

max hilmer | 4 Jan 13:30 2015

Auto Transform Text

I would really like to see a feature that auto transforms text written in markdown to WYSIWYG. So if you type *this* it will automatically make the markdown disappear and the word would then be emphasized. This feature is available on apps like Ulysses, Scrivener, and Macchiato, aka for apps focused on writing rather than programming. However I haven't found a way to incorporate this into my wordpress site -allowing all authors this feature. 

Any valuable comments to this issue would be much appreciated, 
    Max Hilmer
Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net
mofo syne | 15 Dec 01:09 2014

markdown/commonmark document specification concept

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. 


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

Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net
Piero Wbmstr | 18 Nov 21:16 2014

Re: Announce: Markdown (extended) specifications

Hello Jakub,

I didn't know this project (I agree with you: there are already too many
MD projects ...).

I will look at CommonMark in details to see if I may help on this or
propose something like a "merge" of both CommonMark and MarkdownExtended
or anything else.

By the way, is there a place where all known MD projects are listed ?

Thank you for the info.


Le 18/11/2014 18:28, Jakub Jirutka a écrit :
> Hi Pierre,
> are you familiar with the [CommonMark project](http://commonmark.org)? It’s _de facto_
standardized Markdown with very precise [specification](http://spec.commonmark.org). If you wanna
extend Markdown syntax, then I highly recommend to start on top of this spec. No one needs yet another
incompatible and ambiguous Markdown dialect, there are too many of them already.
> Best regards,
>   Jakub Jirutka

Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net
Piero Wbmstr | 18 Nov 15:09 2014

Announce: Markdown (extended) specifications

Dear all,

I'm quite a newcomer to both the "markdown-discuss" mailing-list and the Markdown W3C Community Group. So first of all let me make a brief introduction: I am a french PHP developer and I work (from a long time now) on a Markdown parser that you can find at http://github.com/piwi/markdown-extended (this is not the subject of this email).

**I want here to announce that I'm working on writing specifications for a version of the syntax that I called "Markdown Extended" (to differentiate it from the "classic" one).**

I know some of you are against the idea of such specifications for various reasons ... I won't here try to convince you all about their usefulness, but I would appreciate to have your feedback and comments about this work before publishing it "officially". Those who are fundamentally against such specifications may notice that I tried to clearly separate the "Extended" syntax of the original. Let's consider that the Markdown Extended syntax has its specifications where classic Markdown doesn't.

**You can read the draft of this work at http://aboutmde.org/ which is actually in ´alpha´ version.**
**Please feel free to make some returns via this email or the bug tickets of the original repository (it is hosted on GitHub at http://github.com/markdown-extended/manifest).**

I want to thank in advance all those of you who might take a little time to read this work and give me a comeback.
Moreover, any contribution is welcome.

Kind regards,
-- Pierre Cassat
Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net
Sean Leonard | 12 Nov 00:47 2014

Opinions on in-band variation signaling

Regarding the text/markdown registration:

At least one commentator (Larry Masinter) specifically requested that the variant identifier be
included in-band in the Markdown content, rather than as part of the metadata. I disagree with in-band
signaling (as has been registered earlier on this list). Nevertheless, I wanted to take a straw poll and
see if anyone has tried to implement in-band Markdown variation identifiers, with any success. Do any
implementers have experience with picking the type of Markdown based on some info at the top of the
Markdown content? Does it work—or will it never work? Or is it “bad” for particular reasons?

By in-band, I mean a Markdown file with content like this:

% This is a Title
% Sean Leonard
% November 2014

Blah blah *blah*.
<<< (fortin’s suggestion)

[!pandoc]: # "This is a pandoc document."
% This is a Title
% Sean Leonard
% November 2014

Blah blah *blah*.
<<< (seantek’s suggestion)

Sean Leonard | 12 Nov 00:44 2014

Progress on text/markdown at IETF 91

Hello Markdown Community:

There was discussion and progress on text/markdown at IETF 91. Here are slides:

and here are the interim minutes:

The view is that the syntax parameter of draft-03 should be simplified to a parameter currently called
“variant”, which is a simple US-ASCII case-insensitive identifier. Other considerations are
discussed on the apps-discuss IETF mailing list. The proposal was posted last week, and is below.

I will work on draft-04 over the next couple of weeks.



Optional Parameters:
variant: An optional identifier that serves as a “hint” to the recipient of the specific Markdown
variant that the author intended. When omitted, there is no hint; the interpretation is entirely up to the
receiver and context. This identifier is plain US-ASCII and case-insensitive. People who want interop
can optionally register them using a simple webform (IANA registry), which just asks for the Identifier,
a Description, and Contact Information. If a receiver does not recognize the variant identifier, the
receiver MAY present the identifier to a user to inform him or her of it.
Other parameters MAY be included with the media type. The semantics of such parameters MAY be defined by the
variant; they are not defined here. As an alternative, the variant MAY be registered under another media
type; this text/markdown registration does not preclude other registrations.

With the text above in the registration template, pretty much all of Section 3 (draft-03) would be
eliminated. Additionally, Section 6 (IANA Considerations) would be cut down to about 1/3 of its current size.

"Variant" means a lightweight markup language that differs in some respect from other Markdown-derived
languages. The purpose of a variant is to distinguish a given variation from other Markdown variations,
as well as from Gruber's original syntax specification and implementation, where two parties wish to
interoperate by implementing the common variation.

The IANA Registry shall be called "Markdown Variants". The intent of this name is to broaden the uses of
variant identifiers, so protocols that do not rely on Internet media types can still tag Markdown content
with a variant name. For example, a file can be named "file.pandoc.markdown", which could have the
equivalent meaning as "Content-Type: text/markdown; variant=pandoc". (Credit goes to Michel Fortin
for suggesting that the classification of variants have broader value than just the media type
registration; for example, in content management systems that do not use media types to classify formats.)
Jeff McNeill | 11 Nov 07:38 2014

Re: Markdown-Discuss Digest, Vol 139, Issue 3

> As a mere user, I've noticed the same thing. One of the purported 
> benefits of markdown is its portability, i.e., the ability of the user 
> to write in any editor, knowing that he can then load it into any number 
> of parsers and get consistent results.
> But, with all the different flavors out there, one now has to think, 
> "which parser will I use to convert this file?" and insert markdown 
> accordingly. I recently discovered at least four different ways in which 
> parsers deal with typographic quotes and dashes, from the original 
> SmartyPants to the Python Markdown implementation of SmartyPants to the 
> Calibre implementation of it to RMarkdown's implementation (not to 
> mention ReStructuredText and Textile, both of which do it differently, 
> yet). So, I have to commit to a given dialect and converter before I 
> begin to type. To me, that's defeating one of the fundamental purposes 
> of markdown.
> Virgil

I believe that is why a neutral, “Bland” Markdown recommendation is needed. Not as yet another parser
or syntax but as something to tell writers and editors to use, so that their content can be properly processed.

This is actually not too difficult. http://jeffmcneill.com/bland-markdown

Jeff McNeill 
Markdown-Discuss mailing list
Markdown-Discuss <at> six.pairlist.net