Desde hace un tiempo he ido adoptando Grav como una solución para wikis, principalmente por su simplicidad y por su portabilidad.

En una época (época, era, o como se llame) en la cual naturalizamos que cada porción de nuestra operación se alquila y paga as-you-go, a veces olvidamos el detalle de la portabilidad y la no menor redundancia de esos datos.

Hace no mucho, charlando sobre esta misma idea, le pregunté a alguien cómo se imaginaba su operación si tal o cual servicio dejara de operar, y la respuesta fue de estupor.

Todo lo anterior, sumado a otros cambios operativos, me han llevado a optar por Grav como solución para mantener documentación pública y/o privada.

Si quisiera crear una nueva wiki o sitio de documentación que más o menos se pueda preciar de ser tal, podría usar la siguiente receta.

Preparo mi entorno/container/servidor con PHP 8.1 (no olvidar prestar atención al estado de salud de las versiones de PHP) y usando Composer ejecuto en el root del que será mi host. (En un escenario default estaríamos ejecutando esto en /var/www/html)

composer create-project getgrav/grav .

Unos segundos después ya tenía mi sitio navegable.

Vamos a intentar no publicar online ningún plugin que no sea necesario. El módulo Admin es el mejor ejemplo de esto, ya que si bien lo puedo querer usar por su practicidad (aunque no es condición para crear contenido), no quiero que esa funcionalidad esté online.

Como ya vimos en el post del ejemplo de blog, vamos a usar el gestor de paquetes de Grav para instalar. Vale aclarar que cuando hablamos de paquetes nos referimos tanto a plugins como a themes.

Primero, ejecutamos bin/gpm index para ver todos los plugins posibles.

bin/gpm index

Para mi wiki voy a comenzar con:

bin/gpm install admin

Una vez finalizado, al acceder a la URL/admin de mi sitio, ya tengo la inicialización (también lo vimos en el post del blog).

El archivo .gitignore incluido con la distribución se encargará de excluir este plugin y su archivo de configuración del repositorio, por lo que no debemos preocuparnos.

Avanzo ahora con plugins más específicos para este proyecto.

Como theme, el que se puede usar como buen punto de partida, es Learn2. Lo instalamos con:

bin/gpm install learn2

Ahora, desde el backend, en la sección de Themes, lo puedo activar y configurar algunos parámetros.

Si decido no usar el admin, debo editar el archivo user/config/system.yaml y en pages -> theme, indicar, en este caso, el nombre learn2.

Archivos que voy a sumar o actualizar en el repositorio ahora:

  • user/config/system.yaml
  • user/config/themes/learn2
  • user/themes/learn2

Mientras que user/config/media.yaml lo podemos agregar al archivo .gitignore ya que el admin no estará versionado.

Ahora ya tengo mi theme activo. Como siempre, si consideran que necesitarán editar el theme, crear un child theme es la mejor opción (también hay un pequeño ejemplo en el post sobre cómo crear un blog).

Algunos plugins que en mi caso me gusta instalar.

  • breadcrumbs: para tener una ayuda visual extra en la navegación y profundidad del contenido.
  • external_links: ayuda visual para los links que te llevarán fuera del sitio.
  • prism-highlight: antes usaba el módulo highlight para mostrar código, pero en nuevas versiones estoy probándolo dado que tiene mejor soporte.
  • mermaid-diagrams: nos permite generar gŕaficos que pueden ser muy útiles para explicar circuitos, y siendo que es para una wiki, siempre me resulta útil.
  • simplesearch: hasta ahora nunca me ha decepcionado y, sin agregar nada de infraestructura o servicios de terceros, se puede tener una búsqueda efectiva y rápida.

Veamos caso por caso.

bin/gpm install breadcrumbs

El resultado fue.

Eso está bien. Ahora, al hacer un git status, puedo ver que no hay nada para agregar al repositorio. Esto se debe a que, por defecto, se ignoran todos los plugins a través de estas dos líneas en el .gitignore.

  • user/plugins/*
  • !user/plugins/.*

Algunos módulos se van a instalar cuando se ejecute el composer install, por lo que yo voy a modificar el .gitignore para incluir aquellos que yo he instalado mediante el uso de bin/gpm.

Instalo ahora los módulos faltantes de la lista que definí antes.

bin/gpm install external_links prism-highlight mermaid-diagrams simplesearch

El resultado fue:

Reading time lo terminé quitando de este ejemplo ya que es necesario customizar el theme Learn2 para que muestre la información.

Y ahora edito el .gitignore para sumar esos plugins también. El resultado final de esa sección sería:

!user/plugins/.*
!user/plugins/breadcrumbs
!user/plugins/external_links
!user/plugins/mermaid-diagrams
!user/plugins/prism-highlight
!user/plugins/simplesearch
user/themes/*

Ahora si, mi contenido por defecto se ve en este formato.

De aquí en más, es cuestión de agregar páginas usando el admin o dentro del directorio /user/pages usando como ejemplo las páginas que ya tenemos de la instalación base.

Pros y contras

En el comienzo del post hablaba sobre adoptar esto como práctica por sobre el uso de herramientas SaaS. A esta altura tenemos más que claro que ni uno es tan bueno y ni el otro es tan malo. La solución que abracemos va a traer una serie de beneficios pero de seguro debamos sacrificar algo.

En mi caso, al menos hasta el momento en el que estoy escribiendo el post, dada la naturaleza de la implementación, tengo una copia local de mi wiki, la cual uso con el módulo admin y versiono en un repositorio. Cada vez que agrego nuevo contenido, hago un push de los cambios y de ahi, Jenkins se encarga de deployar la última versión online.

Algo parecido se repite con las distintas wikis de proyectos o clientes. Para cada uno de ellos tengo una wiki independiente.

Claramente, estos detalles califican para el grupo de las contras.

  • Necesito tener una copia local del repositorio.
  • La edición es local.

Por el otro lado, las situaciones que significaron una mejora fueron:

  • Todos los documentos están en un formato abierto y portable.
  • Tengo copia de seguridad por diseño (online porque necesito que sea accesible por otros o por mi desde distintos lugares y dispositivos, en el repositorio, en mi computadora).
  • Con un pequeño/económico servidor puedo disponibilizar una cantidad significativa de wikis sin que tenga un problema de costos por licencias.

Créditos: la foto de portada es de Beatriz Pérez Moya.