Octopress ha anunciado en su blog la llegada de Octopress 3.0 – Jekyll’s Ferrari, como se puede interpretar, Octopress en un plugin de Jekyll y la forma en como se desarrollan los blogs en esta nueva versión ha cambiado de forma sustancial, ya que la integración con Jekyll es mucho mayor.

Instalación

Para instalar Octopress se requieren los siguientes prerequisitos:

$ sudo apt-get install build-essential git rbenv ruby-full nodejs

A través de gem, que es un instalador de paquetes de ruby, se procede a instalar el plugin de Octopress.

$ sudo gem install octopress bundler

Una vez instalado el proyecto, se procede a crear los archivos del sitio para la publicación de blogs, primeramente se crea la carpeta que albergará los archivos del sitio y dentro de ella se indicará a Octopress que será la carpeta raíz del sitio a través del comando octopress new ., donde el . indica que ahí es la ubicación de la raíz del sitio.

$ mkdir librebit
$ cd librebit
$ octopress new .

Debido a que Octopress se encuentra en fase beta, hay varios plugins que deben ser instalados adicionalmente al proyecto, estos plugins sólo tendrán efecto en el sitio que se desarrolle bajo esta carpeta. Para indicar los plugins se modifica el archivo Gemfile, y se descomenta la sección de jekyll_plugins, tal como se muestra a continuación.

$ nano Gemfile

 group :jekyll_plugins do
   gem "octopress-image-tag"
   gem "octopress-quote-tag"
   gem "octopress-codeblock"
   gem "octopress-social"
   gem "octopress-filter-tag"
   gem "octopress-filters"
   gem "octopress-comment-tag"
   gem "octopress-render-code"
   gem "jekyll-sitemap"
   gem "jekyll-paginate"
 end

Adicionalmente hay que indicar la version de minima que se va a utilizar para el blog.

gem "minima", "1.0.1"

Una vez modificado el archivo Gemfile se procede a la instalación de los plugins para el sitio, para ello se utiliza el comando bundler, que es un instalador de paquetes.

$ bundle install

En caso de que no se instale algun gem por medio de bundler, se puede utilizar el comando gem para su instalación.

$ sudo gem install octopress-image-tag

Si se requiere agregar o eliminar algunos plugins para el sitio, se debe modificar nuevamente el archivo Gemfile, eliminar el archivo Gemfile.lock y ejecutar nuevamente bundler

$ nano Gemfile
$ rm Gemfile.lock
$ bundle install

Una vez instalado todos los plugins para el sitio, se procede a generar los archivos que conformarán el sitio, esto se hace utilizando el comando jekyll, con la opción build genera los archivos del sitio, la opción serve habilita un servidor web en el puerto 4000 para obtener una vista previa el sitio, la opción --h 0.0.0.0 permite que el servidor web pueda ser observado desde computadoras remotas y finalmente --watch es para que el sitio se actualice en tiempo real ante las modificaciones que se hagan a los archivos del sitio.

$ jekyll build
$ jekyll serve --h 0.0.0.0 --watch

Para modificar el título del blog y otros parámetros, el archivo _config.yml contiene varios datos de configuración para la generación del sitio.

Para agregar un post al sitio, se utiliza el comando octopress new post.

$ octopress new post "Mi título"

Este comando creará un archivo .markdown en la carpeta de _posts/ en donde se guardarán los posts que conforman el sitio.

Modificación de Minima.

Por default, el tema que viene con Octopress es Minima de Jekyll, es una tema básico que puede ser modificado para integrarle los diferentes plugins que se requieran en el sitio.

Favicon.

Para agregar un favicon al sitio, solo se tiene que agregar el archivo .ico en la raíz del sitio.

Integración de redes sociales.

Para integrar los botones y otras opciones de las redes sociales en el blog se utiliza el plugin de octopress-social, este plugin permite la fácil integración de estos elementos sin recurrir a los codigos embebidos.

Para agregar los sitios de Facebook, Twitter y Google Plus, se tiene que modificar el archivo default.html del proyecto Minima, los archivos del proyecto se ubican en /var/lib/gems/2.1.0/gems/minima-1.0.1/_layouts.

