WordPress.org

Making WordPress.org

Opened 3 years ago

Closed 21 months ago

#618 closed enhancement (wontfix)

Introduce quick-reference shortcodes for use in Explanations and Examples in the Code Reference

Reported by: DrewAPicture Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

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 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: wp_parse_args()

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

Outputs: publish_post

[class name="WP_Meta_Query"]

Outputs: WP_Meta_Query

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

Outputs: WP_Query->have_posts()

Change History (4)

#1 @DrewAPicture
3 years ago

Forgoing the shortcodes idea and implementing wplink for comments wouldn't be a half-bad idea, especially since it would solve all three of the concerns listed above, especially validation.

#2 @nacin
3 years ago

I think an awful lot of this (in particular, function names, class names, and method names) can be done on the fly by parsing content.

This ticket was mentioned in Slack in #meta-devhub by siobhan. View the logs.


3 years ago

#4 @coffee2code
21 months ago

  • Resolution set to wontfix
  • Status changed from new to closed

wontfix'd in favor of #1483, which was implemented in [2814], which as nacin noted is much better parsed on the fly rather than introducing a shortcode (which I believe @DrewAPicture has since agreed with).

Note: See TracTickets for help on using tickets.