You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

readme.txt 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394
  1. === Prismatic ===
  2. Plugin Name: Prismatic
  3. Plugin URI: https://plugin-planet.com/
  4. Description: Display beautiful syntax-highlighted code snippets with Prism.js or Highlight.js
  5. Tags: code, css, fence, highlight, language, pre, prettify, prism, snippet, syntax
  6. Author: Jeff Starr
  7. Contributors: specialk
  8. Author URI: https://plugin-planet.com/
  9. Donate link: http://m0n.co/donate
  10. Requires at least: 4.1
  11. Tested up to: 4.6
  12. Stable tag: 1.0
  13. Version: 1.0
  14. Text Domain: prismatic
  15. Domain Path: /languages
  16. License: GPL v2 or later
  17. Display beautiful syntax-highlighted code snippets with Prism.js or Highlight.js
  18. == Description ==
  19. __The only 3-in-1 syntax highlighter!__
  20. Display beautiful code snippets with Prism.js, Highlight.js, or plain code escaping:
  21. * __Prism.js__ - Code escape + syntax highlight using [Prism.js](http://prismjs.com/)
  22. * __Highlight.js__ - Code escape + syntax highlight using [Highlight.js](https://highlightjs.org/)
  23. * __Plain Flavor__ - Code escape without syntax highlight (for custom styles)
  24. **Prism.js Features**
  25. * Supports over __30__ coding languages
  26. * Choose from all __7__ available Prism themes
  27. * Enable Prism plugin [Line Numbers](http://prismjs.com/plugins/line-numbers/)
  28. * Enable Prism plugin [Line Highlight](http://prismjs.com/plugins/line-highlight/)
  29. * Enable Prism plugin [Show Language](http://prismjs.com/plugins/show-language/)
  30. * Highlights code in post content, excerpts, and comments
  31. * Detects `language-` and `lang-` class prefixes
  32. * Limit syntax highlighting to Posts and Pages
  33. * Highlight single-line and multi-line code
  34. * Granular control over code escaping
  35. * Smart loading of CSS & JS assets
  36. **Highlight.js Features**
  37. * Supports __22__ coding languages
  38. * Choose from all __77__ available Highlight themes
  39. * Customize the Highlight.js init JavaScript
  40. * Highlights code in post content, excerpts, and comments
  41. * Limit syntax highlighting to Posts and Pages
  42. * Highlight multi-line blocks of code
  43. * Detects `language-` and `lang-` class prefixes
  44. * Enable support for no-prefix class names
  45. * Granular control over code escaping
  46. * Smart loading of CSS & JS assets
  47. **Plain Flavor Features**
  48. * Enable code escaping for post content, excerpts, and/or comments
  49. * Enable code escaping on the frontend, Admin Area, or both
  50. * Escapes single-line and multi-line code snippets
  51. **General Features**
  52. * Easy to set up & configure
  53. * Built with the WordPress API
  54. * Squeaky clean, error-free code
  55. * Born of simplicity, no frills
  56. * Lightweight, fast and flexible
  57. * Focused on performance and security
  58. * Loads CSS/JS assets only when required
  59. * Adheres to HTML coding best practices
  60. _Prismatic escapes only the essentials to keep your code clean._
  61. [Check out the screenshots](https://wordpress.org/plugins/prismatic/screenshots/) for more details!
  62. == Screenshots ==
  63. 1. Prismatic General Settings
  64. 2. Prismatic Prism.js Settings
  65. 3. Prismatic Highlight.js Settings
  66. 4. Prismatic Plain Flavor Settings
  67. 5. Prism.js : Twilight theme (choose from 7 Prism.js themes!)
  68. 6. Highlight.js : Arduino Light theme (choose from 77 Highlight.js themes!)
  69. 7. Highlight.js : Gruvbox Dark theme (choose from 77 Highlight.js themes!)
  70. 8. Cleanly escaped code without syntax highlighting (Plain Flavor)
  71. == Installation ==
  72. **Installing Prismatic**
  73. 1. Make a backup of your database
  74. 2. Upload the plugin to your blog and activate
  75. 3. Visit the plugin settings to configure options
  76. __Note:__ Please read the section below on "code escaping" to understand how it works.
  77. _[More info on installing WP plugins](http://codex.wordpress.org/Managing_Plugins#Installing_Plugins)_
  78. **Uninstalling**
  79. Prismatic cleans up after itself. All plugin settings will be removed from your database when the plugin is uninstalled via the Plugins screen.
  80. **Restore Default Options**
  81. To restore default plugin options, either uninstall/reinstall the plugin or visit the Prismatic General Settings > Restore default plugin options.
  82. **Usage: Syntax Highlighting**
  83. The Prismatic plugin follows the same conventions used by [Prism.js](http://prismjs.com/) and [Highlight.js](https://highlightjs.org/). Here are the basic steps:
  84. 1. Visit the Prismatic General Settings and choose your library
  85. 2. Visit the settings tab for your chosen library
  86. 3. Choose a theme and configure your options
  87. Once the settings are configured, you can enable syntax highlighting for any code snippet by doing one of the following:
  88. __Wrap multi-line code with pre & code tags:__
  89. <pre><code><pre><code>put your code here</code></pre></code></pre>
  90. __Wrap single-line code with code tags:__ (Prism.js only)
  91. <code>put your code here</code>
  92. With the proper markup in place, you can indicate a specific language by adding a class of `language-***` or `lang-***` to the `<code>` tag (where `***` is the language identifier).
  93. For example, to indicate PHP as the language for a single-line code snippet (Prism.js only):
  94. <code class="language-php"><?php echo 'Hello world'; ?></code>
  95. Likewise, to indicate HTML as the language for a multi-line code snippet:
  96. <pre><code class="language-html">
  97. <table>
  98. <tr>
  99. <th>Name</th>
  100. <th>Side</th>
  101. <th>Role</th>
  102. <tr>
  103. <td>Darth</td>
  104. <td>Dark</td>
  105. <td>Sith</td>
  106. </tr>
  107. </table>
  108. </code></pre>
  109. So the prefix of the class names are the same for Prism.js and Highlight.js. The difference is the language identifier used to specify each language. Check out the following "About Prism.js" and "About Highlight.js" sections for more information.
  110. __Note:__ In addition to detecting the `language-` and `lang-` prefixes, Highlight.js also will try to auto-detect the language without it being specified. Plus as an option, you can enable the Highlight.js setting, "Support no-prefix class names" to enable use of language identifiers without any `language-` or `lang-` prefix.
  111. **Usage: Code escaping**
  112. Just like Prism.js and Highlight.js, the Prismatic plugin follows HTML coding standards. To enable code escaping:
  113. 1. Visit the Prismatic General Settings and choose your library
  114. 2. Enable "Code Escaping" via the settings tab of your chosen library
  115. 3. Do one of the following:
  116. * Wrap single-line code with code tags: `<code>...</code>`
  117. * Wrap multi-line code with pre &amp; code tags: `<pre><code>...</code></pre>`
  118. For example, the code snippets included in either of the following markup examples would be escaped:
  119. This is a single-line example, <code><?php echo 'Hello world'; ?></code>.
  120. This is a multi-line code example:
  121. <pre><code>
  122. <table>
  123. <tr>
  124. <th>Name</th>
  125. <th>Side</th>
  126. <th>Role</th>
  127. <tr>
  128. <td>Darth</td>
  129. <td>Dark</td>
  130. <td>Sith</td>
  131. </tr>
  132. </table>
  133. </code></pre>
  134. So what exactly happens when the "Code Escaping" options are enabled? Here is a summary that applies to each section (post content, excerpts, and comments):
  135. * __Frontend only__ - code snippets are escaped at runtime (no changes made to content in the database)
  136. * __Admin Area only__ - code snippets are escaped when viewed via the Admin Area (changes will be saved to database if the "Update" or "Publish" button is clicked)
  137. * __Frontend &amp; Admin Area - both of the previous are applied
  138. * __None__ - all code escaping is disabled
  139. Note that each library -- Prism.js, Highlight.js, and Plain Flavor -- features its own code-escape settings. So the code-escape settings that are applied depends on the currently active library. Visit the plugin's General Settings to choose your library. Then visit that library's tab to configure its code-escape settings.
  140. When code escaping is enabled for either/both the frontend or Admin Area, the plugin makes the following changes to any code contained within `<code></code>` tags:
  141. \r removed
  142. & replaced with &amp;
  143. < replaced with &lt;
  144. > replaced with &gt;
  145. trailing whitespace removed
  146. These are the _only_ changes made to your code, no other changes are made.
  147. As mentioned, the difference between code escaping on the frontend vs. the Admin Area is that, on the frontend, the above changes are made at runtime and not saved to the database; whereas in the Admin Area, the changes are made when the code is viewed via a content editor, such that any changes made will be saved to the database when the user clicks the "Update" or "Publish" button. Please keep this in mind when choosing your code-escape settings.
  148. __Important!__ As explained, enabling code escaping in the Admin Area may result in the escaped code getting saved in the database. This is fine in most cases, but there may be situations where escaping should only happen at runtime. If that is the case, or if you are unsure, choose the "Frontend only" option for the "Code Escaping" setting. The "Frontend only" option only modifies code when displayed on the frontend and does not save any changes to the database.
  149. **About Prism.js**
  150. Prism.js version used in Prismatic plugin: __1.5.1__
  151. __Prism.js resources__
  152. * [Homepage](http://prismjs.com/)
  153. * [GitHub](https://github.com/PrismJS/prism)
  154. * [Changelog](https://github.com/PrismJS/prism/blob/gh-pages/CHANGELOG.md)
  155. __License &amp; Info__
  156. /*
  157. Prism: Lightweight, robust, elegant syntax highlighting
  158. MIT license http://www.opensource.org/licenses/mit-license.php/
  159. @author Lea Verou http://lea.verou.me
  160. */
  161. __Supported Languages__
  162. Language Class
  163. Apache = apacheconf
  164. AppleScript = applescript
  165. Bash = bash
  166. C = c
  167. C# = csharp
  168. C++ = cpp
  169. C-like = clike
  170. CoffeeScript = coffeescript
  171. CSS = css
  172. Diff = diff
  173. Git = git
  174. HTTP = http
  175. Ini = ini
  176. Java = java
  177. JavaScript = javascript
  178. JSON = json
  179. Makefile = makefile
  180. Markdown = markdown
  181. Markup = markup
  182. NGINX = nginx
  183. Objective-C = objectivec
  184. Perl = perl
  185. PHP = php
  186. Python = python
  187. Ruby = ruby
  188. SASS = sass
  189. SCSS = scss
  190. SQL = sql
  191. Twig = twig
  192. YAML = yaml
  193. So for example, to specify a code block as C++, you would write:
  194. Single line: <code class="language-cpp">...</code>
  195. Multi-line: <pre><code class="language-cpp">...</code></pre>
  196. To disable Prism.js syntax highlighting for any code block, simply omit the language class.
  197. _I'm glad to add more languages, [make a suggestion](https://perishablepress.com/contact/)_
  198. **About Highlight.js**
  199. Highlight.js version used in Prismatic plugin: __9.7.0__
  200. __Highlight.js resources__
  201. * [Homepage](https://highlightjs.org/)
  202. * [GitHub](https://github.com/isagalaev/highlight.js)
  203. * [Changelog](https://github.com/isagalaev/highlight.js/blob/master/CHANGES.md)
  204. __License &amp; Info__
  205. /*
  206. Syntax highlighting with language autodetection.
  207. Copyright (c) 2006, Ivan Sagalaev https://highlightjs.org/
  208. All rights reserved. BSD3 License @ https://git.io/hljslicense
  209. */
  210. __Supported Languages__
  211. Language Class
  212. Apache = apache, apacheconf
  213. Bash = bash, sh, zsh
  214. C# = cs, csharp
  215. C++ = cpp, c, cc, h, c++, h++, hpp
  216. CSS = css
  217. CoffeeScript = coffeescript, coffee, cson, iced
  218. Diff = diff, patch
  219. HTML/XML = xml, html, xhtml, rss, atom, xjb, xsd, xsl, plist
  220. HTTP = http, https
  221. Ini = ini
  222. JSON = json
  223. Java = java, jsp
  224. JavaScript = javascript, js, jsx
  225. Makefile = makefile, mk, mak
  226. Markdown = markdown, md, mkdown, mkd
  227. Nginx = nginx, nginxconf
  228. Objective-C = objectivec, mm, objc, obj-c
  229. PHP = php, php3, php4, php5, php6
  230. Perl = perl, pl, pm
  231. Python = python, py, gyp
  232. Ruby = ruby, rb, gemspec, podspec, thor, irb
  233. SQL = sql
  234. So for example, to specify a code block as C++, you would write:
  235. Single line: <code class="language-cpp">...</code>
  236. Multi-line: <pre><code class="language-cpp">...</code></pre>
  237. To disable Highlight.js syntax highlighting for any code block, add a class of `nohighlight`, like so:
  238. <code class="nohighlight">...</code>
  239. _I'm glad to add more languages, [make a suggestion](https://perishablepress.com/contact/)_
  240. == Upgrade Notice ==
  241. To upgrade Prismatic, remove the old version and replace with the new version. Or just click "Update" from the Plugins screen and let WordPress do it for you automatically.
  242. __Note:__ uninstalling the plugin from the WP Plugins screen results in the removal of all settings from the WP database.
  243. == Frequently Asked Questions ==
  244. **Can you add another language for Prism.js or Highlight.js?**
  245. Yes, feel free to [suggest a language](https://perishablepress.com/contact/)
  246. **Got a question?**
  247. Send any questions or feedback via my [contact form](https://perishablepress.com/contact/)
  248. == Support development of this plugin ==
  249. I develop and maintain this free plugin with love for the WordPress community. To show support, you can [make a cash donation](http://m0n.co/donate), [bitcoin donation](http://m0n.co/bitcoin), or purchase one of my books:
  250. * [The Tao of WordPress](https://wp-tao.com/)
  251. * [Digging into WordPress](https://digwp.com/)
  252. * [.htaccess made easy](https://htaccessbook.com/)
  253. * [WordPress Themes In Depth](https://wp-tao.com/wordpress-themes-book/)
  254. And/or purchase one of my premium WordPress plugins:
  255. * [BBQ Pro](https://plugin-planet.com/bbq-pro/) - Pro version of Block Bad Queries
  256. * [SES Pro](https://plugin-planet.com/ses-pro/) - Super-simple &amp; flexible email signup forms
  257. * [USP Pro](https://plugin-planet.com/usp-pro/) - Pro version of User Submitted Posts
  258. Links, tweets and likes also appreciated. Thank you! :)
  259. == Changelog ==
  260. **1.0 (2016/10/21)**
  261. * Initial release