Add support for Markdown.md output

[EWSoftware]

Moved from CodePlex
Originally submitted by SharpGIS

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.

SharpGIS wrote May 28, 2014 at 3: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

[EWSoftware]

In setting up my projects here on GitHub I was unable to embed an image in a wiki topic. Looking at the example above for the class topic, this functionality does appear to be broken at the current time. The only workaround I was able to find is to host the wiki images externally either in the code repo or at a separate site altogether and use a fully qualified URL to show them. As such, it would seem necessary that any presentation style using a markdown format would need a project property to specify the root URL to add to all image references.

[dotMorten]

@EWSoftware Yes something is up with relative image paths. They are returned but as octet streams, so the browser won't display them. I've submitted a request to GitHub to get this fixed.

[dotMorten]

@EWSoftware Issue on GitHub has now been fixed. Here's an example page showing two working syntaxes: https://github.com/dotMorten/SandcastleMarkupDocTest/wiki/TestPage

Also here's an example page for members now displaying right: https://github.com/dotMorten/SandcastleMarkupDocTest/wiki/TestNamespace.StoredNumber%20Class

[EWSoftware]

@dotMorten Thanks for the update and the example.

[EWSoftware]

I've made a start on this and have a rough framework for the presentation style itself. I still need to integrate it into the build engine.

Limitations
The markdown generated is geared towards GitHub flavored markdown. Results may vary on other sites.

Code colorization is left to the markdown processor. The line numbering and collapsible region features of the code block component are not supported. Those features will be ignored.

Obviously, the language filter from the HTML help formats is not supported. As such, language-specific text will be shown using the generic, multi-language style. Likewise, syntax sections and code blocks are shown in a sequential fashion similar to the topic previewer.

Address anchors on elements such as list items and table cells are not supported as GitHub strips most attributes from elements. Links to title elements and the introduction should be supported.

"No Bullet" style lists and image placement options are not supported as GitHub strips the style attribute from all elements.

Literal HTML in conceptual topics and XML comments may not be rendered as expected since the markdown processor strips most attributes from the elements (id, style, etc.).

It isn't possible to check for and escape every possible markdown directive in conceptual topic text and XML comments text. As such, certain constructs may be interpreted as markdown and rendered differently. For example, if your comments contain the literal text "Some text surrounded by asterisks", it will most likely be rendered as emphasized text rather than literal text in asterisks as it would in website output.

Markdown processors make certain assumptions about various elements which do not always hold true for the content generated by the presentation style. In addition, certain HTML elements must be formatted very specifically to work around issues in the markdown processors. For example:

• Markdown table cells cannot span multiple lines.
• Markdown list items cannot contain multiple paragraphs.
• Markdown elements embedded within certain HTML elements (i.e. li elements) do not get processed.
• HTML tables must be followed by a non-breaking space or the markdown processor may ignore markdown elements within the cells.

As such, a lot more HTML is generated by the presentation style than you would see if it was written by hand to work around such limitations since the presentation style cannot assume the content fits the layout requirements expected by the markdown processors.

GitHub uses the filename as the page title. Topics will continue to use the selected naming method and, as such, you will see that filename at the topic of each page. The topic title rendered by the presentation style will appear below it. This may not be ideal but is necessary. The topic title cannot be used as the filename since they need to be unique across all topics documented. For example, if Class1 appeared in two separate namespaces and the topic titles were used as filenames, the topics from one of the classes would overwrite the other. Fully qualifying the names and including parameter information would allow them to be unique but would most likely result in extremely long filenames that could exceed the maximum filename length limit.

If these limitations are not acceptable, it is suggested the you generate the content as a website and host it somewhere such as the GitHub Pages site related to your project.

[dotMorten]

@EWSoftware Nice! This is awesome progress!