Saltar a contenido

Sistema de documentación

Manifiesto
Configuración de Obsidian

Arquitectura del Sistema

La idea general

Resumen de la arquitectura

Aquí hay una representación gráfica de la arquitectura del sistema:

flowchart LR
A(Contenidos) --> B(Control de versiones)
C(Software de edición) --> A
A --> D(Hacer accesible en línea)

En detalle:

Resumen de la arquitectura

flowchart LR
A[Obsidian] <--> B{Archivos}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Tema: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D
  • Obsidian: Un editor de texto opcional, pero recomendado por mí, para editar archivos Markdown.
  • Archivos: Los archivos Markdown que contienen el contenido de mi documentación.
  • Github Desktop: Una herramienta para gestionar fácilmente mis repositorios de Git.
  • Github: Un servicio en línea para control de versiones y colaboración.
  • Github Pages: Un servicio gratuito para publicar mi sitio web.
  • MkDocs: Una herramienta para generar automáticamente el sitio web a partir de mis archivos Markdown.
  • MkDocs-Material: Un tema para MkDocs que ofrece un diseño moderno y atractivo.
  • MkDocs-Publisher: Una colección de plugins que facilita la colaboración con Obsidian y ofrece funcionalidad adicional.

Componentes en detalle

1. Markdown

Markdown como base

Utilizo el formato Markdown para mi documentación. Markdown es un lenguaje de marcado sencillo que me permite dar formato de texto simple (por ejemplo, encabezados, listas, enlaces).

Ventajas:

  • Es fácil de aprender y usar, lo que me permite centrarme en el contenido.
  • Es independiente de la plataforma, por lo que puedo continuar mi trabajo en cualquier dispositivo.
  • Es ideal para el control de versiones, lo que me permite rastrear y gestionar los cambios.
  • Es a prueba de futuro y no propietario, lo que me da la seguridad de que mi trabajo seguirá siendo accesible a largo plazo.

Markdown

2. Obsidian

Obsidian como editor de texto

Obsidian es un editor de texto opcional, pero recomendado por mí. Me ofrece las siguientes ventajas:

  • Puedo almacenar mis datos localmente y editarlos sin conexión, lo que me da flexibilidad y control.
  • Puedo enlazar y conectar archivos fácilmente entre sí, lo que me ayuda a organizar información compleja.
  • Puedo etiquetar y gestionar archivos fácilmente, lo que me proporciona una dimensión adicional de organización.
  • Puedo visualizar mis datos gráficamente, lo que me ayuda a reconocer patrones y relaciones.
  • Puedo ampliar la funcionalidad de Obsidian mediante plugins, lo que me permite adaptar la herramienta a mis necesidades específicas.

3. Git y Github

Git para control de versiones

Git es un sistema de control de versiones que me permite rastrear y gestionar los cambios en la documentación. Github es un servicio en línea que me permite almacenar mis repositorios de Git y colaborar con otros.

Ventajas:

  • Control de versiones: Cada cambio se documenta y se puede rastrear en cualquier momento, lo que me ayuda a evitar errores y a mantener una visión general.
  • Colaboración: Varias personas pueden trabajar en la documentación al mismo tiempo, lo que me da la oportunidad de integrar comentarios y contribuciones de otros.
  • Copia de seguridad: Mi documentación está segura y se copia de seguridad regularmente, lo que me da la seguridad de que mi trabajo no se perderá.

4. Github Desktop

Github Desktop como herramienta

Github Desktop es una interfaz gráfica para Git que me permite usar Git de forma sencilla y sin línea de comandos.

Ventajas:

  • Fácil de usar, lo que me facilita el uso de Git.
  • No se requieren conocimientos de línea de comandos, lo que me ahorra tiempo y esfuerzo.
  • Simplifica mi flujo de trabajo, lo que me permite centrarme en la creación de contenido.

5. MkDocs

MkDocs como generador de sitios web

MkDocs es un generador de sitios estáticos que convierte mis archivos Markdown en un sitio web estático.

Ventajas:

  • Creación sencilla de sitios web, lo que me permite publicar mi documentación de forma rápida y sencilla.
  • Actualización rápida, lo que me permite ver los cambios en tiempo real.
  • Diseño coherente, lo que garantiza una presentación profesional y uniforme de mi documentación.
  • Vista previa sin conexión, lo que me permite revisar mi documentación antes de publicarla.

6. Github Pages

Github Pages para alojamiento

Github Pages es un servicio de alojamiento gratuito de Github que me permite publicar mi sitio web fácilmente en línea.

Ventajas:

  • Alojamiento gratuito, lo que me permite publicar mi documentación sin costes adicionales.
  • Publicación sencilla, lo que me libera de la implementación técnica de la publicación.
  • Fiable, lo que me da la seguridad de que mi documentación estará disponible en todo momento.

7. MkDocs-Material

MkDocs-Material como tema

MkDocs-Material es un tema para MkDocs que ofrece un diseño moderno y atractivo.

Ventajas:

  • Diseño moderno, lo que hace que mi documentación parezca profesional y actual.
  • Personalizable, lo que me permite adaptar el diseño a mis necesidades específicas.
  • Fácil de usar, lo que me facilita el uso de la documentación.

8. MkDocs-Publisher

MkDocs-Publisher como colección de plugins

MkDocs-Publisher es una colección de plugins de MkDocs que simplifican la colaboración con Obsidian y ofrecen funciones adicionales.

Ventajas:

  • Integración simplificada con Obsidian: Adaptación automática de la sintaxis Markdown de Obsidian (callouts, wikilinks, etc.).
  • Metadatos ampliados: Integración de etiquetas y categorías del frontmatter de Obsidian.

Flujo de trabajo

Mi flujo de trabajo

Aquí está mi flujo de trabajo típico:

  1. Creo y edito archivos Markdown con un editor de texto (opcionalmente Obsidian).
  2. Guardo los archivos Markdown localmente.
  3. Subo mis cambios al repositorio de Git con Github Desktop.
  4. Genero automáticamente el sitio web con MkDocs.
  5. Publico el sitio web con Github Pages.

Sistema de archivos

Estructura de directorios

Aquí está la estructura de directorios de mi sistema:

/docs/     (Aquí están mis archivos Markdown)
/site/     (Aquí se genera el sitio web)
license    (Información de licencia)
mkdocs.yml (Archivo de configuración para MkDocs)
readme.md  (Archivo para describir el repositorio)

Alternativas para la creación de contenido

Alternativas para la creación de contenido

Soy consciente de que no todo el mundo está familiarizado con Markdown y Git. Por lo tanto, ofrezco las siguientes alternativas:

  1. Wordpress: El contenido se puede crear en Wordpress como una página.
  2. Archivo de texto, archivo de Word: El contenido se puede crear como un archivo de texto, un archivo de Word (o en otros formatos típicos).

En estos casos, puedo incorporar el contenido al sistema.