Building a website takes dogged determination. If you stick with it, you wind up with a platform to show off your awesome brand; you! Choose a ready-made plan like Wordpress or Wix and you are stuck with a convoluted system of extensions and dependencies. The compromised security and longer loading times may negatively affect your search engine rankings.
A website running on the newer JAMstack architecture delivers better performance, higher security, lower cost of scaling, and a better developer experience. A Static Site Generator (SSG) is an automated build system that can quickly serve pre-baked markdown stored to a Content Delivery Network (CDN) and has none of the moving parts of a traditional LAMPstack. A CDN is a geographically distributed group of servers which work together to provide fast delivery of Internet content, rather than being stored on a single server. A CDN augments traditional web hosting, by caching content at the network edge, which improves website performance.
This is a git-centric work-flow, not the old-school ftp method. Your git server updates the CDN when changes are detected. Commandline, therefore more suited towards technical users. This means following instruction sets and running commands in your computers’ terminal. A quick file browser like ranger and a handy text editor like vim/neovim will ease the pain as you will be moving and editing files frequently. More important than having prior knowledge of HTML, CSS, or the language of your site-specific platform, is the willingness to alter the files that some very smart people put together in the first place. Dogged because, there will be times you feel like giving up and a few kind words from a parent or spouse may help put you back on track. Software is like this: you’re scratching your head when it doesn’t work and you’re scratching your head when it does, but you always get there in the end.
Static is sometimes synonymous with simple sites with not an enormous number of pages. However this is a fast moving ecosystem and there is a vibrant developer community. Big companies such as Sequoia Capital are building serious projects with it. As described in this 2016 talk, ‘static’ is a misnomer; hyper-dynamic is how they should be described. Content is stored with the source-code and doesn’t require a multitude of dependencies. The hosting and the build process are decoupled, reducing the surface area of the api meaning security is enhanced.
Javascript provides the following functionality through third-party targetted APIs: interactive comments, forms, ecommerce, payments, functions, and search. You could build a live terminal using react components or re-use the static elements that define the layout of a webpage, while dynamically populating the page with data from a Shopify store with Liquid.
Prominent SSG’s include; ‘Next’ built in javascript and react, ‘Hexo’: node.js Nuxt: vue.js, Jekyll: ruby, ‘Gatsby’: graphql and react, pelican: python. For documentation you have sphinx: python and gitbook:node.js for developing in git and markdown. For this site, I chose Hugo, “an efficient, compiled programming language that feels lightweight and pleasant”, is written in Google’s golang.
One advantage of Hugo is that you can learn markdown and never need to use
javascript,react,redux,vue.js,ruby-on-railsor any other means of conveyance.
No back-end services means less complicated and cheaper hosting. Free in fact with Netifly and Github Pages who specialize in hosting static sites. I selected the 12 month free-tier of AWS Amplify as they also specialize in modern static sites. Amplify provides a commandline interface and supports GraphQL, a newish protocol for streamlining API interfacing. Amplify Console comes with a nice user guide to help you get started.
To get started: install hugo. Check your package manager first: in my case, hugo is available in the Debian buster repository. Create a site with hugo new site whatever-name-you-want, cd into the directory and initialize it with git init. Now you get to pick a theme. There are hugo themes for every taste, and live demos for each. Clone or download your theme into the themes folder.
If you would rather try many of them out for yourself, you may download all of the themes, run
hugo server, defining each one in turn in the config file at the root of your project as you try them out.
You’re ready to create your first page of content with the command
hugo new post/article.md. Content is first written in simple markdown (see my tutorial). Much easier to edit the glaring inconsistencies you (and the entire world) will notice when it’s on the web!
It is worth your time to become familiar with the hugo documentation. In no time you will learn how to merge your HTML templates, CSS, javascript, media, and even data, into a flexible working site.
For version control you can use Github or even host your own Gitea server with PostgreSQL. For my project, I set up git with AWS CodeCommit. My edits are reflected on the webpage as soon as I issue the three familiar commands: git add ., git commit -m "documention message" and git push -u origin master.
No rebuilding or recompiling required, your edits are immediately applied from the commandline to the CDN with
git.
AWS Amplify automatically generates a yaml file that helps to launch your site. You need to put the .yml into your project’s root directory to tell Amplify how to run it.
Only when you are in the midst of your project and stuck, it dawns on you that real choice you made is whether to eat 100 onions or 100 horse apples. In all likelihood you will have eaten all 200 by the time you launch your site.
The same problem was outlined in this helpful blogpost. The yaml file needed to be replaced with one that would use a more recent version of Hugo to be compatible with the version used to create the site. I hope AWS catch this oversight and fix it in future versions.
Presto! The process completed and the build successfully deployed but with no published content. In my haste, I had overlooked these essential steps: remove the draft flags from the files, run hugo --buildDrafts and then simply enter the command: hugo to build the site. That command will generate HTML files into a newly created public folder. The files are thus made-ready to serve.
I knew I wanted a dark-theme. Blue light emanating from screens may be deleterious to health. To counteract it, I use a the redshift program and a dark-theme browser extension.
The archetypes/ and layouts/ folders store page templates. Copy the ones pertaining to the theme from the theme folder and customise your page templates further. Same goes for the config.toml and CSS files; copy the contents assets/ into your root directory too. Files that are in the root directory of your project will take precedent in hugo’s lookup order, your changes to them will be in effect and the original defaults won’t be overwritten if and when you upgrade.
To theme the site, I selected After Dark as it includes extra features. I have since discovered a small group of friendly developers there who welcome discussion and coding contributions. The documentation includes some handy prebaked CSS shortcodes.Hack.css is provided for making style alterations as there are also optional CSS files that can be enabled in the config.toml for a different look to your site. I increased the font-size and the width of the text-body down at the bottom of theme.css to optimize for laptops.
The colors are borrowed from the gruvbox palette (below). To get the hex code for use in the CSS files, there’s the linux program Kcolorchooser. Using the eyedropper tool you sample the color and it tells you the code. It also produces a color chart where you can select a lighter or darker shade in that range of tonality. The font I used is Titillium Web which I first encountered over at the excellent Qt Foundation. Thanks for reading!
