[wp-meta] [Making WordPress.org] #618: Introduce quick-reference shortcodes for use in Explanations and Examples in the Code Reference

[Making WordPress.org]

#618: Introduce quick-reference shortcodes for use in Explanations and Examples
in the Code Reference
-------------------------+-------------------------------------
Reporter:  DrewAPicture  |      Owner:
    Type:  enhancement   |     Status:  new
Priority:  normal        |  Component:  developer.wordpress.org
Keywords:                |
-------------------------+-------------------------------------
 Despite the non-love for shortcodes on wp.org, I propose that we implement
 a few quick-reference shortcodes that could be leveraged for quickly
 linking to other functions, hooks, classes, or methods in Explanations and
 Examples in the Code Reference.

 This would be directly tied to the 'Grand Migration' effort that's
 looming.

 Granted there's a case to be made that this could be covered using the
 Link functionality basked in the editor, though this isn't currently
 possible in comments/Examples on the front-end or otherwise as far as I
 know.

 The primary goal would be to create some parity in the experience between
 editing content in the Code Reference with editing content in the Codex
 with these shortcodes.

 I've opened a [https://github.com/Rarst/wporg-developer/pull/22 pull
 request] on the wporg-developer repo to this end.

 There are three outstanding items to resolve before that could be
 considered for merge:

 1. Decide if this is even a good idea
 2. Do a security audit of incoming shortcode attributes to ensure we
 aren't opening ourselves up to abuse
 3. Figure out the best method for verifying the function, hook, class, and
 method slugs before output. Querying for them or pinging the URLs is not
 going to scale well at all. Maybe some kind of cached whitelist would
 work.

 Example usage in context:


 {{{
 [function name="wp_parse_args" label="wp_parse_args()"]
 }}}

 Outputs:
 [https://developer.wordpress.org/reference/functions/wp_parse_args
 wp_parse_args()]

 {{{
 [hook name="new_status_post-post_type" label="publish_post"]
 }}}

 Outputs: [https://developer.wordpress.org/reference/hooks/new_status_post-
 post_type publish_post]

 {{{
 [class name="WP_Meta_Query"]
 }}}

 Outputs: [https://developer.wordpress.org/reference/classes/wp_meta_query
 WP_Meta_Query]

 {{{
 [method name="have_posts" class="WP_Query" label="WP_Query->have_posts()"]
 }}}

 Outputs: [https://developer.wordpress.org/classes/wp_query/have_posts
 WP_Query->have_posts()]

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/618>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org