Cómo crear una wiki con Markdown

Guía práctica para crear una wiki de equipo o personal con Markdown usando GitHub Wikis, Wiki.js, Obsidian Publish, MkDocs y otras herramientas.

Una wiki es una base de conocimiento organizada donde un equipo o una persona documenta procesos, decisiones y conocimiento. Markdown es el formato perfecto para wikis: fácil de escribir, fácil de versionar y fácil de migrar.

Por qué crear una wiki con Markdown

Problemas de las wikis tradicionales

  • Confluence/Notion: Tus datos están en la nube de otro. Si la empresa cierra o cambia precios, pierdes acceso.
  • Google Docs: No tiene estructura de wiki. Es difícil navegar y encontrar información.
  • SharePoint: Complejo de configurar, lento, interfaz anticuada.

Ventajas de una wiki en Markdown

  • Versionable: Cada cambio queda registrado en Git con autor, fecha y motivo.
  • Portable: Si quieres cambiar de herramienta, tus archivos .md funcionan en cualquier otra.
  • Colaborativa: Cualquiera puede contribuir con un pull request.
  • Búsqueda: grep funciona en archivos de texto. Las herramientas modernas añaden búsqueda instantánea.
  • Offline: Funciona sin internet. Editas localmente y sincronizas cuando puedas.

Herramientas para wikis con Markdown

GitHub Wikis

Cada repositorio de GitHub incluye una wiki gratuita. Es la opción más rápida si tu equipo ya usa GitHub.

Cómo crear una wiki en GitHub:

  1. Ve a tu repositorio en GitHub
  2. Haz clic en la pestaña Wiki
  3. Crea la primera página (Home)
  4. Añade más páginas con el botón New Page

La wiki de GitHub es un repositorio Git independiente. Esto significa que puedes clonarla con git clone y editarla localmente con tu editor favorito, lo cual es mucho más cómodo que usar el editor web para cambios grandes.

Estructura recomendada:

Una buena organización desde el principio te ahorrará dolores de cabeza cuando la wiki crezca. Esta estructura separa la documentación general de los procedimientos operativos y las decisiones de arquitectura:

Home.md                    # Pagina principal
_Sidebar.md                # Navegacion lateral
_Footer.md                 # Pie de pagina
Onboarding.md              # Guia para nuevos miembros
Architecture.md            # Arquitectura del proyecto
Deployment.md              # Proceso de despliegue
Runbooks/
  Incident-Response.md     # Respuesta a incidentes
  Database-Migration.md    # Migraciones de BD
ADR/
  001-Use-PostgreSQL.md    # Decision de arquitectura
  002-Migrate-to-AWS.md    # Otra decision

El archivo _Sidebar.md es especial: GitHub lo usa para generar la barra de navegación lateral de tu wiki. Sin él, GitHub mostrará una lista automática de todas las páginas, pero el orden será alfabético y poco útil. Definir tu propio sidebar te permite agrupar las páginas por temática:

Sidebar personalizado (_Sidebar.md):

**General**
- [[Home]]
- [[Onboarding]]
- [[Architecture]]

**Operaciones**
- [[Deployment]]
- [[Runbooks/Incident-Response]]
- [[Runbooks/Database-Migration]]

**Decisiones**
- [[ADR/001-Use-PostgreSQL]]
- [[ADR/002-Migrate-to-AWS]]

Limitaciones:

  • Sin búsqueda avanzada (solo búsqueda básica)
  • Sin control de permisos por página
  • No soporta plugins ni temas

Wiki.js

Si necesitas algo más potente que la wiki de GitHub, como permisos por página, búsqueda avanzada o autenticación con el sistema de tu empresa, Wiki.js es la mejor opción open source. Es una aplicación web completa que puedes instalar en tu propio servidor o en la nube.

Ventajas:

  • Editor Markdown con vista previa
  • Búsqueda fulltext
  • Permisos granulares por página
  • Sincronización con Git
  • Temas personalizables
  • Autenticación con Google, GitHub, LDAP, etc.

