Skip to content

Use Markdown code fence notation instead of shortcodes to denote code blocks #44

@coffee2code

Description

@coffee2code

Related to the prematurely closed #38, which was partially worked around in #meta5346 and the non-worked-around part has now been raised in #meta5443 (which I'm going to close since this ticket will address the issue), formatting for code encapsulated within code shortcodes are not always properly retained (in particular, HTML entity display). I'll quote what I said there:

This is an outstanding issue in general that for which the likely culprit is the SyntaxHighlighter Evolved plugin's handling of code shortcodes. Its block handling is superior and doesn't have this issue, but in this case the Code Standards Handbook is fully imported from GitHub, and thus originates as text in a Markdown format.

I believe the issue would be resolved if the source documents avoided the use of code shortcodes (e.g. [php], [html], [css], [javascript], or [code]) and instead used triple backticks (with optional language hinting) without pre-encoding, e.g.

```html
<?php if ( have_posts() ) : ?>
<div class="hfeed">
    <?php while ( have_posts() ) : the_post(); ?>
         <article id="post-" class="">
             <!-- ... -->
         </article>
    <?php endwhile; ?>
</div>
<?php endif; ?>
```

The Block Editor Handbook is also imported from GitHub and uses backticks (e.g. [a source .md file[(https://github.com/WordPress/gutenberg/edit/master/docs/designers-developers/developers/themes/theme-json.md) and its resultant handbook page) which could be used for reference.

What needs to happen:

  • Convert all existing uses of shortcodes (for 'css', 'html', 'js', and 'php') to Markdown code fence notation
  • Update style guide to require use of markdown instead of shortcodes
  • Update style guide to render the Markdown code examples intended to demonstrate use of code fences rather than formatting the code for display
  • Update style guide to include 'HTML' as a type of 'Fenced Code Block'

PR forthcoming.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions