DEV Community: Simon

I messed up my git history: retrieving your lost commits

Simon — Sun, 23 Jan 2022 13:39:45 +0000

Photo by Elisa Ventur.

When using git commands that rewrite a branch's history, like rebase or reset, you might end up losing some commits by mistake.

But don't worry, as long as you committed your changes once, you should be able to get them back!

Indeed, a magical git command can help us: git reflog.

Git keeps a trace of all your commit in reference logs: this is, for instance, what allows you to use commands like git checkout my-branch@{two.week.ago} to checkout on your branch as it was two weeks ago.

So if you just messed up with your branch, you can do something like git checkout my-branch@{ten.minute.ago}, otherwise, it can be more accurate to look directly at the reference logs entries with the git reflog command.

Reading the reference logs

The format of the reference logs is as follows:

commit hash (branch name) handle: action: action description.

Here is an example of a git reflog output:
can be

0e60901 (HEAD -> feature-branch, main) HEAD@{0}: reset: moving to main
2b38384 HEAD@{1}: commit: feat: new feature
0e60901 (HEAD -> feature-branch, main) HEAD@{2}: checkout: moving from main to feature-branch

Here for instance we have:

HEAD@{2} - creation of a new branch named feature-branch
HEAD@{1} - add a commit with the message feat: new feature
HEAD@{0} - reset on branch main

When I have reset my branch on main, I used the --hard option, so currently the changes from my commit feat: new feature are lost.

But thanks to the reflog, I can checkout on them or directly reset my head on it with the following command:

git reset --hard HEAD@{1} # or with the commit hash: git reset --hard 2b38384

Here we go, I got back my lost commit!

Git: how can I force pull a distant repository

Simon — Fri, 21 Jan 2022 06:48:02 +0000

Photo by Vidar Nordli-Mathisen.

Sometimes you want to set the state of your local branch to its remote version but cannot do so using the git pull command because your local version and the remote one have diverged.

This can happen for several reasons.
For me, the two main ones are:

I have checked out on a colleague branch for a review, he has made some changes on it that have changed the branch history, and I want to pull this new version
I have messed up my history during a rebase with conflicts and want to start again from the remote version

In these cases, using git pull will try to merge or rebase the remote branch into your local one, which is not the behavior we are looking for.

What we want instead is to start over with the distant branch. Of course, we could naively do so by deleting our local branch before pulling the distant one, but that is a bit cumbersome if you have to do so regularly.

Thankfully, git provides a more handy way to manage this scenario with the reset --hard command.

 git reset --hard origin/my-branch

git reset is a command that took me some time to understand but is worth knowing.
If you are interested to learn more about it, I have written an article about its possibilities.

Basically, the reset command set our head to the targeted commit, here to the last commit on origin/my-branch.
Using it with the --hard option allows to discard all local changes, committed or not, and therefore force the current state to the distant one.

If you find yourself using it often, I would advise you to set an alias for it.

git config --global alias.rh '!git fetch && git reset --hard origin/$(git rev-parse --abbrev-ref HEAD)'
git rh  # rebase hard on your local repo after having fetched its last state

One last thing. When modifying your history, you might end up losing commits that you wanted to keep. Fortunately, there is a way to retrieve these commits that are no longer in your branch.

Git reset, when and how to use it

Simon — Wed, 19 Jan 2022 12:04:03 +0000

Git reset is part of the git commands that used to confuse me, as I did not understand its purpose or use-cases at first.

On top of that, it seemed to be doing very different things depending on its input, which is either a commit or a path.

But once I dug a bit deeper into each option of this command and understood the logic behind it, which eventually is about undoing staged or committed changes, it really helped me to manage my commit history or revert my mistakes, which is particularly useful for my rebase workflow.

With this article, I hope to help you clarify how this command works and how you can use it in your daily development tasks.

Git reset with a path: unstaging files

When used with a path, the reset command does the opposite of git add: it removes changes from the staging area.

NB: a new command was recently added to git, git restore, to fulfill this purpose and will probably become the advised way to perform this action.
For now, git restore is still experimental. Still, I think it should be preferred over git reset for unstaging changes, as its implementation seems more intuitive, whereas git reset should be used to update the branch's head, as we will see after.

But if you want to use the reset command for unstaging files, here are some examples:

git reset # unstage all changes
git reset file-a file-b # unstage file-a and file-b files
git reset folder-a/ # unstage all changes in the folder folder-a

I personally do not use git reset for this purpose as I don't deal much with staging my changes. I usually commit everything (I have set an alias for this purpose that I am always using), and if I need to commit partial changes, I prefer to use my IDE to do so.

Git reset with a commit: modifying the head of your branch

When used with a commit, git reset allows us to change the head of our branch. While doing so, it allows us to extract the changes between our current head and the new one, and put them in our staging area, working directory, or forget them depending on the mode used.

Let's see how the different modes work.

The soft mode 🪶

The soft mode keeps your current staging area and working tree as it is while moving your head to the specified commit. Changes between your previous head and the new one are added to the staging area.

This option provides a great way to rewrite your history in only one commit, instead of using an interactive rebase to squash your commits:

git reset --soft main
git commit -m' feat: an atomic feature'

The mixed mode 🥗

Using git reset with the mixed mode (the default mode) puts all your changes between your previous and current head, including your current staged changes, in the working directory.

This option is handy when you want to rewrite your history in several commits, for instance to create two commits from all the changes you made from your main branch:

git reset --mixed main
git commit --interactive -m' fix: a correction aside the main feature'
git commit --all -m' feat: the main feature'

The hard mode 🪨

The heavy-handed one!
It sets the index to the given commit and removes all changes between your previous and current index or in your working directory.

This option is perfect if you want to get rid of your current changes:

git reset --hard HEAD # or just git reset --hard

NB: use this command only if you know you are not interested in keeping your current changes, as you will not be able to recover them.
If you are unsure yet but want to start back from your last commit, use git stash instead to put your current changes aside.

Another interesting use-case is to reset your branch to the state of the remote one (a kind of force pull):

git reset --hard origin/my-branch

You need to be cautious when using this command as you might lose changes.
If you made a mistake, it is still possible to get your lost commits back, but not your current staged and unstaged changes.

The keep mode ✊

This mode is a bit peculiar. It is similar to the hard mode as it will drop the commits between your previous and new head. But it will carry on your unstaged changes and abort if there is any conflict between these changes and the removed commits.

This command is dedicated to doing one thing: remove commits while being safe that they won't conflict with our current unstaged changes. I don't really find myself in this kind of situation, but if that happens, I guess it is valuable to know this option.

What about the merge mode?

As explained in the documentation, reset --merge is meant to be used when resetting out of a conflicted merge.
This is a particular situation, and as I don't use merge in my workflow, I have never had the use for this command.

