# RaceCriticalTheories

The workflow described below is glued together in a software project/platform **Sandpoints**.

Our website (the published version of the web site is here: https://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/curriculum/) 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://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/_preview/curriculum/ which adds a user friendly header which looks like this:

![](static/images/preview_header_small.png)

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**[^1] and it carries the metadata for that *Markdown file*. Here is the example of one of the topic's header:  
![](static/images/topic_header.png)  

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**[^1] and it carries the metadata for that *Markdown file*. Here is the example of one of the session's header:  
![](static/images/session_header.png)  

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[^2] 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.sandpoints.org/GEMLab/RaceCriticalTheories) 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**, the second line starting with **has_topics** (if home page) or **has_sessions:" (if topic page). The last line of the **header**[^1] 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**:  
![](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://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/curriculum/

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://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/_preview/curriculum/ 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://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/curriculum/) 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://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/curriculum/last-commit-log.txt
- https://pages.sandpoints.org/sandpoints/racecriticaltheories-f16ef346/_preview/curriculum/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 quickly get the Markdown link for the book reference:

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

...