New Feature: Generate Markdown files instead of static HTML

[mcmahonjohn]

TL;DR
Misread line of README to suggest I could generate Markdown files from dartdoc. Realized I can't and would like to request that feature.

Longer version:
First, not having this feature isn't causing any problems.

Second the following line in the README makes me think there was a way to do so, but after digging around I don't believe so. If that is an incorrect determination, please let me know.

The mentioned line, emphasis mine.

By default, the documentation is generated to the doc/api directory as static HTML files.

I looked at the help commend output and the documentation and didn't see anything that might allow this.

However, as a newcomer to Dart. I was interested in a way to take the potentially Markdown written comments within my code and assemble it into Markdown files.

The Use Case being I work on GitHub and BitBucket and both providers store their Wiki sections in git repositories.

So I if I could take the comments and generate Markdown files, I could push them to the Wiki repo of my project repo.

[jcollins-g]

Much of dartdoc's internals presently assume we're building HTML, so this is unlikely to happen anytime soon. The wording in the README is ambiguous, I think it was intended to communicate that the location dartdoc writes to is configurable rather than the output format.

[Stargator]

it would be a great feature

[mcmahonjohn]

@jcollins-g Thanks for the feedback. I understand it's not there now and was likely not in mind for the future.

[jcollins-g]

Reviving this issue. Markdown generation support for dartdoc is now definitely on the radar, and a number of recent PRs are addressing the issue of dartdoc internals assuming HTML generation. These include #2072, #2076, #2077, #2078, #2080, #2081, #2085, and #2086. I'll let @jdkoren fill in more information as the design is fleshed out.

[akashgurava]

All the pull requests have been merged! Any update on the feature?

[jdkoren]

@akashgurava we're pretty close, Dartdoc can generate the pages now. There are a few outstanding things that I might break into separate issues.

[jcollins-g]

@jdkoren Once we're to the point where the pages are reasonable and we have some kind of automated spot-checking for the output, I think we can close this bug and maybe file issues related to markdown separately. Are we at that point now or are there big missing pieces before we can declare the basic implementation done?

[jcollins-g]

I think the only thing we're missing is some more automated spot checking before we can call this at least adequate. @mehmetf @jdkoren What do you think?

[mehmetf]

I am not sure what automated spot-checking means but the functionality has been working great for us so far. Thanks!

[jcollins-g]

Well, if the functionality is working and being widely used, that's good enough. I'd like more end to end tests but I always want more tests. :-) Closing.

[nikunjdk]

What is the command to generate markdown instead of HTML doc?

[jcollins-g]

@nikunjdk Sorry, forgot to unhide the --format command line option. See #2703 for how to use it.