But do not hesitate to read the documentation if you think you might be interested.

Get a clean git history with a rebase workflow

Simon — Tue, 18 Jan 2022 18:27:06 +0000

When I started using git, I had little concern about my commit history.
I only used git as a backup tool for my work without trying to have consistent and readable commits.

That's a common pitfall with git. I have often worked in teams where we would integrate all our commit iterations into our main branch, with commit messages as descriptive as wip, ending with a hardly useful history.

Doing so strongly limits the benefits of using git.
When we choose to enforce having a clean, readable history, composed of well-defined atomic commits on a single linear branch, the advantages of doing so greatly overcome the little extra time we spend to ensure everything we integrate to our main branch is clean:

we can now easily read the history and understand what changes were made
if there are some changes we don't understand, we can read all the relevant associated changes in the same commit
if we have a problem with a deployment, we can easily revert the last commit

In this article, I will introduce the main rules to maintain a clean git history and show you how I personally apply them in my day-to-day development.

There is no right way to use git, so don't take anything as an absolute truth but rather as an inspiration to create your own workflow.

Rules for a clean history

There are only three rules to enforce a clean git history:

a commit should be atomic: it should contain all and only the changes required for a feature or a fix
a commit should have a clear, descriptive message. I also use conventional commits format, which can be helpful when working on a versioned project
a commit should be directly integrated to long-running branches, using the rebase functionality of git, to avoid merge commits.

This last one can seem surprising, as it is easy to use git without even knowing the rebase command.

What rebase does is that it "moves" your commits on top of the branch you are rebasing on.

The main drawback of using rebase is that it rewrites your branch history. Therefore it won't be consistent with your remote repository, and you will need to force push on it.

But it will allow you to have a linear commit history, whereas the merge command will create a new commit for each merge with the changes from the merged branch, resulting in a less readable history.

This workflow works well, no matter if you are alone on a personal project or working in a big team.

But if you can always deal with your mess alone, these rules will be helpful if they are enforced in a team.

Before we start, a word on git aliases

I use several times a day the commands shown in this article.
To be more efficient, I have set up aliases for most of them.
In the below examples, I will use the full command and show you as a comment the version using my aliases.

If you want to know more about them, you can go to my article explaining my git aliases for an efficient workflow.

Starting a new development

I usually start by creating a new branch from the latest main branch.

git checkout main  # git co main
git pull
git checkout -b my-branch  # git nb my-branch

NB: there are two main ways to create a new branch:

git branch my-branch will create a new branch but stay on the current one, which is useful when you want to save your current branch before altering it
git checkout -b my-branch is a checkout command with the -b option that will create the new branch before checking out on it.

At this point, we just created a new branch similar to the main one.

Working on the issue

I then start working and will usually create several commits, depending on the complexity of the development. This allows going back if I take a wrong direction, or change my mind at one point. I still usually try to break things into commits that make sense.

git commit --all -m 'feat: step 1'  # git c 'feat: step 1'
git git push --set-upstream origin/my-branch  # git p
...
git commit --all -m 'feat: stept 7'  # git c 'feat: stept 7'
git push  # git p

But at the end of the feature development, I will rewrite my history to have only one clean commit; or several if it is more appropriate (for instance, if I also fixed something while working on a feature).

To do so, I usually use an interactive rebase.

git rebase -i HEAD~7  # git ri 7

The way interactive rebase works is that it displays the list of commits, with the action you can do on it.
The main ones I use are:

pick or p: the default, keep the commit as it is
reword or r: allows you to rewrite the commit message in a next step
squash or s: integrate the commit with the previous one, you will be asked to edit the message
fixup or f: integrate the commit with the previous one while keeping its message
drop or d: remove the commit. You can also get the same result by removing the entire line

Once the history has been rewritten, I need to force push to the remote repository.

git push --force  # git fp

Rebasing your branch

Before pushing my changes for a review, I will usually rebase on the main branch so that my branch is up to date.

git fetch & git rebase origin/main  # git rom

This is needed only if new changes were integrated into the main branch.
If any conflicts were created, this is when you will be asked to solve them.

Reviewing the changes before integration

I then open a merge/pull request in gitlab/github, and almost always find corrections to make.

If the changes I want to make are important, I will create new commits, but for small corrections I usually integrate them directly to the current commit by amending it.

git commit --amend & git push --force  # git afp

When everything seems clean, I will ask for a review and will usually integrate the changes requested in a new commit so that the reviewer can quickly check them.

Eventually, before integrating this new feature to the main branch, I will regroup the commits into one again as done previously, and rebase on the main branch if necessary.

NB: For this workflow to be effective, you need to enforce rebase merging in gitlab/github.

Cleaning up

Finally, Once merged, I will delete my branch on the server (this is configured to be done automatically after merging) and on my local repository, so that these repositories stay clean.

git branch -D my-branch  # git del my-branch

I have automated the setup of all my projects thanks to tmuxp, and I always start by updating the repository and displaying its status.
That allows me to quickly see what branches I am currently working on.

git fetch && git branch -vv && git status  # git state

Wrapping up

These are the rules and the workflow I try to follow on all my projects.

I admit it requires some effort, but the time you spend making sure that your git history is clean and readable will save you a lot of time when you will need to understand why and how some changes were made.

Follow Your Website Analitycs With Umami

Simon — Sun, 17 Oct 2021 08:58:19 +0000

This article is part of a series showing you how to quickly and freely build and host your own Jekyll blog on GitHub Pages. This series will also cover more advanced topics like adding a comment system directly in our code using Staticman and adding privacy-friendly but still free analytics using Umami.

I divided the tutorial into several parts:

Now that our blog is fully functional, our main job is to write interesting articles.

But you are writing a blog and sharing it with the world, you probably want people to read it.
To do so you will have to bring traffic to your website, and will therefore need to be able to follow your it, know which article attracts the most people, on so on.

Picking a Traffic Analytics solution

When it comes to gathering traffic data from your website, you mainly have two choices of products.

The first one is to use a free solution.
Let's be honest, we are talking about Google Analytics here, which is already pre-integrated with Jekyll.
It is indeed very easy to set up but raises some confidentiality issues as its trackers are very invasive, and all the data collected eventually goes to google.

If you are concerned about collecting your user data through a company that will use them, you can go for a more privacy-focused solution, like Gauges or Simple Analytics.
These companies will also allow you to collect your visitors' data, but without exploiting them.
Most of the time, they are less privacy-invading and only collect relevant information.
They also usually don't use cookies, allowing you to avoid having to put an annoying cookie banner for European visitors to comply with GDPR policies.

The counterpart for using a solution not exploiting your visitor's data?
Well, companies need to make profits to live, so you need to pay for it.
This is totally ok and understandable, but you might not want to spend money just to know how many visitors come to your blog, which is already a generous donation of your time to the community.

