WordPress.org

Making WordPress.org

Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#1802 closed enhancement (fixed)

Restructure reference pages more logically and apply the TOC to allthethings

Reported by: DrewAPicture Owned by: drewapicture
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch has-screenshots
Cc:

Description

In [3563] for #1548, we implemented a table of contents for the explanation or "More Information" section of reference pages. With this ticket I'm proposing three extensions of that effort:

  1. Apply the table of contents to most if not all of the sections of any given reference page
  2. Slightly restructure the reference page sections and in some cases consolidate to provide a more logical flow of information within that table of contents.
  3. Slightly modify the TOC class in the handbook plugin to accept dynamic header text, defaulting to 'Topics'.

For #1, making it possible to apply the table of contents logic to multiple reference page sections requires splitting that content into pieces. My attached patch proposes splitting them all into individual template parts that we therefore capture in output buffering to output all at once.

For #2, I've also slightly restructured the ordering and consolidation of information, namely, made "Description" the top-level section, and moved Parameters, Return, Source, and Changelog under "Description". I've consolidate to two Source sections into one.

I've also grouped Uses and Used By under a new top-level "Related" section that we can further extend in the future with related functionality.

Finally this leaves us with roughly four top-level sections for any given reference page: Description, More Information, Related, and User Contributed Notes.

Before and after screenshots attached.

Attachments (8)

1802_before.png (517.5 KB) - added by DrewAPicture 3 years ago.
1802_after.png (548.0 KB) - added by DrewAPicture 3 years ago.
1802.diff (20.9 KB) - added by DrewAPicture 3 years ago.
1802_handbook.diff (1.2 KB) - added by DrewAPicture 3 years ago.
Handbook changes
1802.2.diff (21.0 KB) - added by DrewAPicture 3 years ago.
Missing <hr /> tags
1802_after.2.png (549.8 KB) - added by DrewAPicture 3 years ago.
w/ 1802.2.diff
1802_handbook.2.diff (1.2 KB) - added by DrewAPicture 3 years ago.
Arguments array
1802.3.diff (24.6 KB) - added by DrewAPicture 3 years ago.
Responsive styles

Download all attachments as: .zip

Change History (20)

#1 @DrewAPicture
3 years ago

  • Keywords has-patch has-screenshots added

@DrewAPicture
3 years ago

@DrewAPicture
3 years ago

Handbook changes

#2 @DrewAPicture
3 years ago

1802_handbook.diff includes the handbook plugin changes.

@DrewAPicture
3 years ago

Missing <hr /> tags

@DrewAPicture
3 years ago

Arguments array

#3 @theMikeD
3 years ago

I think this looks great and will make the page more cohesive and uniform.

#4 @drewapicture
3 years ago

In 3625:

developer.wordpress.org: Allow WPorg_Handbook_TOC to accept optional display arguments for overriding values such as the header text for the Table of Contents container.

See #1802.

@DrewAPicture
3 years ago

Responsive styles

#5 @drewapicture
3 years ago

In 3626:

developer.wordpress.org: Restructure reference pages to leverage a table of contents for the majority of the page output.

  • Splits large sections of content-reference.php into individual template parts captured via output buffering.
  • Introduces four top-level sections for any given reference page: Description, More Information (if an explanation exists), Related, and User Contributed Notes
  • Improves overall responsive styling for smaller viewports

See #1802.

#6 @drewapicture
3 years ago

  • Owner set to drewapicture
  • Resolution set to fixed
  • Status changed from new to closed

In 3627:

developer.wordpress.org: Bump styles version.

Fixes #1802.

#7 @drewapicture
3 years ago

In 3628:

developer.wordpress.org: Restore the .source-content class to the Source section tag, which is required for the source code accordion to operate.

See #1802.

#8 @drewapicture
3 years ago

In 3629:

developer.wordpress.org: Prevent breakage caused by unnecessarily passing all reference page content through the the_content filter on output.

  • The extra filtering is not necessary since the markup for the various reference pages handle this independently
  • Fixes broken user contributed notes output

See #1802.

#9 @kevinwhoffman
3 years ago

@drewapicture I'd like to recommend that the ToC links be styled in a way that better affords interaction. There is currently no indication that the black text is clickable, and the only hover effect is the default cursor change.

See the old styling of the Codex content menus for a possible quick fix.

#10 follow-up: @DrewAPicture
3 years ago

@kevinwhoffman Let's create a new ticket. Can you make one?

#11 in reply to: ↑ 10 @kevinwhoffman
3 years ago

Replying to DrewAPicture:

@kevinwhoffman Let's create a new ticket. Can you make one?

Done. See #1814.

#12 @drewapicture
3 years ago

In 3660:

developer.wordpress.org: Remove the id attribute from the related template <hr /> tag to prevent clashes with dynamically-added ToC markup.

See #1802.

Note: See TracTickets for help on using tickets.