A collective writing of a Pirate Care Syllabus.
This repository has been archived on 2020-03-27. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
Tobias c1517d404a Update de.assistingpeopleinisolation.md 2020-03-22 23:59:33 +00:00
archetypes hugo stuff... 2020-03-05 05:10:52 +01:00
config Update 'config/_default/config.toml' 2020-03-17 18:29:24 +00:00
content Update de.assistingpeopleinisolation.md 2020-03-22 23:59:33 +00:00
custom_syadmin hugo stuff... 2020-03-05 05:10:52 +01:00
data/books new books... 2020-03-08 14:03:44 +01:00
static Upload files to 'static/topic/coronanotes' 2020-03-18 09:43:08 +00:00
themes/piratecare changes in templates so has_sessions/topics now requires the full markdown file name 2020-03-21 02:50:40 +01:00
PUBLISH.trigger.md Update 'PUBLISH.trigger.md' 2020-03-21 15:00:03 +00:00
README.md Update 'README.md' 2020-03-17 21:14:03 +00:00



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:

  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 stands for just / if on the home page or 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. 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 and then for Syllabus' home page the third line will be has_topics: with topics shown in sidebar menu, or for topic page the third line will be has_sessions: first_session_name, second_session_name etc. 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. In the case of Markdown file for session the top three lines will be three dashes, title, and then three dashes again. None of those lines will appear at the web site. That's called header1 and it carries the metadata for that Markdown file.

  5. 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 commit2 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 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 header1 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 header1 should always contain only three dashes ( --- ). The header's first and last line should have only those three dashes ( --- ). The names of the topics following has_topics: will appear in the side bar menu. The same goes for topic page which lists its sessions in the line starting with has_sessions:. 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 header1 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 :)


  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. ↩︎