Skip to content

The anyhowly also got standards guide

Jump to bottom
Chen Hui Jing edited this page Apr 30, 2019 · 3 revisions

The SingaporeCSS website is hosted on GitHub, because we are an organisation with an operating budget of zero dollars. The site itself is built with Jekyll (don't judge), and makes use of Jekyll's out-of-the-box data files for most of the information management. Styles are written in .scss files and will be compiled with Gulp (^v.4).

Because we continously strive to be the most anyhowly meet-up in Singapore, the package.json file is always updated with the latest dependencies, just because. You can use npm-check-updates from your command line to do this.

For updating website with monthly recaps

If you don't really care about the architecture of the site or Jekyll in general but need to update the website with meetup recaps or something, this section will suffice. Basically, how the site is set up, the latest blog post's content will be displayed on the home page by default.

Usually, when the meetup is over, and Engineers.SG releases the videos, we will do a meetup recap. The steps are as follows, noting that Step 1 is for the next month's Talk.CSS, while Step 2 onwards covers instructions for the current month's meetup recap:

  1. Create a post for the next month's Talk.CSS, this will become the new content on the home page

    • This file should be in the /_posts folder
    • The filename is in the format YYYY-MM-DD-XX.markdown, where YYYY-MM-DD is the date you are creating the post, and XX is the meetup count
    • Copy the content of the post from the template.markdown file in the /_drafts folder and update the relevant front matter

  2. Update the speakers.yml file in the /_data folder

    • You only need to add a new entry for a speaker who has never spoken at Talk.CSS before
    • The format for a speaker entry is as follows: 
      39:
  SPEKAER_SHORTCODE: // Should match the shortcode field below
      name: "SPEAKER_NAME"  // Speaker's full name
      twitter: "SPEAKER_TWITTER_ACC"  // Speaker's twitter account, if not, GitHub also supported, otherwise just delete the field
      shortcode: "SPEAKER_SHORTCODE"  // Used as a reference key in the meetups.yml file, should match the string used 1 level up 
      bio: "SPEAKER_BIO"  // Ask speakers for it, if they don't provide, improvise and write it yourself
    • On the Speakers page, there is a count of total speakers which reads from this file. So if you change the format, check if you broke anything.

  3. Ask the speaker for their favourite headshot. If they don't provide one, feel free to Google-stalk them until you find one you like. Preferably find one of a higher resolution because you may need to do some manual cropping until you get a square headshot.

    • Generate 2 headshot files of 256x256 and 128x128 respectively. Make sure you name them to match the speaker shortcode in the speakers.yml file
    • Optimise the headshots and put them in the /assets/img/speakers folder. Consult other headshots for reference if you are confused

  4. Update the videos.yml file in the _data folder

    • The format for upcoming meetups are as follows: 
      TALK_SHORTCODE:  // Should match the shortcode field below
  title: "TALK_TITLE"  // Self explanatory
  link: "YOUTUBE_URL"  // Right-click and copy from the Youtube video
  shortcode: "TALK_SHORTCODE"  // Use the format sXX0X, where the first XX is meetup number, and the second X is the talk order, so first talk in Talk.CSS #39 is s3901
  description: "TALK_DESCRIPTION"  // Be creative, as long as it's relevant to the actual talk, it's fine

  5. Update the meetups.yml file in the _data folder

    • The format for upcoming meetups are as follows: 
      39:
  speakers:
    - ref: mystery
    - ref: mystery
      By default, choosing mystery will put the blue kittencorn as the generic placeholder for speakers, so use this when nothing is confirmed, otherwise, make sure the speaker exists in the speaker.yml file then reference using the speaker shortcode.
    • For completed meetups, the format is as follows: 
      38:
  colour:
    name: CSS_COLOUR_NAME
    hex: "#XXXXXX"
    rgba: rgba(XXX, XXX, XXX, 1)
    text: "#fff"  // only required if the colour of the month is a dark colour
  videos:
    - ref: sXX01
    - ref: sXX02
  speakers:
    - ref: SPEAKER_SHORTCODE

  6. Wipe out the existing content of the post (not the front matter), and replace with a paragraph or 2 of whatever you feel like saying about the meetup that just happened. Also, remember to remove the front matter field of novideo if Engineers.SG managed to record successfully.

  7. Create the image assets for each video. Get a Figma account, if you don't have one, and ask Hui Jing to give you access to the working file.

    • Update the title on the image, adjusting the font size and positioning to make sure everything is aligned
    • Export as JPG at 1x size and 0.5x size, you should get a file that is 860x484 and 430x242 respectively
    • Name the images according to the video shortcode, e.g. [email protected] and s3801.jpg
    • Create a folder in the /assets/img/videos folder and name it talk-XX according to the meetup count
    • Optimise the 2 exported images (via TinyPNG or whatever you want to use), then put the optimised images in the folder created in the above step

Details about the implementation

Blog posts exist in the _posts folder and are titled in numerical order. File naming convention is based on the Jekyll default, so for example, the entry for Talk.CSS #39 would look like this:

2019-04-25-39.markdown

The date is the date of creation of the post, not the actual date of the meetup. All posts contain the following front matter:

---
layout: post
title: "Talk.CSS #XX"
date: YYYY-MM-DD 19:00:00 +0800
location: VENUE_FOR_THE_MONTH
event-date: YYYY-MM-DD 19:00:00 +0800
categories: meetup
event-id: EVENT_ID_FROM_MEETUP.COM
meetup: XX
novideos: true
news: MMM YYYY
---
  • layout is a Jekyll default which determines which template your post/page is using. Use post for this value.
  • title is self-explanatory, use the meetup count for this.
  • date is the date which you created the post, can leave the time as is and just update the date value.
  • location would be the venue for the month, but if you haven't found one, can use “TBC”.
  • categories can remain unchanged perpetually.
  • event-id is the meetup.com ID generated when you create a new meetup. It's a 9-digit number, and can be found at the end of your meetup URL.
  • meetup is additional front-matter to indicate the meetup count, and will be used in other places. Number should match that of the title.
  • novideos is a boolean to indicate if there are videos for the meetup or not, can also be an indicator of whether the meetup has taken place or not, because no meetup then no videos. If there are videos and you want them displayed, just remove this line altogether
  • news also acts like a boolean, in that, if this field exists then the recap page will have a link to the HTML & CSS news of the month for that month, enter the appropriate month and year as the value. Use if HTML & CSS news was not recorded

This site is actually quite heavily templated because Hui Jing was tired of copy and pasting markup from page to page and decided it was a better idea to manage data in data files and populate that data via variables in the template files instead.

A lot of it hinges on naming files correctly to make sure they match with shortcodes and meetup counts. If you've never used Jekyll before, Hui Jing apologies for making you do occasional maintanence work on this site. If somehow Hui Jing is incapacitated and you have to take over, you can always redo the whole site in an implementation of your choice.

Jekyll supports both includes, which are read out of the /_includes folder and template files for layout, which are read out of the /_layouts folder.

The following components of the site are repeated on numerous pages and hence implemented as includes:

  • Site metadata, head.html
  • Site header, header.html
  • Site footer, footer.html
  • Newsletter sign up form, newsletter.html
  • Standard recap layout, which includes CSS colour of the month, video list, text link to HTML & CSS news if not recorded, and a Codepen option we never use, recap.html
  • Speaker info for that month's meetup, speakers.html

There are only 3 standard layouts, default, which is the structure of the site and the base markup, page for anything which is not a post, and post for each meetup's recap and info.

For additional information, kindly refer to documentation on Jekyll posts

Site overview

Title Path Accessible from Location in project
Home / Site URL, Site logo /index.html
About /about Navigation bar /_pages/about.md
Platform status /platform-status Navigation bar /_pages/platform.md
Developer voice /dev-voice Navigation bar /_pages/voice.md
Code of conduct /code-of-conduct Navigation bar /_pages/coc.md
Past meetups /archives Home page /_pages/archives.md
Speaking at Talk.CSS /speakers Past meetups /_pages/speakers.md
Meetup recaps /XX, where XX is an incremental positive integer starting from 1 Home page (latest 3), Past meetups /_posts/YYYY-MM-DD-XX.markdown

Clone this wiki locally