This project has moved and is read-only. For the latest updates, please go here.
4

Closed

Add support for Markdown.md output

description

It would be amazing if, in addition to HTML, you could output github .md markdown files. This would enable you to upload the entire library reference directly to the github project's wiki.
Closed Jan 26, 2015 at 7:08 AM by EWoodruff
Moved to GitHub

comments

EWoodruff wrote May 28, 2014 at 3:21 AM

I'm not familiar with github wikis nor markdown in general. How would that work? Would it just output a bunch of topics with no TOC? The new VS2013 style is pure HTML and client-side script so works in the absence of ASP.NET and PHP and is suitable for servers and content delivery networks that don't support anything but pure HTML and client-side script.

SharpGIS wrote May 28, 2014 at 5:05 AM

Think of it as a very simple version of html. The TOC would be a page by itself. I can work with you on it if you give me the pointers to get started on it. Tried but couldn't figure out where to start.

EWoodruff wrote May 28, 2014 at 8:29 PM

Hold off for a week or so until the next release of SHFB is published. It contains some breaking changes to the plug-in and presentation style APIs and some general fixes to the existing presentation styles. Once released, you can create a new presentation style using the project template. There's a walkthrough in the help file that will get you started. Typically, it's best to clone one of the existing presentation styles files and modify them. I'd suggest the VS2013 style as it's the newest.

In this particular case, several changes will need to be made such as to render the snippets as standalone blocks similar to the older VS2005 style (no snippet grouping will be supported). You'll also need to go through the content and transform files and replace the HTML tags with the equivalent markdown elements, remove the script elements, etc. You'll also need to reformat the topic structure accordingly (html/head/body elements).

Since this is a unique format like Open XML, it will require it's own format type. I'll need to add support for that. If you can create a presentation style, I could handle integrating the new format and doing the build task that performs any final steps and generates the final output.

SharpGIS wrote May 28, 2014 at 9:32 PM

Can I just start with current source code rather than the release? Or has the breaking changes not been checked in yet?

EWoodruff wrote May 28, 2014 at 10:34 PM

You can if you like. All the breaking changes are in there. I've got a few minor tweaks to the presentation styles to check in but nothing major that would affect a markdown format.

SharpGIS wrote May 28, 2014 at 11:58 PM

I've tried manually to do a little bit of the markdown doc here as an example:
https://github.com/dotMorten/SandcastleMarkupDocTest/wiki

Markdown files available here:
http://www.sharpgis.net/SandcastleMarkupDocTest.wiki.zip

SharpGIS wrote Jun 13, 2014 at 11:25 PM

Just following up on this. You mentioned you needed add support for custom format type. Is this in the latest release?

EWoodruff wrote Jun 14, 2014 at 12:47 AM

No, I can't add support for a format type until I've got a presentation style that will make use of it so I know what steps need to happen in order to generate the final output.

wrote Aug 25, 2014 at 8:34 AM

wrote Oct 13, 2014 at 8:34 PM

wrote Jan 12, 2015 at 9:54 PM

wrote Jan 26, 2015 at 7:08 AM