HTML, CSS and netlify

Netlify is everything you need to build fast, modern websites: continuous deployment, serverless functions, and so much more.

I’ve been looking for a small project/excuse to use netlify for a little while now, and then something came along this week that seemed like the perfect place to be able at least try it without and fallout.

For some reason I’ve always thought netlify was for all the “modern” JAMStack style build – where you have a static site generator that needs to execute some build steps before it can be deployed. But as I found out this week I was pretty wrong.

I was building out some prototypes for something at work and wanted to get it online somewhere so I could show a few people. Normally I would use AWS S3 or upload to my own domain on a shared web host. There are many steps involved in either of those options that I wasn’t keen on having to set up or wait for DNS and so forth.

Here comes netlify – the prototype I was building was using no libraries or frameworks, using just HTML and CSS. I already had the prototype set up as a Git repository (I highly recommend always using source control, it’s a great “undo” tool and many other benefits).

With my Git repository setup (I am using a private repository for my prototype, I have made a demo one for this article), and my netlify account waiting. You just connect the two together and netlify will make a new build each time you commit. As I am committing directly to master the domain that netlify gives you for the project will always have the latest master commit deployed to it.

Steps

  1. Have a Git repository set up with you code (my example is here: https://github.com/matthewroach/netlify-demo)
  2. Have a netlfiy account – You can sign up with oAuth and use your Github account if you like
  3. Choose “New site from Git”
  4. Continuous deployment – Choose Github, it will run through some steps and ask how you want to connect your account
  5. Choose the repository you want to use for this project/site
  6. Deploy settings – make sure the branch is your main branch – in my case I am using master. Don’t enter anything in the build section
  7.  Click “Deploy site”

You will then get taken to the overview screen for your site. First it will show as in progress, once it’s finished doing it’s thing you will have a link you can view your deployed code at. Netlify will auto generate a name for the site and a URL for you to view it at, for me it gave me the URL – https://gracious-nightingale-a4bf0b.netlify.com

If you look at the code (https://github.com/matthewroach/netlify-demo) and the deployed site https://gracious-nightingale-a4bf0b.netlify.com – You can see there is nothing specific to netlify – it’s deployed the repo as a static site, I have no build steps or any tools or frameworks in place. This allows me to quickly push my code up and have it available for others to view and interactive with. Just having an index.html in the root of the repository is enough.

For local development I am using npx to run a local server using the node module http-server.

netlify site overview

For each commit you make the branch you set as the main branch netlify will make a build for that commit. The URL for the site will always show you the most recent deploy.

You can view all the deploys that have happened in netlify and even view what that build looks like, Each build has it’s own URL you can view at – For example when I connected my repo it only had a readme file you can preview that build here – https://5d6a3e7e0c2e32cbcfc25ddf–gracious-nightingale-a4bf0b.netlify.com

I then added some HTML and CSS files, after pushing to Github netlify picked up the commit and triggered another build. You can see my two builds in the deploys tab of the site.

netlify site deploys

Documenting your CSS with Styledown

Generating a styleguide for your CSS is something that can help other developers, and go a long way in reducing the confusion and possibility of someone reproducing the same styles. Ever jumped around a few projects over time and had to dive into all the CSS to find a style you thought was there, then found there was not one and you wrote it, or you may of even ended up duplicating some work that was brought up in a code review.

“Did you know we had a style already for that”

Generating a styleguide should not be a chore, and something you want your entire team to buy into. It should fit easily into your flow, not be too intimidating to other developers to start and continue with.

There are quite a lot of CSS styleguide generators around if you do a quick Google search, you will be greeted with many choices. I decided to go with styledown, as it looked to be the simplest and required very little in terms of getting up and running. Also the comments you needed to add to your CSS is very minimal, this suited what I was after. Another bonus for styledown was it was not Sass specific, it’s just CSS comments, you can even use markdown files if you so wish. Styledown is a node package, and is available on npm as styledown.

Documenting your CSS with Styledown is a simple as follows:

/***
 * Buttons:
 */

/**
 * Button:
 * `button` - Button stylings for default sbittons on the sitee
 *
 *     @example
 *     button Standard button
 */

The first comment acts as the header, so in this case we are documenting our buttons. A file can contain multiple headers so you don’t have to worry too much about splitting your Sass up into lots of partials. We can then add comments throughout our CSS to give a description and example of the styles. The example part of the comment can be written as either Jade or HTML. The only required thing which can trip you up is the first line of the block you are documenting, in this case Button has to end with a semi-colon (:).

On top of adding comments to your CSS styledown allows you to have a config file, this file is markdown and lets you define what will be output in the head/body of the generated HTML file.

Generating the styleguide is as simple as running the following from your command line, assuming you have install the package globally.

styledown scss/**/*.scss config.md > index.html

If you are using gulp as your build tool you there is a gulp-styledown module, makes things nicer if you want to build the styleguide for each change. I recently added the gulp-styledown module to a new project and have the style guide generating on save of any .scss file.

I am running styledown on my little CSS framework I use for personal projects, it’s more a big reset and normalize in one. You can see the source on Github, or view the styleguide at flucss.com.