Crea Temas de Blogger con Hamlet

Paquete de node para facilitar el desarrollo de plantillas de Blogger.

Desarrollar un tema de Blogger es una tarea complicada, ya que la sintaxis es difícil de leer y un proyecto completo resulta complicado de mantener. Por esto, he desarrollado un paquete de node que usa Handlebars para compilar una plantilla de Blogger, de allí el nombre Hamlet.

Características

Hamlet te permite usar la misma sintaxis de Blogger, por lo que puedes usar las etiquetas que usas en tu tema actual pero incluye características que te ayudarán en desarrollo como:

• Handlebars para compilar archivos HBS y XML.
• Rollup para empaquetar archivos JS.
• PostCSS para procesar archivos CSS, también compatible con SCSS y SASS.
• Minifica archivos CSS y JS usando LightningCSS y Terser. (Puede ser deshabilitado)
• Puedes usar el lenguaje Blogger con algunas facilidades adicionales.
• Puedes usar archivos de configuración para personalizar el proceso de construcción. (Opcional)
• Rápido y fácil de usar.

Tema de ejemplo

Por otro lado, el tema que he creado a modo de ejemplo es el punto de partida perfecto para desarrolladores, ya que es sencillo, sigue buenas prácticas, esta comentado con instrucciones, enlaza a la documentación del código de Blogger (BloggerCode), es fácil de entender, entre otras características:

• Sin dependencias, sin JavaScript, solo HTML y CSS.
• Optimizada para SEO moderno.
• Optimizado para AdSense.
• Diseño responsive.
• Soporta múltiples lenguajes gracias a Blogger.
• Súper optimizada con un tamaño de código muy reducido.
• Compatible con Core Web Vitals.
• Sistema de comentarios con múltiples niveles.
• Widgets formateados.
• Buenas practicas para la creación de temas de Blogger.

Empezando

Iniciar proyecto desde cero

Primero necesitas instalar Node.js (LTS), luego crea una carpeta en cualquier parte de tu pc. Dentro de la carpeta que haz creado, abre la consola que uses e inicia npm con el comando npm init -y. Por último instala el compilador de Hamlet usando el siguiente comando:

    npm install hamlet-builder
  

Iniciar desde el tema de ejemplo

Si prefieres partir del tema de ejemplo, instala Git en tu computadora. Luego clona o descarga el repositorio que contiene el tema Hamlet, por último ejecuta el comando npm i para descargar las dependencias.

Banderas

Ya sea si empezaste de cero o si estas partiendo desde el tema de ejemplo, puedes usar las siguientes banderas en tu archivo package.json para personalizar el comportamiento del compilador:

A continuación, se muestra un ejemplo de cómo usar las banderas en el archivo package.json, ten en cuenta que si estas usando el tema de ejemplo, el archivo package.json ya contiene estos scripts:

{
  "scripts": {
    "dev": "hamlet --mode development --watch",
    "start": "hamlet --mode production --watch",
    "build": "hamlet --mode production"
  }
}

Ahora puedes ejecutar cualquiera de los siguientes comandos, según lo que desees hacer:

npm run start
npm run build

Archivos de Configuración

Rollup

Agrega un archivo .rolluprc.js, rollup.config.js o crea una carpeta .config con un archivo rolluprc.js. También puedes usar la extensión .cjs o .mjs. El archivo sirve para definir los plugins que se utilizarán al compilar los scripts. Aquí tienes un ejemplo de configuración:

import terser from "@rollup/plugin-terser"

export default {
  plugins: [
    terser()
  ]
}

Nota: El plugin babel se utiliza de forma predeterminada si no se especifica un archivo de configuración.

PostCSS

Agrega un archivo .postcssrc.js, postcss.config.js o crea una carpeta .config con un archivo postcssrc.js. También puedes usar la extensión .cjs o .mjs. El archivo sirve para definir los plugins que se utilizarán al compilar los estilos. Aquí tienes un ejemplo de configuración:

import cssnanoPlugin from "cssnano"
import autoprefixer from "autoprefixer"

export default {
  plugins: [
    autoprefixer(),
    cssnanoPlugin()
  ]
}

Nota: El plugin autoprefixer se utiliza de forma predeterminada si no se especifica un archivo de configuración.

Handlebars

