Introduccin

Este es un sistema, llamado Serie Mini, para la creacin de colecciones culturales digitales simples y mnimas. Est pensado como medio educativo en el contexto de las artes y humanidades digitales o como herramienta para proyectos culturales de computacin mnima que requieran crear sitios estticos, livianos y portables.

Como ejemplo, aqu puedes ver un ejemplo de una coleccin de fanzines hecha con Serie Mini: enlace.

El sistema permite crear un sitio web con algunas pginas esenciales en una coleccin cultural digital: una portada, una pgina de exploracin, un recorrido guiado con visualizaciones interactiva, una pgina con metadatos, y una pgina para cada tem de la coleccin con un visor de imgenes y una presentacin de metadatos. Los sitios generados con Serie Mini pueden publicarse en GitHub pages de forma gratuita por defecto (o en otras plataformas de alojamiento), lo que permite crear colecciones con requerimientos mnimos de recursos econmicos y mantenimiento.

Serie Mini est pensada para facilitar al mximo la creacin de colecciones digitales a personas que estn apenas entrando en el tema o en las artes y humanidades digitales en general.

No obstante, estes sistema tambin puede ser extendido por personas con un conocimiento ms avanzado de programacin y diseo web. Concretamente, el sistema est construido usando Node y el framework Svelte de diseo web y componentes personalizados.

Serie Mini est inspirada en otros proyectos similares, especialmente Wax y Collection Builder, que siguen principios de computacin mnima en el campo de las humanidades digitales, pero tiene algunas diferencias:

• Es bilinge. Su interfaz funciona en espaol e ingls.
• Est pensada para, en la medida de lo posible, ser fcil de usar para principiantes. As, es mnima pero tambin simple. Por su simpleza, tiene algunas restricciones artificiales que evitan que los usuarios nuevos se abrumen, pero tambin es extensible.
• No utiliza Jekyll como base. Por el contrario, est basada en Node, que es compatible de fbrica con Windows, Linux y Mac, y se usa de la misma forma en todos los sistemas operativos. Esto evita problemas de instalacin y compatibilidad, y as no es necesario usar contenedores de Docker u otras maromas.
• Es extensible. Se pueden aadir nuevas caractersticas integrables al sistema de base.

Instrucciones de uso

0. Prerrequisitos

Para usar la plantilla es necesario cumplir los siguientes prerrequisitos:

• Tener una cuenta en GitHub y el programa GitHub Desktop instalado en el computador (inicia sesin en Github desktop con tu cuenta de GitHub)
• Tener una versin reciente de Node.js instalada en el computador
• Tener el editor de texto Visual Studio Code (es posible usar otro editor, pero estas instrucciones estn basadas en ese editor)

1. Crear un repositorio a partir de esta plantilla

En el explorador web, entra a tu cuenta de GitHub, visita el repositorio de esta plantilla https://github.com/srsergiorodriguez/serie-mini, y haz clic en "Use this template/Create a new repository". Asigna un nombre al repositorio. Escoge un nombre significativo y sencillo para la coleccin que vas a crear.

2. Cargar el repositorio en el computador

En la aplicacin GitHub Desktop haz clic en "Add/Clone repository", luego busca el repositorio que acabas de crear, selecciona la ruta en donde quieres que se guarde el repositorio en tu computador y haz clic en "clone". Se copiarn todos los elementos de la plantilla en esa carpeta, que llamaremos carpeta del proyecto. Recuerda esa ruta porque se necesitar luego!

Ahora, usando el explorador de archivos de tu sistema operativo busca la ruta escogida y arrastra la carpeta del proyecto a Visual Studio Code. Esto le indicar al editor de texto que todos los archivos de esa carpeta son parte de un proyecto completo. Abre la terminal de Visual Studio Code usando el men "View(o Ver)/Terminal". Se abrir una terminal de lnea de comandos en la parte inferior de Visual Studio code. De ahora en adelante, la llamaremos la terminal. Aqu debemos ingresar varios comandos para completar la configuracin.

3. Instalar dependencias de Node

En la terminal, copia y pega el siguiente comando: npm install y presiona enter. Esto instalar las dependencias del proyecto. Puede tardar unos minutos.

4. Preparar metadatos e imgenes

