Learning new tools

Hey folks!

This week we're changing things up a little bit.

I'll be sharing some steps on how you can build a static site from a private GitHub repository and make some of its contents public on the web.

But also, I'll be doing some commentary on the process of learning something new and using that knowledge to contribute to an OSS project.

With that being said...

Some intro

With the fast-changing tech landscape, it looks like you can get really good at one particular technology or tool and then you see all these other tools being created and popping up in the space and you realize that you will always be a newbie in something no matter your stack or your years of experience doing X or knowing about Y.

For that, the best thing to do is to adopt a beginner's mindset. Turn on your learning gene, go into the fray, get some hands-on experience, and become a better performer.

If you want to take something you've done on and put it online, you can already do it by pushing to a git repo, use GitHub pages and voila! a site with a cool looking Jekyll theme and a link to share with others.

But what if you don't want to publish the whole thing? Maybe because the majority of the work hasn't been done yet or is a WIP.

In that case, you make the repo private and work on it and then when you want to publish it you create another repo (public this time) and put in it all the stuff that's ready for sharing.

Or maybe that just sounds like a lot of manual work to be done and we want to simplify it enough so we don't get bored with the process.

I found that to be the case when I noticed that you can't use GitHub pages to publish stuff from a private repo. So I would have to do that whole process that I already mentioned.

But I wanted a better option that didn't rely on Jekyll or GH pages and possibly would involve more upfront work but would make the process easier for all the other times that weren't the #1.

Doing some research online I found several options, but there was one that caught my attention particularly.

Enter Eleventy

Eleventy is a Static Site Generator (SSG) that was created to be a JavaScript alternative to Jekyll. It’s zero-config by default but has flexible configuration options. It uses several template languages (.md, .liquid, .njk, .haml, .pug, etc..) from which you can pick one to use or a couple whenever you need them in your project.

Unlike things like Gatsby, Nuxt, Next.js, and others, Eleventy doesn't rely on any JS framework. You can just build a site with a bunch of Markdown documents and Eleventy will build them and have them as pre-rendered templates that can be served anywhere.

Eleventy is incremental. You don’t need to start an Eleventy project from scratch. Eleventy is flexible enough to allow conversion of only a few templates at a time. You can add it to any existing project where you want static site capabilities.

With that knowledge, one could go in and starting hacking away and see what can come up from it.
The Eleventy docs are pretty straightforward for the common use case, although one will have to dig in further if something more interesting is to be built with it.

Since it's based on JS, it's available as an npm package that can be installed. (I actually created a small project first and once I knew more or less how it worked, then I actually integrated it in the project that I was working on).

So if you just want to try it out by yourself. First, create a new directory with any name ("eleventy-test" for instance) then get inside the directory and create a package.json with this command.

npm init 

You can answer all the questions it's going to make for the package or you can use the "-y" flag to skip the questions and just use the defaults.

Now you can install Eleventy into the newly created project by running.

npm install --save-dev @11ty/eleventy

Or if you are like me and use yarn then use this one

yarn add -D @11ty/eleventy

After that, if you want to test that everything went right with the installation you can run

npx @11ty/eleventy

With that command, you'll start the server that will turn the pages into templates.
But... we don't have any of those yet, so let's create some.

Again, you can use any type of template languages for this but the easy option here is to use files with the ".md" extension.

For this you can use your editor of choice or from the command line run.

echo '# Main page' > index.md

echo '# About page' > about.md

Now we have two pages to work with. Let's run Eleventy again with

npx @11ty/eleventy

Now you'll see that Eleventy will compile the documents and create ".html" files from it. In this case would be something like index.html from ./index.md and about/index.html from ./about.md

All those generated templates will live in the _site folder by default (unless you change the folder in the Eleventy configs)

You can now deploy that folder to any service that can host static sites.

But what if you want to be able to see your site locally and make some changes before you're fully confident that the site is ready?

