Guide to Posting Code

Welcome Forums Web Site Feedback & Assistance Guide to Posting Code

Viewing 2 reply threads
  • Author
    Posts
    • #255725
      Senior Moderator
      Topics: 10
      Replies: 192
      Points: 1,031
      Helping Hand
      Rank: Community Hero

      The WordPress plugin used to display code on this forum was changed recently. The new plugin is called Crayon Syntax Highlighter. There are new features, and also some new issues. This guide will explain how to successfully post code using the new plugin.

      Crayon Dialog
      You can use Crayon by clicking on this button in the Text editor mode:
      Text editor Crayon button
      or this button in the Visual editor mode:
      Visual editor Crayon button
      but I’ve noticed that sometimes the button doesn’t display in the Visual editor mode:
      Visual editor Crayon button missing
      I’m not sure why this happens – the behavior seems inconsistent. The button in the Text editor seems to be always present.

      Either way, you should see this dialog box pop up:
      Crayon dialog box
      There are a lot of options in this dialog, but you don’t need to mess with them unless you want to explore. All you have to do is type or paste your code into the “Code” box and then click “Add” at the top, and your code will be inserted and will display properly in your post.

      Manual Formatting
      You can also produce good results by manually typing out the tags, but there are some complications.

      In order to decode HTML entities, you need to set decoding to true in the opening pre tag, which looks like this:

      This will force the greater than/less than symbols, ampersand, and quotation marks to decode from their HTML entity versions to their respective characters. With this attribute set, you should see

      rather than

      You can also use the code tag to format short bits of in-line code, but code does not accept attributes and does not decode greater than, less than or ampersand, as you can see here:
      > < & ' "
      I recommend avoiding this if you need to show code containing redirects.

      Additionally, the backtick (`) (also know as grave accent or backwards apostrophe) can be used the same as the code tag, but it does not decode any of the HTML entities:
      > < & ' "
      I recommend avoiding this entirely.

      New Features
      There are several features in Crayon that you can use to enhance the display of code in your post.

      Probably most useful, you can highlight specific lines in the code using the “mark” attribute, which is applied like this:

      Example:

      Crayon supports many code languages, so you can display non-PowerShell code if you need to. You can specify the language with the “lang” attribute, which is applied like this:

      Example:

      You can see the list of available languages in the Crayon dialog box. If you write the tag manually and you do not specify a language, Crayon will attempt to identify it based on command syntax, or will default to PowerShell.

      You can also assign a title to your code block with the “title” attribute, which is applied like this:

      Example:

      You can apply a theme to your code block with the “theme” attribute, which is applied like this:

      Example:

      Here’s a post that shows the available themes

      And of course, you can combine as many attributes inside of class="..." as you need. The attributes are separated with spaces, and the order does not matter:

      Example:

      Limitations & Issues
      The following methods for formatting code are not recommended as they produce various issues when displaying the code:
      Visual editor Format Code
      (Visual Editor -> “Format” Menu -> “Code”)
      Visual editor Format Blocks Preformatted
      (Visual Editor -> “Format” Menu -> “Blocks” -> “Preformatted”)
      Visual editor dropdown Preformatted
      (Visual Editor -> format dropdown -> “Preformatted”)

      Also, note that the forum no longer automatically parses gist links from github. You can still include code from an external source like a gist by pasting the link in the URL field of the Crayon dialog, or by adding the “url” attribute to the pre tag like this:

      Example:

      This must be a direct link to the code file, which on github is the “Raw” link.

      Why the change?
      The plugin we were using before had been out of active development for years. WordPress finally dropped it from its library of supported plugins, so it wasn’t available for us anymore.

      Technical
      The original Crayon Syntax Highlighter project isn’t actively developed, but there is a forked version that is being worked on and that’s the version we are using. You can see the project on github: https://github.com/urvanov-ru/crayon-syntax-highlighter
      There’s more information there, but it’s not completely documented and some of the information is carried over from the original and is consequently out of date.

      I’ve also done various feature testing in this thread, if you want to see more examples of what works and what doesn’t.

      This thread is open to take any questions related to posting code on the forum and using Crayon. Unrelated posts will be deleted.

      • This topic was modified 2 months, 2 weeks ago by grokkit.
      • This topic was modified 2 months, 2 weeks ago by grokkit.
      • This topic was modified 2 months, 2 weeks ago by grokkit.
      • This topic was modified 2 months, 2 weeks ago by grokkit.
      • This topic was modified 1 month, 4 weeks ago by grokkit.
    • #261015
      Senior Moderator
      Topics: 10
      Replies: 192
      Points: 1,031
      Helping Hand
      Rank: Community Hero

      The trouble with backticks
      The backtick character (`) is the escape character for PowerShell.

      Unfortunately, this conflicts with the way that bbPress (the forum software) handles backticks. They are used to wrap text in a forum post that should display as code (essentially, a legacy form of the code tag). This is a core feature of bbPress (not from a plugin, and not a configuration option) so we probably won’t be able to change it.

      There is a workaround. If you need to post PowerShell code containing escape sequences, you can replace the backticks in your code with their HTML entity code, which is written as `. If you use this inside of a pre class=”decode:true” block as described above, the forum will display a backtick character and won’t interpret the HTML entity code as a literal backtick, so it won’t break the formatting for your script.

      Example:

      These escapes are written inside a pre class=”decode:true” block like so:
      `" `n `r `t `a

      I realize this is not a great solution, but at the moment there isn’t a better one.

      • This reply was modified 1 month, 3 weeks ago by grokkit.
      • This reply was modified 1 month, 3 weeks ago by grokkit.
      • This reply was modified 1 month, 3 weeks ago by grokkit.
    • #264581
      Participant
      Topics: 0
      Replies: 1
      Points: -15
      Rank: Member

      Thank you for this helpful guide, I’m a newbie here and I hope I learn many new things from PowerShell.

Viewing 2 reply threads
  • You must be logged in to reply to this topic.