Verdis Blog

The Main Site: https://www.verdisgov.org

Verdis, officially the Free Republic of Verdis is a sovereign state located between Croatia and Serbia along the Danube river. This blog serves as a place for official government communications.

How to Create Posts:

It's pretty simple, you just create a Markdown file with the format YYYY-MM-DD-Title.md in the _posts folder. Each file must be started with the following structure:

---
title: Insert Title
excerpt: Insert Excerpt
author: Insert Author
---
{% include header.html %}

To include images or gifs, just upload the file to the static folder. This is where all of files will be hosted and can be accessed within the Markdown. The following line can be used:

![Name]({{ site.baseurl }}{% link static/filename %})

An example of which would be:

![Cat]({{ site.baseurl }}{% link static/cat.gif %})

This is done through the use of Jekyll's built-in tag system, which is useful but not exactly flexible. For more control, you can render HTML directly in the Markdown file, which works, but is just not ideal. Below is an example of the same cat gif from above, just bigger with HTML:

<img alt="Cat" src="https://raw.githubusercontent.com/garv-shah/nova-blog/main/static/cat.gif" width="500"/>

Maths:

Jekyll supports rendering maths with Latex. For more information on the syntax, you can visit https://en.wikibooks.org/wiki/LaTeX/Mathematics, with https://quicklatex.com allowing for some quick rendering since GitHub's built-in Markdown does not.

How it Works:

Essentially, the main website is just an RSS Reader, which loads the feed.xml generated by Jekyll (from https://the-nova-system.github.io/blog/feed.xml). This then grabs the headers (title, excerpt and author) and creates a text box with the makeBlogPost() function that gets pushed into the main page. This is all done through the loadFeed.js file :D
Everything should be automatically updated after uploading a post

Summary of Jekyll

Jekyll is essentially a renderer that makes writing blogs much much easier. It lets you put in a Markdown file and produces a full html website.
Markdown is a lightweight markup language, and in essence, it's very similar to writing a Word document, as most of it is just text, with a bit of syntax to tell the renderer what stuff is (https://www.markdownguide.org is a great resource to learn more about Markdown)
As mentioned above, Jekyll goes slightly beyond the scope of Markdown, allowing for the rendering of Liquid and Textile out of the box, with support for other markup languages like LaTeX as well.

At build time, Jekyll compiles all the files above and creates a few new directories. GitHub Pages (the host for this project) supports Jekyll natively, so above, you don't see the actual directory that is served to the user but rather a precompiled version. As an example of this, the "feed.xml" file mentioned above is nowhere to be found in the repo above, and is instead created by Jekyll on build.
This being said, the website you see above isn't structured exactly like any Jekyll site, as in the actual "home page" doesn't use Jekyll at all. Rather, the page you see is an RSS reader. Technically it's creating an Atom feed, but RSS and Atom feeds are similar enough to the point that I use the terms interchangeably. Same thing.
This grabs the RSS feed that Jekyll has generated and serves up its own website. The advantage of this is that the home-page is much more "website like" and customisable, with the theming options evident, while still making the blogs very easy to publish. At the same time, it also presents the disadvantage of the whole codebase not being unified. This is why the theming for the two look different as I can't be bothered creating a whole new Jekyll theme.
Finally, when you click on the "Read More", it just redirects you to the pages that Jekyll did generate, which are the blog posts.

Build Locally

To be honest, it doesn't exactly matter if you create a post and push it directly to the main branch here, since you can always change it. Building locally is mostly useful for quick testing purposes, or debugging (GitHub doesn't give the best error results)
The below instructions are for a Mac, I'm not currently using a Windows device for development, and the people that this explanation is for don't need it. You need admin permissions too.

To start, first clone the GitHub repo from above. It's recommended to use an app such as GitHub Desktop, since the command line can be a bit daunting at first. Just install the app from here (https://desktop.github.com) and log in. You should see an option to clone a repository, and you can either paste the https link in or select it if it's there.
Time for the terminal! This repo uses Bundler to manage all the dependencies. For this, you'll first need to install Ruby. You probably already have it installed. If ruby -v returns anything besides the command ruby not being found, skip the next step, as you already have it. If not, use Homebrew, and type in sudo brew install ruby.
Now to install Bundler. Just type in :

sudo gem install bundler

Type in your password if required. Now navigate to the repository you cloned before using the cd command. If you used the default for GitHub Desktop, the command should be:

cd ~/Documents/GitHub/nova-blog/

Now run these two commands.

sudo bundle config set --local path 'vendor/bundle'
sudo bundle install

If all went well, it should have installed all the gem dependencies, and you should be good to go. Just run bundle exec jekyll serve and it should start hosting the site at http://127.0.0.1:4000/. Yay!