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 using the Markdown files from this Git repository served to you by Gitea. 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:

a) 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.

b) To add a new topic one should use the button/link add_new_topic. In the field Name your file... type the new topic's name (without spaces) ending with .md. Make sure that the first line of the Markdown file has only three dashes --- followed in the second line with title: "A Very Good Page Title" (mind the quotes). The third line start with has_sessions: ["first_session_name.md", "second_session_name.md"] (mind the brackets and quotes). The sessions listed in that line will appear in a sidebar menu for that topic. In this case the forth line will be again three dashes --- and an empty line just before the content of the page. None of those lines will appear at the web site. That's called header¹ and it carries the metadata for that Markdown file. Here is the example of one of the topic's header:

c) To add a new session one should use the button/link add_new_session. In the field Name your file... type the new session's name (without spaces) ending with .md. Make sure that the first line of the Markdown file has only three dashes --- followed in the second line with title: "A Very Good Page Title" (mind the quotes). In this case the third line will be again three dashes --- and an empty line just before the content of the page. None of those lines will appear at the web site. That's called header¹ and it carries the metadata for that Markdown file. Here is the example of one of the session's header:

d) 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² the web site will be published. The new changes will be visible to everyone visiting the web site.

~
WARNING: the rest of the document is more technical.
The user friendly header with buttons:

edit_this 
add_new_topic
add_new_session
publish

should be more than enough to contribute to this web site.
ymmv.... 
~

2. One could also edit the web site by using directly 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

   • It is very important to always keep the header¹ 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, the second line starting with has_topics (if home page) or **has_sessions:" (if topic page). The last line of the header¹ should always contain only three dashes ( --- ). So, the header's first and last line should have only those three dashes ( --- ). The names of the topics Markdown files following has_topics: will appear in the side bar menu. The same goes for topic page which lists its sessions Markdown files in the line starting with has_sessions:. The list of the names of the Markdown files looks something like this: ["first_session.md", "second_session.md"] (Mind the brackets and the quotes.) Here is one of the headers from 📁 Syllabus/content/topic/housingstruggles.md:
     

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¹ 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:

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

Library bookmarklet quickly get the Markdown link for the book reference:

javascript:(()=>{alert(`![](bib:${location.href.replace(RegExp(".*book/"),"")})`);})()

...

---

1. Header is called 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. ↩︎