5. Cómo funciona nanoc
Cuando creas un sitio usando
$ nanoc create_site nombre_del_proyecto
nanoc crea una serie de carpetas:
- nombre_del_proyecto
- content (donde guardaremos el contenido de cada página)
- layouts (aquí estarán los distintos layouts de nuestro site)
- lib (aquí guardaremos los plugins y extensiones que creemos)
- tasks (para guardar tareas de Rake)
- templates (plantillas para el contenido del site)
La idea fundamental de nanoc es separar el diseño del contenido.
Cuando compilas el site, nanoc incrusta el contenido de cada página en su layout correspondiente, genera el HTML y lo copia a la carpeta de salida (por defecto es 'output')
Vamos a verlo con un ejemplo.
Nuestra primera página
Vamos a empezar creando un proyecto nanoc de pruebas:
$ nanoc create_site nanoc_ejemplo
create config.yaml
create Rakefile
create tasks/default.rake
create content/content.yaml
create content/content.html
create asset_defaults.yaml
create page_defaults.yaml
create layouts/default/default.yaml
create layouts/default/default.html
create templates/default/default.yaml
create templates/default/default.html
create lib/default.rb
Created a blank nanoc site at 'nanoc_ejemplo'. Enjoy!
$ cd nanoc_ejemplo
$
Ya tenemos listo el esqueleto de nuestro primer site con nanoc. Podemos compilar el contenido por defecto usando
$ nanoc compile
Compiling site...
create [0.00s] output/index.html
Site compiled in 0.00s.
$
Para ver qué ha generado nanoc, podemos arrancar el servidor web que incorpora nanoc ejecutando:
$ nanoc autocompile
Ahora puede abrir un navegador y visitar http://0.0.0.0:3000/ donde verás nuestra glamourosa página por defecto.
Muy interesante... ¿cómo cambio el contenido de la página?
Si abres el directorio nanoc_ejemplo/content verás un fichero content.html y un fichero content.yaml
Estos dos ficheros definen el contenido (content.html) y los metadatos de una página (content.yaml).
Edita el contenido de content.html y escribe lo siguiente:
Este es mi nuevo contenido :)
Guarda el documento, y si no has cerrado el terminal donde ejecutaste nanoc aco, sólo tendrás que actualizar el navegador.
Muy bien... ya sabemos cómo cambiar el contenido de la página de inicio...
¿Y de dónde sale el resto del código?
Si miras el código fuente de la página de inicio, verás algo como esto:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>A Brand New nanoc Site - Home</title>
<style type="text/css" media="screen">
...
</style>
</head>
<body>
<div id="main">
Este es mi nuevo contenido...
</div>
<div id="sidebar">
<h2>Documentation</h2>
<ul>
<li><a href="http://nanoc.stoneship.org/help/tutorial/">Tutorial</a></li>
<li><a href="http://nanoc.stoneship.org/help/manual/">Manual</a></li>
</ul>
<h2>Community</h2>
<ul>
<li><a href="http://groups.google.com/group/nanoc/">Discussion Group</a></li>
<li><a href="http://groups.google.com/group/nanoc-es/">Spanish Discussion Group</a></li>
<li><a href="http://nanoc.stoneship.org/trac/">Wiki</a></li>
</ul>
</div>
</body>
</html>
¿De dónde sale el resto del HTML?
Si miras en nanoc_ejemplo/layouts/default/, encontrarás un fichero default.html que contiene este código:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>A Brand New nanoc Site - Home</title>
<style type="text/css" media="screen">
...
</style>
</head>
<body>
<div id="main">
<%= @page.content %>
</div>
<div id="sidebar">
<h2>Documentation</h2>
<ul>
<li><a href="http://nanoc.stoneship.org/help/tutorial/">Tutorial</a></li>
<li><a href="http://nanoc.stoneship.org/help/manual/">Manual</a></li>
</ul>
<h2>Community</h2>
<ul>
<li><a href="http://groups.google.com/group/nanoc/">Discussion Group</a></li>
<li><a href="http://groups.google.com/group/nanoc-es/">Spanish Discussion Group</a></li>
<li><a href="http://nanoc.stoneship.org/trac/">Wiki</a></li>
</ul>
</div>
</body>
</html>
Los bloques de <%= ... %> son marcas de ERB que sirven para incrustar el contenido de la página en la plantilla. @page.title y @page.content son dos variables de Ruby que contienen los datos de la página. Al compilar la plantilla, nanoc reemplaza las variables por el contenido de cada página.
¡Pero yo no he puesto ningún título de página!
Efectivamente... si abres el fichero nanoc_ejemplo/content/content.yaml verás lo siguiente:
# Built-in
# Custom
title: Home
Prueba a cambiar el campo title, guarda y recarga la página...
TextMate Power Tip: activa en "Preferences » Advanced » Save Files when Focus is Lost" y no tendrás que volver a preocuparte de guardar un fichero al cambiar de aplicación :)
¿Y qué metadatos puedo usar en la página?
Por defecto, nanoc "entiende" los siguientes campos en una página:
- custom_path: Ruta que tendrá el fichero una vez se compile, añadiéndole un
/al inicio. Por ejemplo, la página feed.xml puede tener como ruta/feed.xml - extension: La extensión del fichero compilado. Muy útil para crear ficheros .css, .js o .xml
- haml_options: Opciones para el filtro Haml, si lo usas.
- filename: Nombre del fichero una vez compilado. Por defecto es
index - filters: Una lista de filtros que quieras aplicar al contenido. Por defecto no se usa ninguno (texto plano)
- is_draft: Si es "true", la página no se compilará. Muy útil para no enviarle páginas a medio terminar a tu cliente :)
- layout: Nombre del layout que usaremos para esta página. Te vendrá de maravilla para los sitios que tienen varios diseños dependiendo de la sección.
- skip_output: Determina si quieres exportar esta página. Por defecto es "true".
Además de los campos por defecto, puedes usar cualquier atributo que se te ocurra. Por ejemplo, el campo title no está en la lista de los atributos que entiende nanoc :)
Para usar un atributo propio en el contenido de una página o en un layout, usa <%= @page.nombre_de_atributo %>.
Por ejemplo, si quisieras usar un atributo "sección", pondrías en content.yaml
seccion: "Sobre Nosotros"
y estaría disponible en tus plantillas como
<%= @page.seccion %>
Creando una página nueva
$ nanoc cp test_page
create content/test_page/test_page.yaml
create content/test_page/test_page.html
A page has been created at /test_page/.
Cambiando la ruta de salida de una página
Cambiamos content/test_page/test_page.yaml y añadimos:
custom_path: /ruta_de_la_pagina.html
(Importante: que no se te olvide la / inicial)
Partials
Usando el helper "render" (incluído por defecto por nanoc), podemos incluir ficheros ("partials") en nuestros ficheros. Por ejemplo,
<%= render 'head' %>
incluirá el layout 'head' de la carpeta 'layouts'
<%= render 'head', :title => 'Foo' %>
Incluye el contenido de la plantilla 'head', y dentro de la misma asigna a la variable @title el valor "Foo".
Sigamos
Paso siguiente, tuneando nanoc