Agrega un archivo .handlebarsrc.js, handlebars.config.js o crea una carpeta .config con un archivo handlebarsrc.js. También puedes usar la extensión .cjs o .mjs. El archivo sirve para definir helpers personalizados que se utilizarán en las plantillas. Aquí tienes un ejemplo de configuración:

const sayHello = (name) => {
  return `Hello, ${name}!`
}

export default {
  helpers: {
    sayHello
  }
}

{{foo}}

Nota: Los helpers asset y currentYear están disponibles siempre aunque exista un archivo de configuración, pero pueden ser reemplazado si se vuelven a especificar.

Browserlist

Crea un archivo .browserslistrc en la raíz del proyecto o agrega la información en el archivo package.json usando la clave browserslist. Aquí tienes un ejemplo de configuración:

{
  "browserslist": [
    "last 2 versions",
    "not dead"
  ]
}

Para obtener más información sobre la configuración de Browserslist, consulta el repositorio de Browserslist.

Contexto del tema

Agrega un archivo .themerc, .themerc.json, theme.config.json o crea una carpeta .config con un archivo themerc.json. También puedes agregar la información en el archivo package.json usando la clave theme. Los datos serán el contexto de las plantillas Handlebars, aquí tienes un ejemplo de código en formato JSON:

{
  "name": "Hamlet",
  "author": "zkreations"
}

{{name}}
{{author}}

Estructura

Eres libre de organizar los archivos y carpetas como desees, ya que el sistema buscará archivos scss, sass, css, js, hbs y xml dentro de la carpeta de entrada (por defecto src) para compilarlos.

Compilar estilos

El sistema buscará archivos sass, scss y css para compilarlos. Si el nombre del archivo comienza con un guion bajo _, se considerará un archivo parcial, por ejemplo:

├── src
│   ├── scss
│   │   ├── _module1.scss
│   │   ├── _module2.scss
│   │   └── main.scss

@use "module1";
@use "module2";

Otro ejemplo con archivos css:

├── src
│   ├── css
│   │   ├── _module1.css
│   │   ├── _module2.css
│   │   └── main.css

@import "_module1.css";
@import "_module2.css";

El archivo main.scss o main.css será el archivo principal que se compilará y se guardará en la carpeta de salida (por defecto dist) o en la que especifique el usuario. Ten en cuenta que si no usas scss deberas instalar el plugin postcss-bundler para poder importar módulos.

Nota: Los plugins de PostCSS también se aplicarán a los archivos sass y scss después de ser compilados.

Compilar scripts

El sistema buscará archivos js, sin embargo, solo se considerarán aquellos que terminen con bundle.js como archivos principales, por ejemplo:

├── src
│   ├── js
│   │   ├── module1.js
│   │   ├── module2.js
│   │   └── main.bundle.js

import './module1'
import './module2'

El archivo main.bundle.js será el archivo principal, mientras que los demás archivos se considerarán como módulos. Además, cuando se compila el archivo principal, se eliminará "bundle" del nombre del archivo, por lo que el archivo resultante será main.js.

Nota: El nombre del archivo principal tambien se utilizará como nombre de la función generada por Rollup en caso de que se requiera.

Compilar plantillas

El sistema buscará archivos hbs y xml para compilarlos. Si el nombre del archivo comienza con un guion bajo _, se considerará un archivo parcial, por ejemplo:

├── src
│   ├── templates
│   │   ├── _module1.hbs
│   │   ├── _module2.hbs
│   │   └── main.hbs

{{> module1}}
{{> module2}}

Otro ejemplo con archivos xml:

├── src
│   ├── templates
│   │   ├── _module1.xml
│   │   ├── _module2.xml
│   │   └── main.xml

{{> module1}}
{{> module2}}

El archivo main.hbs o main.xml será el archivo principal que se compilará y se guardará en la carpeta de salida (por defecto dist) o en la que especifique el usuario.

Nota: Si tienes una carpeta con parciales que sueles crear, eliminar o cambiar frecuentemente, y que también se llaman juntas en un archivo principal, puedes utilizar el prefijo folder. para incluir todos los parciales de esa carpeta, por ejemplo: {{> folder.NOMBRE_CARPETA}}.

Puedes crear cualquier número de parciales y organizarlos como desees, solo asegúrate de usar nombres únicos. Cuando el nombre de un parcial se repite, recibirás un mensaje de advertencia.

Helpers

Estos helpers están definidos por defecto en el sistema, y puedes usarlos en tus plantillas o anularlos en el archivo de configuración de Handlebars:

