Una wiki desde la terminal con Vimwiki

Una de las grandes cosas que han ayudado a tener un mayor acceso al conocimiento acumulado de la humanidad, gracias a Internet y a la World Wide Web, es sin duda Wikipedia. Las ya famosas wikis nos llevan acompañando durante las últimas décadas (incluida Vimwiki, de la que hablaremos hoy) desde aquel lejano 1994, cuando un programador llamado Ward Cunningham creó la primera.

Ya sea para acumular notas, diarios o incluso anuncios, las wikis se han hecho imprescindibles para proyectos de desarrollo, de grupo o individuales, o tener todo el conocimiento, junto con los procedimientos, de un departamento de sistemas informáticos.

No es la primera vez que hablamos de wikis, en su día hablamos de MediaWiki y de Dokuwiki.

¿Qué es vimwiki?

Según leemos en su web en Github tiene como objetivo ser una wiki personal para Vim, esto es, una serie de archivos de texto vinculados que tienen su propio resaltado de sintaxis, del que hablaremos más adelante.

Con esta herramienta podemos organizar notas e ideas, administrar listas de tareas pendientes, escribir documentación, llevar un diario o incluso exportar todo a HTML, si fuese necesario.

Una wiki rápida con Vimwiki

El popular editar Vim tiene un sinfín de complementos, muestra de ellos son la gran cantidad de entradas que ha dedicado el amigo Victorhck en su web Victorhckinthefreeworld al asunto. En nuestro caso el proyecto Vimwiki, desde su página de Github, que hemos mencionado antes, ofrece diferentes maneras de instalar este complemento junto a Vim. La que utilizaremos para esta entrada es instalar el paquete de Vim para más tarde generar las respectivas etiquetas de ayuda. NOTA: Debemos tener instalado como mínimo la versión de Vim 7.3

git clone https://github.com/vimwiki/vimwiki.git ~/.vim/pack/plugins/start/vimwiki
# Para generar documentación ':h vimwiki'
vim -c 'helptags ~/.vim/pack/plugins/start/vimwiki/doc' -c quit

Tal y como se muestra en la imagen:

Instalar y habilitar Vimwiki

En cualquier caso, sea como fuere el método de instalación que escojamos, todos requieren que en nuestro directorio personal se incluya un archivo llamado «.vimrc» con las siguientes líneas:

set nocompatible
filetype plugin on
syntax on

Estas líneas permiten que se integre Vimwiki con Vim, sino lo hacemos el complemento no funcionará correctamente. Para comprobar que todo ha ido bien, solo hemos de escribir, una vez dentro del programa:

:help vimwiki

De esta manera se mostrará la ayuda en línea. Mientras tenemos la ayuda en línea podemos aprender a utilizar este complemento.

Ayuda de Vimwiki

Además el archivo de configuración «.vimrc», que hemos mencionado antes, debe conocer la clave principal que procede a cada combinación de teclas. Si no la conocemos, podemos acceder a ella, de la siguiente manera:

:echo mapleader

Algunas distribuciones como Debian, no tiene la clave definida por defecto, por lo que la debemos configurar:

:let mapleader="KEY"

Empezando a trabajar

Para empezar a trabajar, debemos escribir, desde la línea de comandos:

vim ‑c VimwikiIndex

Entonces debemos presionar una tecla para crear el directorio correspondiente de Vimwiki, en nuestra «home». Si deseamos agregar una página adicional debemos seguir estas indicaciones.

Primero de todo ingresar un nombre en la página de índice para después mover el cursor a la primera palabra del nombre. Una vez hecho esto presionamos la tecla «Enter» para crear un enlace en la primera palabra. En enlace se mostrará con un cuadrado doble.

A continuación, presionamos la tecla «Enter» nuevamente, para así crear un nuevo búfer en blanco, donde podemos ingresar información de la nueva página. Cada página puede contener subpáginas, pero lo recomendado es no utilizar más de tres niveles. Estas páginas también se pueden agregar al índice. Guardamos la nueva página. Presionemos la tecla de retroceso para así regresar al índice. Estas acciones las podemos repetir las veces que sean, según nuestras necesidades.

También podemos crear un enlace que contenga varias palabras, para ello debemos presionar la tecla «v» para ingresar al modo visual de Vim, seleccionamos las palabras para el enlace y presionamos a continuación «Enter» En un fichero de extensión «.vimwiki», podemos utilizar los doble corchetes «[[palabro segunda-palabro … ]]»

Muestra de creación de índice y apartados

