Unlimited Wordpress themes, plugins, graphics & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Jekyll

Cómo crear y publicar una gema de tema de Jekyll

by
Read Time:11 minsLanguages:

Spanish (Español) translation by Andrea J (you can also view the original English article)

Una de las características nuevas más destacadas de Jekyll es la capacidad de crear temas oficiales en forma de gemas Ruby. Estos temas pueden ser instalados por un usuario de Jekyll para diseñar su blog o sitio web estático con facilidad, dejándolos para administrar su contenido.

Antes de esta nueva función para tematizar, Kezz Bracey escribió un gran tutorial sobre cómo crear un tema de Jekyll. En este tutorial, extenderemos la publicación de Kezz convirtiendo nuestra plantilla en una gema de tema oficial de Jekyll.

Jekyll en Envato Market

La categoría Jekyll en Themeforest tiene un montón de temas que van desde $16 a $29 dólares. ¿Por qué no enviar el tuyo, todo envuelto como una gema de Ruby ordenada?

Jekyll on ThemeforestJekyll on ThemeforestJekyll on Themeforest
Temas de Jekyll en Themeforest

Preparación

Antes de comenzar, te recomiendo leer el tutorial anterior. Asumiré que ya tienes un tema de Jekyll creado con el método de Kezz, o incluso puedes tener un sitio de Jekyll bien escrito que te gustaría convertir en un tema oficial de Jekyll.

Vas a necesitar usar la línea de comandos cuando trabajes en tu tema de Jekyll, pero una vez más, ¡Kezz te tiene cubierto!

Abre tu herramienta de línea de comandos y asegúrate de tener instalada la última versión de Jekyll (en el momento de este artículo es la versión 3.3) usando lo siguiente:

También necesitarás Bundler, que es una gema para administrar otras gemas. Explicaré por qué necesitas esto más adelante. Puedes instalar esto usando:

Finalmente, deberás registrarte para obtener una cuenta de RubyGems.org. Hacer esto te permite insertar tu tema en su registro para que otros usuarios de Jekyll puedan descargarlo y usarlo.

Empezar

Para ayudarnos a comenzar, Jekyll tiene un comando solo para crear un nuevo tema. En tu herramienta de línea de comandos, busca el directorio en el que planeas trabajar y usa el siguiente comando para crear los archivos base para tu tema:

Deberías ver algo como la siguiente lista en tu carpeta de trabajo:

Las carpetas _layouts/, _includes/ y _sass/ son las mismas que las carpetas que verías en un proyecto Jekyll normal, que contienen todos tus diseños de página, "incluidos" (o "parciales") y archivos Sass.

La carpeta assets/ es para los archivos que quieres enviar al sitio del usuario. Por ejemplo, JavaScript, archivos de imagen o estilo. Normalmente colocarías estos archivos en carpetas js/, css/ o images/.

awesome-jekyll-theme.gemspec es el archivo que describe tu tema de gemas. Aquí es donde puedes enumerar el nombre, la versión, una descripción, una página de inicio y una lista de gemas para tu gema de tema.

El Gemfile es para Bundler, que mencionamos antes. Esto vincula las gemas enumeradas en tu archivo .gemspec con Bundler en tu herramienta de línea de comandos. Usaremos Bundler más adelante para probar tu tema.

Finalmente, los README.md y LICENSE.txt están ahí para documentar tu tema y proporcionar una licencia adecuada. Probablemente estés familiarizado con estos archivos si creaste un proyecto de GitHub anteriormente.

Nota: Es importante documentar tu tema a fondo. De esa manera, las personas que quieran usar tu tema podrán hacerlo fácilmente y usar las opciones y controles que hayas proporcionado dentro de él.

Convertir tu tema

Dado que un proyecto Jekyll tiene una estructura de archivos bastante similar a un tema Jekyll, puedes continuar y copiar la mayoría de tus archivos. Probablemente querrás sobrescribir los archivos de diseño preexistentes que vienen con el tema base con los tuyos. Por lo tanto, todos tus archivos de diseño deben ir a la carpeta _layouts/, tus inclusiones en la carpeta _includes/ y tus archivos Sass en la carpeta _sass/ dentro del tema base que creaste.