Abre la carpeta "data" contenida dentro de la carpeta del proyecto en el explorador de archivos, aqu debes reemplazar el archivo "metadata.csv" por uno que contenga los metadatos de tu coleccin y debes reemplazar las imgenes contenidas en la carpeta "raw_images" por las que corresponden a tu coleccin, cada imagen debe nombrarse con un pid (identificador personal nico) que corresponda a una fila en tu archivo de metadatos. Puedes usar archivos jpg, png, tiff, y gif; o, en el caso de varias imgenes por tem, puedes crear una carpeta (que debe tener el nombre del pid) con varias imgenes en los formatos vlidos (estas imgenes pueden tener cualquier nombre, pero en la presentacin se mostrarn por orden alfabtico).

:eyes: OJO: es NECESARIO que el archivo csv contenga al menos dos columnas: una llamada "pid" (en minsculas) con un identificador NICO para cada tem de la coleccin, y una llamada "label" (en minsculas) con un ttulo para el tem. El pid de cada tem solo puede contener nmeros y letras ascii (es decir, nada de signos de puntuacin, espacios, acentos u otros caracteres). Todas las dems columnas son opcionales y pueden tener los datos que consideres relevantes y siguiendo tus propios protocolos (aunque no puedes iniciar el nombre de la columna con un guion bajo '_', est reservado). Revisa el archivo "metadata.csv" que viene por defecto ante las dudas.

:eyes: OJO2: es NECESARIO que las imgenes o la carpeta con mltiples imgenes tengan EXACTAMENTE (incluyendo maysculas y minsculas) el mismo nombre que el "pid" del tem al que corresponden. Revisa las imgenes que vienen por defecto en la carpeta "raw_images" ante las dudas.

5. Crear archivo de configuracin.

En la terminal, copia y pega el siguiente comando npm run config y presiona enter. Se iniciar una interfaz de configuracin en la terminal que te guiar en el proceso de creacin del sitio de tu coleccin. La informacin que te pedir la interfaz de configuracin es la siguiente:

| Configuracin | Descripcin | |--- |--- | | Nombre de usuario | Nombre de usuario de la cuenta de GitHub en donde se subir el sitio | | Nombre del repositorio | Nombre del repositorio creado desde la plantilla | | Ttulo de la coleccin | Ttulo que aparecer en el banner del sitio | | Mensaje crditos | Mensaje que aparecer en el footer con los crditos. Por ejemplo, tu nombre o nombre de organizacin | | Mensaje copyright | Mensaje de derechos de autor que aparecer en el footer. Por defecto, "Todos los derechos reservados" | | Mensaje crditos | Mensaje que aparecer en el footer con los crditos. Por ejemplo, tu nombre o nombre de organizacin| | Metadatos para mostrar | Lista de las columnas de metadatos que se mostrarn en la pgina de cada tem de la coleccin | | Metadatos para indexar | Lista de las columnas de metadatos que indexarn en el buscador. Solo estos metadatos se podrn buscar en la interfaz de explorar. Si no escoges niguno se indexarn TODOS |

:eyes: OJO: Asegrate de haber preparado la tabla de metadatos antes de hacer la configuracin. Algunas de las preguntas de la interfaz de configuracin usan esa tabla. Luego puedes aadir nuevos tems (filas) a la tabla sin problemas, pero debers correr de nuevo la interfaz de configuraci si quieres que se presenten esos nuevas columnas en las pginas de tems o que sean indexados en el buscador.

:point_up: NOTA: si ya tienes familiaridad con este tipo de sistemas de configuracin, puedes editar el archivo "serie.config.js" directamente en la carpeta "data" sin necesidad de usar la interfaz de configuracin.

6. Construir el sitio en modo desarrollador

Antes de crear la versin final del sitio, puedes construirlo en modo desarrollador, esto te permitir ver y editar una versin de previsualizacin localmente, sin necesidad de subirla a internet. Para hacerlo, copia y pega el siguiente cdigo en la terminal npm run dev y presiona enter.

Este cdigo realizar algunas tareas de construccin del sitio, de acuerdo con tu configuracin, metadatos e imgenes. Dependiendo de la cantidad de imgenes que tengas en tu colecicn, estas tareas pueden tomar unos minutos. Luego se crear el sitio y se servir localmente. Busca en la terminal un aviso que dice Local: seguido de una direccin en color azul. Copia esa direccin en tu explorador web, all podrs previsualizar cmo se ver tu sitio.

