Bug 27441

I've never used Markdown files, but I've used Genesis ROMs :)

Care to create a git-formatted patch for that?

Created attachment 39077 [details] [review]
Markdown patch

Ok, I attached a patch.
Markdown is used quite a lot by the github community.

Will this patch be included soon?

Thanks.

Is the extension .md actually the most common? Ikiwiki <http://ikiwiki.info/> uses .mdwn, for instance.

(In reply to comment #4)
> Is the extension .md actually the most common? Ikiwiki <http://ikiwiki.info/>
> uses .mdwn, for instance.

I rewrote some days ago Markdown syntax highlighting for gedit. See

<https://bugzilla.gnome.org/show_bug.cgi?id=384446>

I had to make a choice about file extension(s) associated with this syntax highlighting. Here was my approach:

# Markdown file extension #

There's no official Markdown file extension, so I did some research on actual
usage by text editors, implementations' documentation or other stuff.

## Actual usage review ##

### Text editors ###

- BBEdit: `.mark`, `.markdown`, `.text`
- Eclipse (Markdown Editor plugin): `.md`; suggests to also add `.txt`
- Elements (iOS text editor): `.markdown`, `.md`, `.mdown`, `.mdwn`
- Emacs: (markdown-mode): no extension by default, but gives an example to
associate `.text` with markdown-mode, with the following precision: *"There is
no consensus on an official file extension so change `.text` to `.mdwn`, `.md`,
`.mdt`, or whatever you call your markdown files."*
- Geany: `.mdml`
- Gedit (gedit-markdown): `.mdtxt`
- Jedit (Jedit mode for Markdown/Pandoc): `.markdown`, `.md`, `.pandoc`, `.pdc`
- Kate (Markdown Color Syntax Highlighting): `.md`, `.mmd`, `.text`
- Notepad++ (markdown_npp): `.md`
- SubEthaEdit: `.markdown`, `.md`
- Textmate: `.markdn`, `.markdown`, `.md`, `.mdown`
- vi and vim (pdc.vim): for filetype detection, suggests `.pdc`

### Implementations ###

Extensions used for documentation/README files written in Markdown.

- BlueCloth (Ruby fork): `.markdown`
- lua-discount (Lua): `.mkd`
- lunamark (Lua): `.markdown`
- Maraku (Ruby): `.md`
- Markdown (Perl): `.text`
- MarkdownJ (Java): `.markdown`
- Markout (Java): `.text`
- MultiMarkdown (C): `.markdown`
- Pandoku (Ruby): `.markdown`
- pegdown (Java): `.markdown`
- peg-markdown (C): `.markdown`
- PHP Markdown (PHP): `.text`
- python-markdown (Python): `.txt`
- python-markdown2 (Python): `.md`
- RDiscount (Ruby): `.markdown`
- rpeg-markdown (Ruby): `.markdown`
- text-markdown (Perl): `.text`

### Other ###

- ayans (news system): `.mdtxt`
- GAE django blog: `.md`, `.mdtxt` (for HELP and README files)
- github.com: `.markdown`, `.md`, `.mdown`, `.mkd`, `.mkdn` (for README files
written in Markdown)
- Markdown-Discuss list: in 2 discussions on Markdown-Discuss list, extensions
reported to be used by participants are: `.markdown`, `.md`, `.mdown`, `.mkd`,
`.text`, `.txt`
- Squeletml: `.mdtxt`

## Unscientific statistics ##

**Unscientific** statistics (number of times extensions are used or suggested):

- `.markdown`: 16
- `.md`: 13
- `.text`: 8
- `.mdown`: 4
- `.mdtxt`: 4
- `.mkd`: 3
- `.txt`: 3
- `.mdwn`: 2
- `.pdc`: 2
- `.mark`: 1
- `.markdn`: 1
- `.mdml`: 1
- `.mdt`: 1
- `.mkd`n: 1
- `.mmd`: 1
- `.pandoc`: 1

## My choice ##

It seems to me that `.text` and `.txt` extensions are really too generic to be
automatically associated with Markdown syntax highlighting.

I think it's reasonable to choose `.markdown` and `.md` (almost all text
editors support one or other), and `.mdtxt` to ensure compatibility/transition
with gedit-markdown.

## Sources ##

