DEV Community: Adrien Joly

Things We Wish We Knew When We Started

Adrien Joly — Sun, 20 Mar 2022 14:39:50 +0000

Hi! Our names are Adrien, Benjamin, Fabien, Florent, Johan, Laurent and Rainer. We have been working in the software industry for several years. We share a growth mindset and always enjoy taking a step back to retrospect on what we've learned.

During SoCraTes France 2022, we decided to put together a few words of advice to our younger selves. Tips we wish we were given when we started in the profession. We hope that they will be helpful to newcomers of our industry.

Write Tests

Writing code that does what we intend is hard. So we regularly test these intended behaviors. As code evolves, new bugs will appear, and old bugs may re-appear. Writing automated tests helps us find bugs before they impact the users of our software.

Automated tests give us trust in our code, and a feeling of safety when we change that code. Seeing automated tests pass is addictively satisfying. Automated tests make our lives better. We love getting continuously better at writing them.

Working on legacy code convinces us of the importance of automated tests. They help us understand and improve code for the long run, and reduce the risk of causing bugs while doing so.

Test-driven development (TDD) helps us develop our skills, by encouraging us to write higher quality code.

Code With Your Teammates

Code is rarely meant to be read and changed by just one person. We write code that our current and future colleagues can understand easily.

Preferences are personal. There is no winner in the "tabs versus spaces" debate. Using both makes a codebase look bad. Consistency makes code look the most clean and professional.

We discuss preferences with the team. Agree on common guidelines, then stick to them. If your preference is not agreed upon, remind yourself that this is not about you. Also, remind yourself that your preferences will evolve.

When we feel stuck by a technical problem, it's most likely a people problem. We don't jump to conclusions. We don't jump to solutions. We explain our problem to the team, ask for their help, then find a solution together.

Pair programming is not a waste of time. It helps find better solutions to problems, faster. Pair programming is an opportunity to learn and grow. It makes us converge to design decisions, instead of having to defend our choices after implementing them.

Ensemble programming (a.k.a. mob programming) is pair programming at scale. With more brains involved, we find more adequate solutions. By programming all together regularly, we won't have to document or repeat ourselves as much.

Learn, Chat, Share

Loving to code motivates us to practice and learn. Building software with a team helps us have a bigger impact. Confronting our ideas, opinions and experiences to other developers helps us develop our craft.

At local "meetup" communities, conferences and un-conferences (like SoCraTes), we learn about new practices. We share our experiences. We make new friends. These discoveries help us orient and improve our career. Friends sometimes become team-mates.

We learn about the history of computer science to better understand why things are the way they are. We learn about fundamentals to avoid reinventing the wheel. We discuss principles and methodologies to feel wherever and whenever it's appropriate to not follow them. We play with different languages to discover new mental models that may become handy someday.

We ask our peers to recommend good books to read. We form skills and opinions by practicing what we discover. We help other developers grow by sharing our learnings with them. It's never too early to start sharing. And there are various ways to do so.

Improve the Collaboration Progressively

Building software is not a sprint, it's a marathon. Our goal as developers is to solve problems by writing code. After some time, that code may become the source of new problems. We are mindful of the consequences of our choices. We inform our colleagues of the implied costs and risks, so we can adjust the strategy if necessary.

Deadlines are artificial. If we feel we can deliver a requested feature on time, we go for it. Otherwise, we negociate the deadline. Or propose alternatives. Understanding the objective or constraints behind a deadline usually helps.

We collaborate well with our squad. Contemplate how features are brought to life, from ideation to production. Understand how our contribution fits in the production cycle. Get to know our collaborators, stakeholders and the users of our software.

Whenever something is missing to do our part well, we ask. Whenever we are not sure to understand what is being built, for whom, or why, we ask. Whenever we are not sure about something, we are not afraid to say "I don't know".

We are not afraid to fail. Retrospectively talk about failure (without blaming) is how we learn and improve. We just strive to not commit the same mistake twice.

When leading a team, it can be tempting to point out several problems about the codebase, the processes and/or the team that made it. Bringing change is difficult and takes time. We don't change too many things at the same time. Instead, we start with the most critical or impactful change, then proceed with the next. We pick our battles.

Design Slowly

Software grows quickly. While growing, its complexity also grows. We strive to keep complexity to a minimum, by properly understanding and modeling the domain of application of the software. Domain-Driven Design (DDD) is one way to remain connected to users and stakeholders, and to keep the corresponding complexity in check.

We don't let technical details impact the domain logic. We design our code in a way to make it easy to replace external dependencies: databases, caches and 3rd-party APIs, without impact on our domain logic.

Performance is not always a priority. Unless needed otherwise, we prefer code legibility and separation of concerns. We design services that can scale independently rather than optimize code prematurely.

When we are considering a solution to a problem, we discuss its pros and cons. We keep a trace of our decisions in Architecture Decision Records, to help our future colleagues understand what compromises we agreed to make, and why.

You Are In Control

We are not servants to our employers, clients or managers. We negociate each job or mission opportunity towards a win-win partnership. Salary is just one among many variables to discuss. There are many others: opportunities to learn, to discover an interesting business domain, to try out a new role, to work with exceptional colleagues, to find the right work-balance, etc...

Sleep is not a luxury. Our job requires a healthy brain. To be productive and creative, our brain needs a lot of time to rest.

Health is not a commodity. We take care of our physical and mental health. If work ever compromises it, we seek medical assistance and take measures to resolve the situation as soon as possible. No job is worth sacrificing our health, sanity or dignity.

When a colleague seems to loose control, we propose assistance. We don't tolerate harrassment or abuse of any kind. We stand together against it.

That's all, folks!

Take great care of yourself, and of your community. Take the time to figure out what you love doing most, and why. Be proud to stand by your values. Strive to bring and sustain a positive impact for your collaborators, stakeholders, users, without ever compromising on quality, honesty and humility.

Authors:

Laurent Bossavit, Technical Advisor at CodeWorks
Fabien Giannesini, Software Crafter at SHODO
Benjamin Hugot, Software Crafter at SHODO
Adrien Joly, Software Crafter at SHODO
Johan Martinsson, Tech Coach
Florent Pellet, Software Crafter
Rainer Standke, DevOps Engineer at DB Systel

Let's turn an Openwhyd playlist into a static Jekyll site

Adrien Joly — Sun, 22 Jul 2018 16:12:39 +0000

Today I'm giving a coding challenge to myself:
Make my openwhyd.org profile playable from a pure client-side HTML page (i.e. without API/back-end server), using Jekyll.

Why?

Openwhyd is a platform on which music lovers collect songs that they've found online, on Youtube, Soundcloud, Bandcamp and several other streaming platforms. It allows them to make cross-source playlists, to play them from their laptop or iPhone, and to share their discoveries with other music lovers who subscribed to them.

Behind the scenes, Openwhyd is a web application powered by Node.js and MongoDB. This means that we have to pay our hosting provider a monthly bill to keep it running on a server. (FYI, this costs $15/month)

So far, we have been lucky enough to be sponsored by DigitalOcean: they gave us 1 year of free hosting! But this gift will not last forever, we will soon have to ask users again for donations, in order to pay the hosting bills. Which is not a fun thing to do, for us, nor for our users. (see our OpenCollective page)

This situation got me thinking: would it be possible to keep using Openwhyd without having to pay for hosting?

As I'm a big fan of GitHub Pages, the first solution that came to mind was to get rid of the back-end part of Openwhyd. Turning it into a pure client-side web app (a.k.a. static web app), in which the database would be replaced by data files rendered with Jekyll.

Of course, it would be very complicated to cover all the features of Openwhyd without using a back-end. (e.g. adding tracks to playlists from the web UI, and fetching the stream of latest tracks from users you subscribed to)

But I figured that just being able to play your own playlists would be a good compromise between utility for users and technical complexity to make it work.

If I get this to work, it would allow some Openwhyd users to still be able to play the tracks that they spent years collecting, even if our back-end were to go offline some day.

Design of the technical solution

Here's what currently happens when a user wants to play tracks from their profile, or any of their playlists:

They open a browser tab to the corresponding URL; (e.g. https://openwhyd.org/adrien)
The back-end fetches the 20 latest tracks of that playlist and renders a HTML page containing that list of tracks;
The user's browser displays the page and loads a bunch of JavaScript files, notably WhydPlayer.js that is responsible to making any listed track playable;
When the user clicks on one of the tracks, WhydPlayer.js extracts the source of that track (stored in the DOM node corresponding to that track) and streams it from there;
When reaching the end of the track being currently played back, WhydPlayer.js plays the following track; (still by extracting data from the DOM)
When reaching the last track of the page, WhydPlayer.js asks the back-end for the next page of tracks and appends them to the list.

Based on this (simplified) flow, we can notice that the back-end is only solicited on steps 2 and 6: to fetch and render tracks from the playlists. The rest is done by WhydPlayer.js and other client-side logic.

Step 2 could easily be done on a static web hosting provider like GitHub Pages: we would just have to store the user's playlists as HTML pages. The WhydPlayer.js would still work from it, as long as the DOM structure contains all the data that it needs to stream the music of each track.

Step 6 could be worked around: if HTML pages contain the full list of tracks, there would be no need to fetch pages of next tracks!

Now, let's propose an action plan:

Clone Openwhyd's repository, and get rid of its back-end files;
Create a HTML page that holds one track, and make it playable with WhydPlayer.js;
Download the track listing of an Openwhyd profile (or playlist);
Turn the HTML page into a Jekyll template that will render the track list;
Patch the UI, so that the user can navigate between their profile and playlist pages.

Constraint: I'm going to do my best to apply as few alterations as I can to Openwhyd's codebase (including its file structure), in order to these steps reproducible on its future versions too.

Note: I'm writing this article while following these steps.

Step 1. Clone (and clean) Openwhyd's repository

Let's head to Openwhyd's official open source repository: github.com/openwhyd/openwhyd.

From there, git noobs will be happy to download it as a zip file, thanks to the "Clone and download" button. The pros will use the command line:

$ git clone https://github.com/openwhyd/openwhyd.git
$ cd openwhyd

You'll see several folders and files in the resulting openwhyd directory. Let's get rid of everything that is not relevant for our static version of Openwhyd:

$ rm Dockerfile
$ rm docker-compose.yml
$ rm -r scripts
$ rm -r whydMisc
$ rm -r whydJS/test
$ rm -r whydJS/config
$ rm -r whydJS/screenshots
$ rm -r whydJS/app/controllers
$ rm -r whydJS/app/data
$ rm -r whydJS/app/emails
$ rm -r whydJS/app/lib
$ rm -r whydJS/app/models
$ rm -r whydJS/app/workers
$ rm -r whydJS/app/views
$ rm whydJS/app/*.*

# delete all files from whydJS/, except package.json
$ find whydJS/* -type f -maxdepth 0 | egrep -v "package\.json" | xargs rm

# delete all folders from public/, except a few ones
$ find whydJS/public/* -maxdepth 0 | egrep -v "css|fonts|html|images|js|swf" | xargs rm -r

# delete all folders from images/
$ find whydJS/public/images/* -type d -maxdepth 0 | xargs rm -r

# delete all files from public/css, except a few ones
$ find whydJS/public/css/* -maxdepth 0 | egrep -v "[^-]common|userPlaylistV2|userProfileV2" | xargs rm

# delete public/html/*, except a few ones
$ find whydJS/public/html/* -maxdepth 0 | egrep -v "channel|\bYoutubePlayerIframe" | xargs rm -r

# delete public/js/*, except a few ones
$ find whydJS/public/js/* -maxdepth 0 | egrep -v "autoresize|\bjquery|mustache|playem|soundmanager|swfobject|ui|whyd\.js|Player\.js" | xargs rm -r

# delete whydJS/app/templates/*, except a few ones
$ find whydJS/app/templates/* -maxdepth 0 | egrep -v "feed\.html|mainTemplate|posts\.html|userPlaylistV2\.html|userProfileV2\.html|whydPlayer" | xargs rm -r

# let's see the tree of remaining folders
$ ls -R | grep ":$" | sed -e 's/:$//' -e 's/[^-][^\/]*\//--/g' -e 's/^/   /' -e 's/-/|/'
   |-docs
   |---img
   |-whydJS
   |---app
   |-----templates
   |---public
   |-----css
   |-----fonts
   |-----html
   |-----images
   |-----js
   |-----swf

Ok, now we have much fewer files to distract us from our mission!

Step 2. Create a HTML page with a playable track

Let's try a naive move: save a playlist page from openwhyd.org to a HTML file and see if we can play a track from it.

For that, I'm gonna open my profile page on Google Chrome, and press Cmd-S to save it as a "Simple HTML file":

Of course, if I try to open that download file in my browser, it looks completely broken and it's impossible to play tracks from it. That is because all the references to JavaScript, CSS and image files are broken.

Extract from the resulting HTML file:

    <title>Adrien Joly's tracks - Openwhyd</title>
    <link href="/css/common.css?1.1.1" rel="stylesheet" type="text/css" />
    <link href="/css/browse.css?1.1.1" rel="stylesheet" type="text/css" />
    <link href="/css/tipsy.css?1.1.1" rel="stylesheet" type="text/css" />
    <link href="/css/userProfileV2.css?1.1.1" rel="stylesheet" type="text/css" />
    <link href="/css/userPlaylistV2.css?1.1.1" rel="stylesheet" type="text/css" />
    <link href="/css/dlgEditProfileCover.css?1.1.1" rel="stylesheet" type="text/css" />
    <script src="/js/jquery-1.10.2.min.js"></script>
    <script src="/js/jquery-migrate-1.2.1.js"></script>
    <script type="text/javascript" src="/js/jquery.history.js"></script>
    <script src="/js/soundmanager2-nodebug-jsmin.js"></script>

As you can see, that page uses absolute paths to all its assets. So we're gonna have to setup a web server locally that will give access to these resources from these paths.

In order to respect that file structure, it would make sense to move the HTML file in the whydJS/public/ folder. That way, we can consider that is folder is gonna be the root of our web server, making both our HTML file and the asset subfolders accessible through it.

So I'm running the following commands:

# (assuming that you are still in the openwhyd folder we created earlier)
$ cd ./whydJS/public
$ move ~/Downloads/my-openwhyd-profile-playlist.html 
$ python -m SimpleHTTPServer # to start python's http server
Serving HTTP on 0.0.0.0 port 8000 ...

Now, let's open http://0.0.0.0:8000/my-openwhyd-profile-playlist.html in Google Chrome:

As you can see, some elements of the UI still look broken, but the layout is working and you may even be able to play some of the tracks by clicking on them!

...Except Youtube tracks, because Openwhyd's Youtube player was patched to play tracks through another domain name. In our case, we don't want this behaviour, so let's make the patch script think that we're running locally (even if we're not):

# let's force `var isLocal = true;`, in whydJS/public/js/playem-youtube-iframe-patch.js
$ sed -i -e "s/var isLocal = /var isLocal = true; /" ./whydJS/public/js/playem-youtube-iframe-patch.js

This should make it work better, after refreshing the page!

3. Store the track listing into a data file

So far, we have a static HTML page in which the tracks are hard-coded. As we will want to turn that page into a template that will be able to render any playlist, let's download a playlist in raw format, without the HTML rendering.

Fortunately, Openwhyd makes it easy to download a raw track list in JSON format, from any page. We just have to add the ?format=json suffix to the URL of that page.

In my case, I want the track list of my profile, so I am going to download the JSON content of https://openwhyd.org/adrien?format=json and save it to openwhyd/whydJS/public/_data/tracks.json.

The contents of the file should look like this:

[{"_id":"5b4b6b81314fcb64d074e462","uId":"4d94501d1f78ac091dbc9b4d","uNm":"Adrien Joly","text":"","pl":{"name":"classical & epic","id":1},"name":"Max Richter - November","eId":"/yt/2Bb0k9HgQxc","ctx":"bk","img":"https://i.ytimg.com/vi/2Bb0k9HgQxc/default.jpg","src":{"id":"https://totoromoon.wordpress.com/2018/07/13/max-richter-november-sarajevo/","name":"MAX RICHTER November &amp; Sarajevo | totoromoon"},"nbP":8,"nbR":1,"lov":[]},{"_id":"5b34c9731db44a36a795f96a","uId":"4d94501d1f78ac091dbc9b4d","uNm":"Adrien Joly","text":"","pl":{"name":"epic coding session soundtrack","id":53},"name":"alexanderbrandon - sunrise on vanaar","eId":"/bc/alexanderbrandon/sunrise-on-vanaar#https://t4.bcbits.com/stream/6b5b84ad5900cbb22b532a778f63701d/mp3-128/3200645745?p=0&ts=1530272235&t=01ec41132994dcb46b2a5f5c213a53c39cddb5dc&token=1530272235_39982de236fdfd2e66cf14379f8ba69b44f02f51","ctx":"bk","img":"//s0.bcbits.com/img/bclogo.png","src":{"id":"https://alexanderbrandon.bandcamp.com/album/aven-colony-original-game-soundtrack","name":"▶︎ Aven Colony (Original Game Soundtrack) | Alexander Brandon"},"lov":[]},{"_id":"5b326e261db44a36a795f844","uId":"4d94501d1f78ac091dbc9b4d","uNm":"Adrien Joly","text":"smiling band from cuba, fantastic female drummer !","pl":{"name":"Jazz meets World","id":61},"name":"Yissy García & Bandancha: NPR Music Tiny Desk Concert","eId":"/yt/Y1Kv_sFZHqI","ctx":"bk","img":"https://i.ytimg.com/vi/Y1Kv_sFZHqI/default.jpg","src":{"id":"https://www.youtube.com/watch?v=Y1Kv_sFZHqI&feature=youtu.beq","name":"Yissy García &amp; Bandancha: NPR Music Tiny Desk Concert - YouTube"},"nbP":9,"lov":[]},{"_id":"5b2e34f51db44a36a795f4ff","uId":"4d94501d1f78ac091dbc9b4d","uNm":"Adrien Joly","text":"","pl":{"id":2,"name":"rock","collabId":null},"name":"KADAVAR - Come Back Life (OFFICIAL MUSIC VIDEO)","eId":"/yt/4xgi91s7zf8","img":"https://i.ytimg.com/vi/4xgi91s7zf8/0.jpg","repost":{"pId":"520de33ae4d15ab75a0030f5","uId":"51e92a777e91c862b2af478a","uNm":"Thomas Radioyes"},"lov":[],"nbR":0,"nbP":6},{"_id":"5b2b72c11db44a36a795f361","uId":"4d94501d1f78ac091dbc9b4d","uNm":"Adrien Joly","text":"chiptune","pl":{"name":"epic coding session soundtrack","id":53},"name":"Ujico*/Snail's House - Hello [Ordinary Songs
[...]

Feel free to reformat this JSON file using JSON Pretty Print, or to convert it to YAML using json2yaml.com if you want, but this is not required for the Jekyll template to work.

Note: if you don't remember your Openwhyd username, you can also use the URL https://openwhyd.org/me?format=json.

4. Turn the HTML page into a Jekyll template

In step 2, we had made Openwhyd's player work on the list of tracks that were dumped in a static HTML file. Now, let's turn this HTML file into a template, so that the list of tracks can be loaded from our JSON file. (like we had done in my previous tutorial: How to maintain a collection of music albums online, using Jekyll and Github Pages)

Basically, what we want to do is to delete the elements that represent tracks from our HTML file, and replace them by a Jekyll template.

In Openwhyd, tracks are displayed using <div> elements with the post classname:

# (assuming that you are in the openwhyd/whydJS/public, where your HTML file is)
$ grep '<div class="post' *.html

                <div class="posts">
<div class="post " data-pid="5b546297314fcb64d074e8d3"
<div class="post " data-pid="5b4b6b81314fcb64d074e462"
<div class="post " data-pid="5b34c9731db44a36a795f96a"
[...]

First, using our favorite code editor, let's cut and paste all these <div> elements into a separate HTML file (e.g. posts.html), so that we can use this HTML code as an example when we'll write our Jekyll template.

After doing this operation, your playlist's HTML file should contain a <div class="posts"> element that just contains the  comment. That's where we are now going to add our Jekyll template.

In order to make it easier to build that template, let's copy the code of one of the posts that we moved out of our HTML file, except its child nodes that have the classes ago, stats, btns and ext, back under the <div class="posts"> element.

After re-formating the HTML, it should look like this:

<div class="posts">

  <!-- TRACKS TAB CONTENT -->

  <div class="post "
        data-pid="5b546297314fcb64d074e8d3"
        data-initialpid="5b540c4d314fcb64d074e891" 
        data-time="1532256919000" >

    <div class="playBar"></div>

    <a class="thumb"
        href="//youtube.com/watch?v=u8rVPIV-Y4Y"
        target="_blank"
        data-eid="/yt/u8rVPIV-Y4Y"
        onclick="return playTrack(this);"
        style="background-image:url('https://i.ytimg.com/vi/u8rVPIV-Y4Y/default.jpg');">
      <img src="https://i.ytimg.com/vi/u8rVPIV-Y4Y/default.jpg">
      <div class="play"></div>
    </a>

    <h2>
      <a href="/c/5b546297314fcb64d074e8d3"
          class="no-ajaxy"
          onclick="toggleComments('5b546297314fcb64d074e8d3');return false;">
          Paraphon Tree - Firefly (Official Music Video)</a>
    </h2>

    <p class="author">
      <span style="background-image:url('/img/u/4d94501d1f78ac091dbc9b4d');"></span>
      <a href="/u/4d94501d1f78ac091dbc9b4d">Adrien Joly</a> added this track
      to <a href="/u/4d94501d1f78ac091dbc9b4d/playlist/12">post-rock / progressive</a>
      via <a href="/u/544c39c3e04b7b4fca803438">Stefanos Mavrogenis</a>
    </p>
  </div>

</div>

Now, let's turn this sample post into a Jekyll template that can be used to render any track.

In order to do that, we replace all the hard-coded values by mustache placeholders that contain the path of that value in any track from our tracks.json file.

For example, I replace the following HTML code:

<a href="/u/4d94501d1f78ac091dbc9b4d">Adrien Joly</a> added this track
to <a href="/u/4d94501d1f78ac091dbc9b4d/playlist/12">post-rock / progressive</a>

... by this template code:

<a href="/profile">{{ track.uNm }}</a> added this track
to <a href="/playlist-{{ track.pl.id }}">{{ track.pl.name }}</a>

It should end up like this:

<div class="posts">

  <!-- TRACKS TAB CONTENT -->

  {% for track in site.data.tracks %}
  <div class="post"
        data-pid="{{ track._id }}"
        data-initialpid="{{ track.repost.pId }}">

    <div class="playBar"></div>

    <a class="thumb"
        href="#"
        data-eid="{{ track.eId }}"
        onclick="return playTrack(this);"
        style="background-image:url('{{ track.img }}');">
      <img src="{{ track.img }}">
      <div class="play"></div>
    </a>

    <h2>
      <a href="#">{{ track.name }}</a>
    </h2>

    <p class="author">
      <span style="background-image:url('{{ user.img }}');"></span>
      <a href="/profile">{{ track.uNm }}</a> added this track
      to <a href="/playlist-{{ track.pl.id }}">{{ track.pl.name }}</a>
      via <a href="https://openwhyd.org/u/{{ track.repost.uId }}">{{ track.repost.uNm  }}</a>
    </p>
  </div>
  {% endfor %}

</div>

In order to test the rendering of this template, the python -m SimpleHTTPServer that we ran above will not help. So let's stop it (press Ctrl-C) and use Jekyll instead.

Here is how I set Jekyll up from my openwhyd/whydJS/public/ folder:

# let's make sure we have ruby installed
$ ruby -v
ruby 2.3.7p456 (2018-03-28 revision 63024) [x86_64-darwin15]

# let's install jekyll in openwhyd/whydJS/public/
$ bundle init
$ bundle install --path vendor/bundle
$ bundle add jekyll
$ bundle install

# this command installs jekyll in ./vendor/bundle => let's git-ignore it (optional)
$ echo /whydJS/public/vendor >>../../.gitignore
$ echo /whydJS/public/_site >>../../.gitignore

When it's fully set up, we can run the Jekyll server by typing this command:

$ bundle exec jekyll serve
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Let's open http://127.0.0.1:4000/my-openwhyd-profile-playlist.html.

The good news is that our page is properly served by Jekyll. The bad news is that our template failed to render. It looks like Jekyll did not interpret the template from the HTML file.

I looked up online to see what's Jekyll process (and criteria) to render templates, and found this:

Jekyll looks for files with front matter tags (the two sets of dashed lines --- like those in index.md) and processes the files (populating site variables, rendering any Liquid, and converting Markdown to HTML).

(source: Convert an HTML site to Jekyll | Jekyll)

So let's add two sets of dashed lines at the very top of our HTML file:

---
---
<!DOCTYPE html>
<html lang="en">
[...]

Normally, the jekyll serve command should have detected this modification, and the track list should be rendered correctly from the JSON file, when opening/refreshing http://127.0.0.1:4000/my-openwhyd-profile-playlist.html in your web browser!

Great job!

Next steps

I'm now done with my objective of the day: we turned an Openwhyd profile into a static Jekyll site. The list of tracks was downloaded in JSON format and used by Jekyll to render it into HTML, following the template that we wrote.

The next step will be to fix the navigation, so that visitors of the static version of my Openwhyd profile can also browse my playlists, following the same principle.

In order to do that, I intend to use Jekyll collections.

Until I get back to writing the sequel to this article, let me know in the comments if you have alternative ideas on how to make this work!

Make your Static Site Searchable with Jekyll-Algolia

Adrien Joly — Tue, 17 Jul 2018 15:34:26 +0000

About two weeks ago, I published a tutorial called "How to maintain a collection of music albums online, using Jekyll and Github Pages".

By the end of that tutorial, we were able to generate a 100% static, 100% freely-hosted and well-looking website out of a YAML list of albums, thanks to a Jekyll template. It looked like this:

We saw that maintaining that collection of albums was quite easy and convenient: we just have to edit the _data/albums.yaml, which is in an almost plain-text format.

You can find the source code what we produced in that github repository: github.com/adrienjoly/jekyll-tutorial.

Now that we're able to edit a list and render it in HTML, let's make our collection of albums searchable!

Note: Written for experienced developers and beginners alike, this tutorial also covers the parts that unexpectedly went wrong. My intention is to also share my problem-solving process, so that beginners can learn how to solve their own problems, down the road. Thanks for your understanding! 🤓

Proposed solution

After joining Algolia, I discovered that one of my colleagues had released a plug-in to make Jekyll sites searchable: Jekyll-Algolia. (License: MIT)

So, yeah, I'm definitely biased on this one, but I'm gonna go ahead and try it!

Step 1. Integrate the plug-in

Ok, let's start with the prerequisites mentioned in the README file: "the plugin requires at least Jekyll 3.6.0 and Ruby 2.3.0".

$ jekyll -v
jekyll 3.6.2

$ ruby -v
ruby 2.1.4p265 (2014-10-27 revision 48166) [x86_64-darwin14.0]
# ❌ Oops... Let's upgrade ruby!

$ curl -sSL https://get.rvm.io | bash -s stable

# ⚡️ Let's restart the terminal, as suggested by https://stackoverflow.com/a/38194139/592254

$ rvm install 2.3
# (Ended up compiling from its source code, maybe because I'm still on El Capitan?)

$ ruby -v
ruby 2.3.7p456 (2018-03-28 revision 63024) [x86_64-darwin15]
# ✅ We're good to go!

$ rvm use 2.3 --default

Now, let's install the plug-in into our codebase: "add the jekyll-algolia gem to your Gemfile, in the :jekyll_plugins section"

✋ Blocker: I don't have a Gemfile yet!

So, let's follow the corresponding steps suggested by GitHub's tutorial: Setting up your GitHub Pages site locally with Jekyll, first.

I end up with a Gemfile at the root directory of my project, with the following contents:

# Gemfile

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins

group :jekyll_plugins do
  gem 'jekyll-algolia', '~> 1.0'
end

Back to Jekyll-Algolia's instructions: "download all dependencies with bundle install".

$ bundle install

Step 2. Set up the search index

Let's follow the Basic Configuration section of the instructions.

I already have an account on algolia.com, so I'm gonna use that one. You may need to create one for yourself.

Our next step is to create an "application", there. As our codebase will remain open source, we can safely pick the "Community" plan, free of charge.

I'm calling my application "album-shelf", because that's the name of the website on which I want to add search.

After picking a region (EU WEST, in my case), let's head to the "API Keys" tab. Copy and paste your Application ID to the a new _config.yml at the root of your project, like this:

# _config.yml

algolia:
  application_id: 'paste_your_application_id_here'

Also copy the Admin API Key, necessary to run the plug-in, like this:

$ ALGOLIA_API_KEY='paste_your_admin_api_key_here' bundle exec jekyll algolia
[✗ Error] No index name defined

Note: your Admin API Key can be used to read, update and delete your Algolia application => make sure you keep it for yourself only! (i.e. to store it to your public GitHub repository 😅)

Oops, looks like I need to add the name of my search index in the _config.yml file:

# _config.yml

algolia:
  application_id: 'paste_your_application_id_here'
  index_name: 'albums'

I've picked the name "albums", because that's what I want visitors to be able to search for, on my website. Type any name that you like, there!

Let's try to run the plug-in again:

$ ALGOLIA_API_KEY='paste_your_admin_api_key_here' bundle exec jekyll algolia
[✗ Error] No records found

Make sure you did not exclude too many files from indexing using the
`files_to_exclude` option. You are currently excluding the following files:
    index.html, index.markdown, index.mkdown, index.mkdn, index.mkd, index.md

Damn it!

Ok, let's remove any possible exclusions, by completing the _config.yml like this:

# _config.yml

algolia:
  application_id: 'paste_your_application_id_here'
  index_name: 'albums'
  files_to_exclude: []

... and try to run again:

$ ALGOLIA_API_KEY='paste_your_admin_api_key_here' bundle exec jekyll algolia
Configuration file: /Users/adrienjoly/Dev/adrienjoly/jekyll-tutorial/_config.yml
Processing site...
Rendering to HTML (100%) |======================================================================|
Extracting records (100%) |=====================================================================|
Updating settings of index albums
Getting list of existing records
Updating records in index albums...
Records to delete: 0
Records to add: 4
✔ Indexing complete

It worked! 🙌

Let's see how our search index looks, back in our Algolia dashboard:

The good news is that the dashboard displays "Blood sugar sex magik", which is one of the albums listed on my website!

The bad news is that it contains 4 records, whereas my collection currently contains 2 albums. Something wrong must have happened during the indexing process... 🤔

Thanks to an error message I had got previously when trying to run bundle exec jekyll algolia (and that I did not include completely above, for simplicity), I discovered that it was possible to specify what HTML elements should be indexed: the nodes_to_index property.

So let's tell Jekyll-Algolia to index our article elements (as specified in the Jekyll template we had written during the previous tutorial), by updating our _config.yml file:

# _config.yml

algolia:
  application_id: 'paste_your_application_id_here'
  index_name: 'albums'
  files_to_exclude: []
  nodes_to_index: 'article'

After running the bundle exec jekyll algolia command again and refreshing the Algolia dashboard, we now have 2 albums in our search index! ✊

Quick test before moving on: let's search for one of my albums, from Algolia's dashboard:

✅ Working as expected!

Step 3. Integrate the search bar

It's very cool to have a search index automatically populated from our website! But it's quite useless before we display a search bar on it. And this new step is beyond the scope of Jekyll-Algolia: we now need to use one of Algolia's search clients into our website.

(3.1) Import `instantsearch.js`

Let's head to the "Build Search UI" section of Algolia's Documentation website. We are gonna use the easiest and most versatile UI integration: InstantSearch.js.

As advised in the Getting started instructions, let's import the CDN-based stylesheets and script into our index.md file:

<link rel="stylesheet" href="index.css" />

## Albums

{% for album in site.data.albums %}
  <article>
    <a href="{{ album.url }}">
      <img src="{{ album.img }}" alt="{{ album.title }} {{ album.artist }}"/>
      <p>{{ album.title }}</p>
    </a>
    <p>by {{ album.artist }}</p>
    {% if release-date %}
      <span class="release-date">{{ album.release_date | date: "%b %-d, %Y" }}</span>
    {% endif %}
  </article>
{% endfor %}

<!-- algolia search -->

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1/dist/instantsearch.min.css">
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1/dist/instantsearch-theme-algolia.min.css">

<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1"></script>

<script>
  /* we are going to add some javascript code here */
</script>

<!-- end of algolia search -->

I like to test regularly that I did not break anything:

$ bundle exec jekyll serve --incremental

  Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

When I open http://127.0.0.1:4000 in my browser (Google Chrome), I find the following errors in the JavaScript console:

Refused to apply style from 'https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1/dist/instantsearch.min.css' because its MIME type ('text/plain') is not a supported stylesheet MIME type, and strict MIME checking is enabled.
Refused to apply style from 'https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1/dist/instantsearch-theme-algolia.min.css' because its MIME type ('text/plain') is not a supported stylesheet MIME type, and strict MIME checking is enabled.
GET https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1 404 ()
Refused to execute script from 'https://cdn.jsdelivr.net/npm/instantsearch.js@2.8.1' because its MIME type ('text/plain') is not executable, and strict MIME type checking is enabled.
Uncaught ReferenceError: instantsearch is not defined

Let's ignore CSS errors for now (1, 2), and start with JavaScript errors (3, 4, 5) instead, because they are the ones that prevent the search from initialising:

The last error (5) is caused by the fact that the instantsearch.js could not be loaded (3, 4). And apparently, it was not able to load because the provided URL does not have the expected MIME type. It could be that MIME type checking is enforced when opening a webpage from localhost, like I'm doing now.

The same problem seems to happen with CSS files.

When trying to open theses files in separate browser tabs, I understand that it's not only a matter of MIME types, these URLs are returning pages with an error message: "Couldn't find the requested release version 2.8.1."!

By removing the "@2.8.1" part of these URLs, they seem to work fine! After applying this same change to my index.md file and refreshing the page, all errors disappeared from the JavaScript console! 😇

(3.2) Instantiate the search bar and hits

Now that instantsearch.js is imported properly, we need to write some code to instantiate our search bar and hits.

First, we are going to add <div> elements in index.md, so that instantsearch.js knows where to integrate the search bar and the hits.

As advised in the "Add a searchbox" part of Instantsearch's tutorial, we start by adding the following HTML code between our Jekyll template (to display albums) and the section that imports instantsearch.js:

<div id=="search-box">
  <!-- SearchBox widget will appear here -->
</div>

<div id="hits">
  <!-- Hits widget will appear here -->
</div>

Remember the /* we are going to add some javascript code here */ comment we had written in a <script> element of index.md? The time has come to fill this <script> element!

As advised in the "Initialization" and "Display results" of Instantsearch's tutorial, let's add the following JavaScript code there:

  const search = instantsearch({
    // TODO: enter our own algolia credentials here
    appId: 'latency',
    apiKey: '6be0576ff61c053d5f9a3225e2a90f76',
    indexName: 'instant_search',
    routing: true
  });

  search.addWidget(
    instantsearch.widgets.searchBox({
      container: '#search-box',
      placeholder: 'Search for albums'
    })
  );

  search.addWidget(
    instantsearch.widgets.hits({
      container: '#hits',
      templates: {
        empty: 'No results',
        item: '<em>Hit {{objectID}}</em>: {{{_highlightResult.name.value}}}'
      }
    })
  );

  search.start();

Now, let's refresh the http://127.0.0.1:4000 browser tab to see if it works. (you may need to restart the $ bundle exec jekyll serve --incremental command)

That's what I get:

The search box is displayed nicely, but we're also seeing several Hit : } lines under it... 🤔

If we had been more attentive, we would have seen that the bundle exec jekyll serve command had given us a warning that seems linked to this problem:

Liquid Warning: Liquid syntax error (line 55): Unexpected character { in "{{{_highlightResult.name.value}}" in index.md

My hypothesis is that the template I had copy-pasted from Instantsearch's tutorial conflicts with Jekyll's template parser. If this hypothesis is right, moving this JavaScript code to a separate .js file should fix this problem.

I can confirm that my hypothesis was right: moving the JavaScript code to a new search.js file, and importing that file from index.md using <script src="search.js"></script> does the trick! 😁

So now, here is what I get:

The list displayed under the search bar does adapt in real-time when I type in it, but the hits are not albums!

(3.3) Customise for our search index

We need to plug the right Algolia index to our instantsearch.js instance. In order to do that, we have to change the values of the appId, apiKey and indexName properties, to match the credentials of our own Algolia index.

Note: These credentials will be used by instantsearch.js just to send search queries, so you should enter your "Search-Only API Key" here. (found on the same page as the "Admin API Key")

After doing that, I'm able to search my album collection:

We're getting some hits when typing words that are part of our albums' names, but the name of the resulting albums are not displayed.

As you can see on your Algolia dashboard, the title of albums are stored in an attribute called content. So that's what we should display.

To do that, we need to update our hit template from search.js, from:

      item: '<em>Hit {{objectID}}</em>: {{{_highlightResult.name.value}}}'

... to:

      item: '<em>Hit {{objectID}}</em>: {{{_highlightResult.content.value}}}'

That should do! ✊

Resulting files

You can find the source code what we produced in that github repository: github.com/adrienjoly/jekyll-tutorial.

Here are the files that we created or updated in this tutorial:

Gemfile:

# Gemfile

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins

group :jekyll_plugins do
  gem 'jekyll-algolia', '~> 1.0'
end

_config.yml:

# _config.yml

algolia:
  application_id: 'paste_your_application_id_here'
  index_name: 'albums'
  files_to_exclude: []
  nodes_to_index: 'article'

index.md:

<link rel="stylesheet" href="index.css" />

## Albums

{% for album in site.data.albums %}
  <article>
    <a href="{{ album.url }}">
      <img src="{{ album.img }}" alt="{{ album.title }} {{ album.artist }}"/>
      <p>{{ album.title }}</p>
    </a>
    <p>by {{ album.artist }}</p>
    {% if release-date %}
      <span class="release-date">{{ album.release_date | date: "%b %-d, %Y" }}</span>
    {% endif %}
  </article>
{% endfor %}

## Search

<div id="search-box">
  <!-- SearchBox widget will appear here -->
</div>

<div id="hits">
  <!-- Hits widget will appear here -->
</div>

<!-- algolia search -->

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js/dist/instantsearch.min.css">
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/instantsearch.js/dist/instantsearch-theme-algolia.min.css">

<script src="https://cdn.jsdelivr.net/npm/instantsearch.js"></script>

<script src="search.js"></script>

<!-- end of algolia search -->

search.js:

const search = instantsearch({
  appId: 'R6Y1H83FNX',
  apiKey: 'b0f283176b810e5223f70e3ab3ac7c04',
  indexName: 'albums',
  routing: true
});

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#search-box',
    placeholder: 'Search for albums'
  })
);

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      empty: 'No results',
      item: '<em>Hit {{objectID}}</em>: {{{_highlightResult.content.value}}}'
    }
  })
);