Instalación con Docker:

La forma más rápida de probar Wiki.js es con Docker. El siguiente comando descarga la imagen oficial, configura una base de datos SQLite (suficiente para equipos pequeños) y expone la interfaz en el puerto 3000:

docker run -d \
  -p 3000:3000 \
  -e "DB_TYPE=sqlite" \
  -e "DB_FILEPATH=/data/wiki.db" \
  -v /ruta/datos:/data \
  ghcr.io/requarks/wiki:2

Después de ejecutarlo, abre http://localhost:3000 en tu navegador y sigue el asistente de configuración inicial. Para producción, se recomienda usar PostgreSQL en lugar de SQLite.

MkDocs + Material

Si tu wiki no necesita edición en el navegador y prefieres un flujo basado en Git (escribes en local, haces commit, y se publica automáticamente), MkDocs con el tema Material es la opción ideal. Genera un sitio web estático que puedes alojar gratis en GitHub Pages, Netlify o Vercel.

La configuración se define en un archivo mkdocs.yml en la raíz del proyecto. Aquí se especifica el nombre del sitio, el tema, los plugins y la estructura de navegación:

# mkdocs.yml
site_name: Wiki del equipo
theme:
  name: material
  features:
    - search.highlight
    - navigation.tabs
    - navigation.sections
    - navigation.expand

plugins:
  - search
  - tags

nav:
  - Home: index.md
  - Onboarding: onboarding.md
  - Arquitectura: architecture.md
  - Runbooks:
    - Incidentes: runbooks/incidents.md
    - Migraciones: runbooks/migrations.md

Ventajas:

  • Sitio estático (rápido, se aloja gratis en GitHub Pages)
  • Búsqueda integrada
  • Excelente documentación
  • Plugins para tags, revision dates, etc.

Obsidian como wiki personal

Para una wiki que solo vas a usar tú, ya sean notas de estudio, investigación personal o un segundo cerebro, Obsidian es difícil de superar. Funciona completamente offline, tus archivos son Markdown puro almacenado en tu disco, y la interfaz es rápida e intuitiva. Estas son sus funcionalidades más destacadas para uso como wiki:

  • Backlinks: [[página]] crea enlaces bidireccionales
  • Grafo: Visualiza las conexiones entre páginas
  • Tags: Categoriza con #etiqueta
  • Búsqueda: Instantánea en todos tus archivos
  • Plugins: Dataview para consultas, Templater para plantillas

Publicar la wiki: Obsidian Publish (8$/mes) convierte tu vault en un sitio web con navegación, búsqueda y grafo. Si prefieres una alternativa gratuita, puedes usar MkDocs o Quartz para generar un sitio estático a partir de tus notas de Obsidian.

Comparativa rápida

HerramientaTipoPrecioColaboraciónBúsquedaGit
GitHub WikiCloudGratisSíBásicaSí
Wiki.jsSelf-hostedGratisSíAvanzadaSí
MkDocsEstáticoGratisVia PRBuenaSí
ObsidianLocalGratisLimitadaExcelenteManual
GitBookCloudGratis (básico)SíBuenaSí
DocsifyEstáticoGratisVia PRPluginSí

Estructurar una wiki de equipo

Páginas esenciales

Toda wiki de equipo debería tener al menos estas páginas. No hace falta crearlas todas el primer día: empieza con Home y Onboarding, que son las más urgentes, y añade el resto cuando surja la necesidad.

1. Home / Índice

La página principal es el punto de entrada a tu wiki. Debe funcionar como un mapa: cualquier persona del equipo debería poder encontrar lo que busca en menos de 10 segundos. Organízala por categorías con enlaces directos:

# Wiki del equipo

Bienvenido a la wiki del equipo de ingenieria.

## Empezar aqui
- [Onboarding](onboarding.md) - Primeros pasos
- [Arquitectura](architecture.md) - Como funciona todo

## Procesos
- [Deployment](deployment.md) - Como desplegar
- [Code Review](code-review.md) - Guia de revisiones
- [Incidentes](incidents.md) - Que hacer si algo falla