Fortunately, development is an amazing world and some analytics companies have open-sourced their code.
Here, we will see how we can deploy one of them, Umami, and how to use it for our website.

Deploying Umami on Heroku

As we already did for our comment system, we will deploy Umami on Heroku. You can see how to do so here, but we will do it together anyway.

First, you need to fork the Umamy repository on GitHub.

Then, go to your Heroku account, create a new app, and under the Deploy section choose connect to Github as Deployment method, search for the repository you just forked, and connect to it.

We then need to add a database. Go to the Ressources tab, search for Heroku Postgres in the Add-ons section and install it.

Now we need to create the required tables.
Click on your new add-on (open in a new tab), then go to Settings -> View Credentials.
You will get everything you need to connect to your database. Personally, I have installed the Heroku CLI so I just run the corresponding line in my terminal.

I then copied the lines from the schema.postgresql.sql file to init the tables.
You can check everything went ok by running the \dt command.

\dt

List of relations
 Schema |   Name   | Type  |     Owner      
--------+----------+-------+----------------
 public | account  | table | ivcqpajmowwzfs
 public | event    | table | ivcqpajmowwzfs
 public | pageview | table | ivcqpajmowwzfs
 public | session  | table | ivcqpajmowwzfs
 public | website  | table | ivcqpajmowwzfs
(5 rows)

Then go back to the app page and, in the Settings -> Config Vars, add an HASH_SALT environment variable with any random string as a key.

Phew, we finally ended the configuration of our app!

You can now go to the Deploy section and click Deploy Branch in the Manual deploy part.

Once the build is over, you will be able to open the app and log into it with the username admin and the password umami.

The first thing you want to do is to change this password in Settings -> Profile -> Change password.

We now have to add our website to the application. To do so, go to Settings -> Website -> Add website

Click then on get tracking code to get the script line to add to your website head.

<!-- _includes/head.html -->
...
{%- if jekyll.environment == 'production' -%}
        <script async defer 
            data-website-id="<your-id>" 
            src="<your-src>">
        </script>
{%- endif -%}

Redeploy your website with it and visit it, then go to your Umami dashboard, you should see your first visit!

Yeah, my first visitor, myself!

Wrap up

Congrats, you have reached the end of this tutorial!

I hope it was beneficial to you and that you enjoyed it. You can find the code of this sample project here.

We covered quite a lot, from setting up and deploying your blog to its customization and the add of features like a commenting system or analytics.

A lot can still be done, and I encourage you to explore new possibilities from here.

If there is a subject you are particularly interested in, please share it in the comment section.

But in any case, don't forget that the most important on the website is the content ;).

Add A Comment System To A Jekyll Blog Using Staticman - 2 / 2

Simon — Sat, 16 Oct 2021 15:10:00 +0000

I divided the tutorial into several parts:

Introduction
Setting Up
Create Content
Customize Display
Commenting System Part 1
Commenting System Part 2 <- you are here
Analytics

In the last part, we added a functional comment system.

But there are still a lot of features that can be added, starting by allowing to respond to a comment.

Add a reply feature

To enable replying to a message, we need to know that a comment is a reply to another one.

To do so, we will add a parent_id field in our messages.
To allow it, add it to the allowedFields property in the staticman.yml file.

# staticman.yml
comments:
  allowedFields: ["name", "message", "parent_id"]
  ...

We do not add it to the requiredFields as only replies will have a parent message.

Then we need to add this field in our comment-form.html file.

<!-- _includes/comment-form.html -->
<form method="POST" action="{{ site.staticman_url }}" class="comment-form">
  <!-- options inputs -->
  ...

  <input
    name="fields[parent_id]"
    type="hidden"
    value="{{ include.parent_id }}"
  />

  <!-- user fields inputs -->
  ...
</form>

We store the parent_id field in a hidden input field using the value given by the include variable, which holds the include's inputs.

Now we will add this form below each comment with its corresponding parent id. This will be the input form used to reply to this comment.

For each comment, we will also display its replies. To do so, we will recursively include comment-list.html with the parent_id as input.

<!-- _includes/comment-list.html -->
{% assign parent_id = include.parent_id | default: '' %} 
{% assign comments = site.data.comments[page.slug] | where_exp: "item", "item.parent_id == parent_id" %} 
{% assign sorted_comments = comments | sort: 'date' %}
{% for comment in sorted_comments %}
<div class="comment">
  <h3>{{comment.name}}</h3>
  <time
    class="post-meta dt-published"
    datetime="{{ page.date | date_to_xmlschema }}"
    itemprop="datePublished"
  >
    {%- assign date_format = site.minima.date_format | default: "%b %-d, %Y" -%}
    {{ comment.date | date:"%H:%M - %b %-d, %Y, %Y" }}
  </time>
  <p>{{comment.message | strip_html | markdownify }}</p>
  <div class="comment-reply">
    <p>Reply to {{ comment.name }}:</p>
    {% include comment-form.html parent_id=comment._id %} 
    {% include comment-list.html parent_id=comment._id %}
  </div>
</div>
{% endfor %}

We now have the ability to reply each message and we display its replies under it.

Here is the result. I just added .comment-reply { padding: 15px; } in _sass/comments.scss to create a simple nested effect.

It's a start, but we definitely don't want to display all these reply boxes. They should appear only if we hit a reply button.

We will implement this feature using only HTML and CSS.

First, let's update our comment reply box.

<!-- _includes/comment-list.html -->
...
<div class="comment-reply">
  <input id="reply-{{ comment._id}}" type="checkbox" class="checkbox" />
  <label class="open" for="reply-{{ comment._id }}">
    Reply to {{ comment.name }}
  </label>
  <label class="close" for="reply-{{ comment._id }}">X</label>
  {% include comment-form.html parent_id=comment._id %} 
  {% include comment-list.html parent_id=comment._id %}
</div>
...

The display of the reply box is held by a checkbox. This one will not be displayed, but instead targeted by the two labels, reply to ... to open the reply box and X to close it.

Each label will be displayed depending on the checked property of the checkbox.

Here is the css code to make it work.

// _sass/comments.scss
...

.comment-reply {
  padding: 15px;
  padding-top: 5px;
  display: flex;
  flex-direction: column;

  .open {
    font-style: italic;
  }

  .close {
    display: none;
    align-self: flex-end;
    padding: 5px 10px;
    border: 1px solid #ddd;
  }

  .open:hover,
  .close:hover {
    cursor: pointer;
  }

  .comment-form {
    display: none;
  }

  .checkbox {
    display: none;
    &:checked ~ .open {
      display: none;
    }
    &:checked ~ .close {
      display: block;
    }
    &:checked ~ .comment-form {
      display: flex;
    }
  }
}