search.start();

Next: Fix the UI

In this tutorial, we:

created a search index on algolia.com
setup Jekyll-Algolia to populate this index from our list of albums
integrated instantsearch.js (despite a CDN issue)
and plugged our own index to the search components

We also learned how to upgrade ruby and how to preview the Jekyll site from localhost.

Despite the fact that we have a working search bar on our album collection, the resulting website is not good looking, nor usable.

In the next tutorial, we will define what user experience we're aiming for, and implement it. Hopefully, our album collection will look great again, after that!

Stay tuned, and please share your comments, questions and suggestions, if any!

How to maintain a collection of music albums online, using Jekyll and Github Pages

Adrien Joly — Sat, 30 Jun 2018 15:26:34 +0000

I love to make lists.

Lists of tasks (ToDo), of books to read, of cities I visited, of places I'd like to go, of my favorite restaurants in Paris, of the most recommendable freelancers...

As a matter of fact, I'm pretty sure that at least half of all the business and productivity apps out there were made to help us maintain lists.

The Motivation

One of my lists is very dear to my heart. It's my collection of music albums.

In the past, it used to be materialised by a stack of cassettes. Then, it turned into a shelf of CDs. Then, it became a list of folders full of MP3 files, stored in the hard-disk of my computer.

More recently, it's become more convenient to stream music directly from the Internet, without having to own anything, thanks to services like Spotify. Eventually, my collection of albums turned into a very long list of playlists, stacked on the left of my Spotify window, without cover art...