$ sudo nano /var/lib/gems/2.1.0/gems/minima-1.0.1/_layouts/default.html

Dentro de body se agregan las siguientes líneas.

{% twitter_script_tag %}
{% facebook_script_tag %}
{% gplus_script_tag %}

Si se ejecuta el comando de jekyll serve se observará que no hay ningún cambio en la página, ya que estos comandos solo habilitan el servicio de las redes sociales dentro del sitio.

Para agregar los botones de like y compartir se debe de modificar el archivo post.html de Minima.

$ sudo nano /var/lib/gems/2.1.0/gems/minima-1.0.1/_layouts/post.html

Y agregar los botones después de {{ content }}

{% tweet_button %}
{% gplus_one_button %}
{% gplus_share_button %}
{% facebook_like_button %}
{% facebook_send_button %}

Si se desea integrar la herramienta de Disqus para agregar comentarios a los posts, primero se tiene que configurar los parámetros de conexión en el archivo de _config.yml.

disqus:
  shortname: librebitblog                          # Your site's disqus identifier
  comments_link_text: Comments                     # Text label for comments link
  comments_disabled_link_text: Comments disabled   # Set to '' to not output a comments link when disabled

y agregar el comando {% disqus_comments %} en el archivo /var/lib/gems/2.1.0/gems/minima-1.0.1/_layouts/post.html después de los botones de las redes sociales.

Existen más parámetros de configuración para las redes sociales en Octopress, estos se agregan al archivo _config.yml. Para conocerlos, se puede consultar la página de Octopress-social.

Integración de Mathjax.

Mathjax es una herramienta que permite desplegar ecuaciones matemáticas en las páginas de jekyll, para agregar esta función solo se copia el siguiente script en el archivo head.html.

$ sudo nano /var/lib/gems/2.1.0/gems/minima-1.0.1/_includes/head.html

<script type="text/javascript" async
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

Visualización del blog.

Por default, el tema de minima despliega todos los títulos de los posts en una sola página, sin poner un extracto de los contenidos y sin agregar paginación a los blogs. Para agregar estas características se debe de modificar los archivos _config.yml e index.html del sitio.

Vista previa del post.

Para indicar la palabra que limitará el tamaño del extracto del post, se debe agregar la variable excerpt_separator en el archivo _config.yml.

$ nano _config.yml

excerpt_separator: <!-- more -->

Para que el sitio reconozca el comando <!-- more --> como indicador del extracto del post, es necesario agregar el comando `` después del título del post dentro del archivo index.html.

