Code block improvements

by Gabrys on 22 Mar 2010 23:16

flickr:1949843244

One of the most lovely features of Wikidot is support for code blocks. If you are a programmer, you probably want to share some pieces of your code. At Wikidot just wrap such a code in a [[code]][[/code]] tags (use [[code type="php"]] if you share PHP code) and you'll get beautifully highlighted code. Like this one:

<?php
$dna = '*';
echo str_replace(chr(42), $dna, base64_decode($dna));
?>

Inside code block, you can have [[include]] tags, that lets you combine code from other pages or even sites. This can be very useful, for example to show the source of a particular page:

[[code]]
[[include :blog:blog:_start]]
[[/code]]

This gives us:

[[module CSS]]
.footnotes-footer { 
    display: none;
}
[[/module]]

[[module ListPages limit="no" category="blog" date="@URL" tags="@URL" perPage="7" rss="Wikidot Blog" rssLimit="10"]]
[[div class="page-title blogpost-title"]]
%%linked_title%%
[[/div]]
[[div class="blogpost-author"]]
by %%created_by%% on %%date|%e %B %Y, %H:%M%%
[[/div]]
[[div class="blogpost-content"]]
%%short%% 
[[/div]]

[[div class="blogpost-comments"]]
[[a href="%%link%%#comments" class="icon"]]%%comments%% [[span class="icon-comments-alt"]]@<&nbsp;>@[[/span]][[/a]] [[a href="%%link%%" class="btn btn-default readmore"]]Read more[[/a]] 
[[/div]]
~~~~

---------

[[/module]]

This is exactly the wiki source of blog:_start page from blog.wikidot.com site!

Code block content is also available for download using specially constructed URL, like: http://themes.wikidot.com/green-fresh/code/1 .

When accessing this URL you will get the content of code block number 1 from the page Green Fresh from themes.wikidot.com.

Consult the documentation of Code Blocks for more details.

Nice, but

The ability to show a program or wiki code is really useful, but we would like to improve the way it works. There are a few ideas of how to make it work better.

Code block rendering via URLs

We want to improve the access of code blocks using URLs like /pagename/code/1 in the following ways:

  • When you extract a code block using its URL, includes will be resolved the same way as when you show the page. This would let you create (for example) CSS themes using cross-site includes and symbolic replacement (!).
  • Code blocks that are commented out won't be any longer accessible via the URL. If you need to access a commented code block you may need to wrap it in [[div style="display: none"]]  [[/div]] instead. Or, if you use this trick to inject custom HTML into your page, have a look at newly created html tag!
  • Code blocks that are formatted by the category _template will be accessible via the URL (today they're not).

All these changes would make code blocks accessed by URL identical to those appearing on a page.

Recognized languages

To make programmers and hackers even more happy we would like to increase the number of recognized languages. We have already had a few requests to add support for some languages, like SQL, BASH or C#. Right now it would be quite hard to do because the library we use to highlight the code is quite outdated and not developed anymore.

What we would like to do instead is to use one of JavaScript-based code highlighters, which are much more extendable. It's usually really easy to add support for another programming languages in them. We could even ask Wikidot users to write highlighting rules for Wikidot syntax. I believe this would be real fun for some of You :-).

With the changing of code highlighting library, we could make even more improvements. I would really love displaying the line numbers and a minimal header for each code block that would provide links to download the code, remove highlighting or toggle wrapping of long lines.

Code block processing

Last, but not least, we would like to introduce a minimal (but useful) processing of code blocks that could enable you to:

  • highlight a particular line
  • disable the processing of [[include]] and [[code]] tags inside of a code block, so you can show literal [[include]] instead of included page content, or use a literal [[/code]] tag inside your code block. Without a special way it would actually end your code block where that tag appears.

The idea of how to do this is using a special character — backslash — in the front of a line to trigger special handling of it. For example:

  • Prepend a line with "\@" (backslash at) to disable processing of special tags inside the code block (currently they are [[code]] and [[include]]). "@" corresponds to the use of "@@  @@" for escaping Wikidot code.
  • Prepend a line with "\*" (backslash asterisk) to highlight the line. "*" corresponds to the use of "**  **" to make the text inside bold.
  • Start a line with "\\" (backslash backslash) to display a line starting with a literal backslash.

Example

Let's see how that works:

[[code type="php"]]
<?php
\*$dna = '*';
echo str_replace(chr(42), $dna, base64_decode($dna));
echo "
\@[[include hello-world]]
\\n";
[[include footer]]
?>
[[/code]]

Line 2 ($dna = '*';) would be highlighted.
Line 5 would just say [[include hello-world]].
Line 6 would say \n";.
From line 7, there would be injected the source of page footer.
After that, there would be (as expected) literal ?>.

Nicer, isn't it

Let us know, if you like the changes suggested here. Internally we use code blocks very often and percive them as a very important tool, but is it as important to you? Do you use code blocks at all? Will using them be really easier if we improve them as described? We're waiting for your opinions and thoughts!



PHP code comes from http://www.patrickschneider.com/blog/2005/05/how-to-write-a-php-quine/

Comments: 15

Add a New Comment