I was looking for a way to easily publish documentation for Dedomenon , the information storage engine behind MyOwnDB.com which I'm again developing heavily. And as I'm developing, I want to write complete and up to date documenation. I was looking for a hosted solution, which I wouldn't have to maintain myself, but I still wanted to have full control of the content, so I could easily move to another solution in the future if needed.

I thought of a wiki, but didn't go for it as I'm not sure of the export functionalities of hosted solution and the ease of integrating the content in a new solution. Each wiki seems to have its own markup, and I'm afraid that an export functionality is not enough to ensure long term availability of the content.

I then looked at Jekyll , a tool to maintains web sites (and more specifically blogs) developed by Github . It has some very compelling functionalities:

• can be hosted as Github pages, which responds to my hosting requirement
• content is written in markdown or textile. As I had some content in textile format already, it's a plus!
• I can write content with my prefered editor (vim)
• Hosting on github means I can (I must!) handle the content's history with git
• categorizes content based on the directories hierarchy

The only problem I had it that it didn't seem a ready-made solution to handle non-blog oriented website. But after some work, I got a working solution which is worth sharing: Jekyll Base .

Jekyll Base is simply the basic directory hierarchy expected by jekkyl, with a ready-to-use template offering:

• Cross-browser layout thanks to YUI Grids
• FreshPick based CSS
• Use of Yahoo’s CDN for delivery of YUI Grids files
• Google Analytics activated by putting site id in config file
• Google Ajax Search activated by putting your API key in the config file
• Listing of documents in current section
• List of subsections
• Breadcrumbs to help in navigation

It includes 2 helpers script to add sections and pages. You can of course see it in action at http://dedomenon.github.com/documentation .

Thanks to the use of YUI Grids, the template is very simple, though will render in all browser as expected. Combined with the FreshPick CSS, it gives an acceptable solution. This is particularly important as I'm really not a designer.

Jekyll Base source is available on github and its documentation is of course self-managed and hosted as Github pages at http://raphinou.github.com/jekyll-base/

ALL YUI 3 code on a page is placed in its own sandbox. This allows several parts of a page to be completely independent, with benefits in maintainability and stability: one sandbox cannot have any effect on another sandbox on the page, and a sandbox only uses the modules it needs. These sandboxes are create with YUI.use :

If you have a function based on YUI that you are going to reuse often, as I had with transitioning MyOwnDB to YUI 3, the best solution is to define it in a module that you'll use in each sandbox that needs it. Defining a module is done with YUI.add which also lets you specify which other modules it depends on. The body of the module is simply adding a namespage to YUI, which will hold all my code, defining the function and putting it under the namespace just created, like this:

Now I can simply use my new module and its associated function in any sandbox I define:

Thanks to Satake and Daniel Cook on the YUI Forum for their advice .

As I'm working on the new interface of MyOwnDB based on YUI, I have discovered 2 subtle differences between IE and FF when creating nodes with YUI 3.

1. You can't change attribute values of INPUT nodes created from a template using the long closing node syntax

Update: IE is actually doing the right thing, as the input tag does not accept a closing tag as defined by the W3C .

By long syntax, I mean closing a tag with an explicit closing tag:

as opposed to the short syntax:

If you create an input node with YUI3 based on the long syntax with IE, you won't be able to set attribute values:

The solution is to use the short syntax to close your tag:

Note that this is only for input nodes. Divs are workling fine with the long syntax:

2. With IE, you can't set the type of an input node to "file"

This code will generate a file field with FF, but a text field with IE:

If you want to make it work with IE, you have to make your template include the type attribute:

I've put a demo page for those interesting in the code, with a YUI console.

YUI2's Datatable is a great widget I use in MyOwnDB and here's a small tip for when you use it to load a remote data source .

In that case, the datatable is getting the data to display from a YUI2 DataSource that has been configured with the URL to use when fetching the data requested by the datatable.

When instanciating the datatable, you can pass it a configuration object, with amongst other option, the initialRequest that should be sent by the associated datasource when the datatable is displayed for the first time. initialRequest is a string that is simply appended to the URL passed to the DataSource.

So if your datasource URL is "http://www.myurl.com?all=true", and your initialRequest is "sort=name", the request sent by the DataSource will be for the URL "http://www.myurl.com?all=truesort=name", which is clearly not good.

The solution here is to either be sure that the datasource URL ends with a ? or a &, or to always start the initialRequest with &.

The second option is the easiest in my case.