Sugerencia: ¿Nuevo en Sass? Echa un vistazo a este curso de Adi Purdila, 14 días para aprender Sass

Deberás colocar tus estilos principales, JavaScript y recursos gráficos en la carpeta assets/. Esta es una carpeta clave para la creación de temas de Jekyll, ya que es el único directorio que aparecerá en el sitio de usuarios finales. Puedes terminar con una carpeta de recursos que se ve así:

A su vez, deberás actualizar las rutas en tu código para reflejar este cambio de ruta. Por ejemplo, css/styles.scss cambiará a assets/styles.scss.

Sugerencia: Para asegurarte de que tus rutas están correctas en tu tema, es posible que quieras consultar relative_url y absolute_url que se han agregado recientemente a Jekyll.

Los metadatos de tu tema

El archivo .gemspec está diseñado para proporcionar información básica sobre tu gema de tema. El tema base de Jekyll viene con este archivo, pero deberás reemplazar los valores de ejemplo con los tuyos. Este es un ejemplo de archivo .gemspec:

A continuación te muestro un resumen de lo que cambié en mi archivo .gemspec:

El name debe ser el nombre de tu tema, el cual debe coincidir con el nombre del archivo .gemspec. La version debe ser el último número de tu gema de tema. Los authors pueden ser una lista de personas, pero, por ahora, solo soy yo el que desarrolla este tema. El email debe ser el mismo correo electrónico con el que te registraste en RubyGems.org.

El summary y la description deben ser explicaciones cortas y largas, respectivamente, de tu gema de tema. Puedes configurar la homepage para una demostración en vivo del tema o incluso el repositorio de GitHub en el que se encuentra.

La license debe coincidir con cualquier licencia que hayas proporcionado en la gema de tema (el archivo LICENSE.txt). El valor de files no debe modificarse, ya que marca los archivos y carpetas que se utilizarán en tu gema de tema final.

La última parte del archivo .gemspec es una lista de gemas que se necesitan para que tu tema funcione correctamente. En mi ejemplo, solo tengo una gema que se necesita para que se ejecute: jekyll-seo-tag. Las otras gemas enumeradas, jekyll y bundler, son gemas de desarrollo y solo se necesitan cuando alguien está desarrollando la gema de tema.

Asegúrate de agregar todas las gemas que necesitas para tu tema en este archivo. Puedes encontrar una lista completa de los plugins de Jekyll en su sitio.

Probar el tema

Ya que tenemos nuestros archivos de tema y nuestro archivo .gemspec se completó, podemos realizar algunas pruebas iniciales. Sin embargo, necesitaremos algo de contenido de muestra, así que copia el archivo _config.yml de tu tema de plantilla anterior, junto con algo de contenido de descuento. Un archivo index.md con algo de contenido debería ser suficiente para una prueba inicial, pero es posible que también quieras agregar una publicación de ejemplo. Los blogs son una de las características clave de Jekyll, por lo que sería una buena idea probar esto.

Nota: asegúrate de que tu contenido principal tenga un diseño seleccionado o es posible que no veas el tema correctamente cuando se ejecute localmente.

¿Recuerdas que instalamos Bundler y ese Gemfile en la base de nuestro directorio de temas? Bueno, Bundler usa Gemfiles para administrar gemas en proyectos y si abres ese archivo, verás lo siguiente:

Lo que hace este archivo es decirle a Bundler que busque en RubyGems.org las gemas en tu archivo .gemspec. Entonces, con eso en mente, probemos tu tema.

En tu herramienta de línea de comandos, usa el siguiente comando para instalar todas las gemas necesarias para tu gema de tema:

Esto debería instalar todos los temas en tu .gemspec, que, en mi ejemplo, solo sería jekyll-seo-tag. Ahora podemos ejecutar el tema localmente usando:

Después, deberías poder ver tu tema en http://localhost:4000. Si ocurre un error, podría deberse a que te falta una gema en tu archivo .gemspec.

Nota: es posible que debas incluir gemas en la lista blanca en tu archivo _config.yml, si aún no lo has hecho, así como mencionarlas en tu .gemspec. Si tienes dificultades para familiarizarte con Jekyll, Guy Routledge creó un gran curso para Tuts+ sobre cómo crear sitios web estáticos con Jekyll.

