101 lines
4.7 KiB
Markdown
101 lines
4.7 KiB
Markdown
|
---
|
||
|
|
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"`):
|
||
|
|
|
||
|
|
-->
|