- <http://code.google.com/p/ayans/wiki/Readme>
- <http://daringfireball.net/projects/markdown/>
-
<http://gae-django-blog.git.sourceforge.net/git/gitweb.cgi?p=gae-django-blog/gae-django-blog;a=tree;h=refs/heads/master;hb=refs/heads/master>
- <http://jblevins.org/projects/markdown-mode/>
- <http://michelf.com/projets/php-markdown/>
- <https://fedorahosted.org/deploymentguide/wiki/EditingInMarkdown>
- <https://github.com/asb/lua-discount/>
- <https://github.com/bobtfish/text-markdown>
- <https://github.com/fletcher/peg-multimarkdown>
- <https://github.com/github/markup/blob/master/lib/github/markups.rb>
- <https://github.com/jgm/lunamark>
- <https://github.com/jgm/peg-markdown>
- <https://github.com/lunant/pandoku>
- <https://github.com/mislav/bluecloth/>
- <https://github.com/myabc/markdownj>
- <https://github.com/nex3/maruku>
- <https://github.com/rtomayko/rdiscount/>
- <https://github.com/rtomayko/rpeg-markdown/>
- <https://github.com/sirthias/pegdown>
- <https://github.com/thomsmits/markdown_npp>
- <https://github.com/trentm/python-markdown2>
- <http://six.pairlist.net/pipermail/markdown-discuss/2006-October/thread.html>
-
<http://six.pairlist.net/pipermail/markdown-discuss/2010-November/thread.html>
- <https://sourceforge.net/projects/markout/>
- <http://www.dyeager.org/post/2008/06/markdown-color-syntax-highlighting-kate>
- <http://www.freewisdom.org/projects/python-markdown/>
- <http://www.jpfleury.net/logiciels/gedit-markdown.php>
- <http://www.red-sweater.com/forums/discussion/comment/1034/#Comment_1034>
- <http://www.vim.org/scripts/script.php?script_id=2389>
- <http://www.winterwell.com/software/markdown-editor.php>
- <http://xbeta.org/wiki/show/Markdown>

(In reply to comment #5)
> - `.markdown`: 16
> - `.md`: 13
> - `.text`: 8
…

> It seems to me that `.text` and `.txt` extensions are really too generic to be
> automatically associated with Markdown syntax highlighting.

.text is obviously a Mac-flavoured use, but you're right, too generic.
 
> I think it's reasonable to choose `.markdown` and `.md` (almost all text
> editors support one or other), and `.mdtxt` to ensure compatibility/transition
> with gedit-markdown.

If .md is already defined, and a quick check on fileformats.info[1] lists two more instances of formats using this extension, it would probably be best to avoid redefining .md and only add .markdown. Is a transition definition for .mdtxt really that necessary if it is to be included for years…

It's a shame markdown doesnt make for easy magic matching or I would submit a patch to add it - relying on extensions as the list above shows, is flakey.


1 http://www.fileformat.info/ext/m.htm

(In reply to comment #6)
> If .md is already defined, and a quick check on fileformats.info[1] lists two
> more instances of formats using this extension, it would probably be best to
> avoid redefining .md and only add .markdown.

So you mean matching Markdown document only with `.markdown` extension?

> Is a transition definition for
> .mdtxt really that necessary if it is to be included for years…

Probably not. But I can explain my choice to initially have used `.mdtxt`. Since Markdown documents are plain text with a particular syntax, I think `.mdtxt` is a very good compromise between too generic extensions (like `.txt` and `.text`) and not so suggestive ones for those not familiar with Markdown (like `.md` and `.markdown`). In `.mdtxt`, the part `txt` informs that we will open a plain text file, and the part `md` suggests that this plain text file uses a particular syntax.

All of Github is using markdown files with the .md extension.
I think this is more important than Genesis ROM.

Indeed, *.md doesn't seem to be associated with Genesis ROM at http://www.file-extensions.org/md-file-extension -- only with 10 other file formats including markdown :)

I tried to track the origin of the addition of .md to genesis rom, but that predates freedesktop.org.xml, so it came from the initial mime databases from kde and gnome (iirc), and I couldn't find it in kde3...

In summary, I'm in favour of this change, and I can commit it to the shared-mime-info repository.

Just one question before I do that: is there a way to come up with "magic" for markdown files, which could help resolve conflicts in case more file types with *.md are added to shared-mime-info?

Header
------

Header
======

# Header
## Header
### Header

* list
+ list
- list

> quote

*em* _em_
**bold** __bold__

[link](url)



I admit it's a bit hard to match these.
Full syntax here: http://daringfireball.net/projects/markdown/syntax

OK, I see. That's hard to match indeed, since we don't even know which type of header will be used in the file.

Committed in eb5f17c1ae435ab4aaf267b9373903be05448f94

(In reply to comment #12)
> Committed in eb5f17c1ae435ab4aaf267b9373903be05448f94

Thanks a lot. For reference, this commit is viewable here:

http://cgit.freedesktop.org/xdg/shared-mime-info/commit/?id=eb5f17c1ae435ab4aaf267b9373903be05448f94

Extensions matched with Markdown documents are `.md`, `.mkd` and `.markdown`.

Extension that is no longer matched with Genesis ROM is `.md`.

David, do you know in which version of shared-mime-info this commit will be shipped? So I could prepare to drop support of Markdown MIME type in gedit-markdown.

(In reply to comment #14)
> David, do you know in which version of shared-mime-info this commit will be
> shipped?

The latest version is 0.90, so this new mimetype will be in any version after 0.90.