We now have a much cleaner reply feature!

Use a markdown editor for messages

There are still a few improvements we can make to our new functionality.
The first one is to use a markdown editor to allow your readers editing their comments in markdown easily

To do so, we will use a javascript markdown editor called SimpleMDE. This is quite an elegant solution as this library will target our textarea and replace them, which mean that our solution will still work if one of our users has javascript disabled on its browser (who does that?).

First, we need to add the link to the library and its CSS in our head file.

<!-- _includes/head.html -->
<head>
  ...

  <!-- Simple Markdown Editor -->
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.css"
  />
  <script src="https://cdn.jsdelivr.net/simplemde/latest/simplemde.min.js"></script>
</head>

Then edit the comment form HTML to add a SimpleMDE instance attached to each textarea.

<!-- _includes/comment-form.html -->
<form method="POST" action="{{ site.staticman_url }}" class="comment-form">
  ...
  <textarea
    id="message-{{ include.parent_id }}"
    class="comment-message"
    name="fields[message]"
    placeholder="Comment (markdown accepted)"
    required
  ></textarea>
  ...
</form>

<script>
  var simplemde = new SimpleMDE({
    element: document.getElementById("message-{{ include.parent_id }}"),
    forceSync: true,
    spellChecker: false,
    status: false,
    placeholder: "Comment (markdown supported)",
  });
</script>

Note that I also added a unique id to the textarea based on the parent id.

I also added some changes to the editor style.

// _sass/comments.scss
...

.CodeMirror,
.editor-toolbar {
  border-radius: 0;
}
.CodeMirror,
.CodeMirror-scroll {
  min-height: 150px;
}

And here we are!

Better management of redirect

Currently, when we send a comment, we are redirected back to the article page. This behavior can be pretty confusing. Usually, we expect to get a notification that our comment was sent. Moreover, as our website need to be rebuilt to display the comment we sent, everything looks as if nothing happened!

Let's work on improving this part.

To improve the experience, we will redirect readers to a thank-you page displaying that the comment will be readable soon.

Let's create a new page, comment-success.markdown in our root directory, that will be almost the same as index.markdown.

<!-- comment-success.markdown -->
---
layout: home
list_title: "Read Our Latest Posts"
title: ''
---

## Thank you!

Your comment was successfully sent!

It will appear on our website soon.

Now change the redirect option in _includes/comment-form.html.

<!-- _includes/comment-form.html -->
<input 
    name="options[redirect]" 
    type="hidden" 
    value="{{ 'comment-success' | absolute_url }}"
>

And that's it!

Of course, there is a lot that could still be done to improve our comment system. But that's already a good start, and we fully build it ourselves!

You can find the code for this part here.

That's quite a journey since we started setting up our blog!

In our last chapter, we will see how to implement free privacy-friendly analytics.

Add A Comment System To A Jekyll Blog Using Staticman - 1 / 2

Simon — Fri, 15 Oct 2021 06:13:32 +0000

I divided the tutorial into several parts:

Introduction
Setting Up
Create Content
Customize Display
Commenting System - Part 1 <- you are here
Commenting System - Part 2
Analytics

Now that we have our blog, let's see how to add some interactivity to it with a commenting system.

How a static website can become dynamic

Adding a commenting system to a Jekyll website is tricky as it is a static site generator, with no backend allowing us to store comments in a database and serve them.

The immediate solution to solve this issue is to use an external service with its own database. Among the popular ones, disqus is often used with Jekyll. It has the advantage of being easy to implement, as it is a script loaded on your page, but it also presents privacy issues and displays ads in its free version.

Another possible solution to add dynamic content to a GitHub website is to use staticman. On the opposite of the previous solutions using external databases, staticman creates files in your repository, updating your website statically. It is free and open-source but not as straightforward to implement as disqus.
The nice thing is that it will store all your comments in your git repository, so there is no risk of losing them.

As we are courageous, this is the solution we will implement for our website.

Deploying Staticman on Heroku

In order to use staticman, we need to deploy it on a server. This app will be used as a proxy to receive our comments and create files in our repository.

We will use Heroku to deploy our staticman instance. You might need to create an account first if you don't have one.

Hence this is done, go to the staticman GitHub repository and fork it.

On your Heroku dashboard, go to New -> Create new app, type the name that you want for your app, and hit Create app.

In the Deployment method of the Deploy tab, click on GitHub. Once connected, choose the staticman repository and hit Connect.

Once this is done, you can go to the Manual deploy section and click on Deploy Branch.

This will deploy an application to https://<app-name>.herokuapp.com/.
There should be an error displayed. It is expected as we haven't configured it yet. We will take care of it now.

The app will need to be able to access your GitHub repository. To do so, create a new application in GitHub Settings → Developer settings → GitHub Apps.

Create an app with the following inputs:

Homepage URL: https://staticman.net/
Webhook URL: https://<app-name>.herokuapp.com/v1/webhook
Repository permissions / Contents: Access: read and write
Repository permissions / Pull Requests: Access: read and write
Subscribe to events: Pull request

Once your app is created, go to General → Private keys and hit Generate a private key.

Finally, go to Install App and hit Install.

Go back to Heroku. Now it is time to configure our app.

In Settings -> Config Vars, create the following variables:

GITHUB_APP_ID: the GitHub app id displayed at the beginning of the General section
GITHUB_PRIVATE_KEY: the private key we just generated
RSA_PRIVATE_KEY: a private key that will be used to encrypt content, you can use the same as GITHUB_PRIVATE_KEY

Go back to the deploy tab and run a manual deployment again.

Once the deployment is over, you should now see a welcome message when you visit your app.

Adding Staticman to our project

We now need to add staticman to our project.
First, we will create a staticman.yml file that defines its configuration as follow.

# staticman.yml
comments:
  # (*) REQUIRED
  #
  # Names of the fields the form is allowed to submit. If a field that is
  # not here is part of the request, an error will be thrown.
  allowedFields: ["name", "message"]

  # (*) REQUIRED
  #
  # Name of the branch being used. Must match the one sent in the URL of the
  # request.
  branch: "main"

  # Text to use as the commit message or pull request title. Accepts placeholders.
  commitMessage: "Comment from {fields.name} on {options.slug}"

  # (*) REQUIRED
  #
  # Destination path (filename) for the data files. Accepts placeholders.
  filename: "entry{@timestamp}"

  # The format of the generated data files. Accepted values are "json", "yaml"
  # or "frontmatter"
  format: "yaml"

  # List of fields to be populated automatically by Staticman and included in
  # the data file. Keys are the name of the field. The value can be an object
  # with a `type` property, which configures the generated field, or any value
  # to be used directly (e.g. a string, number or array)
  generatedFields:
    date:
      type: date
      options:
        format: "timestamp-seconds"

  # Whether entries need to be approved before they are published to the main
  # branch. If set to `true`, a pull request will be created for your approval.
  # Otherwise, entries will be published to the main branch automatically.
  moderation: false

  # When allowedOrigins is defined, only requests sent from one of the listed domains will be accepted.
  allowedOrigins: ["localhost", "simondosda.github.io"]

  # (*) REQUIRED
  #
  # Destination path (directory) for the data files. Accepts placeholders.
  path: "_data/comments/{options.slug}"

  # Names of required fields. If any of these isn't in the request or is empty,
  # an error will be thrown.
  requiredFields: ["name", "message"]

