[Pandoc]: https://pandoc.org/ "Pandoc is a free and open-source command-line document conversion tool."
[Git]: https://git-scm.com/ "Git is a free and open-source distributed version control system."
[Hugo]: https://gohugo.io/ "Hugo is a free and open source static website builder."
# Introduction
For an outline of basic *Sandpoints* features see .
Here is an outline:
- *Sandpoints* is a module/theme for [Hugo][].
- Hugo is a static website builder.
- Static websites serve a client a fixed HTML page according to a CSS and/or JavaScript files. Static websites require no dynamic processing or customizations to be performed by a server.
- Thus, static websites are lightweight, robust, fast, and given that they are simple HTML, they are resilient to technological updates.
- Static websites are also portable, meaning they can be stored, copied, and run via a USB stick.
- Content in *Hugo* and *Sandpoints* is managed with *Markdown files*.
- Markdown is an open specification for plain-text human readable files.
- Markdown files can be opened and edited by any text editor.
- Markdown formatting syntax is simple and quite easy to learn (see also ).
- Since they are plain-text, they are extremely lightweight (this file is 6KB).
- They can easily serve distributed collaboration through version control (i.e. [Git][]).
- They can be rendered to many other formats with tools such as [Pandoc][] (e.g. to pdf, docx, etc.), which can also compile bibliographic references.
- *Sandpoints* add functionalities to *Hugo* projects pertaining to open and collaborative publishing.
- It features a particular ontology that follows a [triadic hierarchy](#ontology).
- It features extended hypertext functionalities that allow for non-linear content traversal, such as browsing entries by type, keywords, or [backlinks](#backlinks).
- All the content is open and listed at the [sitemap](/) (see also [sitemap](#sitemap)).
- It allows for entries or groups of entries to be exported into interactive and printable PDFs (see ).
- It offers integration with a project-specific portable library (described in ).
# Content organization
Content in *Sandpoints* is formatted in Markdown files, which are organized in subdirectories within the directory `/root/content/`.
Each subdirectory inside `content/` is named after and corresponds to a specific content type.
This project features the following content types (and subdirectories):
-`journal` (the parent object, with only one instance: `index.md`)
-`issue`
-`article`
-`editor`
-`contributor`
-`print`
# Ontology
Sandpoints supports a triadic hierarchy. This follows that content is organized, or parented according to a tree structure with a depth of three (entities). This project follows the scheme `journal>issue>article` (other examples to visualize this content are `book>chapter>section`, and `ship>deck>room`).
```
Journal
└── Issue
└── Article
-Editor
-Contributor
-Print
```
This ontology follows that:
- there is *one*`journal` item, that serves as a parent item,
- which can have multiple `issues`, and
- each `issue` can have multiple `articles`.
Furthermore:
- each `issue` is associated with `editors`, and
- each `article` is associated with `contributors`.
Lastly, `print` items are used to enable printing of any of the above elements (e.g. `article`, `issue`, or the whole `journal` ).
Note that the names of the basic triad elements are arbitrary. However:
- they have to correspond to content folders (as in `content/issue/`),
- they have to exist in the theme's dictionary which pairs singular and plural versions of the item name, as in `"article" : "articles"`.
This dictionary is located at:
```
root/_vendor/.../data/sandpointsnamegraph.json
```
# Parenting and associating content
For parenting and associating items see the .
<!--
- journal (parent)
- issue (child of journal)
- article (child of issue)
- contributor (article author)
- editor (issue editor)
- print (entity to facilitate printing of any item -- e.g. article, issue, or journal)
-->
# Sitemap
*Sandpoints* projects feature a [sitemap](/), that lists all published content (all content that is not marked as draft).
The sitemap is at the root URL of any given project.
# Backlinks
The concept of backlinks was described in early speculations that informed hypertext (i.e. by Vannevar Bush and later Ted Nelson), but were not implemented the WWW.
According to these ideas, hyperlinks are bi-directional, which follows that a hyperlink is visible both in the document that features a link *and also* at the target document where the link is pointing to. The latter aspect is a backlink. By this scheme, any document knows which other documents point to it.
The same concept is used by search engine algorithms, such as 'page rank' by Google, that function by creating an index of how many webpages link to a specific target website -- or how many backlinks a given webpage has.
*Sandpoints* allows backlinks for selected items. These can be set at the config file, at the `sandpointsMentionedIn` array (see [Sandpoints config file](#sandpoints-config-file)).
```

A link from this article to some other one, at the latter article will generate a backlink that would appear at the top right of the page (`mentioned in this-article`).
_Sandpoint_ can generate printable and interactive PDFs for single entries, groups of entries (as in issues), and for all content. For PDFs containing more than one entry, _Sandpoints_ will dynamically generate a table of contents.
To browse printable content, look for material with the ‘print’ prefix in the [sitemap](/).
To create a print version for a given entry see the .
See also .
# Sandpoints project file structure
The root folder of the project contains the following files and folders.
|Folder/ or File | Description|
|--|--|
|`_vendor/` |the folder containing the *Sandpoints* theme.
|`content/` | the folder with all content (Markdown files) organized in subfolders corresponding to and named after content types.
|`archetypes/` | a folder containing templates per type for generating new content.