## Referencias
- [Stack tecnico](stack.md) - Tecnologias que usamos
- [Glosario](glossary.md) - Terminos del dominio

2. Onboarding

La página de onboarding es probablemente la más valiosa de toda tu wiki. Cada vez que entra alguien nuevo al equipo, esta página le guía paso a paso en su primera semana. Sin ella, el conocimiento queda atrapado en la cabeza de los veteranos y cada incorporación requiere horas de explicaciones repetidas. Usa checkboxes para que la nueva persona pueda marcar su progreso:

# Onboarding

Bienvenido al equipo! Sigue estos pasos en tu primera
semana.

## Dia 1: Setup
- [ ] Configurar acceso a GitHub
- [ ] Clonar el repositorio principal
- [ ] Instalar dependencias (`npm install`)
- [ ] Ejecutar el proyecto en local
- [ ] Leer la [arquitectura](architecture.md)

## Dia 2-3: Contexto
- [ ] Leer los ultimos 5 ADRs
- [ ] Revisar los 3 PRs mas recientes
- [ ] Hablar con tu buddy (asignado en Slack)

## Primera semana
- [ ] Resolver tu primer issue (etiqueta: good-first-issue)
- [ ] Abrir tu primer PR
- [ ] Asistir a la retro del viernes

3. ADRs (Architecture Decision Records)

Los ADRs documentan decisiones técnicas importantes y, sobre todo, el porqué detrás de cada decisión. Seis meses después, cuando alguien pregunte "¿por qué usamos PostgreSQL y no MySQL?", la respuesta estará en el ADR correspondiente. Cada ADR sigue un formato estándar con estado, contexto, decisión, motivos y consecuencias:

# ADR-001: Usar PostgreSQL como base de datos

## Estado
Aceptado (2024-11-15)

## Contexto
Necesitamos una base de datos relacional para el
servicio de usuarios. Las opciones son PostgreSQL,
MySQL y SQLite.

## Decision
Usaremos PostgreSQL.

## Motivos
- Soporte nativo de JSON (jsonb) para datos flexibles
- Mejor rendimiento en consultas complejas
- El equipo tiene experiencia previa
- Extensiones utiles (PostGIS, pgvector)

## Consecuencias
- Necesitamos configurar un servidor PostgreSQL
- El backup requiere pg_dump en lugar de copiar archivos
- Migraciones con Prisma o similar

4. Runbooks

Un runbook es un procedimiento paso a paso para situaciones críticas. La idea es que cualquier persona del equipo pueda seguir el runbook y resolver el problema, incluso si es su primer día o son las 3 de la madrugada. Cuanto más detallado y claro, mejor. Incluye comandos exactos que se puedan copiar y pegar:

# Runbook: Respuesta a incidentes

## Severidad critica (produccion caida)

1. **Comunicar**: Mensaje en #incidents de Slack
2. **Evaluar**: Revisar dashboards en Grafana
3. **Mitigar**: Rollback si es un deploy reciente
   ```bash
   git revert HEAD && git push origin main
   ```
4. **Investigar**: Revisar logs en Datadog
5. **Resolver**: Aplicar fix y desplegar
6. **Postmortem**: Crear documento en /postmortems

Buenas prácticas

  1. Escribe para tu yo del futuro: En 6 meses no recordarás por qué se tomó una decisión. Documéntalo.
  2. Mantén un índice actualizado: Si no se encuentra, no existe.
  3. Fecha las páginas: Añade Última actualización: 2026-03-12 para saber si la información es reciente.
  4. Usa plantillas: Crea plantillas para tipos de páginas recurrentes (ADRs, runbooks, onboarding).
  5. Revisa periódicamente: Programa una revisión mensual para detectar contenido obsoleto.
  6. Empieza pequeño: No intentes documentar todo de golpe. Empieza con onboarding y runbooks, que son los más urgentes.

Recursos relacionados

👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.

para estar al día con mi contenido. 😊