:point_up: NOTA: si solo necesitas la previsualizacin pero no requieres ejecutar las tareas nuevamente, por ejemplo, si no modificaste las imgenes, la configuracin o los metadatos, pero necesitas previsualizar y editar el contenido de las pginas o su diseo en Svelte, puedes simplemente ejecutar el siguiente cdigo: npm run preview. Igualmente, si solo necesitas ejecutar las tareas, para posteriormente crear el build final del sitio, sin pasar por previsualizacin, puedes ejecutar el cdigo: npm run tasks.

7. Editar el contenido del sitio

En la carpeta "data/content" dentro de la carpeta del proyecto encuentras una serie de archivos en formato svx que definen el contenido de las pginas estticas de la coleccin. Estas pginas se pueden editar usando las convenciones de Markdown. Los cambios hechos en estos archivos se insertarn y actualizarn automticamente, as que, en modo desarrollador, podrs ver la apariencia final de las pginas y editarlas a tu gusto.

Como esta es una plantilla simple y pensada como herramienta pedaggica, el sitio contiene una serie de pginas de base en Markdown en esta carpeta que cumplen varias funciones especficas. Como se describe a continuacin:

| Pgina | Descripcin | |--- |--- | | portada | Es la primera pgina que aparece cuando se carga el sitio. Aqu puedes hacer una introduccin a la coleccin | | explorar | Esta pgina contiene un buscador y una galera bsicos para ver un sobrevuelo de la coleccin | | tour | En esta pgina puedes hacer un ensayo o recorrido por temas o elementos particulares de la coleccin con algunas visualizaciones interactivas | | creditos | En esta pgina puedes poner tus crditos detallados. Se accede a travs del footer | | metadatos | En esta pgina se muestra una tabla con los metadatos de la coleccin y un botn para descargarlos. Puedes usarla, como se muestra en el ejemplo, para poner otra informacin relacionada con la recoleccin y modelado de los datos. Por ejemplo, sus protocolos |

Componentes adicionales

Adicional al formato tradicional de Markdown, puedes incrustar en las pginas diversos componentes interactivos y visualizaciones que extienden la narrativa y navegacin de la coleccin. Para agregar un componente es necesario importarlo dentro de una etiqueta de script entre el front matter y el contenido del archivo svx. Para importar un componente debes usar este formato:

JavaScript <script> import NOMBREDECOMPONENTE from "$components/NOMBREDECOMPONENTE.svelte" </script>

Ante las dudas, revisa el archivo "tour" en "data/content".

Luego de la importacin puedes poner los componentes en la parte del contenido que consideres necesario usando la etiqueta con el nombre del componente y sus props o argumentos, si aplica. Los props son los argumentos que requiere un componente para funcionar adecuadamente. La siguiente tabla describe los componentes implementados hasta el momento (los props con asterisco son opcionales).

| Componente | Props | Descripcin | |--- |--- |--- | | ItemPreview | pid=pid de tem, *title=texto descriptivo *alt=texto alternativo *page=por defecto, 1. Pgina del tem a mostrar | Previsualizador de tem de la coleccin. Si se cliquea lleva a la pgina del tem | | SearchBar | | Barra de bsqueda simple de tems de la coleccin | | Gallery | *metadata=array con metadatos prefiltrados, *filters=array con nombres de columna para los filtros | Galera de tems de la coleccin con filtros | | VizBarChart | key=nombre de columna categrica | Grfico de barras horizontales que muestra un conteo de categoras | | VizHistogram | key=columna con valores numricos | Histograma que muestra la frecuencia de valores numricos | | VizTree | keys=array con nombres de columnas categricas, *metadata=array con metadatos prefiltrados | rbol filtrable que muestra la estructura jerrquica de la coleccin | | VizTimeline | dateKey=nombres de columna con fechas vlidas, *metadata=array con metadatos prefiltrados | Lnea de tiempo que permite explorar los tems de acuerdo con fechas |

:point_up: NOTA: usuarios ms avanzados pueden crear sus propias pginas y componentes adicionales usando Svelte.

8. Publicar el sitio

Una vez tengas una versin terminada del sitio lista para publicar, asegrate de salir del modo "dev" (presionando Ctrl/command + c), copia y pega este cdigo en la terminal: npm run build y presiona enter. Esto crear una versin publicable del sitio en la carpeta "docs" dentro de la carpeta del proyecto. Ahora visita tu repositorio en el sitio web de GitHub (no olvides loggearte), haz clic en el botn "Settings" y, luego, en la columna izquierda, haz clic en "Pages". All, selecciona, justo debajo de la opcin "Branch", lo siguiente: en el selector que dice "None", selecciona "main". Y en el nuevo selector que aparecer, selecciona "/docs". Esto le indica a Github que tu pgina para publicar est en la carpeta "docs".

