The power of Pandoc: a handy tool for publishing on multiple platforms.

[Kerbas_ad_astra]

I love Markdown (specifically the GitHub-flavored variety). You love Markdown. GitHub, KerbalStuff, and KerbalX love Markdown, but CurseForge and the forums don't. Since the latter two are official, this leaves us mod makers with the trouble of having to manually shoehorn our README files and such into the forum and CurseForge editors.

Fortunately, there's a tool called Pandoc which can convert documents between various markup and markdown formats.  Now we can write our README files once, export them, and then paste them into CurseForge and the forum. For that matter, we can write forum posts in our favorite text editors, and then convert them. This very post was entirely composed in Notepad++, formatting and all. Empirically, it's very handy for laying down thoughts and drafting stuff when I'm not able to access the forums, or when I'm working on something too big or in too early a stage to go to the trouble of writing it in the forum editor.

I've started putting the following batch file into all of my addon folders, so I don't have to type out the commands every time. As I get more advanced in my build and publishing automation, it can be called as part of the publishing process.

pandoc -f markdown_github -t html -o README.html README.md

I can then open the resulting HTML file in my browser and copy it (formatting and all) into the forum or CurseForge editors.

Outdated information:

Spoiler

I love Markdown (specifically the GitHub-flavored variety). You love Markdown. GitHub, KerbalStuff, and KerbalX love Markdown, but CurseForge and the forums don't. Since the latter two are official, this leaves us mod makers with the trouble of having to manually shoehorn our README files and such into HTML and BBCode. There's a tool called Pandoc which can convert documents between various markup and markdown formats, but it doesn't handle BBCode by default. Fortunately, somebody else went to the trouble of making a BBCode exporter, and I have produced a modified version which works with vBulletin's flavor of BBCode. (I don't actually know Lua or pandoc specifically, so please let me know if you find any issues. In particular, I'd like to have a nice way to get the true width of a table, because when pandoc ingests Markdown tables, it doesn't seem to get any width information, so the resulting BBCode table always defaults to width 500.)

Now we can write our README files once, export them, and then paste them into the "source editors" of CurseForge and the forum. For that matter, we can write forum posts in our favorite text editors, and then convert them to BBCode. This very post was entirely composed in Notepad++, formatting and all. Empirically, it's very handy for laying down thoughts and drafting stuff when I'm not able to access the forums, or when I'm working on something too big or in too early a stage to go to the trouble of writing it in the forum editor.

I've started putting the following batch file into all of my addon folders, so I don't have to type out the commands every time. As I get more advanced in my build and publishing automation, it can be called as part of the publishing process. (The BBCode is for the forums, and the HTML is for CurseForge.)

pandoc -f markdown_github -t "..\..\Other source repositories\pandoc-bbcode\panbbcodeVBulletin.lua" -o README.bbcode README.md
pandoc -f markdown_github -t html -o README.html README.md

(I should note, I've got my files set up so that, in my main "KSP stuff" folder, I have an "Addons" folder which holds all of my addons, and an "Other source repositories" folder which holds my clones of anyone else's repositories. That's where the pandoc-bbcode converter lives. I put this batch folder in e.g. my AntennaRange Relays folder, so it goes up one level to get to "Addons", another level to get to "KSP stuff", and then down to where panbbcode.lua lives. Since the batch file is in the top of the addon directory, same as the README files, they don't need any folder information.)

 

Edited December 8, 2015 by Kerbas_ad_astra
Revised for the new forum.

[DMagic]

This should be helpful. I hate dealing with BBCode, so I'll have to try that out.

For CurseForge, while it might not like raw markdown, it is perfectly happy with parsed markdown. Take the KerbalStuff mod description, the standard info screen, the one that anyone else sees, not the editing screen, copy everything, and paste it into the Curse addon description. It should come out correctly formatted. I'm not sure if it handles GitHub markdown, but it seems fine with standard markdown, I use that method for nearly all of my addons.

[Kerbas_ad_astra]

This should be helpful. I hate dealing with BBCode, so I'll have to try that out.

For CurseForge, while it might not like raw markdown, it is perfectly happy with parsed markdown. Take the KerbalStuff mod description, the standard info screen, the one that anyone else sees, not the editing screen, copy everything, and paste it into the Curse addon description. It should come out correctly formatted. I'm not sure if it handles GitHub markdown, but it seems fine with standard markdown, I use that method for nearly all of my addons.

I suspect your method works because CurseForge works with HTML (that's what shows up when I edit its stuff in source mode -- and that's why I include that output mode in my script). Since that's what KerbalStuff parses the markdown into, that's what would get copied. We could probably test this by copying and pasting the displayed text from GitHub (or the forums, or any old random text from some other webpage) and seeing what happens.

[Kerbas_ad_astra]

I've made a fork of 2ion's converter that is more fully compatible with vBulletin -- it produces tables and headers, and doesn't produce any tags that don't work with the KSP forums, like 2ion's sometimes did (headers and the "em" tag instead of "I" for italics): https://github.com/Kerbas-ad-astra/pandoc-bbcode

[Kerbas_ad_astra]

I've modified my instructions for the new forum.  In particular, there's no "source mode", but I've found that I can export a Markdown file to HTML, open the resulting page in my browser, and copy the displayed page into the editor -- formatting is preserved.  Therefore, I'm tentatively deprecating the BBCode exporter, since it doesn't seem to be necessary anymore.  (I'm leaving up the repository, just taking it out of the main body of the post -- see the "Outdated information" spoiler for instructions.)