If you have experience creating websites or blog using Jekyll then the below steps should be familiar to you. You will still benefit from a refresher, so please read or skim and note of the changes since the last time you’ve worked with Jekyll or contributed to our Tech Blog.

Markdown Language

If you use Github via a browser, updated a README.md of a repository, responded to a PR request for changes with some formatting, and used Visual Studio or VS Code to write some documentation then most likely you are already using Markdown.

In case you have not done any of the above, start at https://www.markdownguide.org/getting-started/ or https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax to learn the syntax.

Setting up Ruby & Jekyll on MacOS

Ruby via Homebrew, a Non-System Ruby

While MacOS comes preinstalled with Ruby, we advice using the homebrew installed version, you will find tutorials and other documentation refer to this is “system Ruby”. Install rbenv via homebrew instead using the command below.

brew install rbenv ruby-build

The above will install Ruby and prepare your environment for the next steps. As engineers, we work with projects with various requirments, it is important to isolate each project requirements into project

Gem Management

RubyGems is a package management for things we need in Ruby. It (gem) comes preinstalled with homebrew Ruby. If you already have Ruby installed prior to this setup guide, your setup may benefit from an upgraded gem

gem update

This will update your local RubyGems setup. We need this to setup another tool we use.

Bundler, Consistent Environment

With a Gemfile file in a project tree, contributors will be able to setup a local copy of the system having Bundle handle the consistency of the environment.

Bundler or bundle is a RubyGem, hence, we need to install it with the command below.

gem install bundler

Visit Bundler if you want to learn more about the value that it adds into the chain.

Jekyll, Static Site Generator

We are using a static site generator built on Ruby and using the markup language - a notation to annotate a document’s content to give information regarding the structure of the text or instructions for how it is to be displayed, specifically Markdown.

Install Jekyll.

gem install jekyll

This will install the latest copy of Jekyll into your MacOS.

Setup a Working Copy

1. Clone the Tech Blog Repository

git clone https://github.com/FullSpeedInc/fst-tech-blog

Change into the directory you clone the Tech Blog.

We have not completely switched the default branch to the latest redesign of our Tech Blog. It is important to switch to the correct branch before proceeding.

git switch redesign

1. Prepare Local Environment.

The above setup steps only installed the necessary tools to setup your local environment based on the project setup.

Ensure that you are in the correct branch by executing: git branch, you should an asterisk beside the branch you are in. Similar to below:

  master
* redesign

This step will utilize the Gemfile of the working copy to install the gems using bundle

bundle install

Sometimes environment differences will cause setup issues. Differences like architecture and existing versions of gems or tool chain. One quick way to address this in this particular scenario is to remove Gemfile.lock if this file exists in your working copy and run bundle install again.

There will be deprecation messages. Unless it completely stops you from being able to run bundle install completely and successfully after the above instruction, it should be ok.

1. Test Working Copy

To ensure you have a working copy that is working, run:

bundle exec jekyll serve --host=0.0.0.0

The above command will serve convert the markdown documents under _posts and serve it locally through port 4000 if you don’t have anything running on port 4000, otherwise, read carefully your terminal on which I.P. and Port the static pages are being served.

You will notice that we are specifying a host of 0.0.0.0 in our development copy. This is to ensure that assets that it needs are properly loaded in the browser. When running at localhost, some assets will not load and will cause contributors to perceive items to be a bug or might report a missing asset, it is not a bug or missing. It has something to do with the paths used in the CSS framework we leveraged. Having it at 0.0.0.0 will load those assets correctly.

Visit http://0.0.0.0:{PORT} or the exact URL displayed in your terminal.

Contributing

Author File

In your working copy, you should be able to see a directory _authors, it contains meta information about contributors or authors like below.

---
short_name: {Should be same with filename without extension}
title: {Full name, all lowercase with spaces replaced with "-"}
name: {Full name with spaces}
role:
 previous:
    title: {Official Role Title, not Project Role Designation}
    year: {Year the role ended}
    description: {See description under current role. Not used but good to preserve the information you previously added.}
 current:
    title: {Official Role, not Project Role Designation} 
    year: {Year the role started}
    description: {One line. It can be a very long line. No new line.}
layout: author
---

You can put any other markdown or html here but note that the maximum width you can add here is only around 280px.

Replace the text encapsulated with curly braces, including the curly braces with the correct information about you.

Above is a template and sample for the latest author file. You can view the rolavides.md author file under _authors to view how it should be formatted. Author file serve as a way to establish your ownership, accountability, and create a collection of articles in our Tech Blog. For the example author file in this paragraph and with a tested working copy, you may visit http://0.0.0.0:{PORT}/authors/rolavides.html to view how it will appear as static site. Several important information in the markdown frontmatter is used in other ways not covered or discussed in this document.

Frontmatter are the data contained within the pair of --- in the sample above. Frontmatter is YAML. Each markdown document in a Jekyll site should have a frontmatter that gives and tells Jekyll information above that particular markdown.

New Contributor

If you are a new contributor, please create an author file with your correct information and according to the sample above.

Existing Contributor

If you have contributed article in the past, please update your author file with your latest and better information.

Contribute an Article

File Naming Format

The filename of your article should follow the following format:

1. The first 10 character should indicate the date the article was written or completed in ISO 8061 Date format. That is YYYY-MM-DD
2. A minus symbol (-) separator between the date portion and the title.\
3. The article title all in lowercase with spaces replaced with the minus symbol (-)

Tip: Rename the file after writing the article or before a git add or git commit

Article Frontmatter

---
layout: post
title: "{Your Article Title Goes Here}"
author: {your author file shortname}
last_modified: {ISO 8601 Date & Time}
thumbnail: /assets/images/{image filename}
categories:
- {category1}
tags:
- {tag1}
- {tag 2}
---

Article Guidelines

Below are important items to note in the article you will be contributing

• Following the file naming convention above, create the file under _posts directory.
• The article markdown should have a frontmatter similar to the sample above. Encode the correct and appropriate data in the frontmatter.
• As much as possible, use markdown in formatting the articles including images and links.
• Always have an introduction paragraph. A short description of what your article is about or what problem you are trying to solve. This introduction article serves as the description when displaying your article in the article cards in our homepage and paginated areas among others. You can use very long paragraph as introduction but make sure to include or use <!--more--> to delineate where you want the system to cut-off the introduction.
• Do not add a header (H1, H2, …, H6) for your introduction paragraph. Or do not use #, ##, etc. before the introduction paragraph.
• Always use headers to properly organize what you are trying to convery to a reader. The headers after the introduction paragraph serves as reference for generating a table of contents. This greatly aids readability of your article. Readability is very important, very much like software engineering.
• Asset files should always reside under assets directory or a subdirectory of it. Where appropriate. If in doubt where to store an asset, get in touch with a vice department manager.
• When referencing assets, make sure the links to your asset does not start with ../. If it does, it’s a tell tale sign that you are running your local development copy under the wrong setup. Revisit the setup instructions above.
• Do not submit Chat GPT generated articles. You may reference Chat GPT generated ones but rephrase and validate that the information you provided is accurate, true, and valid at the time of writing. We accept correction commits and Pull Requests.
• Do not use frontmatter YAML not mentioned in the sample above even when you see them in the markdown documents under _posts. They will be adjusted soon to match the redesigned content and structure.
• Do not submit potentially copyright infringing articles. Tech Blog maintainers will review your article.