Luego de hacer esto, GitHub crear un sitio web con la coleccin. Puede tomar unos minutos en terminar. Una vez est completo, podrs visitar el sitio en un enlace con este formato: https://TU_NOMBRE_DE_USUARIO.github.io/TU_REPOSITORIO/.

:point_up: NOTA: Asegrate de haber ejecutado npm run dev o npm run tasks antes de crear la versin terminada del sitio si modificaste la configuracin, los metadatos o las imgenes de la coleccin.

Opciones para usuarios intermedios

• En el archivo serie.config.js en la carpeta data puedes modificar el texto que aparecer como nombre de cada columna de metadatos modificando el objeto "metadataToShow" y el parmetro "label" en cada elemento.
• En el archivo serie.config.js en la carpeta data puedes agregar un parmetro para aadir logos en el footer y uno para aadir una imagen de fondo al encabezado. Para aadir logos, debes incluir el parmetro "logos", y este debe contener una array de objetos. Cada objeto representa un logo y debe tener los siguientes parmetros {img: RUTA_LOCAL_O_URL_A_IMAGEN, link: ENLACE}. Para aadir una imagen de fondo al encabezado, debes incluir el parmetro "banner" y darle como valor una ruta local (en la carpeta static o una url a una imagen).
• En el archivo serie.config.js en la carpeta data puedes modificar el tipo de presentacin de cada metadato modificando el objeto "metadataToShow" y el parmetro "type" en cada elemento. Esta es una opcin muy poderosa, porque permite enriquecer la diversidad de metadatos de la coleccin. El tipo por defecto es "text", que simplemente muestra el valor como texto plano. Los tipos de presentacin posibles son:

| Tipo | Descripcin | |--- |--- | | text | Se mostrar el texto del dato tal cual como est en la tabla | | link | El dato debe ser una url vlida. Se mostrar un enlace cliqueable a tal url | | ref | Una lista, separada por / y sin espacios de pids de otros elementos dentro de la coleccin. Se mostrar una serie de enlaces que llevan a la pgina de cada pieza referenciada por pid | | image | El dato debe ser una ruta vlida desde la carpeta static a un archivo de imagen o una url externa. Se mostrar la imagen | | video | El dato debe ser una ruta vlida desde la carpeta static o una url externa a un archivo de video en un formato vlido. El video debe ponerse en esa ruta. Por ejemplo: video/mi-pelicula.mp4. Se mostrar un reproductor de video incrustado | | audio | El dato debe ser una ruta vlida desde la carpeta static o una url externa a un archivo de audio en un formato vlido. El audio debe ponerse en esa ruta. Por ejemplo: audio/mi-grabacion.wav. Se mostrar un reproductor de audio incrustado | | youtube | El dato debe ser el id de un video de YouTube. Por ejemplo, en el video https://www.youtube.com/watch?v=VTvluHmL4fY&ab_channel=Automata, el id es la secuencia de letras y nmeros despus de v= y, si es el caso, antes del caracter &. As, en el ejemplo, el id es VTvluHmL4fY. Se mostrar un reproductor de video de YouTube incrustado. |

Funciones de lnea de comandos

Las siguientes son las funciones de la lnea de comandos disponibles en Serie Mini

| Comando | Accin | |--- |--- | | npm run config | Inicia la interfaz CLI de configuracin del proyecto. Usar este comando cuando se crea el proyecto por primera vez | | npm run clear | Elimina la carpeta con derivatives IIIF | | npm run tasks | Elimina la carpeta con derivatives IIIF, actualiza los metadatos, el ndice de bsqueda, la presentacin basada en la configuracin y crea nuevos derivatives desde cero | | npm run dev | Elimina la carpeta con derivatives IIIF, actualiza los metadatos, el ndice de bsqueda, la presentacin basada en la configuracin, crea nuevos derivatives desde cero e inicia el servidor local de prueba. Usar este comando cuando se crea la coleccin por primera vez | | npm run preview | Inicia el servidor local de prueba sin modificar los metadatos o derivatives de la coleccin y sin actualizar la presentacin basada en la configuracin. Usar este comando cuando solo se quiere modificar el contenido o la apariencia del sitio | | npm run update | Actualiza los metadatos, y crea derivatives solo para nuevos tems. Este commando evita tiempo de procesamiento cuando solo se quiere extender la coleccin con ms elementos o actualizar la presentacin basada en el archivo de configuracin | | npm run build | Crea una versin de produccin. Usar este comando cuando se quiere publicar una nueva versin del sitio |

