Skip to content

Commit dd3e419

Browse files
justwheeljustwheel
committed
🕸️ website: Initial commit (closes #13, closes #18)
This commit is a first attempt at documenting the FOSS@MAGIC GitHub Pages website, hosted at https://fossrit.github.io. Most of this content is adapted from @ct-martin's documentation written in RITlug/ritlug.github.io#254. Most importantly, it explains how to add content to the website, like announcements, events, and projects. Closes #13. Closes #18. Signed-off-by: Justin W. Flory <[email protected]> :heavy_check_mark: Address @ct-martin's feedback in PR #30 Address parallelism, drop `date` frontmatter from example announcement. Signed-off-by: Justin W. Flory <[email protected]> :heavy_check_mark: Address @10eMyrT's feedback in PR #30 Reorganize structure to move meta information about how the site works to the "About" section. Makes "How to add content" section easier to follow. Signed-off-by: Justin W. Flory <[email protected]>
1 parent d8ebe06 commit dd3e419

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎docs/infra/website.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
Website (fossrit.github.io)
2+
===========================
3+
4+
This page documents the official FOSS@MAGIC website hosted on GitHub Pages.
5+
The website source code is found in [FOSSRIT/fossrit.github.io](https://github.com/FOSSRIT/fossrit.github.io "Official website for Free and Open Source Software @ RIT MAGIC Center and FOSS academia").
6+
7+
8+
## About
9+
10+
* The site is built using [Jekyll](https://jekyllrb.com/), [Bootstrap](https://getbootstrap.com/) (via CDN), [Font Awesome](https://fontawesome.com/) (via CDN), & [GitHub Pages](https://help.github.com/categories/github-pages-basics/)
11+
* [PDF.js](https://mozilla.github.io/pdf.js/) is used for embedding PDFs in pages (via CDN)
12+
* "Pretty links" is turned on in the Jekyll configuration (see [`permalink: pretty`](https://github.com/FOSSRIT/fossrit.github.io/blob/master/_config.yml))
13+
* `github-pages` Gem used to simplify dependencies
14+
* The live site is updated by committing changes to the `master` branch
15+
16+
_The site uses an undocumented feature of Jekyll where categories are defined using `category/_posts/` instead of `_posts/category/`._
17+
18+
### Git work flow
19+
20+
This describes how to make any type of contribution to the FOSS@MAGIC website:
21+
22+
1. Fork repository to your GitHub account (go to [FOSSRIT/fossrit.github.io](https://github.com/FOSSRIT/fossrit.github.io) and click "fork")
23+
2. Clone repository locally to your workstation
24+
3. Create/add files
25+
4. Git commit
26+
5. Git push to your fork
27+
6. Open pull request against `master` branch of FOSSRIT/fossrit.github.io repository
28+
7. When pull request is merged, site updates in a couple of minutes
29+
30+
### Jekyll and Front Matter
31+
32+
Jekyll is what builds the site.
33+
It renders Markdown and handles templating.
34+
_Jekyll requires that all post pages start with a valid date in the syntax `YYYY-MM-DD-<title>.md`_.
35+
36+
Jekyll uses something called [Front Matter](https://jekyllrb.com/docs/front-matter/) to know more information about the page.
37+
Front Matter defines what the page looks like and metadata such as the title, author, and event details (where applicable).
38+
39+
Frontmatter should be at the top of a post and should be surrounded by triple-dashes (`---`).
40+
_All times are of the timezone `America_New_York`._
41+
42+
Additionally, Jekyll uses the string `<!--more-->` to define where the summary of pages end.
43+
This is used when showing post previews on the site.
44+
Optionally, the `excerpt` frontmatter can be defined instead to override this (if using an HTML page instead of Markdown in special cases, the `excerpt` frontmatter _should be used_ instead of `<!--more-->`).
45+
Please use this functionality to keep lists of posts readable.
46+
47+
#### Example post
48+
49+
```yaml
50+
---
51+
title: Example thing
52+
layout: post
53+
---
54+
Hello FOSS folks!
55+
56+
This week...
57+
58+
<!--more-->
59+
60+
Other things happening.
61+
62+
- Signature
63+
```
64+
65+
66+
## How to update FOSS Hours time/place
67+
68+
Edit [`_config.yml`](https://github.com/FOSSRIT/fossrit.github.io/blob/master/_config.yml) and update the settings `meeting-day`, `meeting-place`, and `meeting-time`.
69+
These settings are used across the website automatically.
70+
The meeting time and place are referenced in the `_config.yml` so they are updated in one place.
71+
72+
Example:
73+
74+
```yaml
75+
# --- meeting schedule settings ---
76+
77+
# They appear exactly as typed. Follow the format already here when updating.
78+
meeting-day: Thursday
79+
meeting-place: MSS/71-3190 (conference room)
80+
meeting-time: 5:00PM - 7:00PM
81+
```
82+
83+
84+
## How to add content
85+
86+
This section describes how to add new content to the FOSS@MAGIC website.
87+
88+
Add a new `.md` file to one of the `_posts/` folders for a category.
89+
Store assets (a.k.a. pictures, PDFs, or other downloadable files) in a folder within that category (e.g. `projects/assets/`).
90+
Include the date in asset file names so it is clear what references it.
91+
92+
Content categories include the following:
93+
94+
* [Announcements](https://github.com/FOSSRIT/fossrit.github.io/tree/master/announcements)
95+
* [Events](https://github.com/FOSSRIT/fossrit.github.io/tree/master/events)
96+
* [Projects](https://github.com/FOSSRIT/fossrit.github.io/tree/master/projects)
97+
98+
### How to create announcements
99+
100+
Announcements spread the word about what is happening in the community.
101+
Posts in this category are added to an RSS Feed (at [fossrit.github.io/feeds/latest.xml](https://fossrit.github.io/feeds/latest.xml)).
102+
103+
* Create a new Markdown file in `announcements/_posts/` named with the convention `YYYY-MM-DD-<title>.md`
104+
105+
#### Example announcement
106+
107+
See [2019-12-17-spring-2020-volunteers.md](https://github.com/FOSSRIT/fossrit.github.io/blob/67282a55a6330a5c61397eaeac92ef9c025f0432/announcements/_posts/2019-12-17-spring-2020-volunteers.md):
108+
109+
```yaml
110+
---
111+
author: Justin W. Flory
112+
title: "Call for Volunteers: Spring 2020"
113+
layout: post
114+
---
115+
116+
Hi FOSS folks!
117+
We are looking for volunteers from the RIT community!
118+
If you are interested in volunteering with FOSS@MAGIC in the Spring 2020 semester…
119+
```
120+
121+
### How to create events
122+
123+
Events are written before or after an event.
124+
125+
Events often use an image gallery functionality.
126+
Typically, photos are added to the gallery after an event.
127+
Use the `images` Front Matter with an array of photos.
128+
The `images` parameter takes relative links to the RITlug site or absolute links for images hosted on other sites.
129+
See the example event below for how to do this.
130+
131+
* Create a Markdown file in `events/_posts/` named with the convention `YYYY-MM-DD-<title>.md`
132+
133+
#### Example event
134+
135+
See [2019-11-05-election-night-hackathon.md](https://github.com/FOSSRIT/fossrit.github.io/blob/67282a55a6330a5c61397eaeac92ef9c025f0432/events/_posts/2019-11-05-election-night-hackathon.md):
136+
137+
```yaml
138+
---
139+
layout: event
140+
title: Election Night Hackathon 2019
141+
authors:
142+
- Justin W. Flory
143+
- D. Joe Anderson
144+
excerpt: Help transcribe suffragist papers or hack on other project during Election Night.
145+
images:
146+
- /events/assets/2019/11/election1.jpg
147+
- /events/assets/2019/11/election2.jpg
148+
- /events/assets/2019/11/election3.jpg
149+
- /events/assets/2019/11/election4.jpg
150+
---
151+
Students and faculty collaborated and worked on projects during the 2019 US midterm elections.
152+
153+
{% include content-blocks/gallery.html %}
154+
155+
> FOSS@MAGIC proudly presents… the 9th Annual Election Night Hackathon!
156+
```
157+
158+
### How to add projects
159+
160+
Projects are about things the FOSS@RIT community work on.
161+
They are not added to an RSS Feed.
162+
163+
* Create a Markdown file in `projects/_posts/` named with the convention `YYYY-MM-DD-<title>.md`
164+
* The date is required because of a Jekyll requirement to list projects
165+
* Should be updated at least once a year if project is on-going
166+
167+
Like events, projects often use the image gallery.
168+
169+
Some projects use custom HTML (in-line or entirely) to have a better show effect.
170+
If using custom HTML, rememberto set the `excerpt` Front Matter.
171+
If doing the page entirely in custom HTML, the `layout` should be set to `default`, which includes the FOSSRIT navbar & footer, but not the page background.
172+
173+
The `author`/`authors` frontmatter should be defined.
174+
Additionally, the `permalink` property is commonly used to give a more special URL.
175+
176+
#### Example project
177+
178+
See [2018-01-01-teleirc.md](https://github.com/FOSSRIT/fossrit.github.io/blob/67282a55a6330a5c61397eaeac92ef9c025f0432/projects/_posts/2018-01-01-teleirc.md):
179+
180+
```yaml
181+
---
182+
layout: project
183+
title: TeleIRC
184+
permalink: /projects/teleirc
185+
authors:
186+
- Mark Repka (@repkam09, original author)
187+
- Justin W. Flory (@jwf, current maintainer)
188+
- Seth Hendrick (@xforever1313)
189+
- Nate Levesque (@thenaterhood)
190+
- and others
191+
excerpt: TeleIRC bridges Telegram groups and IRC channels.
192+
---
193+
194+
{% include content-blocks/gallery.html %}
195+
196+
NodeJS implementation of Telegram <=> IRC bridge…
197+
```

0 commit comments

Comments
 (0)