ntWeb

Un pequeño sitio web con grandes intenciones.

ntWeb es un pequeño sitio web con grandes intenciones. Funciona como un portafolio, una plataforma de blog, una colección de retos de programación, una galería, documentación para paquetes Go y una API JSON.

Probablemente cualquiera podría pensar que este proyecto es muy sencillo y que su autor no tiene buenas capacidades en desarrollo frontend, y de hecho es cierto en algunos aspectos porque no es mi especialidad, pero su sencillez es intencional (y está escrito con tecnologías web modernas).

El sitio web es creado con Hugo y parte de su contenido es generado con Go y Mage (los proyectos y la documentación de los paquetes Go).

Para mostrar la pagina principal solo se descargan ~30 KB (~12 KB sin los favicons), para esta página se descargan ~265 KB (incluyendo sus imágenes). Es usable sin JavaScript y puede visualizarse en navegadores web TUI.

Todo su contenido también puede obtenerse como JSON, por lo que es posible crear nuevos frontends más complejos sin necesidad de tener que repetir el contenido. Por ser una API estática se obtiene un buen rendimiento pues no se realiza ningún computo extra al de leer el archivo, es bastante segura porque no hay servidor de base de datos que pueda ser atacado y puede hospedarse en cualquier servicio que soporte archivos estáticos.

API

Casi todas las páginas HTML tienen JSON como formato alternativo, que puede ser obtenido agregando index.json al final de su URL. Por ejemplo, para esta página, el URL de su formato JSON sería https://ntrrg.dev/es/proyectos/ntweb/index.json.

Cada página tiene las siguientes propiedades:

url - Cadena

URL del recurso.

kind - Cadena

Tipo de recurso. Puede ser home, section, taxonomy, term o page.

type - Cadena

Tipo de contenido. Puede ser blog, gallery, projects, tag o page.

lang - Cadena

Idioma del recurso.

title - Cadena

Título del recurso.

image - Cadena

URL de la imagen del recurso.

params - Cadena

Parámetros del frontmatter del recurso. Puede variar según el tipo del contenido.

content - Cadena

Contenido Markdown procesado del recurso (HTML). Se debe tener en cuenta que esta propiedad contiene una cadena UTF-8 codificada en Base64 y las cadenas de JavaScript son UTF-16.

data - Objeto

Datos específicos del recurso. Para la página principal, contiene todos los elementos de primer nivel; para colecciones, contiene los elementos que la componen e información sobre la paginación; y para recursos individuales, contiene una lista con contenido relacionado.

altLang - Vector de Objeto

Traducciones del recurso. Cada objeto tiene las propiedades lang y url.

altMediaType - Vector de Objeto

Formatos alternativos del recurso. Cada objeto tiene las propiedades mediaType y url.

$ wget -qO - https://ntrrg.dev/es/proyectos/ntweb/index.json | jq
{
  "url": "https://ntrrg.dev/es/proyectos/ntweb/",
  "kind": "page",
  "type": "projects",
  "lang": "es",
  "title": "ntWeb",
  "image": "",
  "params": {
    "comments": true,
    "description": "Un pequeño sitio web con grandes intenciones.",
    "draft": false,
    "iscjklanguage": false,
    "metadata": {
      "license": "CC-BY-4.0",
      "source-code": "https://github.com/ntrrg/ntweb"
    },
    "tags": [
      "sitio-web",
      "json-api",
      "go",
      "html",
      "css",
      "javascript",
      "hugo",
      "mage",
      "docker",
      "netlify"
    ],
    "title": "ntWeb",
    "toc": true
  },
  "content": "...",
  "data": {
    "related": [...]
  },
  "altLang": [
    {
      "lang": "en",
      "url": "https://ntrrg.dev/en/proyectos/ntweb/"
    }
  ],
  "altMediaType": [
    {
      "mediaType": "text/html",
      "url": "https://ntrrg.dev/es/proyectos/ntweb/"
    }
  ]
}

Endpoints

Principal