Refinar y agregar personalización

Luego, dedicarás un tiempo a perfeccionar tu tema para asegurarte de que funcione con una variedad de formatos y tamaños de contenido. Es posible que también quieras tener en cuenta las opciones de personalización, ya sea a través de una configuración global en _config.yml o en páginas separadas en la portada.

El usuario tiene la capacidad de sobrescribir cualquier archivo en tu gema de tema con su propio archivo en su propio sitio Jekyll. Por ejemplo, si tienes _includes/header.html en tu gema de tema, el usuario del tema puede sobrescribir ese archivo con _includes/header.html en su propio sitio. Es posible que quieras pensar en hacer que tu tema sea lo suficientemente flexible como para que el usuario del tema pueda sobrescribir fácilmente tus archivos para hacer que su propio sitio sea más único.

Documentación

Si le estás agregando personalización a tu tema, necesitarás documentación que lo acompañe. Documentar tu gema de tema es muy importante. Si la documentación es deficiente, la gente no querrá usar el tema.

Estas son algunas de las cosas que esperaría ver en la documentación de un tema:

  • Una buena descripción del tema y sus usos
  • Una lista de características
  • Instrucciones de instalación claras
  • Contenido de demostración para mostrar cómo usar el tema
  • Cómo funcionan las opciones de configuración
  • Cómo funcionan las opciones de página
  • Cualquier shortcodes / includes que se pueda usar
  • Referencias a cualquier proyecto de código abierto que usaste para ayudar a crear el tema.

Todo esto se puede enumerar en el archivo README.md, que se creó cuando creamos el tema base de Jekyll. Cuando el tema se inserta hasta RubyGems.org, el archivo Léame se procesará y se mostrará en la página de gemas para que las personas puedan hacer referencia a ella.

Junto con tu documentación, recomendaría proporcionar algún contenido de demostración para que la gente empiece con tu tema. Un archivo _config.yml, index.md y ejemplo de publicación, similar a los que usaste para probar tu tema anteriormente, junto con un Gemfile debería ser suficiente. Aunque solo debería requerir que el usuario agregue la gema a su Gemfile, sería muy útil proporcionar una configuración de ejemplo que puedan descargar y usar de inmediato.

Deberás proporcionar una captura de pantalla para tu tema, como se indica en la documentación oficial de Jekyll, con el nombre screenshot.png. Esto no solo permitirá a las personas ver cómo se ve su tema de un vistazo, sino que también proporcionará una coherencia en todos los temas de Jekyll para que se puedan mostrar en una galería o interfaz de usuario de administración en el futuro.

Publicar tu tema

Una vez que estés satisfecho con tu tema y lo hayas probado y documentado, deberás insertarlo en el registro de RubyGems.org para que otros puedan usarlo.

Ubica tu gema de tema con tu herramienta de línea de comando y usa lo siguiente:

Asegúrate de hacer coincidir el nombre del archivo .gemspec en tu tema con el comando que se muestra arriba. Esto creará un archivo llamado awesome-jekyll-theme-0.0.2.gem, ¡que es tu gema de tema oficial Jekyll! Luego, deberás enviar tu gema a RubyGems.org. Usa lo siguiente en la herramienta de línea de comandos:

Si esta es la primera vez que envías una gema a RubyGems.org, se te pedirá que inicies sesión con los detalles que usaste para registrarte. Después de eso, la gema debe enviarse al registro, lo que significa que tu gema de tema se publicó.

Sugerencia: Con la mayoría de las herramientas de línea de comandos, si escribes las primeras letras de un archivo y luego presionas Tab, debería completarse automáticamente el resto del nombre de archivo, siempre y cuando no haya otro archivo que comience con las mismas letras en la misma carpeta.

Una vez que esto haya sucedido, deberás hacer algunas pruebas adicionales y seguir tus propias instrucciones sobre la instalación y el uso de la gema de tema. Las instrucciones deben ser bastante similares a las que se muestran en el sitio oficial de Jekyll.

Lecturas adicionales

Además de seguir este tutorial, es posible que quieras consultar estos recursos cuando se trata de crear tu propia gema de tema Jekyll:

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.