content creation was split into 2 different workflows (CLI/preview site) made public
This commit is contained in:
parent
ef434de5db
commit
95cd1b836d
3 changed files with 176 additions and 99 deletions
101
content/article/int-content-cli.md
Normal file
101
content/article/int-content-cli.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: "Content creation via the terminal 👷"
|
||||
date: "2023-07-04T18:30:44+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
draft: false
|
||||
keywords:
|
||||
- internal
|
||||
- guide
|
||||
- journal management
|
||||
abstract: |
|
||||
(Internal) Guide for creating new content via the terminal.
|
||||
---
|
||||
|
||||
|
||||
# Creating new content via the terminal {#cli}
|
||||
|
||||
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](#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](#filenames), 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.*
|
||||
|
||||
# File naming conventions, Hugo commands, and instructions for creating new entries {#filenames}
|
||||
|
||||
File naming:
|
||||
- All **lowercase**
|
||||
- Use **dash as separator**
|
||||
- No spaces
|
||||
- No underscores
|
||||
|
||||
Examples, Hugo commands, and instructions, per entry type:
|
||||
|
||||
| Type | Filename convention | Hugo command | Instructions template|
|
||||
|-|-|-|-|
|
||||
| contributor | name-surname.md | `hugo new contributor/name-surname.md`| |
|
||||
| editor | name-surname.md | `hugo new editor/name-surname.md` | |
|
||||
| issue (x is number) | 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` | |
|
||||
<figcaption>Table 1: File naming conventions, Hugo commands, and instructions per content type. </figcaption>
|
||||
|
||||
|
||||
*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.*
|
||||
# Archetypes {#archetypes}
|
||||
|
||||
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.
|
||||
|
||||
<!--
|
||||
The absolutely necessary information required is the YAML 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, editing, and publishing new content
|
||||
|
||||
1. Create a new file, named according to [file naming conventions](#filenames).
|
||||
3. Open the new file, and follow the included instructions to fill in the metadata fields:
|
||||
1. add your name in the `author` field
|
||||
2. edit header information (title, keywords, abstract, etc.)
|
||||
4. Edit file content.
|
||||
5. Commit changes via Git when necessary.
|
||||
6. When editing is done and the new entry is ready for publishing, change `draft: true` to `draft: false`.
|
||||
7. Commit changes via Git.
|
||||
8. To recompile the site and include these changes include the keyword `!publish!` in your commit message.
|
||||
|
||||
<!--
|
||||
# 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:
|
||||
> `hugo new print/p-x-short-title.md`
|
||||
|
||||
Notes: creating a new print item will most likely break the site if the print destination file does not exist (edit the print target field accordingly: `print: "article/some-article.md"`):
|
||||
|
||||
-->
|
||||
75
content/article/int-content-online.md
Normal file
75
content/article/int-content-online.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: "Content creation via online preview site 👷"
|
||||
date: "2023-08-14T19:31:03+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
draft: false
|
||||
keywords:
|
||||
- internal
|
||||
- guide
|
||||
abstract: |
|
||||
(Internal) Guide for creating new content via the Sandpoints preview page.
|
||||
---
|
||||
# Creating new content via the online Sandpoints preview site {#online}
|
||||
|
||||
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](#filenames), 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.
|
||||
# Filename conventions and instructions for creating new entries {#filenames}
|
||||
|
||||
File naming:
|
||||
- All **lowercase**
|
||||
- Use **dash as separator**
|
||||
- No spaces
|
||||
- No underscores
|
||||
|
||||
Examples and instructions per entry type:
|
||||
|
||||
| Type | Filename convention | Instructions template |
|
||||
|-|-|-|
|
||||
| contributor | name-surname.md | |
|
||||
| editor | name-surname.md ||
|
||||
| issue (x is number) | issue-x.md | |
|
||||
| article | article-short-title.md |  |
|
||||
| print | p-issue-x.md |  |
|
||||
<figcaption>Table 1: Filename conventions and instructions per content type.</figcaption>
|
||||
|
||||
# Steps for creating new content
|
||||
|
||||
1. Create a new file, named according to [file naming conventions](#filenames).
|
||||
2. Open the new file, and copy the YAML sample and instructions corresponding to the content type of the new file (Table 1)
|
||||
3. Fill in the metadata fields:
|
||||
1. add your name in the `author` field
|
||||
2. edit header information (title, keywords, abstract, etc.)
|
||||
4. Edit content.
|
||||
5. Commit changes via Git when necessary.
|
||||
6. When editing is done and the new entry is ready for publishing, change `draft: true` to `draft: false`.
|
||||
7. Commit changes via Git.
|
||||
8. To recompile the site and include these changes include the keyword `!publish!` in your commit message.
|
||||
# Preview site interface
|
||||
|
||||
The preview site features a toolbar with five options (Screenshot 1), explained in the table below.
|
||||
|
||||
|
||||
|
||||
|Preview site options||
|
||||
|-|-|
|
||||
| EDIT_THIS | edit the current page |
|
||||
| ADD_JOURNAL / ADD_ISSUE / ADD_ARTICLE | create new entry by type|
|
||||
| PUBLISH | recompile the website to include any unpublished changes |
|
||||
| ? | open the repository website |
|
||||
<figcaption>Table 2: Sandpoints online preview site edit options explained.</figcaption>
|
||||
|
||||
# Editing & new item creation
|
||||
All modifications (edits or new items) are carried out as git commits (Screenshots 2 and 3).
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,99 +0,0 @@
|
|||
---
|
||||
title: "Content creation 👷"
|
||||
date: "2023-07-04T18:30:44+03:00"
|
||||
author: "anybody"
|
||||
contributors: ["constantinos-miltiadis.md"]
|
||||
draft: false
|
||||
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"]
|
||||
---
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue