Welcome Download Install How to use Author License

How to use

The concept of nanon is very simple: define a tag that allows you to place the content of a file anywhere in your HTML code. The tag is <nanon> and it accepts the file parameter, where you specify the relative path to the file that you want to include. This way you can keep reusable code in separate files. A typical example is a navigation menu. All pages of the site are to display this menu. If they include it by the nanon tag, you only have to change the menu file and the nanon command will update the entire site.

A simple example

Suppose you have the following HTML page: 

page.html:

<html>
    <head>
        <title>Hello World</title>
        <link rel="stylesheet" href="style.css" type="text/css">
    </head>
    <body>
        <div id="header">
            <h1>My Site</h1>
            <h2>My Logo</h2>
        </div>
        <div id="menubar">
            <a href="option1.html">Option 1</a>
            <a href="option2.html">Option 2</a>
        </div>
        <div id="mainbar">
            Hello World...
        </div>
    </body>
</html>

This is a common situation: a header, a menu and some content. Suppose that you want to add pages to this site and you want to reuse the look and feel, the header and the menu. The menu will keep growing and you want to be able to change it in one place and propagate these changes to the entire site. Maybe at some point you want to change the look and feel. To do this with nanon, you would divide this page in 4 files: header.nmlx, footer.nmlx, menu.nmlx and page.nml. We use the extension ".nml" for files that are to be processed by nanon to generate ".html" files. NML stands for "Nanon Markup Language" which is equivalent to HTML but adds two extra tags. We already know about the <nanon> tag and will talk about the second one in a moment. Files with the extension ".nmlx" are to be included in ".nml" files but do not directly generate ".html" files.

So here's what you do: 


menu.nmlx:

<div id="menubar">
    <a href="option1.html">Option 1</a>
    <a href="option2.html">Option 2</a>
</div>
This file contains the menu bar. 

header.nmlx:

<html>
    <head>
        <title>Hello World</title>
        <link rel="stylesheet" href="style.css" type="text/css">
    </head>
    <body>
        <div id="header">
            <h1>My Site</h1>
            <h2>My Logo</h2>
        </div>
        <nanon file="menu.nmlx"></nanon>
        <div id="mainbar">
This file contains the header for HTML pages. It takes care of the usual HTML header definitions like page title and CSS file to use. Notice that it then uses the <nanon> tag to include menu.nmlx. 

footer.nmlx:

        </div>
    </body>
</html>
This file contains the footer for HTML pages and closes all the tags that header.nmlx left open. The header and footer files define the page template. As with the menu, these files can be changed later without affecting the content. Just use the nanon command to regenerate the site's pages. 

page.nml:

<nanon file="header.nmlx"></nanon>

Hello World...

<nanon file="footer.nmlx"></nanon>
This file defines the page itself. It begins by including the header and ends by including the footer.

All this work starts to pay off when you want to create more pages, because then you will only have to do something like this: 


page2.nml:

<nanon file="header.nmlx"></nanon>

This is another page with more stuff.

<nanon file="footer.nmlx"></nanon>

Running nanon

nanon is a command line tool. It processes all .nml files in the file mask you specify. For example: 

$ nanon *
Processes all .nml files in the current directory. 

$ nanon site/*
Processes all .nml files in the site directory. 

$ nanon site/page.nml
Processes the site/page.nml file. 

$ nanon -r *
The -r option makes nanon recurse into directories. In this case, .nml files contained in subdirectories of the current directory will also be processed. This is useful when you want to organize your site in a directory hierarchy.

nanon generates a .html file for every .nml file and use the same name so, for example, index.html will be generated for index.nml. All changes to your site must be made in .nml and .nmlx files.

Variables

In the previous sections we described basic nanon use. We will now explain how to use a more advanced feature: variables.

Variables have many uses but let's start with an example. Suppose you want each page in your site to have its own title, but you are reusing an header and that's were the title is specified. You can do this by passing a variable to the header. Let's apply this to our example site: 


page.nml:

<nanon file="header.nmlx" title="Hello"></nanon>

Hello World...

<nanon file="footer.nmlx"></nanon>
We are now passing the title variable to header.nmlx. It's now time to introduce the second nanon tag: <nanonv>. This tag allows you to place the value of some variable that was passed anywhere in HTML code. We will use it in header.html like this: 

header.nmlx:

<html>
    <head>
        <title><nanonv var="title"></nanonv></title>
        <link rel="stylesheet" href="style.css" type="text/css">
    </head>
    <body>
        <div id="header">
            <h1>My Site</h1>
            <h2>My Logo</h2>
        </div>
        <nanon file="menu.nmlx"></nanon>
        <div id="mainbar">
What happens is that <nanonv var="title"></nanonv> will be replaced with the value of variable title, in this case "Hello".

Any parameter that you give to <nanon> tags besides "file" will be considered a variable and passed to the imported file.

To finalize

We just described all the functionalities of nanon. It is a very simple tool and we intend to keep it that way, because we believe its power lies in its simplicity.

This site is generated with nanon and is available in the distribution file as a demo.