Ejemplo de uso del helper asset:

{{asset "dist/css/main.css"}}
{{asset "dist/js/main.js"}}

Si el archivo está en la carpeta node_modules, puedes omitir la carpeta y usar ~ para referenciarlo:

{{asset "~/tooltips/main.js"}}

Importante: Recuerda usar las etiquetas <style> y <script> para incluir los archivos CSS y JS en tu plantilla, ya que de lo contrario no se interpretarán correctamente.

Ejemplo de uso del helper currentYear:

{{currentYear}}

Parciales

Los parciales predefinidos estan disponibles siempre. Estos se identifican con el prefijo super.. Puedes aprender mas sobre estos en la documentacion de los parciales predeterminados. Esta es una lista de los disponibles:

Para incluir estos parciales predeterminaos usa la siguiente sintaxis:

{{> super.defaultmarkups}}

Características adicionales

Al escribir tus plantillas, podrás utilizar el lenguaje de Blogger que ya conoces, con algunas facilidades. El objetivo de este proyecto es poder reducir la cantidad de código que se escribe y mejorar la experiencia de desarrollo.

Etiqueta html

Por lo general, los atributos que los desarrolladores especifican en la etiqueta html no suelen variar, por lo que puedes omitirlos y el sistema los agregará automáticamente. Si deseas cambiar el valor de alguno de estos atributos, simplemente agrégalo:

<html class='test'>

<html class='test' b:css='false' b:js='false' b:defaultwidgetversion='2' b:layoutsVersion='3' expr:dir='data:blog.languageDirection' expr:lang='data:blog.locale'>

Variables

Puedes definir variables solo con el nombre, sin la necesidad de especificar los atributos, pero si omites especificar el tipo, se usará string por defecto:

<Variable name='test'/>
<Variable name='example' value='false'/>

<Variable name='test' description='test' type='string'/>
<Variable name='example' description='example' type='string' value='false'/>

Widgets

En el caso de las etiquetas widget, no se requiere ningún atributo y si omites especificar el tipo o el tipo ingresado no es válido, se usará HTML por defecto:

<b:widget/>
<b:widget type='PopularPosts'/>
<b:widget type='Label'/>
<b:widget type='Label'/>

<b:widget id='HTML1' type='HTML' version='2'/>
<b:widget id='PopularPosts1' type='PopularPosts' version='2'/>
<b:widget id='Label1' type='Label' version='2'/>
<b:widget id='Label2' type='Label' version='2'/>

Eliminación de espacios

Cuando uses etiquetas b:* puedes usar espacios o saltos de línea para mejorar la claridad de tu código, al compilar, estos espacios se normalizarán. Esto no solo mejora la legibilidad del código, sino que también reduce el tamaño del archivo:

<b:include name='@image' data='{
  src: data:sourceUrl,
  resize: (data:shrinkToFit
    ? 500
    : 1280)
}'/>

<b:include name='@image' data='{ src: data:sourceUrl, resize: (data:shrinkToFit ? 500 : 1280) }'/>

Otros recursos

Si estas trabajando en un nuevo proyecto, te recomiendo que visites los siguientes recursos que te ayudarán a desarrollar tu plantilla:

• Handlebars - Documentación oficial de Handlebars.
• Blogger Code - Documentación del código de Blogger.
• Blogger Syntax - Complemento de Blogger para Visual Studio Code.
• Parámetros de imágenes - Parámetros de imágenes de Blogger.
• Meteor icons - Los iconos SVG mas optimizados de internet.
• Blogger AdminWP - Panel Layout estilo WordPress para Blogger.
• Blogger Numeric Pager - Paginación numérica avanzada para Blogger.
• Blogger Related Posts - Entradas relacionadas avanzadas para Blogger.
• Typography - Una hoja de estilos diseñada para optimizar la legibilidad del texto.

Crea tu increible Tema

Si has utilizado este proyecto para desarrollar tu plantilla y te gusta, considera calificar el Tema Hamlet en Github con una estrella y añade al repositorio de tu tema las siguientes etiquetas:

• blogger-hamlet
• blogger-handlebars
• blogger-hbs

Conclusión

Confío que este proyecto te ayudará a desarrollar plantillas de Blogger de forma rápida y sencilla. Si tienes alguna duda o sugerencia, puedes dejar un comentario.