Skip to content

Commit ded047e

Browse files
ct-martinjrtechs
ct-martin
authored and
jrtechs
committed
Add a lot more post info to readme (#254)
Added contributing content information to the readme
1 parent 5c8bd38 commit ded047e

File tree

1 file changed

+248
-10
lines changed

1 file changed

+248
-10
lines changed

‎README.md

Lines changed: 248 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,29 @@
44
55
## Table of Contents
66
* [About](#about)
7-
* [Adding Content & Contributing](#adding-content-contributing)
7+
* [Adding Content & Contributing](#adding-content--contributing)
8+
* [Git Workflow](#git-workflow)
9+
* [Jekyll & Frontmatter](#jekyll--frontmatter)
10+
* [Announcements](#announcements)
11+
* [Talks](#talks)
12+
* [Events](#events)
13+
* [Projects](#projects)
14+
* [Calendar & Placeholders](#calendar--placeholders)
815
* [Updating meeting times / places](#updating-meeting-times--places)
916

1017
## About
1118

1219
The website's last major update was Summer 2018, but content dates back to 2015.
1320

14-
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/).
15-
[PDF.js](https://mozilla.github.io/pdf.js/) is used for embedding PDFs in pages (via CDN).
16-
"Pretty links" is turned on in the Jekyll configuration.
17-
The `github-pages` Gem is used to simplify dependencies.
18-
The live site is updated by committing changes to the `master` branch.
21+
* 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/)
22+
* [PDF.js](https://mozilla.github.io/pdf.js/) is used for embedding PDFs in pages (via CDN)
23+
* "Pretty links" is turned on in the Jekyll configuration
24+
* The `github-pages` Gem is used to simplify dependencies
25+
* The live site is updated by committing changes to the `master` branch
1926
_The site uses an undocumented feature of Jekyll where categories are defined using `category/_posts/` instead of `_posts/category/`._
2027

28+
Please see [CONTRIBUTING.md](https://github.com/RITlug/ritlug.github.io/tree/master/CONTRIBUTING.md) for more info on the technical specifics of the site.
29+
2130
## Adding Content & Contributing
2231

2332
Add a new `.md` file to one of the `_posts/` folders for a category.
@@ -27,13 +36,242 @@ Asset file names should have enough info in the file name to know what reference
2736
Current categories:
2837
* Announcements (`announcements/`)
2938
* Events (`events/`)
30-
* Meetings & Meetups (`meetings-meetups/`) (Note: these are not pages; they are placeholder metadata for the calendar feed and should be deleted when creating the announcement post)
39+
* Meetings & Meetups (`meetings-meetups/`; see [Calendar & Placeholders](#calendar--placeholders))
3140
* Projects (`projects/`)
3241
* Talks (`talks/`)
3342

34-
_Note on timezones: assume times are `America_New_York` and that DST is accounted for_
43+
### Git Workflow
44+
45+
(This is the short version; if you need help using git please ask us, we'll be glad to help)
46+
47+
* Fork the repository to your own Github account (go to the RITlug repository and click "fork")
48+
* Clone the repository locally (if desired - you can also create it online)
49+
* Create and/or add files
50+
* Git commit
51+
* Git push to your repository
52+
* Open a pull request against the master branch (which is default) of the RITlug copy of the repository
53+
* When your pull is merged, the site will update within a couple minutes
54+
55+
### Jekyll & Frontmatter
56+
57+
Jekyll is what builds the site.
58+
It handles rendering of Markdown and templating.
59+
_Jekyll requires that all post pages start with a valid date in the syntax `YYYY-MM-DD-(title).md`_.
60+
61+
Jekyll uses something called Frontmatter to know more information about the page.
62+
Frontmatter defines what the page looks like and metadata such as the title, author, and event details (where applicable).
63+
64+
Frontmatter should be at the top of a post and should be encased in triple-dashes (`---`).
65+
_All times are of the timezone `America_New_York`._
66+
67+
Additionally, Jekyll uses the string `<!--more-->` to define where the summary of pages end.
68+
This is used when showing post previews on the site.
69+
Optionally, the `excerpt` frontmatter can be defined instead to override this (if using an HTML page instead of Markdown in special cases, the `except` frontmatter _should be used_ instead of `<!--more-->`).
70+
Please use this functionality to keep lists of posts readable.
71+
72+
For example,
73+
```
74+
---
75+
title: Example thing
76+
layout: post
77+
---
78+
Hello RITlug!
79+
80+
This week...
81+
82+
<!--more-->
83+
84+
Other things happening.
85+
86+
- Signature
87+
```
88+
89+
If defined, the `date-start` and `date-end` frontmatter will replace the date specified in the file name in the iCal feed (where applicable).
90+
91+
More detail on frontmatter below...
92+
93+
### Announcements
94+
95+
Announcements are used to spread the word about what's happening.
96+
Posts in this category are added to an RSS Feed (at https://ritlug.com/feeds/latest.xml), which get forwarded to the IRC/Slack and Google Group.
97+
Additionally, if the page `layout` is `post-event`, the Calendar iCal feed with get the post added to it.
98+
99+
* Create a new Markdown file in `announcements/\_posts/` named with the convention `YYYY-MM-DD-wNN-your-title.md` (such as `2019-12-06-w13-final-meeting.md`)
100+
101+
Announcing an event (such as the weekly meeting):
102+
```
103+
---
104+
author: Jeffery Russell (@jrtechs)
105+
title: "Final Meeting"
106+
layout: post-event
107+
date-start: "2019-12-06 16:30"
108+
date-end: "2019-12-06 18:00"
109+
location: "GOL-2620 (Med. DB Lab)"
110+
---
111+
```
112+
113+
General Announcement:
114+
```
115+
---
116+
title: title of your announcement
117+
author: your name
118+
layout: post
119+
---
120+
```
121+
122+
### Talks
123+
124+
Talks is for slides and notes about what was presented at a meeting.
125+
Posts in this category work similarly to announcements, including that they get added to an RSS Feed (at https://ritlug.com/feeds/talks.xml), forwarded to IRC/Slack, and get added to the Calendar iCal (they do not get forwarded to the Google Group though).
126+
127+
* Create a Markdown file in `talks/\_posts/` named with the convention `YYYY-MM-DD-wNN-your-title.md` (such as `2019-03-07-w8-zfs.md`)
128+
* There is an extra line in the frontmatter called `slides` which automatically provides an embed & link for slides
129+
* This property is the filename of the talk slides
130+
* Slides should be placed in `talks/slides/`
131+
* File names should be prefixed with year and semester (such as `2015-fall-contributing-to-github-projects.pdf`)
132+
* Slides should be exported as PDF and added committed to git
133+
134+
Example frontmatter:
135+
```
136+
---
137+
title: ZFS
138+
author: Josh Bicking (@jibby0)
139+
layout: post
140+
slides: 2019-spring-w08-zfs.pdf
141+
---
142+
```
143+
144+
### Events
145+
146+
Events are written after the event (to highlight what happened at the event).
147+
Events _are_ added to the Calendar iCal, but are not added to an RSS Feed, auto-posted in IRC/Slack, nor forwarded to the Google Group.
148+
149+
* Create a Markdown file in `events/\_posts/` named with the convention `YYYY-MM-DD-wNN-your-title.md` (such as `2018-08-08-tim-flock.md`)
150+
151+
Events & Projects pages tend to use image gallery functionality.
152+
This can be done using the `images` frontmatter with an array of photos and including the `gallery`.
153+
The `images` parameter takes relative links to the RITlug site or absolute links for images hosted on other sites.
154+
155+
Example event page:
156+
```
157+
---
158+
layout: event
159+
title: President Tim Zabel at Fedora Flock 2018
160+
authors:
161+
- Tim Zabel (@Tjzabel)
162+
excerpt: RITlug President Tim Zabel presents on TigerOS & Remixes at Fedora Flock 2018 in Dresden.
163+
images:
164+
- /events/assets/2018/08/tjzabel-flock.jpg
165+
---
166+
RITlug President Tim Zabel presents on TigerOS & Remixes at Fedora Flock 2018 in Dresden.
167+
168+
{% include content-blocks/gallery.html %}
169+
170+
> (talk abstract)
171+
172+
(link to talk page on conference site)
173+
```
174+
175+
### Projects
176+
177+
Projects are about the things the club works on.
178+
They are not added to an RSS Feed, auto-posted in IRC/Slack, added to the Calendar iCal, nor forwarded to the Google Group.
179+
180+
* Create a Markdown file in `events/\_posts/` named with the convention `YYYY-MM-DD-wNN-your-title.md` (such as `2018-08-08-tim-flock.md`)
181+
* The date is because of a Jekyll requirement we need to list projects; it should be updated at least once a semester or notable update
182+
183+
Like events, projects tend to use the image gallery.
184+
185+
Many projects pages tend to use custom HTML (incline or entirely) to have a better show-off effect.
186+
If using custom HTML, the `excerpt` frontmatter should be set.
187+
If doing the page entirely in custom HTML, the `layout` should be set to `default`, which will include the RITlug navbar & footer, but not add the white page background.
188+
189+
The `author`/`authors` frontmatter should be defined.
190+
Additionally, the `permalink` property is commonly used to give a more special URL.
191+
192+
```
193+
---
194+
layout: project
195+
title: Name
196+
authors:
197+
- ...
198+
permalink: /projects/name
199+
excerpt: Cool thing we do
200+
images:
201+
- /...
202+
---
203+
(Content)
204+
205+
{% include content-blocks/gallery.html %}
206+
```
207+
208+
### Calendar & Placeholders
209+
210+
Jekyll generates an iCal calendar feed of event announcements, talks, and events (see also relevant sections above).
211+
This feed is generated at https://ritlug.com/feeds/calendar.ics
212+
213+
Here's the logic for common, notable event properties:
214+
* Titles come from the `title` frontmatter
215+
* Descriptions come from the page body; uses summaries if defined with `<!--more-->` (or `excerpt` frontmatter)
216+
* Dates:
217+
* If specified, `date-start` and `date-end` will allow manual specification of event date and time
218+
* This is useful when the announcement of an event is not the same day as the event itself
219+
* Also, this allows specifying times in addition to the date
220+
* Otherwise, the date given in the file name will be used
221+
* Locations can be (optionally) specified with the `location` frontmatter
222+
* URLs:
223+
* If redirect, gives link directly
224+
* If for post, gives post link
225+
* Otherwise, gives the "Get Involved" page
226+
227+
Note: Titles get automatically prepended with "RITlug: " because an opinionated developer of the site found it was easier to read in their calendar.
228+
This is stripped on the "Calendar" page of the site.
229+
230+
#### Placeholder Events
231+
232+
Sometimes you want to add an event to the calendar but the details haven't been decided yet.
233+
For example, all the weekly meetings of the semester have a set time and date but the topics and presenters may not be worked out yet.
234+
Well, there's a solution for this!
235+
236+
* Create a Markdown in the `meetings-meetups/_posts/` folder named with the convention `YYYY-MM-DD-your-title.md` (such as `2020-04-25-imaginerit.md`)
237+
238+
Additionally, calendar placeholders are highly encouraged to use the `redirect` layout & frontmatter to specify a link for the event.
239+
240+
For example:
241+
```
242+
---
243+
layout: redirect
244+
redirect: https://ritlug.com/get-involved
245+
date-start: "2020-04-25 16:30"
246+
date-end: "2020-04-25 18:00"
247+
location: "TBD"
248+
title: "ImagineRIT"
249+
---
250+
Help or visit RITlug at ImagineRIT!
251+
252+
Stay tuned for more info closer to the event.
253+
```
254+
255+
Placeholders can also take an `rrule` frontmatter for recurring events, written [to the iCal spec](https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html).
256+
257+
Of particular note,
258+
> The UNTIL rule part defines a DATE or DATE-TIME value that bounds the recurrence rule in an inclusive manner.
259+
> If the value specified by UNTIL is synchronized with the specified recurrence, this DATE or DATE-TIME becomes the last instance of the recurrence.
260+
> The value of the UNTIL rule part MUST have the same value type as the "DTSTART" property.
35261
36-
Please see [this runbook page](http://runbook.ritlug.com/infrastructure/website/) and [CONTRIBUTING.md](https://github.com/RITlug/ritlug.github.io/tree/master/CONTRIBUTING.md) for more info.
262+
For example:
263+
```
264+
---
265+
layout: redirect
266+
redirect: https://fossrit.github.io/
267+
date-start: "2020-01-16 17:00"
268+
date-end: "2020-01-16 19:00"
269+
location: "MSS-3190"
270+
title: "FOSS Hours"
271+
rrule: "FREQ=WEEKLY;UNTIL=20200423T190000"
272+
---
273+
Not a RITlug event, but one we think is worthwhile to share and you'll likely see some of us there
274+
```
37275

38276
## Updating meeting times / places
39277

@@ -42,4 +280,4 @@ Edit `_config.yml` and update the settings "ritlug-time", "ritlug-place", and
42280
These are used (and should be used) everywhere on the website
43281
the meeting time and place are referenced so that they can be updated in
44282
one place.
45-
Please note that this does NOT update events in the iCal feed.
283+
Please note that this does NOT update events in the iCal feed.

0 commit comments

Comments
 (0)