Update 'README.md'

README.md

@@ -1,2 +1,68 @@
 # Syllabus
 
+
+Our website (the published version of the web site is here: https://syllabus.pirate.care/) is rendered/processed into a static HTML web site by [HUGO](https://gohugo.io/) using the *Markdown files* from this [Git](https://git-scm.com/) repository served to you by [Gitea](https://gitea.io/). *Markdown files* which are rendered into web site pages can be found inside the folder 📁 **content** which is listed right below 📁 **archetypes**, and above 📁 **custom_sysadmin**, 📁 **data/books**, 📁 **public/css** etc. *Markdown files* have the extension **.md**. We **add/edit** *Markdown files* in this repository in order to have **HUGO** process/render/convert them into a regular Web Site people can access. Through that process every *Markdown file* gets transformed into an individual Web/HTML Page.
+
+#### There are two ways to edit existing Markdown files and add new ones:
+
+#### 1. One could edit the web site via the custom setup at https://syllabus.pirate.care/_preview/ which adds a user friendly header which looks like this:
+
+![](static/images/preview_header_small.png)
+
+1. To **edit** the current page one should use the button/link **edit_this**. It brings you straight into the editing *Markdown file* "responsible" for that web page.
+
+2. To **add** a new *Markdown file* under the current section (**topic** or **session**) one should use the button/link **current_folder/add_new** (where **current_folder** would expand into either 📁 **topic** or 📁 **session** depending on the current URL one is visiting at that moment)
+
+3. To **add** a new *Markdown file* one should use the button/link **add_new**. (If you want to add a new folder where that new *Markdown file* would sit start by typing the name of the new folder and add **/** (slash) after the name, the moment after you add **/** the input area will automatically let you continue with typing the name of the *Markdown file* to be added. Yet another thing which is easier if you just try it.)  
+
+4. After you are done with editing/adding the *Markdown files* and satisfied with the changes you should click on the button/link **publish** which would bring you straight into editing **PUBLISH.trigger.md** after which commit[^2] the web site will be published. The new changes will be visible to everyone visiting the web site.
+
+
+####  2. One could also edit the web site by using this Gitea instance (https://git.memoryoftheworld.org/PirateCare/Syllabus) where you just read this **README.md** file.
+
+1. To **edit** *Markdown files* you should get inside the 📁 **content** folder where you will find two folders 📁 **topic** and 📁 **session**. All the individual *Markdown files* are saved/accessible inside those folders (you can recognize the files by their extension **.md**).
+
+2. To **edit** a particular *Markdown file* in this repository you should click on the 🖉 (pen) in the top right corner of the Gitea toolbar which appears after you open the Gitea web page of that *Markdown file*
+![](static/images/edit_page.png)
+
+    - It is very important to always keep the **header**[^1] at the top of the *Markdown file*. You can recognize it as it has three dashes ( --- ) in its first line. It is then followed by **title** and/or **date** lines, sometimes **weights**, carrying the obvious value of the **title**, **date** or **weight** of that *Markdown file*. The **weight** value is used by the web site **menus** so the *Markdown file's* corresponding web page with a lower number will apear above the one with a higher number. Usually you make the top of the **menu** with **weight: 10** and the rest with 20, 30, 40... So if you ever go back and add a new *Markdown file* to the repository you could easily make its **weight** values somewhere in between *"the tens"* (e.g. 25, 35, 45..) without changing the **weight** value of any the *"old"* ones. Here is one of the **headers** from 📁 **content/session/badcare.md**:  
+![](static/images/front_matter.png)
+
+3. To **add** a new *Markdown file* one should click the button **[New File]** in the folder where one wants the new *Markdown file* (at the moment these are 📁 **content/topic** and 📁 **content/session**)
+
+    - Every **new** *Markdown file* should have **.md** extension as the part of its name. For example: **thirdsession.md**.
+    - Every **new** *Markdown file* has to have a **header**[^1] at the top. The first line should start with three dashes ( **---** ), the second line should have a **title** (for example: **title: "Third reading group"**), if you want/need you should also add **weight** and/or **date** in the following lines but make sure that the **header** ends again with three dashes ( **---** ). After that last line with the three dashes you should add your actual content.
+
+4. To **upload** images one should click the button **[Upload File]** and upload the image inside the folder 📁 **static/images**. Once inside the 📁 **static/images** there are bunch of already uploaded images. Important to note is that if you are uploading an image, make sure the file name doesn't contain spaces " " but instead has **underscores** or is made into a one-word file name. For example: *team_photo.jpg*, *teamphoto.jpg* or *TeamPhoto.jpg*.
+
+5. To **PUBLISH** the web site with all of the latest changes one should **edit** the file **PUBLISH.trigger.md**. It is listed in the root of this repository. Once there **PUBLISH.trigger.md** should have the 🖉 (pen) in the top right corner of the Gitea page toolbar just like every other page in the repository. The published version of the web site is here: https://syllabus.pirate.care/
+
+6. After you get familiar with the workflow you migh also try this *trick* to *quickly* **PUBLISH** the web site by adding **!publish!** as a part of the commit message just like shown in this screenshot:
+
+![](static/images/commit_publish_small.png)
+
+After you **PUBLISH** the web site by using the **!publish!** *trick* in the commit message you shouldn't go and **edit** **PUBLISH.trigger.md**. If you do that nothing will go wrong but you'll just trigger **HUGO** to do the processing once more.
+
+
+#### NOTE: The "preview" web site at https://syllabus.pirate.care/_preview/ will show automatically all of the changes after every commit/change. The "preview" version of the web site is not supposed to be shown to the public. Once you are satisfied with the "preview" version of the latest changes you are ready to PUBLISH the changes to the "official" version of the web site (https://syllabus.pirate.care/) You can do that by adding !publish! to the commit message or by finding the PUBLISH.trigger.md file, changing it and committing the changes.
+
+---
+
+*If anything goes wrong these two files could help those few people who are not scared of reading logs :)*
+
+- https://syllabus.pirate.care/last-commit-log.txt
+- https://syllabus.pirate.care/_preview/last-commit-log.txt
+
+[^1]: **Header** is called [Front Matter](https://gohugo.io/content-management/front-matter/) in HUGO's documentation.
+[^2]: The phrase *commiting the changes* comes from the Git vocabulary and if this is the first time you hear about it, probably the closest well known equivalent would be to say *saving the file after it has been changed*. In our case here the file being *saved* to the Git repository will add its latest changes to the history log of all of the previous versions of that file, it will add the name of the account which made those changes together with the date when all of this happened. By doing all of this any file in the Git repository is easily reverted to any of the versions from the past, the history of who did what is kept and the whole repository is ready to be distributed, shared, and synced with any of its "clones" on other different computers.
+
+#### Library bookmarklet to quickly get the Markdown link for the book reference:
+
+```javascript
+javascript: (function() {
+    let re = new RegExp(".*book/");
+    let c = `![](bib:${location.href.replace(re, "")})`;
+    navigator.clipboard.writeText(c);
+    alert(`___Markdown link\n\n      ${c}\n\n___copied to clipboard!`)
+})()
+```