Markdown Support

Topics: Developer Forum
May 13, 2013 at 5:27 PM
Has anybody modified Sandcastle to produce markdown, rather than HTML, output?
Coordinator
May 13, 2013 at 7:33 PM
Nobody has as far as I know. The main task would be creating a presentation style that generated the output in markdown format. Depending on how far you wanted to take it, some work may also need to be done on a few of the build components since they all assume HTML output. For example, the reference link components would need to be updated to support outputting the links in the markdown format rather than as HTML anchor links. If generating API topics, the syntax generators use CSS styles to colorize the code in the syntax sections so they may need to change as well.

Eric
Jul 6, 2013 at 8:22 PM
This support would be really cool, and I'm willing to help out on doing some of the work for this.

If it supported Markdown as an output format, you could easily add support for all of the output formats that Markdown can do, such as HTML and pdf. (having pdf based documentation would be really cool, and convenient if the documentation ever needed to be printed off).

The question is, would it be easier to change Sandcastle to support this, or just write a custom program to work off of the XML Visual studio generates?
Coordinator
Jul 8, 2013 at 7:23 PM
As noted, the best way to do it would be to implement a custom presentation style. That would allow it to work with little or no changes to the underlying tools. Build components could be changed and implemented separately too if needed. More information on creating custom presentation styles can be found in the Custom Presentation Style help file topic and its related walkthrough.

Eric
Mar 22, 2014 at 1:48 AM
I took a different approach and converted the HTML output to Markdown, see https://github.com/maxtoroq/sandcastle-md
Coordinator
Mar 22, 2014 at 2:29 AM
If you wrap your code in a plug-in, you could have it run as part of the build process and suppress or run instead of the final help compilation step.

Eric
Nov 6, 2014 at 1:25 PM
Edited Nov 6, 2014 at 1:27 PM
HTML to Markdown is nice, but a converter that would take markdown and turn it into Sandcastle documentation would be a huge time saver too. Probably a little trickier though. Maybe some sweet Resharper templates for the XML!
Coordinator
Nov 6, 2014 at 7:21 PM
Anything's possible I suppose. You could create a presentation style with its own set of plug-ins and build components that replace the conceptual content steps to parse markdown to output the HTML rather than XSL transforming the MAML XML. The API content could still go through the normal XSL transformations.

Eric
Nov 6, 2014 at 8:22 PM
You wouldn't recommend going to MAML first? That was what I was thinking - that way the build process would catch any link discrepancies, etc. and join it to whatever output was being generated, especially in the even that it was going to a non-HTML destination.
Coordinator
Nov 6, 2014 at 11:19 PM
Edited Nov 6, 2014 at 11:21 PM
That seems rather redundant if you're creating a presentation style. Either you'd author your conceptual content in MAML or markdown. If you want to author the content in markdown but have it buildable in any help format and presentation style such as Open XML your best bet would be a plug-in that converts and adds the MAML topics to the build similar to the XML Schema Documenter which converts XSD information to MAML. Chances are that would work with any presentation style and output format.

Eric