Blog tagged site

Welcome to!

Today, we're proud to announce a dedicated Ceylon community, Simultaneously, we're opening up access to our git repositories and even providing a special pre-release build of the Ceylon IDE, only for the truly adventurous.

We're not yet quite ready to release Milestone 1, due to a number of unsolved bugs and integration issues. But we're working really hard to get these sorted out!

I'm taking this opportunity to thank Red Hat's James Cobb for the web design, Emmanuel Bernard for setting up the infrastructure behind this site, and Tom Bentley for helping with much of the content. And, while I'm mentioning people's names, I would also like to thank new hires Stef Épardaud and Tako Schotanus for all the work they did getting the compiler up and running as volunteer contributors before coming on board, and David Festal from SERLI for making the IDE happen.

If you're interested in contributing to Ceylon, now is a really great time to get involved!

Wire the site with spec and ceylondoc

The site now integrates the specification and the ceylondoc for ceylon.language.

How to build the integrated site

Run ./ from the root of your repository. This will

  • clone or refresh the ceylon-spec, ceylon.language and ceylon-compiler repos
  • build the documentation as of the latest in master
  • push the bits in the generated directory of awestruct

How to reference the spec or the ceylondoc

This information is out dated and has changed in later versions of the website, check out our how to edit a page section.

If you want to point the spec to a user in the site, point to /documentation/1.0/spec. This page show the spec in HTML, HTML in single page and PDF.

If you want to point to a specific paragraph in the spec, use the variable site.urls.spec.current and the anchor to the paragraph in the spec.

eg This is a [pointer to the spec](#{site.urls.spec}#anchor-in-spec).

That means the specification anchors should be stable.

Likewise, to point to a ceylondoc entry, use the variable site.urls.apidocs.

[Doc for Comparable](#{site.urls.apidoc_current}/ceylon/language/Comparable.html)

By using these placeholders, we will be able to move the spec or ceylondoc to other places. Note that /documentation/1.0/api page is pretty useless as it is but should be fixed in ceylondoc.

Changed syntax highlighting

I've been writing quite a lot of documentation lately, and my previous decision to require an HTML comment in order to get syntax highlighting of Ceylon code started to look like the wrong choice. Since the vast majority of the code blocks on the site are going to be Ceylon source, and since we're (almost?) always going to want that highlighted I've changed the rules:

  • Now all indented code blocks will be assumed to be Ceylon source code that requires syntax highlighting, unless indicated otherwise.
  • If the source code is not Ceylon, you can use a <!-- lang: foo --> comment (having setup the syntax highlighter and gsub transformer to do highlighting for the language foo).
  • If you don't want any highlighting at all use <!-- lang: none -->

Improved syntax highlighting and deep linking

A couple of improvements to the site generation have been added.

Syntax highlighting

We were previously using literal <pre> blocks in markdown pages so that we could set the CSS necessary for the syntax highlighter. The big downside of this was the need to HTML-escape the code within those <pre> blocks. Using an awestruct 'transformer' it's now possible to use the more natural markdown way of including example code (i.e. using indentation), which means you don't have to worry about using HTML entities for <, & etc.

By default <pre> blocks will not be subject to highlighting. To enable highlighting simply preceed the block with an HTML comment hinting at the language being included. For example

    class Foo() {
        void bar() {


It's also easy to have a page with syntax highlighting of multiple languages, by using an appropriate hint.

For those who are interested, the way this works is having a transformer perform a global gsub on the generated output using a suitable regular expression to pick out the code blocks generated by markdown.

Deep linking

Markdown by itself doesn't allow the author to put id attributes or anchors (<a name="...">) in the generated HTML, which is annoying if you want to link to a particular part of the page. You can of course put <a name="..."> elements in yourself, but:

  • It clutters up the nice markdown with HTML.
  • It forces you to ensure the uniqueness of the ids you use.
  • It's tedious.

Using another transformer we now generate id attributes automatically for all <h*> and <p> elements. For headings we use the heading text (suitably munged into an XML NAME). For paragraphs we use the first few words (again suitable normalized, and also worrying about uniqueness). If an element already has an id then it's untouched. If there's a matching id (or name, since they share the same namespace), steps are taken to disambiguate the generated one.

The long and the short of this is that we can now easily and accurately link into the middle of documents. The caveat is that you should be aware that changing the first few words of a paragraph (or the text of a heading) is likely to break any links which point to it. To prevent such broken links you can always use an explicit <a name=""> at the relevant point.

Home page has a news section

The website home page now has an automatically filled news section.

When you want to advertize a news, add a file to _data/news with the following structure

title: 'My exciting news'
date: 29 August, 2011
more_info_url: /my/url/with/more/details
effective_date: 20110829
Some exciting news today.

A typical example would be

title: 'News section is up'
date: 29 August, 2011
more_info_url: /blog/2011-08-29-news-section/
effective_date: 20110829
The website news section is now up.


I could have reused blog entries tagged #news but it turns out that the first 50 characters a not often useful. So I've decided to go for the explicit _data/news structure.