There are two main workflows for creating new content (new Markdown files). Both workflows make use of Git commits, and require write access to the project repository. These are:
Archetypes are template files for new content. However, these are only taken into account when new content is created via the terminal (not via the preview page).
Archetypes are located at the directory /root/archetypes/ which includes one Markdown file per content type (i.e. issue.md, article.md, etc.).
The archetypes include a list of instructions, per content type, for properly creating, editing, and committing new content. These instructions are included in new content created via the terminal.
The same instructions are also provided in the contents of this issue (see articles linked in Table 1), which can be copied to new entries created via the preview page.
It is recommended to use emojis1 in the title of any new and WIP items, to keep track of unpublished content as well as potential mistakes.
Each new item created from archetypes (via the terminal) will feature two emojis: one to signal a draft (⚫) and a second one associated its particular content type (e.g. 📕📑🧜♕🖶☮). It’s recommended to keep at least the draft emoji as long as an item is in preparation.
The table below describes the logic of emojis used.
Emoji
Description
⚫
draft/WIP entry (included in all new items; removed only when the article is ready for publishing)
📕
new issue entry
📑
new article entry
🧜
new contributor entry
♕
new editor entry
🖶
new print entry
☮
new journal entry (!do not create new journal entries!)
Table 2: Descriptions of emojis placed in the title of new entries.
abstract⁄(Internal) Guide for creating new content via the Sandpoints preview page.
keywords⁄internal, guide
1. Creating new content via the online Sandpoints preview site¶
Sandpoints provides a preview page that allows for both creating new entries and also editing existing entries via a browser, without the requirement of a local clone of the project.
Any action will open a new tab at the project repository page, and requires the user to be logged in to the project repository.
To access the preview page append /_preview/ to the ⁄sitemap URL.
Notes:
Creating new items via the preview site does not make use of archetypes. Any new item created with this workflow will result in an empty Markdown file (Screenshot 3), and will require a YAML header to work.
Therefore, when creating new content via the preview site, it is strongly recommended to copy the contents of the corresponding archetype. See archetype templates at §⁄Table 1, which include instructions as well as a sample YAML header to copy and fill in.
At the moment the interface for creating and editing files does not provide a preview of the Markdown documents.
2. Filename conventions and instructions for creating new entries¶
The optimal way for creating 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 (article, issue, contributor, editor, and print). When created via the terminal, each newly created item:
is generated after its corresponding archetype (see §⁄archetypes);
is set to draft (draft: true), meaning that it’s not public/published;
includes a list of required steps for preparing the entry for publication;
will have two emojis in its title, used to track unpublished content.
Make sure to follow §⁄file naming conventions, and provide adequate commit messages for any additions or modifications.
Note: this workflow requires a local clone of the repository as well as a Hugo installation, in addition to repository credentials.
2. File naming conventions, Hugo commands, and instructions for creating new entries¶
File naming:
All lowercase
Use dash as separator
No spaces
No underscores
Examples, Hugo commands, and instructions, per entry type:
Table 1: File naming conventions, Hugo commands, and instructions per content type.
Note: Creating a new print file can break the site if (a) the print: target points to an inexistent file, or if (b) a public print item points to a non-published target.
New content is generated following archetypes (see root/archetypes/). Archetypes are Markdown files and can be thought of as templates that pertain to specific content types, and dictate the content to be included upon creating a new file.
Currently, archetypes will be generated with a set of instructions for their creator to follow in the form of a to-do list.
4. Steps for creating, editing, and publishing new content¶
Sandpoints allows parenting and associating different content types. This is done in the YAML header of a Markdown entry. Parenting content is done by providing a list of filenames of the children of a given entry. Associating content is done by providing a list of filenames of the associated entries (for an issue or article).
As in the examples below, for either case:
provide filenames including extensions within quotations,
separate entries with commas, as in the examples below, and
make sure to leave a whitespace character been the colon and the square brackets.
Example flag: ["something.md", "something-else.md"]
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 this convention, the YAML header section for each item that has children features the flag:
This is done by providing a list of editors in the YAML section of an issue, or a list of contributors in the YAML section of an article, respectively.
abstract⁄(INTERNAL) This is a copy of the archetype for new issues, and includes instructions for editing and publishing a new issue item, found at root/archetypes/issue.md
keywords⁄archetype, internal, guide
If creating a new entry via the terminal:
The Hugo terminal command for creating a new issue is:
hugo new issue/issue-5.md
This will create new file at content/issue/issue-5.md. The new file will be created according to the archetype for articles at root/archetypes/issue.md. The new file will be created as a draft (draft: true) and will contain the instruction steps below. Please complete all required steps before committing or publishing new content.
If creating a new entry via the online preview page:
the new entry will be empty. Please use the sample §⁄YAML header below as starting point, and also copy to the new file the §⁄instructions provided below.
If creating a new entry via the online preview page, the new entry will be created as an empty file. Please use the sample YAML file below as starting point, and also copy to the new file the instructions provided below.
---
title: "Issue title ⚫ 📕"
date: "2023-07-13T14:15:05+03:00"
author: "file-creator-put-your-name-here"
draft: true
has_articles: ["article-test.md"]
editors: ["jane-editor.md", "joe-editor.md"]
keywords:
- draft
abstract: |
The text of your abstract.
---
Parent issue to journal
- If, and only if this issue is ready to be published and draft: False you can parent go to content/journal/jgdr.md and add the name of this file (not title) to the field has_issues. Note: articles included in this issue will not appear unless this is parented to the journal item. Example:
has_issues: ["this-issues-file-name.md"]
Add issue-editorial text below this section.
Log potential problems or pending tasks with this issue by making another check-list below (commented sample lists provided below).
Git commit and push if/when applicable, providing a commit message describing your changes.
Set the draft flag accordingly. False will make this public: only do that when ready to publish, and when there is already a ‘print’ file for the issue. Leave draft: true when in-progress.
Feel free to put this block inside comments, to be able to view the actual content properly.
abstract⁄(INTERNAL) This is a copy of the archetype for new articles, and includes instructions for editing and publishing a new article item, found at root/archetypes/article.md
keywords⁄archetype, internal, guide
If creating a new entry via the terminal:
The Hugo terminal command for creating a new article is:
hugo new article/article-short-title.md
This will create new file at content/article/article-short-title.md. The new file will be created according to the archetype for articles at root/archetypes/article.md. The new file will be created as a draft (draft: true) and will contain the instruction steps below. Please complete all required steps before committing or publishing new content.
If creating a new entry via the online preview page:
the new entry will be empty. Please use the sample §⁄YAML header below as starting point, and also copy to the new file the §⁄instructions provided below.
abstract⁄(INTERNAL) This is a copy of the archetype for contributors (authors), and includes instructions for editing and publishing a new contributor item, found at root/archetypes/contributor.md
keywords⁄archetype, internal, guide
If creating a new entry via the terminal:
The Hugo terminal command for creating a new contributor is:
hugo new contributor/name-surname.md
This will create new file at content/contributor/name-surname.md. The new file will be created according to the archetype for articles at root/archetypes/contributor.md. The new file will be created as a draft (draft: true) and will contain the instruction steps below. Please complete all required steps before committing or publishing new content.
If creating a new entry via the online preview page:
the new entry will be empty. Please use the sample §⁄YAML header below as starting point, and also copy to the new file the §⁄instructions provided below.
If creating a new entry via the online preview page, the new entry will be created as an empty file. Please use the sample YAML file below as starting point, and also copy to the new file the instructions provided below.
---
title: "Jane Contributor ⚫ 🧜"
date: "2023-07-13T14:15:20+03:00"
author: "file-creator-put-your-name-here"
affiliation: "Some affiliation (optional; remove line if not applicable)"
draft: true
---
abstract⁄(INTERNAL) This is a copy of the archetype for editor items and includes instructions for editing and publishing a new editor item, found at root/archetypes/editor.md
keywords⁄archetype, internal, guide
If creating a new entry via the terminal:
The Hugo terminal command for creating a new editor is:
hugo new editor/name-surname.md
This will create new file at content/editor/name-surname.md. The new file will be created according to the archetype for articles at root/archetypes/editor.md. The new file will be created as a draft (draft: true) and will contain the instruction steps below. Please complete all required steps before committing or publishing new content.
If creating a new entry via the online preview page:
the new entry will be empty. Please use the sample §⁄YAML header below as starting point, and also copy to the new file the §⁄instructions provided below.
abstract⁄(INTERNAL) This is a copy of the archetype for creating new print items, including instructions for creating and properly editing print items, found at root/archetypes/article.md
keywords⁄archetype, internal, guide
If creating a new entry via the terminal:
The Hugo terminal command for creating a new print item for an issue is:
hugo new print/p-issue-5.md
This will create new file at content/print/p-issue-5.md. The new file will be created according to the archetype for articles at root/archetypes/print.md. The new file will be created as a draft (draft: true) and will contain the instruction steps below. Please complete all required steps before committing or publishing new content.
If creating a new entry via the online preview page:
the new entry will be empty. Please use the sample §⁄YAML header below as starting point, and also copy to the new file the §⁄instructions provided below.
If this concerns an issue, say issue-5.md, name this file p-issue-5.md. If this concerns an article say article-title.md, name this file p-article-title.md
YAML Fields
Put your name in the field author inside “quotation marks” as in->author: "creators name"
Set the title to:
Issue X Print (for issues, where X is the issue number or name)
Article title Print (for articles)
Set the correct print destination (e.g. “issue/issue-x.md” or “article/article-name.md”). ERRORS WILL BREAK THE SITE.
Set the draft flag accordingly (false will make this public)
Delete this comment section.
Git commit and push your changes if/when applicable, providing a commit message describing your changes.
Done!
Note: Items that are not public/published (draft: true), cannot have a public/published print.Note: Print items should not have any content under the YAML header.
