Para iniciar el proyecto es recomendable tener clara la estructura que le daremos a nuestro contenido. El proyecto lo he llamado, de forma provisional, Kvintero³ y tiene la siguiente estructura de ficheros:

.
├── html
│   └── ... (directorio donde se publicará)
├── kvintero.el
├── org
│   ├── css
│   │   └── ... (hojas de estilo)
│   ├── img
│   │   └── ... (ficheros de imagen)
│   ├── js
│   │   └── ... (ficheros javascript)
│   └── ... (ficheros org)
├── plantillas
│   └── plantilla-base.org
└── README.org

se pueden apreciar algunas cosas así a bote pronto: los directorios org y html serán idénticos, pero mientras el primero está compuesto de los fuentes de org-mode el segundo es el resultado de convertir los fuentes en html. En esos directorios hay otros subdirectorios para la(s) hoja(s) de estilos, las imágenes y los archivos javascript. También hay un directorio que se llama plantillas, donde hay sólo un fichero de momento y más adelante analizaremos su contenido. Además de todo ésto también hay un fichero de código que se llama kvintero.el que contiene un par de formas que definen algunas variables del proyecto para poder exportar cómodamente en tres teclazos.

Es una estructura muy simple, aunque su visualización en árbol, pueda dar una primera impresión de complejidad. En realidad, sólo necesitas crear el directorio org y dentro de él: el css, el img y el js, cada uno con sus cosas, para que no se mezclen.

Para que dicha estructura sea efectiva es recomendable que luego, en los enlaces se utilicen siempre paths relativos. Para que el sitio desplegado o publicado, ─como prefieras llamarlo─, funcione incluso sin un servidor, es siempre recomendable el uso de dichos paths relativos. Además, se pueden utilizar anclas a etiquetas concretas dentro de otros ficheros org⁴, como veremos después.

Como he dicho antes, el código es muy sencillo, lo pongo aquí y luego lo comentaré un poco:

(require 'ox-publish)

(setq org-publish-project-alist
      '(
        ("fuentes-org"
         :base-directory "~/proyectos/kvintero/org/"
         :base-extension "org"
         :publishing-directory "~/proyectos/kvintero/html/"
         :recursive t
         :publishing-function org-html-publish-to-html
         :headline-levels 4
         :html-preamble t)
        ("org-auxiliares"
         :base-directory "~/proyectos/kvintero/org/"
         :base-extension "css\\|js\\|png\\|ttf"
         :publishing-directory "~/proyectos/kvintero/html/"
         :recursive t
         :publishing-function org-publish-attachment)
        ("kvintero" :components ("fuentes-org" "org-auxiliares"))))

La primera línea no necesita mucho que explicar: nos aseguramos que está en el sistema el paquete que proporciona ox-publish. Después de esa primera forma, nos encontramos con otra que establece la lista de proyectos para publicar. Cada elemento de la lista tiene una forma general tal que:

("nombre-proyecto" ...)

Vamos a analizarlo un poco más despacio.

Una forma de estandarizar y ahorrar tiempo en la publicación de los ficheros org, tanto en html como en pdf es proporcionar al sistema una plantilla que haga las veces de configuración de la página, estableciendo los valores oportunos. En esas plantillas lo que se hace, normalmente, es situar todas las opciones que pondríamos en la cabecera que sean comunes a todas las páginas. Para este proyecto he preparado la siguiente cabecera:

#+author:  Notxor
#+email:   notxor@nueva-actitud.org
#+options: ':t *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline author:t c:nil
#+options: creator:comment d:(not LOGBOOK) date:t e:t email:nil f:t inline:t
#+options: num:t p:nil pri:nil stat:t tags:t tasks:t tex:t timestamp:t toc:t
#+language: es
#+exclude_tags: noexport
#+select_tags:  export

#+options: html-postamble:auto html-postamble:nil tex:t
#+html_container: div
#+html_doctype: xhtml-strict
#+html_head: <link rel="stylesheet" type="text/css" href="css/tus-estilos-favoritos.css" />

Todos esos valores comunes pueden cambiar en un momento dado, porque se quiera mostrar una determinada página con otra hoja de estilos o porque varíen los paths, o por cualquier otro motivo. Estas cosas harán que necesitemos más tipos de cabecera. Por ejemplo, si creamos un subdirectorio dentro de nuestro sitio base y utilizamos la misma cabecera para publicar el sitio, no encontrará el fichero .css, necesitamos cambiar la última línea a:

#+html_head: <link rel="stylesheet" type="text/css" href="../css/style.css" />

Modificando el path en el que debe buscar la hoja de estilos.

Si ya tenemos una plantilla en la que basarnos, generar las demás que nos hagan falta es tan sencillo como copiar la plantilla-base y modificar los valores que queramos cambiar... y llamaremos a dicha plantilla desde el fichero que queramos con el formato:

#+setupfile: ../plantilla/plantilla-base.org
#+title: Este es el Título
#+subtitle: y este el Subtítulo

Como se puede apreciar, la cabecera queda resumida a dos o tres líneas, muchas veces será suficiente establecer el #+setupfile:, o como mucho añadirle un título.

Otro factor a destacar es que establecemos que utilizando la etiqueta noexport se puede eliminar todo un árbol interno del documento cuando lo exportamos.

* Notas    :noexport:

Esta información no se exportará al fichero ~html~

Yo comenzaré con un pequeño fichero de texto en formato org para empezar el proyecto, cualquier texto vale, yo he preparado estos pequeños párrafos para comenzar:

#+setupfile: ../plantillas/plantilla-base.org
#+title: Kvintero ─ Introducción

Dos campanas tañieron al unísono cuando se abrió el arco iris.  Los
viajeros hubieran podido oír las dos, si hubieran prestado atención.
Pero impactados por el viaje no las escucharon.

La primera sonó escondida, como olvidada, oculta entre el ruido del
tráfico y el ajetreo de la ciudad.

La segunda sonó rotunda bajo las estrellas en una noche silenciosa,
pero fue ignorada por aquellos que pudieron llegar a oírla.  Su sonido
rodó por los tejados de pizarra y paja, rebotó por las calles de
piedra y acero, deshaciéndose en ecos hacia las montañas.

Una tercera quiso sonar con ellas, pero rajada y rota apenas consiguió
emitir un chirrido metálico. Sin embargo, ésta obtuvo más atención
cuando lanzó su desafinado tañido.

El /brujo/ abrió los ojos y sonrió con malicia.

[[file:piedra.org][Continuar...]]

Comenzamos con los cambios:

El autor del css utiliza la carga de fuentes desde la habitual URL de gúguel, una política que no es de mi agrado. Yo, en cambio, he bajado de Internet algunas fuentes de daFont, un sitio donde se pueden encontrar fuentes de todo tipo y desde el que se pueden descargar para uso personal. Cada uno se puede bajar las fuentes que quiera, yo he bajado Feathergraphy, que es gratuita para uso personal⁵, en los títulos y para el texto utilizaré la habitual Linux Libertine que uso también como fuente principal en este blog, y que tiene una licencia libre y se puede utilizar para cualquier fin.

Los ficheros ttf los he colocado en un directorio llamado fuentes que no aparece en el árbol de directorios anterior, tenéis que crearlo, copiar las fuente ahí e importarlas en el css como sigue:

