[EspaƱol]

ntWeb

Table of Contents:

GitHub Actions GitHub Actions Netlify Status

ntWeb is a small site with great intentions. It provides a portfolio, a blogging platform, Go packages vanity URLs and a JSON API.

Probably anyone could think of this as a really simple project and its author is a bad frontend developer, and actually, it is true in some way because it is not my profile, but its simplicity is intentional (and it is written with modern web technologies).

The website is created by Hugo and some parts of the content are generated by Go and Mage (specifically the projects and the Go packages vanity URLs).

For been printed in the web browser, the home page downloads ~28 KB (including the favicons), a blog article downloads ~215 KB (including its images, the favicons and disabling the comments). It is functional even without JavaScript and can be visualized on TUI web browsers.

Home page on TUI

Home page on TUI

Blog on TUI

Blog on TUI

Article on TUI

Article on TUI

Its content may be fetched as JSON, so creating new complex frontends is trivial without the need for content duplication. Since it is a static API, it has good performance because of the lack of computing complexity (just reading a file), it is more resistant to cyber-attacks because there is no database server and it can be hosted in any service supporting static files.

API

Almost any HTML page has a JSON output format, it could be fetched by appending index.json to its URL, so the JSON URL of this page should be https://nt.web.ve/en/projects/ntweb/index.json.

Every page has the following properties:

url (string):
Resource URL.
kind (string):
Resource type. It may be one of home, section, taxonomyTerm, taxonomy or page.
type (string):
Content type. It may be one of blog, gallery, projects, tag or page.
lang (string):
Resource language.
title (string):
Resource title.
image (string):
Resource image URL.
params (string):
Resource frontmatter parameters. This may be different from page types.
content (base64 encoded string):
Resource rendered Markdown content.
data (object):
Resource specific data. For the main page, this contains all the sections, taxonomies and top-level pages; for collections this contains its elements and pagination information; and for single elements this is an empty object.
altLang (array of objects):
Resource translations. Every object has the lang and url properties.
altMediaType (array of objects):
Resource alternative formats. Every object has the mediaType and url properties.
$ wget -qO - https://nt.web.ve/en/projects/ntweb/index.json | jq
{
  "url": "https://nt.web.ve/en/projects/ntweb/",
  "kind": "page",
  "type": "projects",
  "lang": "en",
  "title": "ntWeb",
  "params": {
    "comments": true,
    "description": "A small site with great intentions.",
    "draft": false,
    "iscjklanguage": false,
    "metadata": {
      "license": "MIT",
      "source-code": "https://github.com/ntrrg/ntweb"
    },
    "tags": [
      "go",
      "go-templates",
      "html",
      "css",
      "javascript",
      "website",
      "json-api",
      "hugo",
      "mage",
      "docker",
      "github-actions",
      "netlify"
    ],
    "title": "ntWeb",
    "toc": true
  },
  "content": "...",
  "data": {},
  "altLang": [
    {
      "lang": "es",
      "url": "https://nt.web.ve/es/projects/ntweb/"
    }
  ],
  "altMediaType": [
    {
      "mediaType": "text/html",
      "url": "https://nt.web.ve/en/projects/ntweb/"
    }
  ]
}

Endpoints

Main

https://nt.web.ve/en/index.json

Retrieves all the top-level elements. See API for more details about common properties.

data.sections (array of objects):
Website sections. Every object has the url, title and pages properties. The pages property is the count of pages inside the section.
data.taxonomies (array of objects):
Website taxonomies. Every object has the url, title and terms properties. The terms property is the count of terms inside the taxonomy.
data.pages (array of objects):
Top-level pages. Every object has the url and title properties.

Collections

https://nt.web.ve/en/:section/index.json

https://nt.web.ve/en/:section/page/:pageNumber/index.json

https://nt.web.ve/en/tags/:tag/index.json

https://nt.web.ve/en/tags/:tag/page/:pageNumber/index.json

Parameters
section:
Section name. This could be one of blog, gallery or projects.
tag:
Tag name. This should be an existent tag.
pageNumber:
Page number. The first page is retrieved without page/:pageNumber/.

Retrieves the list of elements from the given collection. See API for more details about common properties.

data.pages (array of objects):
List of elements. Every object has the url, title, image, publishDate, date, description and tags properties. The tags property is an array of tags assigned to the element.
data.pagination (object):
Pagination object. It contains the prefix, first, prev, next and last properties.

Elements

https://nt.web.ve/en/:section/:title/index.json

Parameters
section:
Section name. This could be one of blog, gallery or projects.
title:
URL encoded element title.

Retrieves a single element. See API for more details about common properties.

Search index

https://nt.web.ve/en/search-index/index.json

Retrieves all the indexable elements for search engines. It is an array of objects, and every object has the url, title, description and content properties. The value of the content property is base64 encoded.

Note: this doesn't have the common properties.

Offline mode

Requirements:

  • Hugo >= 0.62

Get the source code

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

Run the Hugo server in the project root directory

$ hugo server

Go to http://localhost:1313/ with a browser.

Docker

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

Go to http://localhost:1313/ with a browser.

Acknowledgment

Working on this project I use/used: