Uploaded all internal content (issue with articles + print) -- draft: true bc internal
This commit is contained in:
parent
37d064cefc
commit
943d0d8107
13 changed files with 684 additions and 5 deletions
99
content/article/int-content.md
Normal file
99
content/article/int-content.md
Normal file
|
@ -0,0 +1,99 @@
|
||||||
|
---
|
||||||
|
title: "Content creation (INTERNAL)"
|
||||||
|
date: "2023-07-04T18:30:44+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
contributors: ["constantinos-miltiadis.md"]
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
- journal management
|
||||||
|
abstract: |
|
||||||
|
(Internal) Guide for creating new content.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Creating new content
|
||||||
|
|
||||||
|
The optimal way to create new content (a new Markdown file) is via the terminal. To do so open a terminal window and navigate to the root directory of the project. The general command pattern for creating new content is:
|
||||||
|
> `hugo new <contentType>/filename.md`
|
||||||
|
|
||||||
|
Where `<contentType>` corresponds to a predefined type and corresponding folder. For this project, these are `article`, `issue`, `contributor`, `editor`, and `print`.
|
||||||
|
|
||||||
|
New content is created following `archetypes` (templates), described below.
|
||||||
|
Before creating new content, make sure to follow .
|
||||||
|
|
||||||
|
# Archetypes
|
||||||
|
|
||||||
|
New content is generated following `archetypes` (see `<rootFolder>/archetypes/`). Archetypes are Markdown files and can be thought of as templates that pertain to specific content types, and dictate what content to be included upon creating a new file.
|
||||||
|
|
||||||
|
Currently, archetypes will be generated with instructions for their creator, in the form of a to-do list.
|
||||||
|
|
||||||
|
The absolutely necessary information required is the TOML header of an entry.
|
||||||
|
- `title` (currently inherited from filename)
|
||||||
|
- `date` (automated date)
|
||||||
|
- `draft: true`
|
||||||
|
|
||||||
|
## Suboptimal way to create new content
|
||||||
|
Another way to add content is to duplicate an existing MD file. However, this, along with duplicating the content of the original, will also inherit its header metadata, such as date and author.
|
||||||
|
# Steps for creating new content
|
||||||
|
|
||||||
|
1. Create new file via the terminal.
|
||||||
|
2. Open the new file and edit header information (title, author [file creator], keywords, abstract, etc.)
|
||||||
|
3. Edit file content.
|
||||||
|
4. Commit changes via git when necessary.
|
||||||
|
5. When editing is done and the new entry is ready for publishing, change the `draft: true` to `draft: false`.
|
||||||
|
6. Commit changes via git, and include the keyword `!publish!` in your commit message, which will recompile the site.
|
||||||
|
|
||||||
|
|
||||||
|
# Commands and conventions for creating new files
|
||||||
|
|
||||||
|
Please see first the article on .
|
||||||
|
|
||||||
|
New issue (x is issue number):
|
||||||
|
|
||||||
|
> `hugo new issue/issue-x.md`
|
||||||
|
|
||||||
|
New article (x is issue number):
|
||||||
|
> `hugo new article/x-short-title.md`
|
||||||
|
|
||||||
|
New contributor:
|
||||||
|
> `hugo new contributor/name-surname.md`
|
||||||
|
|
||||||
|
New print perspective (this will most likely break the site if the print destination file does not exist -- edit the field `print: "article/some-article.md"` accordingly):
|
||||||
|
> `hugo new print/x-p-short-title.md`
|
||||||
|
|
||||||
|
# Parenting content
|
||||||
|
|
||||||
|
*Sandpoints* follows a triadic hierarchy, which, here is *Journal>Issue>Article*, or:
|
||||||
|
```
|
||||||
|
Journal
|
||||||
|
└── Issue
|
||||||
|
└── Article
|
||||||
|
```
|
||||||
|
|
||||||
|
Thus, a journal has issues, and issues have articles. Following the same convention, each item that has children, in its TOML header section has
|
||||||
|
|
||||||
|
The journal TOML section has the following field:
|
||||||
|
```
|
||||||
|
has_issues: []
|
||||||
|
```
|
||||||
|
And the TOML section of an issue instance has the field:
|
||||||
|
```
|
||||||
|
has_articles: []
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parenting issues to the journal
|
||||||
|
|
||||||
|
```
|
||||||
|
---
|
||||||
|
title: "The Journal"
|
||||||
|
has_issues: ["some-issue.md", "some-other-issue.md"]
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parenting articles to issues
|
||||||
|
```
|
||||||
|
---
|
||||||
|
title: "Some issue"
|
||||||
|
has_articles: ["some-article.md", "some-other-article.md"]
|
||||||
|
---
|
||||||
|
```
|
83
content/article/int-conventions.md
Normal file
83
content/article/int-conventions.md
Normal file
|
@ -0,0 +1,83 @@
|
||||||
|
---
|
||||||
|
title: "Conventions (INTERNAL)"
|
||||||
|
date: "2023-06-29T23:38:56+03:00"
|
||||||
|
author: "editor-put-your-name-here"
|
||||||
|
contributors:
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
abstract: |
|
||||||
|
Conventions for filenames, etc.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Dates
|
||||||
|
|
||||||
|
> DD.MM.YYYY
|
||||||
|
|
||||||
|
as in 13.05.1998. In general, day first.
|
||||||
|
|
||||||
|
# File naming conventions
|
||||||
|
|
||||||
|
- All **lowercase**
|
||||||
|
- Use **dash as separator**
|
||||||
|
- No spaces
|
||||||
|
- No underscores
|
||||||
|
|
||||||
|
| Type | Filename convention | Creation command |
|
||||||
|
|-|-|-|
|
||||||
|
| contributor | name-surname.md | `hugo new contributor/name-surname.md`|
|
||||||
|
| editor | name-surname.md | `hugo new editor/name-surname.md` |
|
||||||
|
| issue | issue-x.md | `hugo new issue/issue-x.md` |
|
||||||
|
| article | article-short-title.md | `hugo new article/article-short-title.md` |
|
||||||
|
| print (issue)\* | p-issue-x.md | `hugo new print/p-issue-x.md` |
|
||||||
|
| print (article)\*\* | p-article-short-title.md | `hugo new print/p-article-short-title.md` |
|
||||||
|
|
||||||
|
\* where x is issue number
|
||||||
|
\*\* creating a new print file can break the site, until
|
||||||
|
# Files intended for *Internal* use
|
||||||
|
|
||||||
|
|
||||||
|
Files purposed to be for internal use, and are *not public facing*:
|
||||||
|
- start with `int-` , like this file `int-conventions.md`
|
||||||
|
|
||||||
|
Their header file:
|
||||||
|
- features the keyword `internal`
|
||||||
|
- the draft flag is set to true, as in `draft: true`
|
||||||
|
|
||||||
|
# Images and attachments
|
||||||
|
|
||||||
|
> static/issue-x/author/image.png
|
||||||
|
|
||||||
|
<!--
|
||||||
|
# File naming conventions
|
||||||
|
|
||||||
|
Filenames are all lowercase. No spaces, no underscores, only dashes.
|
||||||
|
|
||||||
|
# Contributors, Editors
|
||||||
|
|
||||||
|
> name-surname.md
|
||||||
|
|
||||||
|
as in `pippin-bar.md`
|
||||||
|
|
||||||
|
To create a new contributor do:
|
||||||
|
> hugo new contributor/name-surname.md
|
||||||
|
|
||||||
|
## Issues
|
||||||
|
|
||||||
|
> issue-x.md
|
||||||
|
|
||||||
|
where x is the issue number:
|
||||||
|
- issue-5.md
|
||||||
|
|
||||||
|
To create a new issue do:
|
||||||
|
> hugo new issue/issue-x.md
|
||||||
|
|
||||||
|
## Print files
|
||||||
|
|
||||||
|
Print files correspond to issues or articles.
|
||||||
|
|
||||||
|
> hugo new print/p-issue-5.md
|
||||||
|
|
||||||
|
or
|
||||||
|
> hugo new print/p-article-name.md
|
||||||
|
-->
|
98
content/article/int-infrastructure-info.md
Normal file
98
content/article/int-infrastructure-info.md
Normal file
|
@ -0,0 +1,98 @@
|
||||||
|
---
|
||||||
|
title: "Infrastructure Info (INTERNAL) --legacy"
|
||||||
|
date: "2023-06-24T16:22:47+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
contributors: ["constantinos-miltiadis.md"]
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
abstract: |
|
||||||
|
This is an internal page that contains information on the Sandpoints infrastructure.
|
||||||
|
---
|
||||||
|
|
||||||
|
[Hugo]: https://gohugo.io/ "Hugo is a free and open source static website builder."
|
||||||
|
|
||||||
|
For Sandpoints in general see .
|
||||||
|
|
||||||
|
# Sandpoints general
|
||||||
|
|
||||||
|
Hugo is a framework for generating lightweight static websites. Content is created via Markdown files and requires no programming. It makes use of simple terminal commands for creating content, generating and publishing a website.
|
||||||
|
|
||||||
|
*Sandpoints* functions as a theme for [Hugo][], which adds additional functionality catered to open publishing. Sandpoints as a Hugo theme/module:
|
||||||
|
- adds hypertext functionality, with backlinks.
|
||||||
|
- can include a project related , and content can link to library entries.
|
||||||
|
- can generate  for its content. This, for single entries, for grouped entries (issue of contributions), or for all content. PDFs containing more than one entry include a table of contents.
|
||||||
|
|
||||||
|
|
||||||
|
# Ontology
|
||||||
|
|
||||||
|
Sandpoints supports a triadic hierarchy. Here we use:
|
||||||
|
- Journal
|
||||||
|
- Issue
|
||||||
|
- Article
|
||||||
|
- Editor
|
||||||
|
- Contributor
|
||||||
|
- Print
|
||||||
|
|
||||||
|
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 with pairs singular and plural versions, as in `"article" : "articles"`.
|
||||||
|
This dictionary is located at:
|
||||||
|
- > `/_vendor/.../data/sandpointsnamegraph.json`
|
||||||
|
|
||||||
|
<!--
|
||||||
|
|
||||||
|
# Generate printable PDFs
|
||||||
|
|
||||||
|
*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](/).
|
||||||
|
|
||||||
|
See also .
|
||||||
|
|
||||||
|
-->
|
||||||
|
# Clone & run locally
|
||||||
|
|
||||||
|
Hugo allows compiling
|
||||||
|
|
||||||
|
Preparations:
|
||||||
|
- install Hugo (see [Hugo installation](https://gohugo.io/installation/))
|
||||||
|
- install the [Go Language](https://go.dev/).
|
||||||
|
- install [Git](https://git-scm.com/).
|
||||||
|
- clone this repository.
|
||||||
|
|
||||||
|
To run this site locally:
|
||||||
|
- open a terminal, and navigate to the root folder of this project (which includes the folder `content`).
|
||||||
|
- to run a local dynamic server with the project, run:
|
||||||
|
> `hugo server`
|
||||||
|
- to do the same and include drafts, run:
|
||||||
|
>`hugo server -D`
|
||||||
|
- to compile the site, run:
|
||||||
|
> `hugo`
|
||||||
|
- to compile the website and include drafts, run
|
||||||
|
> `hugo -D`
|
||||||
|
|
||||||
|
# Upgrading Sandpoints
|
||||||
|
|
||||||
|
1. Upgrade *Hugo*.
|
||||||
|
- For Windows, if *Hugo* was installed with the `choco` package manager, open a terminal as administrator and run:
|
||||||
|
> `choco upgrade hugo`
|
||||||
|
- For OSX, if *Hugo* was installed with the `homebrew` package manager, open a terminal and run:
|
||||||
|
> `brew upgrade hugo`
|
||||||
|
2. To check the version of your *Hugo* installation, run:
|
||||||
|
> `hugo version`
|
||||||
|
3. To update *Sandpoints*, navigate to the root folder of the project and run the following two commands, one at a time:
|
||||||
|
> `hugo mod get`
|
||||||
|
> `hugo mod vendor`
|
||||||
|
|
||||||
|
# Library integration
|
||||||
|
|
||||||
|
*Sandpoints* features a project-based library using the infrastructure of [Memory of the World](https://library.memoryoftheworld.org/) library.
|
||||||
|
You can access the project library by clicking the red button at the top right corner of the website.
|
||||||
|
Libraries are created using the open source e-book management software [Calibre](https://calibre-ebook.com/), and managed using the command line tool [Accorder](https://pypi.org/project/accorder/).
|
||||||
|
|
||||||
|
# Notes
|
||||||
|
- For an extended description of *Sandpoints* see [Sandpoints Portfolio (sandpoints.org)](https://pages.sandpoints.org/sandpoints/simplesandpoints-de47f813/draft/portfolio/), which includes descriptions of its implementation in different projects, and related bibliography.
|
||||||
|
- [Sandoints (Gitea project repository)](https://git.sandpoints.org/Drawwell/).
|
||||||
|
- See also:
|
||||||
|
- Graziano, Valeria, Marcell Mars, and Medak Tomislav. ‘Learning from \#Syllabus’. In _State Machines: Reflections and Actions at the Edge of Digital Citizenship, Finance, and Art_, edited by Yiannis Colakides, Marc Garrrett, and Inte Gloerich. Amsterdam: Institute of Network Cultures, 2019. [http://www.statemachines.eu/books/state-machines-reflections-and-actions-at-the-edge-of-digital-citizenship-finance-and-art/](http://www.statemachines.eu/books/state-machines-reflections-and-actions-at-the-edge-of-digital-citizenship-finance-and-art/).
|
|
@ -7,9 +7,9 @@ draft: true
|
||||||
keywords:
|
keywords:
|
||||||
- internal
|
- internal
|
||||||
- library
|
- library
|
||||||
- management
|
- journal management
|
||||||
abstract: |
|
abstract: |
|
||||||
Library management guide for Sandpoints projects.
|
(Internal)Library management guide for Sandpoints projects.
|
||||||
---
|
---
|
||||||
|
|
||||||
[Accorder]: https://pypi.org/project/accorder/ "Accorder at pypi.org."
|
[Accorder]: https://pypi.org/project/accorder/ "Accorder at pypi.org."
|
||||||
|
|
121
content/article/int-management.md
Normal file
121
content/article/int-management.md
Normal file
|
@ -0,0 +1,121 @@
|
||||||
|
---
|
||||||
|
title: "Site Management (INTERNAL)"
|
||||||
|
date: "2023-06-24T16:10:29+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
- journal management
|
||||||
|
abstract: |
|
||||||
|
(Internal) Technical guide for site management.
|
||||||
|
---
|
||||||
|
|
||||||
|
[Obsidian]: https://obsidian.md/ "Obsidian is a free-to-use cross-platform Markdown editor aimed at note-taking."
|
||||||
|
[VS Code]: https://code.visualstudio.com/ "Visual Studio Code (VS Code) is an open-source source-code editor for Windows, macOS, and Linux, developed by Microsoft."
|
||||||
|
[Sourcetree]: https://www.sourcetreeapp.com/ "Sourcetree is a free-to-use Git GUI for Windows and macOS."
|
||||||
|
[iTerm2]: https://iterm2.com/ "iTerm2 is a free and open source CLI Terminal for macOS."
|
||||||
|
[Go language]: https://go.dev/ "Go is an open-source multi-paradigm object-oriented programming language."
|
||||||
|
[Git]: https://git-scm.com/ "Git is a free and open-source distributed version control system."
|
||||||
|
[Hugo]: https://gohugo.io/ "Free and open-source static website builder."
|
||||||
|
[Hugo installation guide]: https://gohugo.io/installation/
|
||||||
|
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
This project runs on *Sandpoints*, a module/theme for the static website builder [Hugo][].
|
||||||
|
Content is organized with plain-text Markdown files, and collaboration/version control is managed via [Git].
|
||||||
|
Thus, with the infrastructure in place, no programming is needed
|
||||||
|
|
||||||
|
# Required tools and installations
|
||||||
|
|
||||||
|
To manage the site you first need to install:
|
||||||
|
1. [Git][] -- version control system.
|
||||||
|
2. [Hugo][] -- a static website builder ([see instruction below](#install-and-upgrade-hugo)).
|
||||||
|
3. It's recommended to install the [Go Language][].
|
||||||
|
|
||||||
|
To manage the site you need the following tools:
|
||||||
|
1. a Markdown editor (e.g. [Obsidian][]), or a code editor (e.g. [VS Code][]) or other general text editor to view and edit Markdown files. For *Obsidian*, open the `content` folder as a vault.
|
||||||
|
2. a command line interface (CLI) terminal. Windows users can use *PowerShell* or *Git Bash* (included with a Git installation). macOS users can use the default *Terminal* app, or [iTerm2][].
|
||||||
|
3. a [Git][] management tool. Experienced Git users can use a terminal. An easier workflow would be to use a GUI git software (e.g. [Sourcetree][]), or the Git integration of [VS Code][].
|
||||||
|
|
||||||
|
## Library management tools
|
||||||
|
Library management requires Calibre, Accorder, and Zotero. For detailed instructions see .
|
||||||
|
|
||||||
|
## Install and upgrade Hugo
|
||||||
|
|
||||||
|
To install [Hugo][] for your system see [Hugo installation guide] -- Hugo is installed via a package manager, e.g. *Homebrew* for macOS or *choco* for Windows.
|
||||||
|
|
||||||
|
To upgrade _Hugo_:
|
||||||
|
- For Windows, if _Hugo_ was installed with the `choco` package manager, open a terminal as administrator and do:
|
||||||
|
```
|
||||||
|
choco upgrade hugo
|
||||||
|
```
|
||||||
|
- For macOS, if _Hugo_ was installed with the `homebrew` package manager, open a terminal and do:
|
||||||
|
```
|
||||||
|
brew upgrade hugo
|
||||||
|
```
|
||||||
|
To check the version of your _Hugo_ installation, do:
|
||||||
|
```
|
||||||
|
hugo version
|
||||||
|
```
|
||||||
|
|
||||||
|
# Cloning the site
|
||||||
|
|
||||||
|
Assuming you have access to the project repository, which should have a URL in the form of `https://github.com/fake-repo/repo.git`
|
||||||
|
|
||||||
|
Using a terminal, go to a folder where you want to clone the repository (e.g. `c:/users/me/` for Windows), and do:
|
||||||
|
```
|
||||||
|
git clone https://github.com/fake-repo/repo.git
|
||||||
|
```
|
||||||
|
|
||||||
|
This will download a copy of all the material of the repository placed inside a folder with the name of the repository (in this example `c:/users/me/repo`).
|
||||||
|
|
||||||
|
# Editing the site
|
||||||
|
|
||||||
|
To edit the site it's recommended use a Markdown or other text editor such as [Obsidian][] or [VS Code][]. Editing only entails working with Markdown files within the `/content/` folder of the project. See also the guides about , , and .
|
||||||
|
|
||||||
|
## Committing changes
|
||||||
|
|
||||||
|
If inexperienced with [Git][], use a GUI tool like [Sourcetree][], that can visualize commits, and branches of the repository, and display file version differences between commits.
|
||||||
|
|
||||||
|
|
||||||
|
<!--
|
||||||
|
# Install or upgrade Sandpoints
|
||||||
|
|
||||||
|
To install or update _Sandpoints_, navigate to the root folder of the project and run the following two commands, one at a time:
|
||||||
|
```
|
||||||
|
hugo mod get
|
||||||
|
hugo mod vendor
|
||||||
|
```
|
||||||
|
-->
|
||||||
|
# Building the site
|
||||||
|
|
||||||
|
Hugo has two main ways of compiling/building a website:
|
||||||
|
1. Create a local real-time HTML server. This makes the site accessible locally via a browser on a URL like `http://localhost:1313/`. This is useful for testing, or for performing and viewing various edits locally before such changes are made public, especially because the site is updated in real-time against changes made in its content.
|
||||||
|
2. Compile a static HTML version of the site. The compiled site will be placed inside the folder `repo/public/`. The contents of this folder can be uploaded to a server (e.g. via [FileZilla][]).
|
||||||
|
|
||||||
|
[FileZilla]: https://filezilla-project.org/ "Free and open-source cross-platform FTP software."
|
||||||
|
|
||||||
|
## Create a local HTTP server
|
||||||
|
|
||||||
|
Navigate to the root folder of the cloned repository (by the previous example that would be `cd c:/users/me/repo/`), and do one of the following:
|
||||||
|
- To create a local server accessible via a browser, that follows real-time changes to your repo clone, do:
|
||||||
|
```
|
||||||
|
hugo server
|
||||||
|
```
|
||||||
|
- To do the same as before, but include all draft content, do:
|
||||||
|
```
|
||||||
|
hugo server -D
|
||||||
|
```
|
||||||
|
|
||||||
|
## Compile a static website
|
||||||
|
Navigate to the root folder of the cloned repository (by the previous example that would be `cd c:/users/me/repo/`), and do one of the following:
|
||||||
|
|
||||||
|
- To build the website (in the folder `/public/`), do:
|
||||||
|
```
|
||||||
|
hugo
|
||||||
|
```
|
||||||
|
- To build the website including all drafts (also in the folder `/public/`), do:
|
||||||
|
```
|
||||||
|
hugo -D
|
||||||
|
```
|
175
content/article/int-sandpoints.md
Normal file
175
content/article/int-sandpoints.md
Normal file
|
@ -0,0 +1,175 @@
|
||||||
|
---
|
||||||
|
title: "Understanding Sandpoints (INTERNAL)"
|
||||||
|
date: "2023-07-11T18:20:10+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
contributors: ["constantinos-miltiadis.md"]
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
- journal management
|
||||||
|
abstract: |
|
||||||
|
(Internal) Infromation on Sandpoints.
|
||||||
|
---
|
||||||
|
|
||||||
|
[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)).
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|

|
||||||
|
```
|
||||||
|
|
||||||
|
This will
|
||||||
|
|
||||||
|
Backlinks (as well as external and internal hyperlinks) are also catalogued at [urls](/urls/)
|
||||||
|
|
||||||
|
|
||||||
|
# Generate printable PDFs
|
||||||
|
_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.
|
||||||
|
|`static/` |the folder containing static files (images, etc.).
|
||||||
|
|`public/` | a folder containing the build of the site (generated via the command `hugo`).
|
||||||
|
|`resources/`| a folder populated dynamically by *Hugo*.
|
||||||
|
|`data/books/catalog.json` | the library catalogue.|
|
||||||
|
|`config.toml` |the configuration file of the website project.
|
||||||
|
|`go.mod` | text file required for upgrading the Sandpoints theme.
|
||||||
|
|`go.sum` | text file that logs upgrade information.
|
||||||
|
| `.git/` | a hidden folder with data from local version control.
|
||||||
|
| `.gitignore` | a text file that dictates which files or folders to ignore from (Git) version control and backup.
|
||||||
|
| `PUBLISH.trigger.md` | git hook for automatically building the website upon certain commit messages
|
||||||
|
| `readme.md` | standard Git repository readme file.
|
||||||
|
|
||||||
|
# Sandpoints config file
|
||||||
|
|
||||||
|
Each Sandpoints project has a TOML config file at:
|
||||||
|
```
|
||||||
|
rootFolder/config.toml
|
||||||
|
```
|
||||||
|
|
||||||
|
This is a plain-text file, that can be edited with a general text editor.
|
||||||
|
|
||||||
|
Key elements of the config file include:
|
||||||
|
- Project title
|
||||||
|
```
|
||||||
|
title = "Game Design Knowledge & Practice Journal?"
|
||||||
|
```
|
||||||
|
- Project home
|
||||||
|
```
|
||||||
|
sandpointsHome = "journal/index.md"
|
||||||
|
```
|
||||||
|
- Description:
|
||||||
|
```
|
||||||
|
description = "Journal Description..."
|
||||||
|
```
|
||||||
|
- Which content types to have backlink mentions (see section [backlinks](#backlinks)):
|
||||||
|
```
|
||||||
|
sandpointsMentionedIn = ["contributor", "article" ]
|
||||||
|
```
|
56
content/article/int-todo.md
Normal file
56
content/article/int-todo.md
Normal file
|
@ -0,0 +1,56 @@
|
||||||
|
---
|
||||||
|
title: "ToDo (INTERNAL)"
|
||||||
|
date: "2023-06-26T13:11:49+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
contributors: ["constantinos-miltiadis.md"]
|
||||||
|
draft: true
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
# To-Do list
|
||||||
|
|
||||||
|
1. [ ] Agree on and draft a mission statement.
|
||||||
|
2. [ ] Figure out editorial board (see [Potential editorial pool](#potential-editorial-pool)).
|
||||||
|
3. [ ] Submissions
|
||||||
|
1. [ ] Open to submissions anytime, or with open calls only?
|
||||||
|
2. [ ] Submission template.
|
||||||
|
3. [ ] Citation style (perhaps author-date style; with explicit CSL file; see [CSL Repository](https://github.com/citation-style-language/styles)).
|
||||||
|
4. [ ] Types of submissions (just artifact; artifact + article, etc.).
|
||||||
|
5. [ ] Artifacts accepted for submission
|
||||||
|
5. [ ] Artifact archiving and indexing
|
||||||
|
1. [ ] Self-hosting ZIP file in library.
|
||||||
|
2. [ ] Embed games.
|
||||||
|
3. [ ] Indexing artifacts with DOI (e.g. via [Zenodo](https://zenodo.org/)).
|
||||||
|
6. [ ] Populate reviewers pool.
|
||||||
|
7. [ ] Reviewer's feedback template.
|
||||||
|
8. [ ] Populate a (working group) library.
|
||||||
|
1. [ ] Collect articles from peers to be uploaded on the journal library, which can be live-linked when referenced in articles.
|
||||||
|
2. [ ] Collect playable artifacts that can be included in the library.
|
||||||
|
9. [ ] Establish journal ISSN (see [issn info](https://www.issn.org/wp-content/uploads/2018/01/GuidelinesExtranetPublisherRegistration-ENG.pdf))
|
||||||
|
10. [ ] Establish GitHub account for:
|
||||||
|
1. sharing tools
|
||||||
|
2. forking repositories submitted as research
|
||||||
|
11. Create a Zotero translator (almost ready; see [translator](#create-a-zotero-translator)).
|
||||||
|
|
||||||
|
|
||||||
|
# Potential editorial pool
|
||||||
|
- Stefano Gualeni
|
||||||
|
- Konstantinos Dimopoulos (videogame urbanist, consultant, game designer, director and coordinator of the Game Design program at SAE Athens).
|
||||||
|
- Eric Zimmerman
|
||||||
|
- Not only dudes
|
||||||
|
|
||||||
|
# Other ToDos
|
||||||
|
|
||||||
|
## Create a Zotero Translator
|
||||||
|
|
||||||
|
> Write a Zotero Translator to scrape reference metadata from entries of this site.
|
||||||
|
|
||||||
|
I wrote a translator that works for Sandpoints/Dotawo, and published it on the [Sandpoints Repo](https://git.sandpoints.org/Drawwell/SandpointsTheme/issues/11). This can be easily modified to work for this project. Will wait Marcell to corroborate and push to the Zotero main repository. The same can be done for this project -- Constantinos (29.06.2023).
|
||||||
|
|
||||||
|
For references on Zotero translators see:
|
||||||
|
- [Zotero guide for web translators](https://www.zotero.org/support/dev/translators/coding#web_translators) .
|
||||||
|
- [Guide for writing and testing a translator with Scaffold in Zotero](https://www.zotero.org/support/dev/translators/scaffold).
|
||||||
|
- [Required metadata for Journal articles](https://aurimasv.github.io/z2csl/typeMap.xml#map-journalArticle).
|
||||||
|
|
32
content/issue/int-issue-management.md
Normal file
32
content/issue/int-issue-management.md
Normal file
|
@ -0,0 +1,32 @@
|
||||||
|
---
|
||||||
|
title: "Project management (Internal)"
|
||||||
|
date: "2023-06-24T16:05:06+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
draft: true
|
||||||
|
has_articles: ["int-sandpoints.md", "int-infrastructure-info.md_","int-management.md","int-library.md","int-conventions.md","int-content.md","int-features.md","int-todo.md"]
|
||||||
|
keywords:
|
||||||
|
- internal
|
||||||
|
abstract: |
|
||||||
|
(Internal) 'Issue' type page, containing 'articles' related to managing and maintaining this project.
|
||||||
|
---
|
||||||
|
|
||||||
|
[Git]: https://git-scm.com/ "Git is a free and open-source distributed version control system."
|
||||||
|
[Hugo]: https://gohugo.io/ "Free and open-source static website builder."
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
This project runs on *Sandpoints*, a module/theme for the static website builder [Hugo][].
|
||||||
|
Sandpoints is developed for free, open, and collaborative publishing using open-source infrastructure.
|
||||||
|
Content is organized with plain-text Markdown files, and collaboration/version control is managed via [Git].
|
||||||
|
Thus, with the infrastructure in place, no programming is needed.
|
||||||
|
|
||||||
|
However, for managing and maintaining the site in a sustainable manner, as well as for processing/publishing submissions, *some knowledge is required pertaining to how this infrastructure works and how it can be maintained; how to work with ; how to manage distributed collaboration via a version control system; and adherence to the agreed upon conventions.*
|
||||||
|
|
||||||
|
This is an internal 'issue' (supposed to remain non-public, intended as a 'living document'), which contains the following 'articles':
|
||||||
|
|
||||||
|
1. , gives an overview of the philosophy of *Sandpoints*.
|
||||||
|
2.  contains instruction and guides for maintainers of the site.
|
||||||
|
3.  contains a guide for creating new content in a consistent and reliable way.
|
||||||
|
4.  is intended for gathering conventions we should go by.
|
||||||
|
5. , contains a guide for the library maintainers and contributors.
|
||||||
|
6. , is intended for listing potential required features, or filing issues.
|
|
@ -3,7 +3,7 @@ title: "Game Design Knowledge & Practice Journal (WIP/Test)"
|
||||||
date: "2023-06-24T15:20:45+03:00"
|
date: "2023-06-24T15:20:45+03:00"
|
||||||
author: "anybody"
|
author: "anybody"
|
||||||
draft: false
|
draft: false
|
||||||
has_issues: ["issue-x.md", "issue-0.md", "int-housekeeping.md", "issue-journal-info.md"]
|
has_issues: ["issue-x.md", "issue-0.md", "int-issue-management.md", "issue-journal-info.md"]
|
||||||
---
|
---
|
||||||
|
|
||||||
This is the journal home.
|
This is the journal home.
|
||||||
|
@ -16,8 +16,8 @@ See .
|
||||||
|
|
||||||
# Editorial board
|
# Editorial board
|
||||||
|
|
||||||
- , affiliation (?)
|
- 
|
||||||
- , some affiliation.
|
- 
|
||||||
|
|
||||||
# Browse content
|
# Browse content
|
||||||
- [Sitemap with all content](/)
|
- [Sitemap with all content](/)
|
||||||
|
|
7
content/print/p-issue-internal.md
Normal file
7
content/print/p-issue-internal.md
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
---
|
||||||
|
title: "Internal Issue Print"
|
||||||
|
date: "2023-07-12T01:43:17+03:00"
|
||||||
|
author: "anybody"
|
||||||
|
draft: true
|
||||||
|
print: "issue/int-issue-management.md"
|
||||||
|
---
|
7
static/sample/dummy-package/dummy-package.txt
Normal file
7
static/sample/dummy-package/dummy-package.txt
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
This is a dummy file
|
||||||
|
|
||||||
|
Include a ZIP with:
|
||||||
|
- Markdown template
|
||||||
|
- CSL file
|
||||||
|
- Bib sample
|
||||||
|
- Word/ODT template
|
BIN
static/sample/jgdr-test-illustration-3x.png
Normal file
BIN
static/sample/jgdr-test-illustration-3x.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 55 KiB |
1
static/sample/jgdr-test-illustration.svg
Normal file
1
static/sample/jgdr-test-illustration.svg
Normal file
|
@ -0,0 +1 @@
|
||||||
|
<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 300"><defs><style>.cls-1{fill:#808285;opacity:0.8;}.cls-2{font-size:15px;}.cls-2,.cls-4,.cls-5,.cls-6{fill:#231f20;}.cls-2,.cls-4,.cls-5{font-family:PFDinTextPro-Regular, PF DinText Pro;}.cls-3{letter-spacing:-0.02em;}.cls-4{font-size:10px;}.cls-5{font-size:25px;}.cls-7{fill:#ec008c;}.cls-10,.cls-11,.cls-12,.cls-15,.cls-8,.cls-9{fill:none;}.cls-10,.cls-11,.cls-12,.cls-13,.cls-14,.cls-15,.cls-8,.cls-9{stroke:#231f20;}.cls-10,.cls-15,.cls-8,.cls-9{stroke-miterlimit:10;}.cls-8{stroke-dasharray:5.03 5.03;}.cls-9{stroke-dasharray:2.01 4.03;}.cls-10,.cls-13{stroke-dasharray:5 5;}.cls-11,.cls-12,.cls-13,.cls-14{stroke-linejoin:round;}.cls-12,.cls-15{stroke-width:2px;}.cls-13{fill:#fff200;}.cls-14{fill:#00aeef;}</style></defs><polygon class="cls-1" points="645.27 300 700 300 700 0.3 590.54 0.3 645.27 300"/><text class="cls-2" transform="translate(26.14 34.55)">This is a sample illust<tspan class="cls-3" x="130.5" y="0">r</tspan><tspan x="135.67" y="0">ation (700x300)</tspan></text><text class="cls-4" transform="translate(465.69 75.82)">10pt text</text><text class="cls-2" transform="translate(465.69 97.42)">15pt text</text><text class="cls-5" transform="translate(465.69 127.88)">25pt text</text><text class="cls-2" transform="translate(465.69 227.73)">1pt line</text><text class="cls-2" transform="translate(465.69 191.39)">1pt dashed line 5-5</text><text class="cls-2" transform="translate(465.69 262.17)">2pt line</text><rect class="cls-6" x="49.84" y="94.74" width="103.4" height="103.4"/><circle class="cls-7" cx="166.88" cy="116.34" r="44.58"/><circle class="cls-8" cx="300.63" cy="119.56" r="48.06"/><circle class="cls-9" cx="378.25" cy="119.56" r="48.06"/><line class="cls-10" x1="465.69" y1="202.06" x2="654.45" y2="202.06"/><polygon class="cls-6" points="652.47 204.96 663.31 202.06 652.47 199.15 652.47 204.96"/><line class="cls-11" x1="465.69" y1="236.49" x2="654.45" y2="236.49"/><polygon class="cls-6" points="652.47 239.4 663.31 236.49 652.47 233.59 652.47 239.4"/><line class="cls-12" x1="465.69" y1="266.37" x2="645.59" y2="266.37"/><polygon class="cls-6" points="641.63 272.18 663.31 266.37 641.63 260.56 641.63 272.18"/><polygon class="cls-13" points="121.08 177.66 82 177.66 62.47 211.5 82 245.35 121.08 245.35 140.63 211.5 121.08 177.66"/><rect class="cls-14" x="179.03" y="138.09" width="16.34" height="79.15" rx="8.17"/><circle class="cls-15" cx="342.74" cy="222.48" r="49.91"/></svg>
|
After Width: | Height: | Size: 2.4 KiB |
Loading…
Add table
Reference in a new issue