@font-face {
    font-family: "Libertine Regular";
    src: url('../fuentes/LinLibertine_R.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;
}
@font-face {
    font-family: "Feathergraphy";
    src: url('../fuentes/Feathergraphy2.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;
}

El paso siguiente es modificar algunos estilos. En las cabeceras, se añade una instrucción font-family: 'Feathergraphy' y en el apartado body se añade font-family: 'Libertine Regular'. Para ver el resultado hay que publicarlo. Sigamos los siguientes pasos:

1. Cargar el código que hicimos antes con el comando M-x load-file y seleccionado el fichero kvintero.el que habíamos creado para tener la lista de proyectos para publicación.

2. A partir de este momento, si estamos en un fichero org podemos emplear el comando de exportar C-c C-e, ahora seleccionamos el apartado Publish (P), y choose project (x), elegimos el proyecto kvintero y se realiza la magia.

   Si no estamos en un fichero org, podemos utilizar el comando M-x org-publish-project RET kvintero RET.

3. Abrir el fichero en un navegador web. Obtendremos algo parecido a:

Vista la imagen, no me gusta cómo queda el título y voy a separarlo en dos. La cabecera del fichero org quedará así:

#+setupfile: ../plantillas/plantilla-base.org
#+title: Kvintero

* Introducción

Tras modificar el org lo guardamos y volvemos a publicar el proyecto, bien con C-c C-e o con M-x org-publish-project. Volvemos a ver cómo ha reaccionado nuestro html. El resultado quedará como:

Bueno, parece que ha surtido efecto, pero me gusta menos aún: aparece un índice que no quiero y el título me lo numera... algo más hay que cambiar. Y lo que hay que cambiar está en la plantilla. En concreto en la línea:

#+options: num:t p:nil pri:nil stat:t tags:t tasks:t tex:t timestamp:t toc:t

Hay que cambiarla por:

#+options: num:nil p:nil pri:nil stat:t tags:t tasks:t tex:t timestamp:t toc:nil

Volvemos a publicar el proyecto por el método habitual. ¿Qué ha ocurrido? ¿Nada? Pues sí, no ha ocurrido nada, porque hemos modificado un fichero que no está dentro del proceso del proyecto. Para que tenga efecto hay que rehacer todos los ficheros que enlacen la cabecera. Lo que yo hago es entrar en el dired, si tienes activado normalmente, como yo el dired-sidebar lo tienes a mano. Pasas a ese buffer, seleccionas los ficheros, ─si son muchos, puedes seleccionar el directorio entero─, pulsando m para marcar y luego pulsas T (obsérvese la mayúscula). Es lo mismo que hacer un touch en una consola, que es el otro método rápido. Si ahora repites el comando de publicar el proyecto, el resultado será:

Voy a poner una imagen en el proyecto, más para ilustrar de otro modo cómo es el proceso de mantener un proyecto completo, el ir haciendo pequeñas modificaciones e ir viendo cómo se van produciendo los resultados.

Lo primero que necesito es encontrar una imagen. Yo me descargué una fotografía de un menhir de Internet y le apliqué algunos filtros con GIMP. Al final, el fichero .png lo he copiado en el directorio img que cuelga del directorio base. Para cargar la imagen, se hace como siempre en org-mode.

#+setupfile: ../plantillas/plantilla-base.org
#+title: Kvintero

* Introducción

[[file:img/menhir.png]]

Una vez introducido el enlace de la imagen, si queremos verla aparecer en nuestro documento html debemos publicar el proyecto. Como seguramente estaremos aún en el fichero org, la pulsación completa será C-c C-e P x kvintero y obtendremos algo así:

Está bien, pero es un poco soso. Vamos a darle un poco de vidilla con la hoja de estilos, a ver si lo adornamos un poco. Primero, me gustaría que la imagen se desplazara a la izquierda y el texto se ajustara a ella mostrándose a la derecha, y no debajo. Eso es fácil de hacer con css.

.float-left {
    float: left;
    margin-right: 1em;
}
.float-right {
    float: right;
    margin-left: 1em;
}

En principio me bastaba con float-left, pero ya puestos, he creado también float-right para tenerlo disponible en el futuro. Así podré manejar imágenes ajustándolas en uno de los laterales. Además añado un margen en el lado donde irá el texto, para que no se junte en exceso a la imagen.

Ya puestos a hacer cambios, ─y puesto que es un documento que hará las veces de /librojuego/─, me gustaría resaltar más algunos elementos, hacer que la primera letra del párrafo inicial se muestre más grande y remarcar la primera línea destacándola. Para esto he añadido un poco más de código a la hoja de estilos.

.p-inicio::first-line {
    font-weight: bold;
    color: rgba(0,0,0,0.85);
}
.p-inicio::first-letter {
    position: relative;
    padding-top: 0.1em;
    display: block;
    float: left;
    font-family: 'Feathergraphy';
    font-weight: normal;
    font-size: 3.2em;
    line-height: 0.8em;
    color: #d33682;
    margin-right: 0.1em;
}

La primera parte, .p-inicio::first-line, establece que la primera línea del párrafo se escriba en negrita y con un color negro con una transparencia del 15%.

La segunda parte, .p-inicio::first-letter, establece que la primera letra del párrafo se muestre con un tamaña 3.2 veces el tamaño de letra normal y que utilice el tipo de letra y el color del título.

Bueno, hechos los cambios necesitamos visualizarlos en nuestro navegador favorito. Como seguramente seguiremos en el buffer donde hemos hecho los cambios podemos publicar el proyecto utilizando la combinación M-x org-publish-project RET kvintero RET. El resultado que debemos obtener sería algo así:

¿No? ¿No ha salido bien? Claro, hemos modificado la hoja de estilos, pero no le hemos dicho al documento qué estilos y dónde tiene que aplicarlos. Eso es fácil:

#+setupfile: ../plantillas/plantilla-base.org
#+title: Kvintero

* Introducción

#+attr_html: :class float-left
[[file:img/menhir.png]]

#+attr_html: :class p-inicio
Dos campanas tañieron al unísono cuando se abrió el arco iris.  Los
viajeros hubieran podido oír las dos, si hubieran prestado atención.
Pero impactados por el viaje no las escucharon.

Delante del elemento del documento que queremos aplicar uno de los estilos que acabamos de crear, utilizaremos el comentario especial #+attr_html: para establecer la :class con el nombre que hayamos puesto en la hoja de estilos. Si lo haces como está en el código anterior y publicas el proyecto como venimos haciendo hasta ahora, obtendrás los resultados como se mostraron arriba.

Por supuesto, ajustar todas estas cosas lleva su tiempo y es recomendable utilizar las herramientas de desarrollador web que provea el navegador que utilices. Yo normalmente estoy utilizando Falkon:

Primero hago los ajustes ahí, probando colores, márgenes, fuentes, etc. y luego lo paso al código definitivo de la hoja de estilos.

Publicar proyectos es una forma sencilla, pero potente de crear contenido web que se puede emplear para muchas cosas desde org-mode. Una de los usos para desarrolladores es, generar la documentación para colocarla en Internet o distribuirla con el programa. Generar un epub fácilmente. Tener un sitio de Internet estático de una manera sencilla. También, en lugar de enfocar la publicación a html se puede enfocar a pdf con LaTeX, o incluso tener proyectos que generen la documentación en varios formatos: info, html, pdf, etc.

Hay un montón de aspectos que no he utilizado aquí, pero están explicados en la documentación de org.