Pueden existir múltiples wiki como subdirectorios del mismo directorio definiendo cada uno en el fichero de configuración «.vimrc», dando a cada uno un número y nombre únicos, una extensión de archivo. Por ejemplo, se utilizamos dos wikis, una personal y otra para el trabajo:

let wiki_1 = {}
let wiki_1.path = '~/vimwiki_trabajo/'
let wiki_1.syntax = 'default'
let wiki_1.ext = '.wiki'
let wiki_2 = {}
let wiki_2.path = '~/vimwiki_personal/'
let wiki_2.syntax = 'markdown'
let wiki_2.ext = '.md'

Y a continuación añadir:

let g:vimwiki_list = [wiki_1,wiki_2,wiki_3]

De esta manera le decimos a Vimwiki que nos enumere las diferentes wikis.

Configurar diferentes wikis

Si todas las wikis que vamos a crear utilizan Markdown o MediaWiki, en lugar de especificar la sintaxis de cada uno, podemos ahorrar tiempo utilizando una sola línea, por ejemplo, si queremos utilizar Markdown por defecto.

let g:vimwiki_ext2syntax = {'.md': 'markdown'}

Una vez que las wikis ya existen podemos navegar y editarlas utilizando los comandos básicos siguientes:

• [number] <leader> wt – Abre el archivo de índice de la Wiki en una nueva pestaña.
• :<leader> ws – Lista y selecciona las wikis disponibles.
• :<leader>wd – Elimina la página de la wiki actual.
• :<leader> wr – Cambia el nombre de la página wiki actual.
• :<Enter>– Seguir o crear enlace wiki.
• :<Tab>– Busca el siguiente enlace wiki.
• :<Shift-Tab> – Busca enlace wiki anterior.
• :<Retroceso> – Regresa al enlace wiki anterior.

Otra sección importante es la de diario. Ya que podemos generar una nueva entrada para el día actual con el comando «<Leader>w<Leader>w«. Todos los diarios se pueden organizar con un índice con el comando: «:VimwikiDiaryGenerateLinks» o bien «:<Leader>w<Leader>i«. Si instalamos «calendar.vim» y agregamos la opción al fichero «.vimrc», podemos crear una entrada para una fecha seleccionándola en el calendario.

Tipos de sintaxis

Admite tres lenguajes de marcado, que son su propia sintaxis predeterminada, Markdown y MediaWiki. Los tres son similares. De hecho, los valores predeterminados de Vimwiki y Mediawiki son los mismos. Ambos comienzan y acaban un encabezado de primer nivel con un signo igual (=) y texto en negrita con un asterisco (*). En cambio Markdown indica un encabezado de primero nivel con un signo de almohadilla (#) y texto negrita con dos asteriscos (**). Sin embargo, en muchos sentidos, los tres tienen estructuras similares, como indicar un título de segundo nivel con dos de los caracteres que indican un título de primer nivel. Lo recomendado, para no liarse, es utilizar siempre un tipo de sintaxis.

Ejemplo de sintaxis

En el ejemplo anterior, se muestra que algunas etiquetas están codificadas por colores. Hay muchas otras opciones, incluidas algunas especializadas, que se enumeran mediante el comando:

:h vimwiki‑syntax

Además de la sintaxis, algunas palabras clave tienen formato automático, como TODO, DONE, STARTED, FIXME y FIXED, también podemos crear una tabla utilizando el comando:

:VimwikiTable COLUMNAS FILAS

Pasar a HTML

Ya he comentado antes que también podemos pasar la información de una página a HTML. Lo haríamos de la sigueinte manera:

:Vimwiki2HTML – Convertimos la página actual en HTML
:VimwikiAll2HTML – Convertimos todas las páginas en HTML

Otras características

Vimwiki incluye muchas funciones avanzadas, tales como combinación de teclas personalizadas, listas plegables para ocultar temporalmente algunos elementos y agregar comentarios y marcadores de posición. Tener habilitadas estas características implica agregar líneas al fichero de configuración “.vimrc” para habilitarlas. En cualquier caso, la configuración de Vimwiki y su estructura nos ocupará mucho tiempo al principio, por lo que tardaremos en buscar nuevas tareas para nuestra inquieta mente.

Aunque tiene una curva de aprendizaje algo elevada, sobre todo al principio, una vez tengamos la herramienta configurada, todo lo demás irá rodado, como la combinación de teclas y su sintaxis.

Una de las ventajas de complemento, aunque realmente es un programa en sí mismo, al ejecutarse desde la línea de comandos, que es que tiene bajo el capó, un motor wiki que es mucho más rápido que la mayoría.

Quizás te puede interesar

Markdown: Qué es y en que consiste

Fuentes consultadas

Web del proyecto en Github.io