For the rest of you we are going to install three further plug-ins:
- FixedPre (v 1.1)
- SyntaxHighlighter (v 1.0); and
- markdownOF (v 1.0 alpha)
FixedPre is a special purpose add-on that you may not need. It allows you embed Modx tags in your source listing without the parser actually rendering the element. A quick example will show you what I mean.
There were no search results for the search "". Please try using more general terms to get more results.
MarkdownOF is a plugin to convert Markdown text to HTML. We'll be talking a lot about this also. It is currently classed as Alpha release, so be cautious about implementing it on client's web sites. So far I've not had any issues, but your mileage may vary.
You should be quite practiced at installing plug-ins, so go ahead and install these three now.
Configuring and using SyntaxHighlighter
There are many options for SyntaxHighlighter. These are covered in part by Bob Ray's tutorial and in more detail in Alex Gorbatchev's pages. We are going to make just one change to the default configuration.
Out of the box, SyntaxHighlighter puts a bright green help "blob" on the RH side of the code block. Personally, I think this is ugly and it can also partially hide long first lines, like this:
To remove the blob, it is neccessary to edit the plugin chunk as follows:
- Find the SyntaxHighlighter plugin in the list of Elements
- Look for the line that says: SyntaxHighlighter.all();
- Add the following line immediately above this line and save: SyntaxHighlighter.defaults.toolbar = false;
- The resulting code should look like this:
The same change should be made to the SyntaxHighlighter snippet as well (I'm only using the plug-in, but we should be consistent).
The good news is that the green blob will no longer be present - the bad news is that this change will need to be made every time the plug-in is updated. If you don't want to change the original plugin/ snippet code, all is not lost - however you will need to add the toolbar: false parameter to every code block you display.
To use SyntaxHighlighter, it is as easy as enclosing the code to be displayed in a <pre> tag and applying the appropriate class. For example in the script above the following option pairs were applied:
<pre class="brush: php; highlight: ; html-script: true">
- use the php brush (the brush parameter is the only one that is mandatory)
- background highlight the second line
- syntax highlight the html script elements as well as those defined by the brush.
These and the other options are described on the SyntaxHighlighter site.
Configuring and using FixedPre
FixedPre requires no configuration. To use it simply wrap the Modx [[ ]] tags in <fixedpre> tags. For example:
If you are using SyntaxHighlighter the <fixedpre> tags must be inside <pre> tags.
Configuring and using MarkdownOF
First, a bit of background on Markdown and why I decided to use it.
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
As I became more familiar with Articles I began to realize that the editing options were not exactly optimal. Out of the box, your choices are plain-text or the TinyMce rich text editor. The problem with plain-text is you need to manually enter all the HTML tags which is not only tedious but highly prone to error. And the problem with TinyMce is that it has a mind of its own and if you have need of specialized tags (like <fixedpre> or <pre> for our source code plugins that we just installed) it will arbitrarily strip them out.
That led me to Markdown which, although I had not used it before, was familiar because of its close relationship to Wiki markup syntax (which I have previously used). The more I use Markdown, the more I like it. It is clean, easy to use and gets around all of my formatting issues. There is still one major problem however - I need to use a separate editor and copy/ paste the code into the plain text editor in Modx. It should not be necessary to perform this extra step, but I can find no easy* way to get around the need. It is, however, possible to use a Markdown output filter - which is what the MarkdownOF plugin is.
(*you could embed an editor like markitup into the Modx back-end, but I'm afraid that is way beyond my Modx knowledge - perhaps the Modx forums could help if you want to go down that path).
FYI, I chose the MarkdownPad editor because I liked the way you get an instant HTML preview.
All of the above is moot if you are building a blog for a client and they have need of a specific editor or if they are unable/ unwilling to use Markdown. This may be a deal-breaker - fortunately it is not for me.
So, after that small diversion, on to configuring and using MarkdownOF...
... and guess what - there is almost nothing to do. Wherever you have the [[*content]] placeholder, change it to [[*content:markdownOF]], then create your markdown content using whatever Markdown editor you choose, paste it into the Articles Content panel and press Save. The MarkdownOF snippet does the rest.
Coming up next
I've now got most of the functionality that I think I want in a blog. Time will tell whether that needs tweaking or not (the jury is still out on Categories). So next up I'm going to start adjusting the look and feel of my blog by applying a new template.