Document available shortcodes in eg. new post page

[voxpelli]

It would be useful if a plugin defining shortcodes also could describe the usecase for the shortcode and the available attributes and the usecases for those attributes in a way that could be exposed in the interface on eg. the new post page.

One could take inspiration from eg. the Drupal Token module which has a token_list() hook that a Drupal module uses to describe every token it describes so that they can be presented to the user in the interface.

Something like:

add_shortcode_description('shortcodename')

That returns something like this would be nice:

array(
  'description' => 'This is used to do foo',
  'attr' => array(
    'bar' => 'A text that will be presented as bar'
  ),
);

[scribu]

This would be useful only if we actually show it somewhere in the UI. Shortcodes are just magic strings, at the moment.

[nacin]

Replying to scribu:

This would be useful only if we actually show it somewhere in the UI. Shortcodes are just magic strings, at the moment.

Agreed. This is a nice idea, however.

[helenyhou]

Maybe a consolidated tab in contextual help?

[voxpelli]

Sketch of what an implementation of something like this could look codewise - interface not worked on and code not complete

[bananastalktome]

Confluence (a product by Atlassian) does an interesting job with presenting shortcodes (they call them macros) to users through their WYSIWYG editor. I'm not affiliated/associated/even really care much for Atlassian, I just have used Confluence and rather enjoy the way they deal with shortcodes.

I'd be glad to follow up this comment with a description and/or screenshots, but I am not sure if doing so would introduce any legal issues for WordPress (I am rather naive when it comes to these things) or if it would even be helpful here.

[helen]

I thought this was pretty interesting, maybe worth exploring in conjunction with the awesome TinyMCE 4 update in 3.9: ​https://github.com/scottsweb/shortcode-suggest/

[johnbillion]

Related: #25661

[chriscct7]

Closing as maybelater. Complete lack of interest on the feature on the ticket over the last 2 years, and the shortcake feature plugin being explored currently could support this. Feel free to reopen when more interest re-emerges (particularly if there's a patch).