You might have to change the name of the branch from which you are deploying and you will have to update the allowedOrigins value with your domain name or remove it if you don't feel like you need this security.

This post will focus on building a simple comment system where any user can enter a name and a message in markdown. We will allow them to respond to other messages as well.

Staticman allows you to check for spam automatically, send email notifications, and implement Recaptcha, but we won't cover this here.

In the _config file, add the following entry, with your own app name, github username, repo and branch.

# _config.yml
staticman_url: https://<app-name>/v3/entry/github/<username>/<repo>/<branch>/comments

Creating the input form

We will now build the form where our readers will be able to write their names and comments.

In the _includes folder, add a new comment-form.html file.

<!-- _includes/comment-form.html -->
<form method="POST" action="{{ site.staticman_url }}" class="comment-form">
  <input
    name="options[redirect]"
    type="hidden"
    value="{{ page.url | absolute_url }}"
  />
  <input name="options[slug]" type="hidden" value="{{ page.slug }}" />

  <textarea
    class="comment-message"
    name="fields[message]"
    placeholder="Comment (markdown accepted)"
    required
  ></textarea>
  <div class="comment-bottom">
    <input
      class="comment-name"
      name="fields[name]"
      type="text"
      placeholder="Name"
      required
    />
    <button class="comment-submit" type="submit">SEND</button>
  </div>
</form>

What we just did is that we set up a form that will send data to the staticman_url.

As we defined in our staticman.yml config file, our comments are based on 2 fields:

name: the name of the sender, defined by <input name="fields[name]" required>
message: the content of the comment, define by <textarea name="fields[message]" required></textarea>

We also provide two options when we validate the form, defined by hidden inputs:

redirect: the URL to be redirected to once the submit call will complete. Here we come back to our page
slug: the slug of the page that will be used to create the comment folder, as we defined our path as "_data/comments/{options.slug}" in the staticman.yml configuration file

Displaying the list of comments

Comments sent to our repository will be stored in the _data/comments/<slug> directory.
The way to access them in Jekyll is with the variable site.data.comments[page.slug].

Let's create a comment-list.html file in our _includes folder to display them.

<!-- _includes/comment-list.html -->
{% assign comments = site.data.comments[page.slug] | where_exp: "item", "true" %} 
{% assign sorted_comments = comments | sort: 'date' %} 
{% for comment in sorted_comments %}
<div class="comment">
  <h3>{{comment.name}}</h3>
  <time
    class="post-meta dt-published"
    datetime="{{ page.date | date_to_xmlschema }}"
    itemprop="datePublished"
  >
    {%- assign date_format = site.minima.date_format | default: "%b %-d, %Y" -%}
    {{ comment.date | date:"%H:%M - %b %-d, %Y, %Y" }}
  </time>
  <p>{{comment.message | strip_html | markdownify }}</p>
</div>
{% endfor %}

What we do here is looping over the page comments sorted by date. The first line with the where_expression filter is required to get the comment values.

For each comment, we display the name, date and message with the strip_html filter to secure the message and the markdownify filter to render markdown.

Adding the comments block

We now have everything we need for our simple commenting feature.

Let's add another file in our _include folder named comments.html that will wrap together our two comments snippets: posting a new comment and displaying received comments.

<!-- _includes/comments.html -->
<section class="comments">
  {% if site.data.comments[page.slug] %}
  <div>
    <h2>Comments</h2>
    {% include comment-list.html %}
  </div>
  {% endif %}

  <div>
    <h2>Leave a Comment</h2>
    {% include comment-form.html %}
  </div>
</section>

Now we can update our _layout/post.html file to display these comments instead of the disqus comments.

<!-- _layout/post.html -->
...
<div class="post-content e-content" itemprop="articleBody">{{ content }}</div>

{% include comments.html %}

<a class="u-url" href="{{ page.url | relative_url }}" hidden></a>
...

Style our comments

Before pushing our brand-new feature, let's add some style to our comments.

As it is a separate feature, the best option is probably to create its own CSS file. Let's create a new comments.scss in the sass file and add the import line @import "comments"; in assets/main.scss.

// _sass/comments.scss
.comment {
  padding-top: 10px;
  h3 {
    display: inline;
    color: royalblue;
  }
  p {
    margin: 0;
  }
}

.comment-new {
  margin-top: 25px;
}

.comment-form {
  display: flex;
  flex-direction: column;
  margin-top: 25px;

  .comment-message,
  .comment-name {
    font-size: 16px;
    padding: 15px;
    border: 1px solid #ddd;
    margin: 0;
  }

  .comment-message {
    min-height: 150px;
    resize: none;
  }

  .comment-bottom {
    display: flex;
  }

  .comment-name {
    flex: 1;
  }

  .comment-submit {
    width: 200px;
    border: 1px solid #ddd;
    color: royalblue;
    font-weight: bold;

    &:hover {
      cursor: pointer;
    }
  }
}

We can now go ahead and deploy our comment system.

When you send a comment, it should open a merge request that will be automatically validated if you set moderation: false in the staticman configuration file.

Our comment system is now functional!

You can find the code for this part here.

This comment system is still very basic, our next step will be to add some features like allowing to reply to a comment or adding a markdown editor.

Customize Your Jekyll Website

Simon — Thu, 14 Oct 2021 06:09:24 +0000

I divided the tutorial into several parts:

Now that we have started adding content to our website, let's see how we can customize its appearance.

How Jekyll generates pages

One of the reasons I like Jekyll is that it provides you a very clean directory as it hides most of the magic behind the website creation.
However, the drawback is that it is easy to feel lost and not to know how to update your theme when it comes to customizing it.

Indeed, layouts are defined by your theme and are not present in your local folder.

So before doing anything, we need to look at our minima theme repository. Please make sure you look at the branch of your current version.
In my case, it is the 2.5 one that is installed (you can have this info in the Gemfile file), so I am looking at the 2.5-stable branch.

Our blog structure mainly relies on two folders:

_layouts: contains the layouts which are used in the Front Matter metadata of each markdown file.
_includes: contains snippets of HTML code that are used in layouts.