Use the Eleventy web server

You can use the same command to run Eleventy but his time, pass in the --serve flag to it. Like so.

npx @11ty/eleventy --serve

You will see in the output the templates created in the _site folder and then you can see some output from Browsersync, which is the tool that is being used to create a hot-reload web server for the files being served.

Now, you can go to the addresses that are shown there to view your site either locally or from an external network. the other set of addresses that says "UI" and "UI external" are for you to go directly to the Browsersync dashboard. (in which you will see the first addresses mentioned)

Now you can make changes in the files, adding content, or create new files, and build the site structure.

One thing we can do to make that process easier, is to do some changes in the package.json.

Add the following lines in the "scripts" section.

  "scripts": {
    "start": "eleventy --serve --watch",
    "clean": "rm -rf ./_site",
    "build": "npm run clean && eleventy"
  }

This will allow you to start the server in watch mode which will look for any changes you make and update the templates accordingly. Also you can clean the output folder and build the site in order to be deployed.

Once the site is built and ready to go, it's time to publish it on the web for others to see.

For that, there are several services we can use (Surge, Vercel, Netlify, etc...) but there's one in particular that can make things easy while also allowing further configurations.

Enter Netlify

I think many of you already know what Netlify is but in case you don't, let me tell you real quick.

Netlify is a platform that allows you to host static sites and gives you a lot of other cool features as well like

• Custom URLs for projects
• A CDN for all the project assets
• The ability to use a domain you own (or buy one from them)
• Free SSL for deployed sites
• And a whole lot more

You can drag & drop plain HTML, CSS, JS sites but it works even better with Static Site Generators (like Eleventy) because it will run the 'build' command of the project and deploy the result live on the web allowing you to have a special link that you can use or share with others to see your site published.

In order for the generated Eleventy site to be published on Netlify, there's a config that we're going to create. It's not totally necessary but it'll make the build process more predictable.

In the current folder of the project, create the file netlify.toml that will contain the following.

[build]
  publish = "_site"
  command = "npx eleventy"

This comes straight from the Netlify docs (which are very thorough and well written btw)

With that change done, you can now push the project to the GitHub repo (that remember from the beginning I said it was a private repo).

Now, import that GitHub repo into your Netlify account (Create one if you don't have it already). Once that's done you can now go to the Netlify dashboard and, if you're already logged in, you'll see all the projects you currently have linked.

Select the one that was recently imported and you will see an overview of the project's deployment status along with the custom link where your site now lives in.

From there, you can trigger another deploy or see the other cool features available if you scroll down the page.

You can also explore the different settings available for the site and if you want to get fancy, the settings for the domain in which the site is hosted.

The good thing about this GitHub + Netlify integration, is that every time you push new changes to the main branch of the project.
Netlify will automatically build the project and deploy the changes to your live site making sure it's always updated.

And with that you now have your own site published on the web thanks to Eleventy & Netlify!

That was pretty much the process I followed in order to create a
site online that doesn't require the use of Jekyll or Github pages.

Having that knowledge, I took the chance to contribute to an OSS project that I think is really awesome. It's called Foam and it's a tool to manage all your notes and writings and discover hidden relationships between its topics. I think a better description would be "Personal knowledge management system".

You can use it for yourself and create whatever workflow that you deem useful but you can also use those personal findings and share them with the core team to create better workflows for others.

So this comes as a double whammy cuz for one side I learned something completely new that I haven't done before. And for another, I was able to contribute in a meaningful way helping others build great software and seeing how others do it themselves.

You can create your own Foam workspace and share the topics and knowledge you have with others by publishing it on the web and sort of create your own Digital Garden and I truly believe that between the sharing of ideas new great things can come to life.

That's it for this week's post! thanks for reading this far. I hope it was useful and informative.

I'll be back next week with another article but for now... Stay Awesome my friend!

Photo by Tim Mossholder on Unsplash