211 lines
11 KiB
Markdown
211 lines
11 KiB
Markdown
# Web
|
|
Este proyecto consiste en un sitio web estático desarrollado con [Jekyll]() con el tema [no-style-please](https://riggraz.dev/no-style-please/) a modo de blog para redactar sobre el Software Libre y de Código Abierto.
|
|
|
|
## Estructura
|
|
El sitio web consta de una página inicial declarada solo con la cabecera como fichero `index.md` en [Markdown](https://daringfireball.net/projects/markdown/) y especificada en formato [YAML](https://yaml.org/) y situada en `_data/menu.yml` a modo de lista. En la misma, se declara los enlaces a las distintas publicaciones y resto de páginas del sitio.
|
|
|
|
Adicionalmente, existe una página de redacción declarada en el fichero `redaction.md` donde se especifican las personas que redactan los artículos.
|
|
|
|
Las publicaciones, están escritas en Markdown, adjuntando una cabecera adicional descrita más adelante, y situadas en `_posts/`.
|
|
|
|
Por defecto, en la página inicial no se listan todas las publicaciones, sino que tienen un máximo definido y pasando al archivo cuando sobre pasa el límite. El archivo es un conjunto de ficheros en Markdown que constan de una única cabecera y están situados en `archive/`. Existe uno general y otro por cada categoría.
|
|
|
|
Las configuraciones generales del sitio se declaran en el fichero `_config.yml`, y el fichero Gemfile indica las dependencias de [Ruby](https://www.ruby-lang.org/) que necesita el sitio.
|
|
|
|
## Funcionamiento
|
|
La web es actualizada cada 30 minutos usando un script en la [crontab](https://pubs.opengroup.org/onlinepubs/007908775/xcu/crontab.html) del usuario donde está instalado Jekyll.
|
|
|
|
El script actualiza la copia del repositorio local, descarga o instala las dependencias de Ruby correspondientes y genera compila el sitio desde los ficheros fuente.
|
|
|
|
El script es el fichero `update.sh`.
|
|
|
|
## Participación
|
|
Cualquier persona puede participar en la redacción de artículos de este sitio web siguiendo las directrices especificadas posteriormente.
|
|
|
|
### Objetivos
|
|
Si bien la descripción del sitio web ya da indicios de lo que se comenta, es conveniente aclarar cuales son los objetivos a cumplir al elaborar artículos.
|
|
|
|
Así como se mencionan, son objetivos, no reglas estrictas, dado que pueden existir casos en los que sea imposible evitar alguna, pero se aspirará a ello en la medida de lo posible.
|
|
|
|
Estos son:
|
|
* Redactar exclusivamente de Software Libre y de Código Abierto
|
|
* Utilizar una expresión natural y neutral
|
|
* Ser neutral en asuntos ajenos a lo que se redacta
|
|
* Ser respetuoso con otros individuos
|
|
|
|
### Páginas
|
|
Las páginas son los elementos estáticos con menos flexibilidad del sitio web.
|
|
|
|
#### Tipos
|
|
Actualmente, el sitio web cuenta con 3 tipos de páginas, declaradas en base a las plantillas del tema:
|
|
* Básico
|
|
* Complejo
|
|
* Inicio
|
|
* Archivo
|
|
|
|
La diferencia principal entre cada tipo radica en la declaración de sus cabeceras donde las básicas cuentan con un número limitado y permanente de atributos y las complejas lo varían.
|
|
|
|
El tipo «Inicio» está reservado para la página de inicio del sitio web mientras del resto se pueden crear tantos como se necesiten.
|
|
|
|
#### Redacción
|
|
La creación y redacción de una página es determinado por acuerdo previo con el resto del personas que participan en la redacción.
|
|
|
|
Para la redacción, es necesario tener en cuenta el formato y situación del fichero que representa cada página, lo que hay que incluir en su cabecera y lo acordado para el contenido.
|
|
|
|
##### Fichero
|
|
Las nuevas páginas son ficheros con extensión `.md` creados en la raíz de las fuentes del sitio web. Sus nombres deberán ser cortos, de una o dos palabras y en minúscula.
|
|
|
|
En el caso de haber una o más páginas que contengan algo en común como las páginas del archivo, deberán ser agrupadas en un subdirectorio nombrandolo de forma que se identifique aquello que tienen las páginas en común y siguiendo la misma regla que para los nombres de las páginas.
|
|
|
|
##### Cacebera
|
|
Para explicar la estructura de la cabecera es necesario un ejemplo de una compleja utilizada en una página de archivo de categoría.
|
|
|
|
```
|
|
---
|
|
layout: archive
|
|
lang: es
|
|
which_category: news
|
|
title: Publicaciones de noticias
|
|
---
|
|
```
|
|
|
|
Cada uno de los elementos previos a los dos puntos, entre el bloque de tres guiones (`---`), es un atributo de la cabecera, junto a su correspondiente valor a la derecha de los dos puntos.
|
|
|
|
###### layout
|
|
Es el primer atributo básico y obligatorio de toda cabecera. Declara el tipo de página.
|
|
|
|
Las complejas tienen nombres propios como la actual y las simples se declaran como `page`.
|
|
|
|
Los valores posibles son los siguientes:
|
|
* `page`
|
|
* `home`
|
|
* `archive`
|
|
|
|
###### lang
|
|
Es el segundo atributo básico y el primero de los opcionales. Declara el idioma establecido para el contenido de la página.
|
|
|
|
Su valor es el mismo que lleva el atributo `lang` asociado a la etiqueta `HTML` al crear páginas en [HTML](https://www.w3.org/html/).
|
|
|
|
Posee el valor por defecto `en` por lo que, aunque no es obligatorio, es necesario establecer el atributo en la creación de cada página para indicar que está en español.
|
|
|
|
###### which_category
|
|
Es el primer y único atributo complejo y el segundo de los opcionales, específico para las páginas de archivos. Declara la categoría de las publicaciones a listar en la misma.
|
|
|
|
Su valor se corresponde con los mismos nombres de las categorías en inglés y en minúscula, quedando de la siguiente forma:
|
|
* `news`
|
|
* `promotions`
|
|
* `tutorials`
|
|
* `opinions`
|
|
|
|
###### title
|
|
Es el tercer atributo básico y el segundo de los obligatorios. Declara el título de la página.
|
|
|
|
Es necesario que el título tenga una relación directa con la página y contenga una o dos palabras indicando su contenido.
|
|
|
|
##### Contenido
|
|
El contenido de las páginas suele mantenerse sin modificar durante bastante tiempo a excepción de las que listan publicaciones, que lo realiza de forma automática, y la que representa el equipo de redacción.
|
|
|
|
Como se ha indicado anteriormente, debe estar en Markdown.
|
|
|
|
### Publicaciones
|
|
Las publicaciones son los elementos estáticos con mayor flexibilidad del sitio web.
|
|
|
|
Son, elementalmente, un tipo de páginas complejas con una serie de atributos específicos.
|
|
|
|
#### Categorías
|
|
Las categorías clasifican las publicaciones por tema.
|
|
|
|
Existen 4 categorías iniciales:
|
|
* Noticias
|
|
* Promociones
|
|
* Tutoriales
|
|
* Opiniones
|
|
|
|
Para añadir nuevas categorías hay que llegar a un acuerdo entre todas y cada una de las personas que participan en la redacción. Una vez acordada, la categoría simplemente se empezará a utilizar en los nuevos artículos.
|
|
|
|
Adicionalmente, tras la creación de una categoría, es necesario añadir el listado de artículos a la página principal y crear su fichero de archivo.
|
|
|
|
#### Redacción
|
|
La creación y redacción de una publicación es determinado por cualquier persona que quiera participar en la redacción.
|
|
|
|
Para la redacción, es necesario tener en cuenta el formato del fichero que representa cada publicación, lo que hay que incluir en su cabecera y cumplir los objetivos al elaborar el contenido.
|
|
|
|
Por otro lado, la persona o personas encargadas de redactar el artículo deberán añadirse en el fichero de redacción usando títulos de segundo nivel para pseudónimos usados para representarse y una descripción propia como introducción.
|
|
|
|
##### Fichero
|
|
Las publicaciones se crean como ficheros sueltos con extensión `.md` en el directorio `_posts`. Sus nombres deberán incluir la fecha en el formato `AAAA-mm-dd` seguido con un guión (`-`) y, finalmente, el título de la publicación en minúscula usando caracteres ASCII.
|
|
|
|
##### Cabecera
|
|
Para explicar la estructura de la cabecera es necesario un ejemplo de una compleja utilizada en una publicación de prueba.
|
|
|
|
```
|
|
---
|
|
layout: post
|
|
lang: es
|
|
title: "Welcome to Jekyll!"
|
|
date: 2021-01-03 13:31:05 -0800
|
|
categories: news
|
|
---
|
|
```
|
|
|
|
Cada uno de los elementos previos a los dos puntos, entre el bloque de tres guiones (`---`), es un atributo de la cabecera, junto a su correspondiente valor a la derecha de los dos puntos.
|
|
|
|
###### layout
|
|
Es el primer atributo básico y obligatorio de toda cabecera. Declara el tipo de página.
|
|
|
|
Su valor, para indicar que es una publicación, debe ser `post`.
|
|
|
|
###### lang
|
|
Es el segundo atributo básico y el primero de los opcionales. Declara el idioma establecido para el contenido de la publicación.
|
|
|
|
Su valor es el mismo que lleva el atributo `lang` asociado a la etiqueta `HTML` al crear páginas en [HTML](https://www.w3.org/html/).
|
|
|
|
Posee el valor por defecto `en` por lo que, aunque no es obligatorio, es necesario establecer el atributo en la creación de cada publicación para indicar que está en español.
|
|
|
|
###### title
|
|
Es el tercer atributo básico y el segundo de los obligatorios. Declara el título de la publicación.
|
|
|
|
Es necesario que el título tenga una relación directa con la publicación, contenga varias palabras, indique algo de su contenido y además intente ser llamativo.
|
|
|
|
###### date
|
|
Es el primer atributo complejo y el tercero de los obligatorios. Declara la fecha de la publicación.
|
|
|
|
La fecha debe seguir el formato `AAAA-mm-dd HH:MM:SS DIFERENCIA-HORARIA` en cada publicación.
|
|
|
|
Una buena forma de obtenerla es especificándola como entrada al programa `date` de la siguiente forma:
|
|
```
|
|
date +"%Y-%m-%d %H:%M:%S %z"
|
|
```
|
|
|
|
###### categories
|
|
Es el segundo atributo complejo y el segundo de los opcionales. Declara la categoría de la publicación.
|
|
|
|
Su valor se corresponde con los mismos nombres de las categorías en inglés y en minúscula, quedando de la siguiente forma:
|
|
* `news`
|
|
* `promotions`
|
|
* `tutorials`
|
|
* `opinions`
|
|
|
|
Como sugiere el nombre, este atributo soporta especificar más de una categoría pero en este sitio web solo utilizaremos una por artículo en caso de así decidirlo.
|
|
|
|
##### Contenido
|
|
El contenido de las publicaciones deberá seguir los objetivos marcados en el sitio web.
|
|
|
|
Al final de cada publicación, deberá incluirse un pie con las personas que han participado en la redacción y un enlace de cada una hasta su sección en dicha página.
|
|
|
|
La estructura del pié deberá ser de la siguiente forma:
|
|
```
|
|
Redacción: [persona1](/redaction.html#persona1), [persona2](/redaction.html#persona1)
|
|
```
|
|
|
|
## Problemas
|
|
Aquí listan los problemas pendientes en la página junto a sus posibles soluciones.
|
|
|
|
### Nombres en la lista de publicaciones
|
|
El problema consiste en que, en la lista de publicaciones en la página principal, los nombres de las publicaciones aparecen en minúscula.
|
|
|
|
La razón de la existencia de este problema es que la persona que desarrolló el tema que usamos en el sitio web, indicó en la plantilla que los títulos cambiasen su capitalización a minúsculas al ser listados.
|
|
|
|
La solución propuesta, de forma temporal, ha sido re-escribir dicha plantilla sin dicha transformación y situarla en el directorio `_includes/` con el mismo nombre de la plantilla original, `post_list.html`.
|
|
|
|
Se ha realizado un informe en el repositorio en GitHub donde se desarrolla el tema. Lo puedes visitar en [no-style-please#11](https://github.com/riggraz/no-style-please/issues/11). |