I've definitely gained in terms of convenience, saving space in my appartment, and reduced fear of losing (or damaging) material records. But what about the pleasure of browsing my collection randomly, while appreciating the beautiful cover art? Lost.

Let's solve this. Let's bring back the joy of having a beautiful music collection again!

Existing solutions

There are many ways to keep an album collection.

Firstly, Spotify does allow me to Add an album to my collection, to later find it in the "Albums" page. But unfortunately, this list also includes the album containing each track I've ever liked on Spotify, even though I don't care about the rest of that album... So in the end, it does not really look like a hand-picked collection of albums.

So let's ask Google: "album collection online". First result is discogs.com. This website does allow to create a profile and add albums to my collection, with cover art! But it was clearly designed for vinyl disc collectors, as each album is listed in various editions with different track lists, and you have to pick one of them in order to add it to your collection. Too cumbersome for me... Also, I did not find any way to play the album in one click from there.

What if I used a more generic service to maintain my collection in a visual manner? Pinterest seems like a good candidate! Unfortunately, Pinterest just provides a full-text description field for each image, making it impossible to browse albums by artist or genre...

Maybe I should keep my collection in a database, and setup a piece of software to maintain it? A content management system (like Wordpress) with a few plug-ins and a good theme could probably work. But at what cost? I'd need to host it on a PHP server, run software updates, tweak plug-ins and themes that somebody else made, and probably pay for hosting. That seems too complicated.

