Re: Add-on: Github Flavored Markdown exporter

[Grant Rettke <gcr@wisdomandwonder.com>]

Dumb question, from where should we pull down your excellent exporter Lars?
Grant Rettke | AAAS, ACM, AMA, COG, FSF, IEEE, Sigma Xi
grettke@acm.org | http://www.wisdomandwonder.com/
“Wisdom begins in wonder.” --Socrates
((λ (x) (x x)) (λ (x) (x x)))
“Life has become immeasurably better since I have been forced to stop
taking it seriously.” --Thompson


On Tue, Apr 8, 2014 at 4:39 PM, Lars Tveito
<larstvei@student.matnat.uio.no> wrote:
> Hi, thanks for checking it out!
>
> Thorsten Jolitz writes:
>
>> Thorsten Jolitz <tjolitz@gmail.com> writes:
>>
>>> Lars Tveito <larstvei@student.matnat.uio.no> writes:
>>>
>>>> Hi!
>>>>
>>>> I have written an exporter for Github Flavored Markdown, which is a
>>>> derived back-end from the Markdown (vanilla) exporter. It adds
>>>> Github-style src-blocks, strike-through and table of contents.
>>
>> Your library works really good, thanks. I would recommend adding it to
>> /contrib. I used it to create new README.md files for all three
>> libraries navi-mode.el, outorg.el and outshine.el, you can find the
>> repos on github.com/tj64 if you want to take a look.
>>
>
> I try adding it soon. Checked out your README'S, looks good!
>
>> I like the idea very much to write this documentation stuff once in one
>> place and then reuse it in all other places. Therefore when I write a
>> source file, I use outorg to write a more or less sophisticated comment
>> header for that file. This is then automatically converted back to a
>> programming language comment section, but I can always convert it back
>> to Org-mode. From the outorg-edit-buffer, I can then export it to html,
>> latex, ascii and now to markdown-github-flavor too, whats nice.
>>
>> I use a little trick to do this:
>> I narrow the buffer to the first 1st level headline, and then use
>>
>> ,--------------
>> | C-1 M-# M-#
>> | C-u 1 M-# M-#
>> `--------------
>>
>> to temporarily insert the default export template, or
>>
>> ,--------------
>> | C-3 M-# M-#
>> | C-u 3 M-# M-#
>> `--------------
>>
>> to temporarily insert a custom export template from a file.
>>
>> A few questions and remarks:
>>
>> - I get the best results with just using example blocks - is it supposed
>>   to work with source-blocks and other blocks too?
>>
>
> Getting it to work with source-blocks was the feature I missed the most
> from the vanilla markdown exporter. If you specify a language in the
> source-block it will be added to the exported version as well; a problem
> occurs if you specify a language not supported by Github. Emacs lisp is
> an example of this, so there is a alist `org-gfm-lang' which by default
> has the value:
>
>     (("emacs-lisp" . "lisp") ("elisp" . "lisp"))
>
> So a source block like this:
>
> #+begin_src emacs-lisp
>   (defun foo ()
>     'foo)
> #+end_src
>
> exports to this:
>
> ```lisp
> (defun foo ()
>   'foo)
> ```
>
> Which provides syntax highlighting in Github Flavored Markdown.
>
>> - Just like the Org exporter in general, it does not know how to deal
>>   with boxes made with rebox2.el, so I replaced them with example
>>   blocks.
>>
>
> I am not familiar with rebox2.el. This back-end inherits most
> functionality from the markdown (vanilla) exporter, which again inherits
> from the html exporter. Since rebox2.el doesn't play nice with any of
> those it will cause problems with the github flavored as well.
>
> If you'd like the boxes created with rebox2.el to appear in the exported
> version you could possibly wrap it inside an example-block.
>
>> - What about numbered lists with longer text/blocks as item content - is
>>   the item numbering supposed to work?
>
> I hadn't tested this, but found an old org-file with notes packed with
> different lists. I generated it, and most of it looks good:
> https://gist.github.com/anonymous/694b7b5f53dd21850bcd (by the way, the
> content is rubbish, and in Norwegian).
>
> The only problems are with latex-code mixed in the document and sloppy
> work from the original org file.
>
> - Lars
>