152 lines
7.7 KiB
Markdown
152 lines
7.7 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 5 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 un atributo complejo y opcional para las páginas de archivos. Declara la categoría de las publicaciones a listar en la misma.
|
|
|
|
Sus valores se corresponden 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.
|
|
|
|
##### 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 páginas son los elementos estáticos con mayor flexibilidad del sitio web.
|
|
|
|
#### 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 junto con 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 (`-`) con su nombre 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: 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.
|
|
|
|
###### date
|
|
La fecha debe seguir el formato `%Y-%m-%d %H:%M:%S %z` 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"`
|