What about keeping my list in a static HTML file with simple CSS styling to make it look like a material album collection? That's definitely less complex and costly to publish! But it's also easy to forecast the limitations: having to edit HTML code every time I want to add an album, necessity to add JavaScript / DOM manipulation in order to make it browseable by artist and searchable...

What if I could maintain my list of albums in a text file, and have HTML files automatically generated from it? 🤔

Isn't that the promise of Jekyll, supported for free by Github Pages?

That's it! I finally found a good excuse to learn how to use Jekyll!

Designing the solution

Let's recap what I expect from my album collection:

Display cover art in a beautiful gallery
Play the album in one-click, from Spotify or other
Browse by artist or genre
Quick and easy CRUD operations (i.e. Create, Retrieve, Update and Delete albums)
Fast search
Low risk of data loss or corruption
Available online, for the world to see!
Easily forkable, for other developers who want to make their own collection.

I know that it's quite easy for me to build a HTML+CSS web page that would cover points 1 and 2.

I've read that Jekyll can generate static HTML pages based on data files expressed in YAML, which is an almost-plain-text structured markup format similar to Markdown. This could cover points 3 and 4.

I also know that Github Pages is my favorite way to publish web pages for free, and that it supports Jekyll out of the box. Meaning that, if I put Jekyll files in my repository, Github will automatically generate the resulting HTML pages. And of course, I can run Jekyll offline on my laptop as well. That will cover points 6 to 8.

