How to create parameter tables in markdown?

[gmaclennan]

How can I use documentationjs to replicate the way doxme creates markdown tables for parameters?

Parameters

parameter	type	description
dox	Object	the output of dox as a parsed JSON object
readme	boolean	whether to output a readme or just docs
package	Object	a parsed package.json
travis	boolean	whether to output a travis badge along with docs

For me the default output of nested lists is harder to read and less compact.

I want to replace doxme with documentationjs for generating README.md from jsdoc.

[wanderer]

I would like this too

[tmcw]

As things go, this is exactly what documentation.js used to output, but I decided that in many cases it didn't work well, and it didn't work at all for nested parameters. I really believe readability doesn't uniformly exist :)

I'd be open to reintroducing this as an option if there's some way to represent nested parameters.

[wanderer]

The other option for me is just to use the json output then pipe that into my own markdown generator. @tmcw what do you think about that approach? Is the json output stable?

[gmaclennan]

Can this be done with a template? Looking at https://github.com/documentationjs/documentation-theme-default/blob/master/markdown.hbs

One solution to nested parameters would be the same as JSDoc,

parameter	type	description
options	Object	options
options.foo	boolean	foo
options.bar	Object	bar

Although this would get messy for deeper nesting.

For me for simpler APIs without nested parameters, the option of this format would be preferable and more readable than the current output, which works well for more complex APIs.

I'm looking at a limited use-case for my needs - there are probably many cases I haven't come across where this won't work well.

[gmaclennan]

ok looks like themes are not used for markdown output, it's hard-coded in lib/output/markdown.js

It would be great to have some theming flexibility here to customize markdown output according to ones whims and prejudices.

[tmcw]

I'd rather introduce this as an option than to go back to Markdown templates (which, like this format, were the previous approach). It was too easy for template authors to mess up formatting in such a way that dynamically-rendered templates were invalid Markdown: the current remark-based system is way better.