For instance, if we look at the code of the post layout, we see the following (shortened for comprehension).

<!-- _layouts/post.html -->
---
layout: default
---
<article
  class="post h-entry"
  itemscope
  itemtype="http://schema.org/BlogPosting"
>
  <header class="post-header">
    <h1 class="post-title p-name" itemprop="name headline">
      {{ page.title | escape }}
    </h1>
    ...
  </header>

  <div class="post-content e-content" itemprop="articleBody">{{ content }}</div>
  ...
</article>

There is a lot to comment on here.

The first thing we see is that the blog layout uses the default layout.
The way layout nesting works is that everything that you have below your Front Matter will be injected in the {{ content }} variable of its parent layout.

For instance when you write a blog post using this layout, its content is injected in the <div class="post-content e-content" itemprop="articleBody">{{ content }}</div> block.

We can also see the use of Front Matter metadata with the title of the post.
The title is displayed using the page variable, which contains all the variables defined in the Front Matter of a template.

These variables can be overridden by the children of the template. In this case, there is no title defined in the Front Matter of our template, it only makes sense for posts using this template.

Now, if we look at the default layout, this is what we see.

<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: 'en' }}">
  {% include head.html %}

  <body>
    {% include header.html %}

    <main class="page-content" aria-label="Content">
      <div class="wrapper">{{ content }}</div>
    </main>

    {% include footer.html %}
  </body>
</html>

The default layout represents the base structure of all our pages.
Besides the content variable where the child layout is injected, it uses several include to inject HTML code.

Let's now dive into them and start customizing our blog by adding a favicon.

Adding a favicon

Let's start gently by adding a favicon to our website. If you are familiar with HTML, you know that the favicon is defined in the head tag. For this theme, it is the _includes/head.html file that contains this tag.

You can override any file of your theme by putting it in your own project.
In this case, we can create our own _includes/head.html, copy the code from GitHub and modify it to add our favicon.

For my favicon, I generated one using a lion emoji for the sake of the exercise.

<!-- _includes/head.html -->
<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  {% seo %}
  <link rel="stylesheet" href="{{ '/assets/main.css' | relative_url }}" />
  {% feed_meta %} 
  {% if jekyll.environment == 'production' and site.google_analytics %} 
    {% include google-analytics.html %} 
  {% endif %}

  <link
    rel="apple-touch-icon"
    sizes="180x180"
    href="{{ '/apple-touch-icon.png' | relative_url }}"
  />
  <link
    rel="icon"
    type="image/png"
    sizes="32x32"
    href="{{ '/favicon-32x32.png' | relative_url }}"
  />
  <link
    rel="icon"
    type="image/png"
    sizes="16x16"
    href="{{ '/favicon-16x16.png' | relative_url }}"
  />
</head>

Modifying the header

The same way we overrode our head.html fille, we can override any file to customize your website as we want.

For instance, let's modify our header by adding our new logo.

To do so we need to add and modify the _includes/header.html file.

<!-- _includes/header.html --> 
<header class="site-header" role="banner">
  <div class="wrapper">
    {% assign default_paths = site.pages | map: "path" %} 
    {% assign page_paths = site.header_pages | default: default_paths %}
    <a class="site-title" rel="author" href="{{ '/' | relative_url }}">
      <img src="{{ 'favicon-32x32.png' | relative_url }}" />
      {{ site.title | escape }}
    </a>
    ...
  </div>
</header>

Customizing our CSS

There are several ways to modify our CSS. As you can see in the head.html file, CSS is currently pulled from assets/main.css.
In the development file, it is actually a scss file that is built from the _sass directory.

An option to customize our css is to copy/paste the _sass directory and edit its files, the same we did for the head file.

Another possibility is to generate a new file that will be loaded after the theme css, so that the rules we put in it will override the default ones. This is the solution I will show you now.

First, let's create the assets/main.scss file with the following code.

// assets/main.scss
--------
--------

@import "minima";
@import "custom";

Compared to the default file, I just added an import of the file custom. We can now create this file in the _sass folder and add some css.

// _sass/custom.scss
.site-title {
  color: orangered;
  &:visited {
    color: orangered;
  }
}

Here I modify the site title color to match our lion. My main point is to show you how you can do it, it is up to you to decide how you want to style your website.

Adding a featured image to our posts

Something you will see in almost every blog is a featured image displayed in the blog list and at the top of an article.

Unfortunately, this is not currently managed by Jekyll, so let's implement this feature ourselves.

This time we want to modify the blog layout directly. We can create our own version in _layouts/post.html.

What we are going to do is to check for a featured_image variable, and if it exists, we will display it on top of our title by adding the following snippet.

{% if page.featured_image %}
<div class="featured-image">
  <img src="{{ '/assets/' | append: page.featured_image | relative_url }}" />
</div>
{% endif %}

Let's add a featured image to our last post. Put the image you want in your assets folder and add its name in the post metadata.

--------
layout: post
title: "Write a Post"
date: 2021-06-31
categories: jekyll blogging
featured_image: featured-image.jpg
--------

We can then add some CSS to our custom.scss file to style it.

// _sass/custom.scss
... 
.featured-image {
  margin-bottom: 50px;

  img {
    width: 100%;
    max-height: 250px;
    object-fit: cover;
  }
}

Here is the result.

Updating the home to display the featured image

Let's improve our home page.

First, copy the home.html in the _layout folder. Following the same principle as for the post layout, we can add our featured images.

<!-- _layout/home.html -->
-------- 
layout: default 
--------

<div class="home">
  {% if page.title %}
    <h1 class="page-heading">{{ page.title }}</h1>
  {% endif %} 
  {{ content }} 
  {% if site.posts.size > 0 %}
    <h2 class="post-list-heading">
      {{ page.list_title | default: "Posts" }}
    </h2>
    <ul class="post-list">
      {% for post in site.posts %}
      <li>
        <div>
          {% assign date_format = site.minima.date_format 
            | default: "%b %-d, %Y" %}
          <span class="post-meta">
            {{ post.date | date: date_format }}
          </span>
          <h3>
            <a class="post-link" href="{{ post.url | relative_url }}">
              {{ post.title | escape }}
            </a>
          </h3>
          {% if site.show_excerpts %} 
            {{ post.excerpt }} {% endif %}
        </div>
        {% if post.featured_image %}
        <div class="featured-image">
          <img
            src="{{ '/assets/' | append: post.featured_image | relative_url }}"
          />
        </div>
        {% endif %}
      </li>
      {% endfor %}
    </ul>

    <p class="rss-subscribe">
      subscribe <a href="{{ '/feed.xml' | relative_url }}">via RSS</a>
    </p>
  {% endif %}
</div>

And update our custom.scss file.