What about fast search? Oh, wait! I work for Algolia, and one of my colleagues made a plug-in to make any Jekyll website searchable: Jekyll-Algolia!

That sounds like a realistic and exciting plan! Let's make this a reality!

Step 1. Initialise a Jekyll page on Github Pages

To get started, let's set a simple goal to ourselves: make Github Pages render and publish a HTML file out of a simple Markdown file.

I assume that you have a Github repository (fresh or not) ready to host your Jekyll files. If not, please create one and make sure that you are able to commit and push files to it from your computer. I will follow each step on that one: github.com/adrienjoly/jekyll-tutorial.

Let's add a index.md file at the root of the master branch of our repository, with the following contents:

Hello world!

This is a **markdown** file.

Now, let's ask Github Pages to render and publish it as a website. For that, go to your repository's settings page (mine: https://github.com/adrienjoly/jekyll-tutorial/settings), and pick the master branch as "Source", in the "GitHub Pages" section:

Then click "Save".

Now, you should be able to see your index by opening the URL https://<your_username>.github.com/<your_repo_name> in your web browser. If everything went well, it must have been rendered in HTML by Github Pages, thanks to Jekyll, and look like that:

Good job!

Step 2. Render a simple list using Jekyll

Now, let's integrate a simple list into that page.

In order to do that, we will:

create a .yaml file in the _data folder,
and add a template to integrate its data in index.md.

In my case, I'm going to create a _data/albums.yaml file with the following contents:

- title: Blood Sugar Sex Magik
  artist: Red Hot Chili Peppers
  img: https://i.scdn.co/image/5a6a1c6514398dc4004c6348a83d77694a3883d4
  url: https://open.spotify.com/album/30Perjew8HyGkdSmqguYyg

And then, I add the following template to index.md:

## Albums

{% for album in site.data.albums %}
- [{{ album.title }} by {{ album.artist }}]({{ album.url }})
{% endfor %}

This template will render a HTML list item for every item from _data/albums.yaml. Each item will be render as a hyperlink displaying the title and artist of the album, and linking to its Spotify page.

Let's refresh https://<your_username>.github.com/<your_repo_name>. After giving Github a few seconds to re-render the website, the resulting page should look like that:

We're making some progress!

Of course, you can add as many items in _data/albums.yaml as you like!

For more information about the syntax of the YAML format, read The YAML Format (Symfony Docs).

Step 3. Make it look better

Now that we know how to create a list in YAML, and how to render it in Markdown, let's make it look like a proper collection of albums!

The first thing that is missing is cover art.

In order to display images, we can of course use the Markdown syntax: ![alt](src). But, in order to get more flexibility while designing our list, we will use some good old HTML instead. Yes, Jekyll does supports HTML markup in a Markdown files.

Let's replace the template we had integrated in the previous step by this one:

{% for album in site.data.albums %}
  <article>
    <a href="{{ album.url }}">
      <img src="{{ album.img }}" alt="{{ album.title }} {{ album.artist }}"/>
      <p>{{ album.title }}</p>
    </a>
    <p>by {{ album.artist }}</p>
    {% if release-date %}
      <span class="release-date">{{ album.release_date | date: "%b %-d, %Y" }}</span>
    {% endif %}
  </article>
{% endfor %}

Assuming that you added at least a second album to your list, the resulting page would probably end up looking like this:

Of course, we can do better by adding a bit of styling in index.css:

* {
  box-sizing: border-box;
}

article {
  display: inline-block;
  width: 320px;
  height: 420px;
  padding: 8px;
  overflow: hidden;
}

article img {
  width: 320px;
  height: 320px;
}

.markdown-body article p {
  margin-bottom: 0;
}

.release-date {
  color: gray;
  font-size: 90%;
}

But, even after refreshing the resulting page, you'll see that this stylesheet was not automatically picked up by Jekyll...

So, now that we know that HTML markup is supported on top of Markdown, let's add a <link> element at the top of index.md, to load our stylesheet:

<link rel="stylesheet" href="index.css" />

After refreshing the page, you will hopefully see some UI improvements:

Looking good!

Now, feel free to clean index.md from our old tests. (e.g. "hello world")

Summary of progress

To illustrate our progress, let's update the list of requirements I had proposed at the beginning of this article:

~~Display cover art in a beautiful gallery~~ ✅
~~Play the album in one-click, from Spotify or other~~ ✅
Browse by artist or genre
~~Quick and easy CRUD operations (i.e. Create, Retrieve, Update and Delete albums)~~ ✅ (room for improvement)
Fast search
~~Low risk of data loss or corruption~~ ✅
~~Available online, for the world to see!~~ ✅
~~Easily forkable, for other developers who want to make their own collection.~~ ✅

Whoa, we've done quite a lot, with so few lines of code and so little effort! ✊

Next steps

So what can we do to make our collection ever better?

For starters, we have not implemented any way to browse by artist or genre yet. There are many ways to do this, and I'm sure that would make an interesting follow-up to this article!

You saw that it was quite easy to maintain the collection in YAML. But we can do better. It would be awesome to automatically populate the album data after typing just its name. Maybe we could achieve that by building a command line interface that would query Spotify's API and update albums.yaml automatically!

Search is also lacking. It would be interesting to try out Jekyll-Algolia, as I proposed earlier.

One more thing: what if I want to use my album collection while being offline? Worse, what if Github Pages dies? Can we run Jekyll ourselves, to generate the HTML website from our index.md template and our albums.yaml data file? Yes, we can! We just need to setup some software tools on our computer, and add a little bit of configuration to the Jekyll website. That's yet another topic that we can explore together in a next article.

Conclusion

I hope that this article convinced you that Jekyll and Github Pages make a powerful (yet easy to use) duo to maintain beautiful and flexible lists online.

As a lover of the Web, I wish that more lists were maintained that way, and that we rely less on closed apps to hold our data. This article aims to be a modest contribution towards promoting the DIY (do it yourself) philosophy to the way we manage our lists of things, and more generally, our data.

I'd love to read your feedback, ideas, and suggestions after reading this article. Please let me know what you'd like me to write about next!

Hi, I'm Adrien Joly

Adrien Joly — Sat, 06 May 2017 12:49:19 +0000

I have been coding for 27 years. (Ok, I kinda started when I was 7!)

You can find me on GitHub as adrienjoly

I live in Montreuil, Paris area, France.

I work for myself by building my own products, and also teach JS programming at EEMI.

I mostly program in these languages: JavaScript, in Node.js and in web browsers.

I am currently learning more about how to sell a product (problem validation and marketing).

Nice to meet you.

DEV Community: Adrien Joly

Things We Wish We Knew When We Started

Write Tests

Code With Your Teammates

Learn, Chat, Share

Improve the Collaboration Progressively

Design Slowly

You Are In Control

That's all, folks!

Let's turn an Openwhyd playlist into a static Jekyll site

Why?

Design of the technical solution

Step 1. Clone (and clean) Openwhyd's repository

Step 2. Create a HTML page with a playable track

3. Store the track listing into a data file

4. Turn the HTML page into a Jekyll template

Next steps

Make your Static Site Searchable with Jekyll-Algolia

Proposed solution

Step 1. Integrate the plug-in

Step 2. Set up the search index

Step 3. Integrate the search bar

(3.1) Import instantsearch.js

(3.2) Instantiate the search bar and hits

(3.3) Customise for our search index

Resulting files

Next: Fix the UI

How to maintain a collection of music albums online, using Jekyll and Github Pages

The Motivation

Existing solutions

Designing the solution

Step 1. Initialise a Jekyll page on Github Pages

Step 2. Render a simple list using Jekyll

Step 3. Make it look better

Summary of progress

Next steps

Conclusion

Hi, I'm Adrien Joly

(3.1) Import `instantsearch.js`