Ruta de trabajo y sostenibilidad del proyecto

Versin actual: 2.0.0

Caractersticas bsicas

A continuacin hay una lista de las caracterstcas desarrolladas para la versin 1.0.0 Es decir, la versin bsica del sistema:

• [x] Readme con documentacin en espaol
• [x] Archivo de configuracin global
• [x] CLI de instalacin bilinge espaol e ingls
• [x] Interfaz de sitio web en espaol e ingls
• [x] Buscador de la coleccin (usa indexado basado en la librera Lunr)
• [x] Procesamiento de imgenes para IIIF 3. Mltiples imgenes por tem (usa la librera Sharp para la produccin de derivatives IIIF y thumbnails)
• [x] Generacin de manifests IIIF para cada imagen (usa la librera digital-piranesi/iiif-manifest-library) (1.0)
• [x] Visor de imgenes IIIF 3 (usa la librera OpenSeaDragon)
• [x] Componente de previsualizacin de tem hipervinculado a pgina de tem
• [x] Soporte Markdown para edicin simplificada de pginas (usa la librera mdsvex)
• [x] Interfaz de galera con filtros de exploracin
• [x] Distintos modos de presentacin de los metadatos (texto, link, referencia, video, audio, imagen...)
• [x] Espacio para banner en el header y logos en el footer

Caractersticas adicionales

Serie Mini funciona modularmente, as que se pueden aadir nuevas caractersticas y capacidades al sistema bsico de colecciones que pueden potenciar las formas de presentacin y anlisis de los tems. Debido a que Serie Mini es un proyecto de cdigo abierto e independiente, se requieren recursos, tiempo y experticia para poder llevar a cabo e incluir esas al sistema. Por ese motivo, estoy abierto a donaciones y patrocinios que permitan continuar con el desarrollo de ellas. Instituciones o individuos interesados pueden aportar al proyecto y pueden sugerir nuevas caractersticas.

Aunque no existe una cantidad especfica para el patrocinio, para que el proyecto y desarrollo de caractersticas sea sostenible, es ideal que una institucin, grupo o individuo patrocinante financie el desarrollo de una caracterstica por completo (o varias de ellas), es decir, las horas de trabajo aproximadas que implicara obtener un resultado de produccin de la caracterstica. Esto en ninguna medida quiere decir que los patrocinantes sean de ninguna manera dueos de la caracterstica o que los tiempos y compromisos del desarrollo estn definidos u obligados por el patroncinio. A continuacin presento una lista de posibles caractersticas que encajan en la ruta de desarrollo del proyecto (algunas de ellas ya desarrolladas):

• [ ] Exportacin de folleto de la coleccin en pdf
• [ ] Visor de textos anotados en TEI
• [ ] Visualizacin de la coleccin con grafos
• [ ] Extraccin de paletas de color de las imgenes de la coleccin
• [ ] Visualizacin de grfico de dispersin de imgenes al estilo ImagePlot
• [ ] Mapa de burbujas y grafo en mapa
• [ ] Paneles interactivos usando Aventura
• [x] Lnea de tiempo, histograma, grfico de barras, grfico de rbol
• [ ] Temas instalables

A cambio de la donacin al proyecto, la institucin, grupo o individuos patrocinantes sern reconocidos pblicamente (usando su nombre y logo y especificando el tipo de patrocinio) en este documento y en el footer del sitio de muestra de la coleccin.

Adicionalmente, individuos interesados pueden donar usando los enlaces de Ko-fi y Buy me a Coffee.

Charlas y talleres

Otra alternativa para apoyar la sostenibilidad del proyecto es la contratacin de charlas relacionadas con humanidades digitales y la construccin de coleccin o talleres acerca del uso de Serie Mini. El costo de las charlas y talleres se calcula en horas y se acuerda con la institucin que lo requiera.

Crditos

Este sistema es desarrollado por Sergio Rodrguez Gmez. Sigue los principios del cdigo abierto y se ampara en una licencia MIT.