Switch to using Markdown code fence notation instead of shortcodes and update style guide accordingly. #45

coffee2code · 2020-09-25T23:24:10Z

Switches to using Markdown code fence notation instead of shortcodes
Removes HTML entity substitutions as they are no longer necessary.

Style guide:

Removes 'Shortcodes' section as shortcodes are no longer recommended. Markdown code fences, as described in prior section, is the preferred method.
Escapes the code fence examples so the Markdown code fence notation themselves are shown. The examples intend to demonstrate the use of code fences (often with language hinting) but when unescaped this results in the code being formatted instead of shown.
Adds an 'HTML' example to the 'Fenced Code Blocks' section as that appears to have been an oversight.

Fixes #44.

Pages look better when viewed as Markdown and, more importantly, are imported into handbooks with better formatting retention. Also removes HTML entity substitutions as they are no longer necessary.

…e fences. * Removes 'Shortcodes' section as shortcodes are no longer recommended. Markdown code fences, as described in prior section, is the preferred method. * Escapes the code fence examples so the Markdown code fence notation themselves are shown. The examples intend to demonstrate the use of code fences (often with language hinting) but when unescaped this results in the code being formatted instead of shown. * Adds an 'HTML' example to the 'Fenced Code Blocks' section as that appears to have been an oversight. Fixes WordPress#44.

jrfnl

@coffee2code Looks good. I left some inline remarks for you to consider.

It would be amazing if this finally solved the code sample display issue 🤞

Honest question: throughout the rest of the text, HTML is still used. Should/can the rest of the text now be converted to markdown too ? (as per the styleguide)

jrfnl · 2020-09-25T23:38:13Z

styleguide.md


 ### Fenced Code Blocks

 #### Javascript
+````
 ```js


The actual pages now use triple-backtick + javascript, while here in the style guide it shows to use triple backtick + js. Which is correct ?

Good catch! This was the pre-existing recommendation that I neglected to update.

jrfnl · 2020-09-25T23:39:54Z

wordpress-coding-standards/javascript.md

 elements
 	.addClass( 'foo' )
 	.children()
 		.html( 'hello' )
 	.end()
 	.appendTo( 'body' );
-	[/javascript]
+	```


Shouldn't this fencing closer be at the start of the line ?

jrfnl · 2020-09-25T23:44:24Z

wordpress-coding-standards/css.md

-&042;/
+```css
+/**
+* #.# Section title


These lines all need a space at the start (before the *) I think, to align the stars.

Agreed, I think this is common, eg https://github.com/WordPress/twentytwenty/blob/6d0a5240af108d02f58ec797fd49b32458a4c698/style.css#L234-L240

jrfnl · 2020-09-25T23:46:11Z

wordpress-coding-standards/javascript.md

@@ -530,19 +530,19 @@ var arr = _.chain( obj )
 	// Exit the chain
 	.value();

-// arr === [ 'first comes thing 1', 'second comes thing 2', 'third comes lox' ][/javascript]
+// arr === [ 'first comes thing 1', 'second comes thing 2', 'third comes lox' ]```


Shouldn't this fencing closer be on a line by itself ?

jrfnl · 2020-09-25T23:47:02Z

wordpress-coding-standards/php.md

-[tab]$foo5  = 'somevalue4';
-[/php]
+```php
+	$foo   = 'somevalue';


The [tab] markings were there on purpose to show tabs should be used not spaces.

jrfnl · 2020-09-25T23:47:27Z

wordpress-coding-standards/php.md

 $args = array(
-[tab]'post_type'   => 'page',


jrfnl · 2020-09-25T23:47:45Z

wordpress-coding-standards/php.md

-[tab]case 'bar':
-[tab][tab]some_function();
-[tab][tab]break;
+	case 'foo':


ntwb

Thanks @coffee2code, fingers crossed when this syncs 😏

@jrfnl Comments covered it all I can see, update and merge away 💯

* Correct styleguide to recommend 'javascript' as language hint for code fences (as used in all examples) * Restore `[tab]` as they are intended to be rendered as-is * Add space before multiline comment to align asterisks * Fix errant positioning of closing code fences

jrfnl

LGTM!

ntwb · 2020-10-11T23:51:19Z

Merging this in now, will check how it all looks after sync shortly

ntwb · 2020-10-12T00:54:11Z

Checking various pages, the only issue I'm seeing as single quotes using ' rather than '
These still have some issues:

https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#description-formerly-long-description
Source for this code snippet, encoding wasn't changed in this PR, just the shortcode change

* Description including a code sample:
*
*    $status = array(
*        &#039;draft&#039;   => __( &#039;Draft&#039; ),
*        &#039;pending&#039; => __( &#039;Pending Review&#039; ),
*        &#039;private&#039; => __( &#039;Private&#039; ),
*        &#039;publish&#039; => __( &#039;Published&#039; )
*    );
*
* The description continues on ...

A few more instances of similar encoding issues as the above:

coffee2code added 2 commits September 25, 2020 16:09

Switch to using Markdown code fence notation instead of shortcodes

7f0d4c1

Pages look better when viewed as Markdown and, more importantly, are imported into handbooks with better formatting retention. Also removes HTML entity substitutions as they are no longer necessary.

jrfnl reviewed Sep 25, 2020

View reviewed changes

ntwb approved these changes Sep 26, 2020

View reviewed changes

coffee2code requested a review from jrfnl September 28, 2020 21:50

jrfnl approved these changes Sep 29, 2020

View reviewed changes

ntwb merged commit eb0aa61 into WordPress:master Oct 11, 2020

ntwb mentioned this pull request Oct 13, 2020

Single Quotes using ' instead of ' #46

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Switch to using Markdown code fence notation instead of shortcodes and update style guide accordingly. #45

Switch to using Markdown code fence notation instead of shortcodes and update style guide accordingly. #45

coffee2code commented Sep 25, 2020

jrfnl left a comment

jrfnl Sep 25, 2020

coffee2code Sep 28, 2020

jrfnl Sep 25, 2020

jrfnl Sep 25, 2020 •

edited

Loading

ntwb Sep 26, 2020

jrfnl Sep 25, 2020

jrfnl Sep 25, 2020

jrfnl Sep 25, 2020

jrfnl Sep 25, 2020

ntwb left a comment

jrfnl left a comment

ntwb commented Oct 11, 2020

ntwb commented Oct 12, 2020 •

edited

Loading

Switch to using Markdown code fence notation instead of shortcodes and update style guide accordingly. #45

Switch to using Markdown code fence notation instead of shortcodes and update style guide accordingly. #45

Conversation

coffee2code commented Sep 25, 2020

jrfnl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jrfnl Sep 25, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ntwb left a comment

Choose a reason for hiding this comment

jrfnl left a comment

Choose a reason for hiding this comment

ntwb commented Oct 11, 2020

ntwb commented Oct 12, 2020 • edited Loading

jrfnl Sep 25, 2020 •

edited

Loading

ntwb commented Oct 12, 2020 •

edited

Loading