// _sass/custom.scss
... .post-list > li {
  display: flex;
  flex-wrap: wrap-reverse;

  div:first-child {
    flex: 4 0 200px;
  }
  .featured-image {
    flex: 1 0 200px;
    margin-bottom: 0;
  }
}

Here you are, you now have all the basics to create your personal blog at your own image.

You can find the code for this part here.

Our next step is now to add a commenting system to our blog.

Create Blog Posts And Static Pages With Jekyll and GitHub Pages

Simon — Wed, 13 Oct 2021 05:19:36 +0000

I divided the tutorial into several parts:

Now that we have initialized our project, let's see how to manage our content by:

updating our home page to add some information before the list of blog posts
adding a static page showcasing our best GitHub projects
adding a new post to our brand new blog

Updating our home page

Our blog already has three pages:

index.markdown: the home page of our site
about.markdown: an about page that we can access from the header
_post/yyyy-mm-dd-welcome-to-jekyll.markdown: an example of a blog post

The beauty of Jekyll is that all pages are build using markdown, which is more readable than HTML and easy to reuse elsewhere.

For instance, I often start writing my posts using Notion and then export them in markdown. And a lot of blogging platforms, like dev.to or hashnode, use this language for their post editor.

Jekyll also creates the navigation of the website automatically, whether you are adding a static page or a blog post.

The home page, which corresponds to the index.markdown file, displays the list of blog posts by default. If you look at its content, you will see that this file is almost empty. Indeed, all the logic behind the display of the blog posts list is hidden in the home layout.

We can update the file to custom our home page, for instance, by changing the title above the list of posts using the property list_title.

Moreover, we can add a welcome message on top of our page. We just need to add some content to the file, and it will be automatically placed above the post list.

Finally, I also added the property title: '' as a trick to avoid Jekyll using the first heading of my content as title and putting it in the header.

Here is the updated code of the file.

<!-- index.markdown -->
---
layout: home
list_title: "Read Our Latest Posts"
title: ''
---

# Github Pages Demo Blog

Welcome to this demo blog!

This website intends to show you how to easily build and
deploy a portfolio with a blog using _GitHub Pages_ and _Jekyll_.

