From 95cd1b836dc44b28418850fb7f6112ef416d5849 Mon Sep 17 00:00:00 2001 From: constantinos Date: Tue, 15 Aug 2023 18:32:30 +0300 Subject: [PATCH] content creation was split into 2 different workflows (CLI/preview site) made public --- content/article/int-content-cli.md | 101 ++++++++++++++++++++++++++ content/article/int-content-online.md | 75 +++++++++++++++++++ content/article/int-content.md | 99 ------------------------- 3 files changed, 176 insertions(+), 99 deletions(-) create mode 100644 content/article/int-content-cli.md create mode 100644 content/article/int-content-online.md delete mode 100644 content/article/int-content.md diff --git a/content/article/int-content-cli.md b/content/article/int-content-cli.md new file mode 100644 index 0000000..1d7319e --- /dev/null +++ b/content/article/int-content-cli.md @@ -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 /filename.md` + +Where `` 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`| ![New contributor archetype](article:int-archetype-contributor)| +| editor | name-surname.md | `hugo new editor/name-surname.md` | ![New editor archetype](article:int-archetype-editor)| +| issue (x is number) | issue-x.md | `hugo new issue/issue-x.md` | ![New issue archetype](article:int-archetype-issue)| +| article | article-short-title.md | `hugo new article/article-short-title.md` | ![New article archetype](article:int-archetype-article) | +| print (issue) | p-issue-x.md | `hugo new print/p-issue-x.md` | ![New print archetype](article:int-archetype-print) | +| print (article)| p-article-short-title.md | `hugo new print/p-article-short-title.md` | | +
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.* +# 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. + + +# 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. + + \ No newline at end of file diff --git a/content/article/int-content-online.md b/content/article/int-content-online.md new file mode 100644 index 0000000..03aa5db --- /dev/null +++ b/content/article/int-content-online.md @@ -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 | ![New contributor archetype](article:int-archetype-contributor)| +| editor | name-surname.md |![New editor archetype](article:int-archetype-editor)| +| issue (x is number) | issue-x.md | ![New issue archetype](article:int-archetype-issue)| +| article | article-short-title.md | ![New article archetype](article:int-archetype-article) | +| print | p-issue-x.md | ![New print archetype](article:int-archetype-print) | +
Table 1: Filename conventions and instructions per content type.
+ +# 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. + +![Screenshot 1: Sandpoints online preview site; edit options.](/internal/sandpoints-online-interface.png) + +|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 | +
Table 2: Sandpoints online preview site edit options explained.
+ +# Editing & new item creation +All modifications (edits or new items) are carried out as git commits (Screenshots 2 and 3). + +![Screenshot 2: Sandpoints online preview site; interface for editing entries (EDIT_THIS).](/internal/sandpoints-online-edit.png) + +![Screenshot 3: Sandpoints preview site; interface for creating new entries (ADD_ARTICLE)](/internal/sandpoitns-online-create.png) diff --git a/content/article/int-content.md b/content/article/int-content.md deleted file mode 100644 index 0c6a913..0000000 --- a/content/article/int-content.md +++ /dev/null @@ -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 /filename.md` - -Where `` 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 ![file-naming conventions](article:int-conventions). - -# Archetypes - -New content is generated following `archetypes` (see `/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 ![file-naming conventions](article:int-conventions). - -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"] ---- -```