$ nano index.html

    {% for post in site.posts %}
      <li>
        <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>

        <h2>
          <a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{$
        </h2>
        {{ post.excerpt }}
      </li>
    {% endfor %}

De este modo se mostrará un extracto del post en la página principal del blog.

Paginación de los posts.

La paginación puede ser útil para no saturar la página principal del blog, para ello se utiliza el plugin jekyll-paginate. Los parámetros de la paginación se indican en el archivo _config.yml

paginate: 5
paginate_path: "/blog/page:num/"

Para que el sitio reconozca la paginación, es necesario agregar el siguiente código al archivo index.html del sitio.

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">Previous</a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  <span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

La versión final de la página principal donde se incluye el extracto del post y la paginación es la siguiente:

---
layout: default
---


<!-- This loops through the paginated posts -->
{% for post in paginator.posts %}
  <h2>
     <a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title | escape }}</a>
  </h2>
  <p class="author">
    <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>
  </p>
    {{ post.excerpt }}
    {% if post.content contains site.excerpt_separator %}
        <a href="{{ post.url | prepend: site.baseurl }}">Leer m&aacutes</a>
        <p></p>
    {% endif %}
{% endfor %}

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">Anterior</a>
  {% else %}
    <span class="previous">Anterior</span>
  {% endif %}
  <span class="page_number ">P&aacutegina: {{ paginator.page }} de {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Siguiente</a>
  {% else %}
    <span class="next ">Siguiente</span>
  {% endif %}
</div>
<p></p>
<p class="rss-subscribe">suscribirse <a href="{{ "/feed.xml" | prepend: site.baseurl }}">via RSS</a></p>

Se puede observar que se modificaron varios parámetros para que la página principal muestre los enlaces en español, así como una etiqueta de Leer más al final de los extractos.

Configuración de Github

Para configurar el servidor de Github para hospedaje de la página, se ejecuta el comando octopress deploy init git, el cuál generará un archivo de configuración _deploy.yml con los parámetros de configuración de la conexión con los servidores de Github.

$ octopress deploy init git https://github.com/librebit/librebit.github.io.git

En caso de que indique que no hay archivos de git, estos se pueden generar con:

$ git init

Además se tienen que configurar los parámetros globales de la conexión git para indentificarse con los servidores

$ git config --global user.email "micorreo"

$ git config --global user.name "minombre"

La conexión se realiza mediante ssh, por lo que es necesario indicar que el sitio de github es un sitio de confianza.

$ ssh-keyscan github.com >> ~/.ssh/known_hosts

Ya configurado los parámetros de conexión, se procede a realizar la sincronización de los archivos del sitio con el servidor de Github, para ello se utiliza el comando:

$ octopress deploy

En caso de que indique que la conexión requiere guardar una llave de ssh, se le indica que si.

Errores comunes

Error de dependencia tzinfo-data

The dependency tzinfo-data (>= 0) will be unused by any of the platforms Bundler is installing for. Bundler is installing for ruby but the dependency is only for x86-mingw32, x86-mswin32, x64-mingw32, java. To add those platforms to the bundle, run `bundle lock --add-platform x86-mingw32 x86-mswin32 x64-mingw32 java`.

Este error se presenta por problemas de compatibilidad del paquete, para evitar que siga apareciendo el mensaje hay que ejecutar el comando de bundle lock

$ bundle lock --add-platform x86-mingw32 x86-mswin32 x64-mingw32 java

Error de new post Si al momento de ejecutar el comando octopress new post se presenta el error:

WARN: Unresolved specs during Gem::Specification.reset:
      rouge (< 4, >= 1.7)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
  Dependency Error: Yikes! It looks like you don't have jekyll-feed or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- jekyll-feed' If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/!
octopress 3.0.11 | Error:  jekyll-feed

Esto significa que bundle no instaló las versiones correctas para la plataforma de octopress, para ello se debe de modificar el archivo de Gemfile e incluir el proyecto de octopress como parte de el.

$ nano Gemfile

Abajo de jekyll se puede agregar la línea de instalar octopress

gem "jekyll", "~> 3.6.2"
gem "octopress"

Finalmente se instala de nuevo el proyecto

$ bundle

Para asegurar que se ejecuten las versiones correctas de los programas se sugiere el comando bundle exec

$ bundle exec octopress new post "Título del post"

Error de url en Disqus El sitio Disqus puede mostrar un enlace incorrecto en los comentarios que se hagan en los posts del sitio, para evitar esto se recomienda generar los archivos del sitio sin la opción --h 0.0.0.0 --incremental --watch

$ jekyll build
$ jekyll serve
$ octopress deploy

En caso de que Disqus tenga los enlaces incorrectos en el sitio, se debe de modificar de forma manual en el sitio de Disqus con la opción de urlmapper.

De este modo Disqus enviará un archivo CSV el cual deberá de modificarse con las direcciones correctas de los posts.

Conclusión.

Aunque el proyecto de Octopress 3.0 no ha madurado todavía, las mejores que presenta con respecto a versiones anteriores resultan bastante prometedoras, aunque hay muchos detalles por corregir. Por lo que puedo mencionar algunos puntos.

El uso del tema de Minima permite tener un sitio bastante sencillo y elegante en pocos pasos, según el proyecto de Octopress están trabajado en un tema propio llamado Octopress Genesis, aunque he tratado de instalarlo para concerlo, tuve muchos problemas para hacerlo funcionar.

La integración de los diferentes plugins, tanto de jekyll como de octopress ha resultado bastante transparente, pero la documentación es muy poca.

Finalmente, realizar la migración de Octopress 2.0 a 3.0 puede ser un poco confusa, ya que las herramientas utilizadas para generar el sitio ahora son diferentes.

Por lo pronto, podemos tener una muestra de lo que es Octopress en esta nueva versión.

@viktor_ivan