https://ntrrg.dev/es/index.json

Obtiene todos los elementos de primer nivel. Ver API para mas información sobre las propiedades en común.

Propiedades:

data.sections - Vector de Objeto

Secciones. Cada objeto tiene las propiedades url, title y pages. La propiedad pages es la cantidad de páginas dentro de la sección.

data.taxonomies - Vector de Objeto

Taxonomías. Cada objeto tiene las propiedades url, title y terms. La propiedad terms es la cantidad de términos dentro de la taxonomía.

data.pages - Vector de Objeto

Páginas de primer nivel. Cada objeto tiene las propiedades url y title.

Colecciones

https://ntrrg.dev/es/:section/index.json

https://ntrrg.dev/es/:section/page/:pageNumber/index.json

Parámetros:

:section - Cadena

Nombre de la sección. Puede ser blog, galeria o proyectos.

:pageNumber - Entero

Número de página. La primera página es obtenida sin page/:pageNumber/.

Obtiene la lista de elementos de una colección específica. Ver API para mas información sobre las propiedades en común.

Propiedades:

data.pages - Vector de Objeto

Lista de elementos. Cada página tiene las propiedades url, title, image, publishDate, date, description, refs, rels y taxonomies. Ver Elementos individuales para más información acerca de sus propiedades.

data.pagination - Objeto

Información de paginación. Contiene las propiedades prefix, first, prev, next y last.

Elementos individuales

https://ntrrg.dev/es/:id/index.json

Parámetros:

:id - Cadena

Identificador único del elemento. Generalmente es el nombre de la sección a la que pertenece y su título codificado para URLs.

Obtiene un elemento. Ver API para mas información sobre las propiedades en común.

Propiedades:

data.related - Vector de Objeto

Lista de contenido relacionado. Cada elemento tiene las propiedades url, type, title, description e image.

Índice de búsqueda

https://ntrrg.dev/es/search-index/index.json

Obtiene todos los elementos que pueden ser procesados por motores de búsqueda. Este recurso no tiene las propiedades comunes. Para invalidación de índices de búsqueda ver Información de compilación

Propiedades:

documents - Vector de Objeto

Lista de elementos indexables. Cada objeto tiene las propiedades url, type, title, publishdate, date, description, content y taxonomies. El valor de la propiedad content es texto plano (sin etiquetas HTML) y está codificado en Base64. Se debe tener en cuenta que esta propiedad contiene una cadena UTF-8 y las cadenas de JavaScript son UTF-16.

Cache

https://ntrrg.dev/cache.json

Obtiene los URLs de cada objeto generado, útil para descargar previamente contenido, por ejemplo con Service Workers.

Información de compilación

https://ntrrg.dev/es/build-info/index.json

Obtiene información acerca de la compilación del proyecto.

Propiedades:

environment - Cadena

Entorno de compilación.

hash - Cadena

Hash de la última confimación de Git usada para compilar el sitio.

date - Cadena

Fecha de compilación.

hugoVersion - Cadena

Versión de Hugo usada para compilar el sitio.

Modo sin conexión

Cada vez que un recurso es abierto, este es almacenado en cache (con la ayuda de un Service Worker), lo que permite acceso sin conexión. Es posible eliminar los archivos almacenados desde la página de Ajustes o incluso descargar el sitio web completo para obtener acceso sin conexión a todos los recursos.

Código fuente

Requerimientos:

Hugo >= 0.82

Descargar el código fuente

$ # Paquete
$ wget https://github.com/ntrrg/ntweb/archive/master.tar.gz
$
$ # Repositorio Git
$ git clone --depth 1 https://github.com/ntrrg/ntweb.git

Ejecutar el servidor de Hugo en la carpeta raíz del proyecto:

$ hugo server

Ir a http://localhost:1313/ con un navegador web.

Docker

$ docker run --rm -p 1313:80 ntrrg/ntweb

Ir a http://localhost:1313/ con un navegador web.

Atribuciones

Trabando en este proyecto uso/usé:

Políticas de privacidad