You can find the sources of this project
[here](https://github.com/SimonDosda/gp-blog).

Adding a static page that showcases our best GitHub repositories

Let's add another static page to our project. If you see this website as your portfolio, something interesting to add is a showcase of your public GitHub repositories.

To do so, create a new file projects.markdown in the root folder.

The first thing to do is filling up the Front Matter metadata (the part in between dashes).

In our case, we indicate for the page a title and permalink of projects.

--------
layout: page
title: Projects
permalink: /projects/
--------

GitHub Pages allows you to easily loop on your public repositories, as they are accessible from the variable site.github.public_repositories. Jekyll uses Liquid templating language to manage variables and statements. It allows us to loop over our repositories.

To filter on my most interesting repositories, I only display repositories that are not forked and contain topics. Feel free to use the conditions that suit you the best.

I then display the repository name, description, list of topics, and last update date. The title also links to the repository URL.

Here is the code and the result.

{% for repo in site.github.public_repositories %}

{% if repo.fork == false and repo.topics.size > 0 %}

## [{{ repo.name }}]({{ repo.html_url }})

{{ repo.description }}

Topics: {{ repo.topics | array_to_sentence_string }}

Last updated: {{ repo.updated_at | date_to_string }}

{% endif %}

{% endfor %}

Notice that the Projects link was added automatically to the navigation bar.

Adding a blog post

Our blog already contains a welcome blog post created by Jekyll when we initialized the project.

Let's add another one to see the main functionalities you will probably use in your posts: titles, code, and images.

As the welcome post states, creating a new post requires creating a new file with the template yyyy-mm-dd-title.markdown.

Let's create a new blog post explaining furthermore how to write one. Go ahead and create a file 2021-06-01-write-a-post.markdown in the _posts folder.



```
--------
layout: post
title: "Write a Post"
date: 2021-06-31
categories: jekyll blogging
--------

The goal of this article is to add some extra info
about blog writing with _Jekyll_.

## Structure your posts

Use level 2 (`##`) and if necessary level 3 (`###`) titles
to structure your posts.

## Display code snippets

You can display a block of code like the following using triple backticks.
You can also specify the language after the first triple backticks.

```

python
def hello(name):
    return f'hello {name}'


```

## Add images

Create an `assets` folder where you can put all your images,
then display them with a link starting with an exclamative mark like this:
`![my inspiring image]({{ "/assets/sample-image.jpg" | relative_url }})`.

![my inspiring image]({{ "/assets/sample-image.jpg" | relative_url }})
_Photo by [Ian Schneider](https://unsplash.com/@goian)_
```

The first things provided are the Front Matter metadata. Only layout: post and title are mandatory, but you can also add the date, categories, author, and so on. You can see more details here.

We then have our article written in markdown, where I display a few extra tips.

Below is the corresponding result.

You now know the basics of content management for your blog.

You can find the code for this part here.

Our next step is now to customize the appearance of our website.

Setup Your Free Portfolio With A Blog Using GitHub Pages

Simon — Tue, 12 Oct 2021 06:27:04 +0000

I divided the tutorial into several parts:

Now, let's see how we can set up and deploy our website.

Create your GitHub Pages repository

To deploy your website using GitHub Pages, you need to create a new public repository using the following convention for the name: <username>.github.io.

Once you have done this, the content of your repository will be deployed on https://<username>.github.io. You can try adding an index.html file at the root of your repository with "Hello World" or anything you fancy written in it to check everything works as expected.

Note that you can deploy a website from any repository, but in this case, the associated URL will be https://<username>.github.io/<repository-name>. This feature is very convenient to deploy documentation of your projects, for instance.

For this tutorial, I will use a specific repository called gp-blog (for Github Pages Blog), which will therefore deploy at https://simondosda.github.io/gp-blog, but you most probably want to deploy your portfolio at the root folder.

Now that our git repository is ready, let's see how to set up Jekyll in it.

Create your Jekyll static website

Jekyll is a Ruby Gem, so make sure you have all the prerequisites installed to use it. You can find their list and the procedure to install them on your OS at https://jekyllrb.com/docs/installation/.

Once you have done this, install Jekyll and Bundler gems.

gem install jekyll bundler

We can now initialize our Jekyll project in the repository we just created with the following command.

jekyll new .

Then, open the Gemfile file and follow the instruction to deploy on GitHub Pages by commenting the gem "jekyll" line and uncommenting the gem "github-pages" one.

# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
# gem "jekyll", "~> 4.2.0"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", "~> 214", group: :jekyll_plugins

For the version (here 214), you can find the latest version here.

You can then type the command bundle update to install your dependencies and serve your website locally with the command bundle exec jekyll serve --livereload.

Your new blog is now served on localhost:4000. As you can see, it needs some customization.

Edit the global configuration

We can now start customizing our new blog. The first thing to do is to update the _config.yml file. There you can edit your blog title, its description, your email address, and GitHub username.

You can also enter your Twitter username or comment the corresponding line if you don't have any.

You can also add the property show_excerpts: true to display posts' excerpts on the home page.

More anecdotical, you can change the permalink generation for pages with the permalink attribute. I like to use a less nested structure like the following.

permalink: /:collection/:year-:month-:day-:title:output_ext

Even though we use the --livereload option, it will not consider changes done in the _config.yml file. You need to kill your server and relaunch it, and you should see your changes appear in your browser.

If everything is ok, you can commit your changes and push them.

Note that you can edit the branch which deploys your website on your GitHub repository in Settings → Pages → Source.

Here we are. We now have our blog backbone up and running!

You can find the code for this part here.

Our next step is now to add some content to our website.

Build A Portfolio With A Blog Using GitHub Pages

Simon — Mon, 11 Oct 2021 06:28:55 +0000

This series of articles will show you how to quickly and freely deploy a personal portfolio website with a blog.

At the end of this tutorial, you will know how to build and host your own Jekyll blog on GitHub Pages, how to create new pages or blog posts, and how to customize them.

We will also cover more advanced topics like adding a comment system directly in our code using Staticman and integrating free privacy-friendly analytics using Umami.

I divided this tutorial into several parts:

Foreword

When I started this blog, one piece of advice made a lot of sense for a developer wanting to start a blog: Even though you are a developer, don’t lose your time building your blog, focus on writing content and publish it on any blogging platform.

I am totally in agreement with this advice. It is too easy for us to spend a lot of time creating a blog from scratch, missing the main point: a blog is about what you have to say. Spending your time to develop your blog is just disguised procrastination.

But the “create your own blog” team had a point though: creating your blog allows you to own your content.

I eventually went for a trade-off between these two approaches: setting my own blog very quickly using GitHub Pages while republishing my content on dev.to, which allows me to reach a broader audience.

After deploying my blog on GitHub Pages, I realized it was also a perfect solution to host a portfolio. GitHub is a natural place to showcase your work as a developer, and this will be a big plus for recruiters or clients if you are a freelancer.

So even if the blogging part does not appeal to you, you still might be interested in following this tutorial.

Why Github Pages?

There are many solutions to create your blog or portfolio, and I am far from trying them all.
Using Github Pages is not the perfect solution, but it has some noticeable pros for developers.

First, you are probably already quite familiar with the use of Git and GitHub. The fact that all your content will be in a Git folder is lovely and provides versioning for your articles and pages.

It also makes sense to have a website link to your GitHub account where you centralize all your development-related content: blog articles, portfolio, side projects, and so on. You can see this as your personal showcase.

And last but not least, deploying and hosting your website on GitHub Pages is really easy and totally free!

How will it work?

In this tutorial, we will use a static site generator named Jekyll. Jekyll is the framework used by GitHub to power GitHub Pages, which gives us the significant advantage of having GitHub building our pages without needing to do anything.

Jekyll builds HTML pages from markdown documents, which is excellent as this is the standard used by many blogging platforms and tools. Once you add an article in a markdown format, pushing it to your deployment branch will update your website.

What are the cons?

There is no perfect solution to build a website, and it is essential to know the limitation of your stack when choosing it.

As a static site generator, Jekyll will build all pages of our website at deployment. This is nice as it provides a fast navigation experience, compared to a website using a back-end for which pages would be build when the user navigates the website.

But it also means that our pages will not be dynamic, with no interactivity with a database. Of course, you can still add some interactivity using javascript and AJAX calls to a service, but it means you will need a separated back-end for this.

Hosting a Jekyll website on GitHub Pages is probably the easiest way, but it also comes with a significant drawback: the limited list of plugins that you can use. You can find the (small) list of available plugins here.

Ready to start?

Now that we have covered what we will achieve in this tutorial, it is time to start the work and set up our project.

Getting The Type Of An Interface Property In Typescript

Simon — Thu, 17 Jun 2021 09:25:37 +0000

Problem

The problem is quite simple, but its solution is not obvious.

Imagine that we are working on a Typescript project, and we have defined an interface with several fields using different types.
Let's take as an example a simple interface representing a blog post.

interface BlogPost {
  title: string;
  content: string;
  publishDate: Date | null;
  isDraft: boolean;
}

Let's say now that we would like to provide a simple setter that will allow us to update a blog post while running some custom logic. For instance, let's consider that our setter will allow updating a post only if it is a draft.

In Typescript, we would write something like this.

function updatePost(post: BlogPost, property: keyof BlogPost, value): boolean {
  if (!post.isDraft) {
    return false;
  }
  post[property] = value; // error: Type 'any' is not assignable to type 'never'.
  return true;
}

While the types of post and property are easy to define, the one for value is a bit more tricky, as it will depend on the property to update.

Currently, Typescript considers it as any as we don't provide any type hint, which gives us the error Type 'any' is not assignable to type 'never'. when we try to update our property. But even if we put the error aside, we are losing the type checking capability of Typescript here.

What we would like to do is to set the type of value to the type of the corresponding property from BlogPost. Let's see now how we can implement that.

Solution

In Typescript, we can access the value of the property of an interface using brackets.

For instance, the following code works perfectly.

function updateDate(post: BlogPost, value: BlogPost["publishDate"]): boolean {
  if (!post.isDraft) {
    return false;
  }
  post.publishDate = value;
  return true;
}

updateDate(post, 42);
// error: Argument of type '42' is not assignable to parameter of type 'Date | null'.

updateDate(post, new Date());

In our case, we want a generic function that will work with any given property of our interface.

To do so, we need to use a type variable for the property.

function updatePost<BlogPostKey extends keyof BlogPost>(
  post: BlogPost,
  property: BlogPostKey,
  value: BlogPost[BlogPostKey]
): boolean {
  if (!post.isDraft) {
    return false;
  }
  post[property] = value;
  return true;
}

const post: BlogPost = {
  title: "my post",
  content: "my awesome content",
  publishDate: null,
  isDraft: true,
};

updatePost(post, "publishedDate", null);
// error: Argument of type '"publishedDate"' is not assignable to parameter of type 'keyof BlogPost'.

updatePost(post, "publishDate", 42);
// error: Argument of type '42' is not assignable to parameter of type 'Date | null'.

updatePost(post, "publishDate", new Date());
// ok

Adding the type variable BlogPostKey for the property type allows us to use it for the value type while still ensuring that the property is a key of BlogPost using extends keyof BlogPost.

I hope that trick can be helpful to you!