DEV Community: Nathan Blaylock

Bootstrap 5 Responsive Mode Buttons

Nathan Blaylock — Sun, 04 Aug 2024 04:01:14 +0000

This only applies to Bootstrap 5.3 and later using dark mode.

I've been exploring dark mode a little more lately for some personal projects using Bootstrap 5. One thing that I find quite annoying is using Bootstrap 5's dark outline button in dark mode. This looks just fine in light mode, but when you switch to dark mode it becomes invisible. How do you get around that?

It's actually quite easy. I call these "Contrast Buttons". These use the default body and background color to present the button with better contrast: dark in light mode and light in dark mode.

All you have to do is plug in this CSS:

.btn-outline-contrast,
[data-bs-theme=light] .btn-outline-contrast {
  --bs-btn-color: #212529;
  --bs-btn-border-color: #212529;
  --bs-btn-hover-color: #fff;
  --bs-btn-hover-bg: #212529;
  --bs-btn-hover-border-color: #212529;
  --bs-btn-focus-shadow-rgb: 33, 37, 41;
  --bs-btn-active-color: #fff;
  --bs-btn-active-bg: #212529;
  --bs-btn-active-border-color: #212529;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #212529;
  --bs-btn-disabled-bg: transparent;
  --bs-btn-disabled-border-color: #212529;
  --bs-gradient: none;
}

[data-bs-theme=dark] .btn-outline-contrast {
  --bs-btn-color: #dee2e6;
  --bs-btn-border-color: #dee2e6;
  --bs-btn-hover-color: #000;
  --bs-btn-hover-bg: #dee2e6;
  --bs-btn-hover-border-color: #dee2e6;
  --bs-btn-focus-shadow-rgb: 222, 226, 230;
  --bs-btn-active-color: #000;
  --bs-btn-active-bg: #dee2e6;
  --bs-btn-active-border-color: #dee2e6;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #dee2e6;
  --bs-btn-disabled-bg: transparent;
  --bs-btn-disabled-border-color: #dee2e6;
  --bs-gradient: none;
}

This follows pretty closely with how Bootstrap handles .btn.btn-outline-dark but changes some colors specifically for dark mode.

Then just add <button class="btn btn-outline-contrast">Button</button> to your HTML, and you should have the appropriate contrast button depending on the selected mode.

This is what you should see:

I Want More

Having the contrast button work for outline buttons is great, but I would also like a regular contrast button. This is all you need in both cases:

.btn-contrast,
[data-bs-theme=light] .btn-contrast {
  --bs-btn-color: #fff;
  --bs-btn-bg: #212529;
  --bs-btn-border-color: #212529;
  --bs-btn-hover-color: #fff;
  --bs-btn-hover-bg: #1c1f23;
  --bs-btn-hover-border-color: #1a1e21;
  --bs-btn-focus-shadow-rgb: 66, 70, 73;
  --bs-btn-active-color: #fff;
  --bs-btn-active-bg: #1a1e21;
  --bs-btn-active-border-color: #191c1f;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #fff;
  --bs-btn-disabled-bg: #212529;
  --bs-btn-disabled-border-color: #212529;
}

.btn-outline-contrast,
[data-bs-theme=light] .btn-outline-contrast {
  --bs-btn-color: #212529;
  --bs-btn-border-color: #212529;
  --bs-btn-hover-color: #fff;
  --bs-btn-hover-bg: #212529;
  --bs-btn-hover-border-color: #212529;
  --bs-btn-focus-shadow-rgb: 33, 37, 41;
  --bs-btn-active-color: #fff;
  --bs-btn-active-bg: #212529;
  --bs-btn-active-border-color: #212529;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #212529;
  --bs-btn-disabled-bg: transparent;
  --bs-btn-disabled-border-color: #212529;
  --bs-gradient: none;
}

[data-bs-theme=dark] .btn-contrast {
  --bs-btn-color: #000;
  --bs-btn-bg: #dee2e6;
  --bs-btn-border-color: #dee2e6;
  --bs-btn-hover-color: #000;
  --bs-btn-hover-bg: #e3e6ea;
  --bs-btn-hover-border-color: #e1e5e9;
  --bs-btn-focus-shadow-rgb: 189, 192, 196;
  --bs-btn-active-color: #000;
  --bs-btn-active-bg: #e5e8eb;
  --bs-btn-active-border-color: #e1e5e9;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #000;
  --bs-btn-disabled-bg: #dee2e6;
  --bs-btn-disabled-border-color: #dee2e6;
}

[data-bs-theme=dark] .btn-outline-contrast {
  --bs-btn-color: #dee2e6;
  --bs-btn-border-color: #dee2e6;
  --bs-btn-hover-color: #000;
  --bs-btn-hover-bg: #dee2e6;
  --bs-btn-hover-border-color: #dee2e6;
  --bs-btn-focus-shadow-rgb: 222, 226, 230;
  --bs-btn-active-color: #000;
  --bs-btn-active-bg: #dee2e6;
  --bs-btn-active-border-color: #dee2e6;
  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
  --bs-btn-disabled-color: #dee2e6;
  --bs-btn-disabled-bg: transparent;
  --bs-btn-disabled-border-color: #dee2e6;
  --bs-gradient: none;
}

Here is what that looks like in both light and dark mode.

I hope this helps anyone looking for a good solution to this missing feature.

Eleventy/Figma Plugin Template

Nathan Blaylock — Mon, 12 Jun 2023 20:24:40 +0000

I recently developed a pretty neat plugin for Figma called Placeholdate which solved a problem I was having with other plugins. I use plugins like "Faker" and "Figma Data Faker" but their date outputs were not formatted the way I wanted. So, I made my own plugin to generate random dates and allow me to output whatever date format I wanted. It was very helpful for me, as well as 2k+ users.

As I was developing that plugin I found that managing all of my code in one .html file was getting rather difficult. So I decided to make my own quick Node script that would allow me to compile all of my separate .js, .scss, and.html files into a single file. It was a pretty hacky script to be honest, but it worked.

I recently decided to try out a new plugin and I started using that same script from my Placeholdate plugin, but I wasn't super happy with it. I looked at other options such as Webpack (Figma's suggestion) and Figsvelte, but I wanted something familiar with a simple setup. I decided to try out Eleventy.

I have used Eleventy before on multiple projects, but I never tried to do things like inlining CSS from a Sass file, or just inlining text from any file type. After some research I wrote a slick filter that could pull code from a file and inject it in the HTML. The output of this Eleventy project is a single, minified HTML file with all scripts and style written inline.

Getting Started

To get started, use the template from GitHub. In a terminal, navigate to this folder and run npm install. This will install all of the Eleventy and Figma dependencies.

Once that is done, you will need to get your own Figma plugin ID. In the manifest.json file you will see an ID field with "###################". You will want to replace that number.

In Figma Desktop go to Plugins > Development > New Plugin.
Add in a plugin name (whatever you want, it doesn't matter), then choose "Figma Design", then next.
Choose "Custom UI". You will then be prompted to save the plugin somewhere.
Open that folder that you saved and open the manifest.json file and copy that ID.
Paste that ID into this template.
OPTIONAL: If you are new to developing plugins for Figma, you might want to read through that README.md file which has additional information not found here.
You can delete that new plugin folder you just created. You don't need it anymore.

This project is set up to use src as the input directory and dist as the output directory. The src directory will include code.ts which is code for the Figma side of the plugin, and other files are handled by Eleventy. This setup uses Nunjucks, but you can use whatever other templating language Eleventy offers if you want. If you open index.njk there will be some comments guiding you on how to use the template.

To begin development, run npm run dev. This will create dist/index.html from the Eleventy project and dist/code.ts from the code.ts file. From here, you can go to Figma > Plugins > Development > Import Plugin from Manifest. Select this project manifest and you can start using the plugin!

Inlining JS, CSS, and Sass

The main limitation to developing plugins for Figma is that everything needs to be in one single .html file. This means that all JavaScript and CSS needs to be used in a <script>...</script> or <style>...</style> tag. You can manually write these, but this template provides a filter to extract that from a separate file and inline it in the output file. You can also use Sass which will automatically compile to CSS. Simply add a filter to your .njk file where ever you want it inserted (see the example below). You can also pull code from node_modules.

<!-- Please note that these file paths are relative to the `.eleventy.js` config file. -->
{{ './src/style.scss' | inlineFromFile | safe }}
{{ './src/style.css' | inlineFromFile | safe }}
{{ './src/script.js' | inlineFromFile | safe }}
{{ './node_modules/alpinejs/dist/cdn.js' | inlineFromFile | safe }}

Adding External Code (CDN)

If you don't want to inline your code, but would rather use a CDN, you will need to modify the manifest.json file to allow the domains. Check out the documentation for more details.

{
  "networkAccess": {
    "allowedDomains": [
      "cdnjs.cloudflare.com" // was "none"
    ]
  }
}

Documentation Links

For more information regarding development, check out the links below.

Extract Data from Google Sheets

Nathan Blaylock — Fri, 25 Mar 2022 04:48:30 +0000

As a JAMStack developer, I have often found a situation where all I need is a way to get data and display it on a website. There are a lot of options out there, like creating a database with an API, using serverless technology like Firebase, or many other options. But that often seems a little overkill.

Sometimes, all I need is a spreadsheet as a read-only data source. Google Sheets is an appealing option because it is familiar to many people, is available as a web application, and makes storing and organizing data a breeze. Wouldn't it be nice to use this as a data source?

One solution I have used to get Google Sheet data was Tabletop.js which was written several years ago and no longer works. Other solutions out there cost money. Some seem a little questionable when you hand over your Google credentials allowing them access to your Google Drive.

Introducing: Extract GSheet

Since I wasn't happy with any of these solutions, I decided to write and publish my own library to extract data from a Google Sheet.

Extract GSheet is a front-end JavaScript library that extracts your published Google Sheet data making it available as a JavaScript object. It can even pull data from multiple tabs within the same document! From there, you can display the content however you would like. Unlike many other libraries, this library does not require an API key.

Example

Take a look at the following CodePen to see how easy it is to extract data from this published Google Sheet data.

Features

Extract GSheet will pull out all text data in the table and convert it as needed. For example, "1" ⇒ 1, "TRUE" ⇒ true, and will convert checkboxes to a true/false value.
It will use the first row in the sheet as the key for the key/value pairs.
It will remove empty rows and columns to keep the data clean.
If there is no column labeled id, it will add an id for each non-empty row.

What This Won't Do

Extract GSheet is intended to only read data from a Google Sheet. It cannot write data to a Google Sheet. If you need to update information on your website, you will need to edit the Google Sheet. Any changes on your Google Sheet should automatically publish once changed. However, some changes may take up to 5 minutes to reflect on your page.
Extract GSheet relies on DomParser and fetch which are not native to Node.js. Because of this, it will only work in a browser.
Extract GSheet will not extract non-text items such as images, comments, and charts.
It does not work in Internet Explorer.

Documentation and Examples

You should have a pretty good idea of how easy it is to implement based on the CodePen above, but if you still need additional help, you can find more information in the documentation.

I also have examples of formatting data using different libraries and frameworks such as jQuery, Vue, React, and more. You can find those examples at https://ngblaylock.github.io/extract-gsheet/.

Questions?

If you have questions, drop them in the comments here, or let me know on GitHub. I hope you find this useful.

How I Set Up a Project With Eleventy

Nathan Blaylock — Sun, 15 Aug 2021 00:07:23 +0000

Introduction

This is a quick overview on my typical setup for an 11ty project. I really like how it is set up and want to share it with other people.

File Structure

.
├── assets
│   ├── favicon.ico
│   └── ... (img, pdf, etc.)
├── dist
│   └── ... (output static files)
├── node_modules
│   └── ...
├── pages
│   ├── _data
│   │   └── global.js
│   ├── _includes
│   │   ├── _footer.njk
│   │   ├── _head.njk
│   │   └── _nav.njk
│   ├── _layouts
│   │   └── default.njk
│   ├── 404.njk
│   ├── index.njk
│   ├── pages.json
│   ├── uikit.njk
│   └── ...
├── styles
│   └── style.scss
├── .eleventy.js
├── package.json
├── package-lock.json
└── README.md

Eleventy Config File (.eleventy.js)

const pluginSass = require("eleventy-plugin-sass");

module.exports = (eleventyConfig) => {
  // Copy our static assets to the output folder
  eleventyConfig.addPlugin(pluginSass, {});
  eleventyConfig.addPassthroughCopy({ assets: "./" });

  return {
    dir: {
      input: "pages",
      output: "dist",
      layouts: "_layouts",
    },
  };
};

NPM Installs and Scripts

Obviously, you need to install Eleventy. I use it as a dev dependency rather than loading it globally.

I install rimraf in order to clean my output directory everytime I build the site. By default, Eleventy won't clean out files in the output directory if you move them or delete them.

I Use cross-env to set environment variables (development or production). This is used in my global data so I can show or hide certain things depending on if I am in development mode or production. For example, I may use vue.js in development to use the browser dev tools, then use vue.min.js in production.

npm install --save-dev @11ty/eleventy rimraf cross-env eleventy-plugin-sass

I use three scripts in my package.json file.

"scripts": {
  "dev": "npm run clean && cross-env ELEVENTY_ENV=dev npx @11ty/eleventy --serve --output=dev",
  "clean": "npx rimraf ./dist ./dev",
  "build": "npm run clean && cross-env ELEVENTY_ENV=prod npx @11ty/eleventy"
}

Global Data

Using cross-env combined with the package.json script you can set an environment variable and use it in your template file. For nunjuks, just use {{global.env}}.

// ./pages/_data/global.js

module.exports = {
  env: process.env.ELEVENTY_ENV
}

Pages Global Data

One of the things that I have found a lot of people want in Eleventy is to set a default layout for the project. In Eleventy's documentation, it says that you can add a <directory>.json and it will use that data as the default data for every template page in that directory. The issue is in the root of the project you can't specify that. If you use a directory like pages as your input directory, then you can set a pages.json and use global data there. The most used one is the layout for me. Most all of my layouts should use "default". You can easily override these in the template front matter. Here is my example:

{
  "layout": "default",
  "description": "default description for project",
  "title": "Default Project Title"
}

My Favorite VS Code Extensions for JAMStack Development

Nathan Blaylock — Wed, 11 Aug 2021 04:53:10 +0000

I wanted to share some of my favorite extensions as a front-end developer. There are thousands of extensions out there, however, some of them are more useful than others. So here is my (ever growing) list in alphabetical order.

Alphabetical Sorter (Ugur Erdal)

Speaking of alphabetical order, this is a nifty extension that will quickly sort a list in alphabetical order. I find this useful with <li> where you have multiple items that need to be sorted. Just write them out, and run the extension.

Auto Rename Tag (Jun Han)

I hate going in and changing the opening tag, and then the closing tag. Once I installed this extension, there was no going back.

But hey, VS Code has this built in now.

Yeah, I know. But I have a hard time getting it to work with .vue files. It is still nice to have or know about if the built in functionality doesn't work.

Autoprefixer ( mrmlnc)

I don't use this as much anymore since I use Sass and my setup automatically autoprefixes, but it is still nice if you are just writing CSS and want to add vender prefixes automatically.

Community Material Theme (Equinusocio)

There isn't really anything wrong with VS Code's default interface styles, but I really like using this one. My favorite is "Material Theme High Contrast"

FiraCode w/ Ligatures

This isn't an extension, but it is some customization to use a different font and use ligatures in VS Code. Check out the documentation for details on how to install it.

Git History (Don Jayamanne)

Version control is awesome, but as a front end developer, I don't just want to see the code from a point in time, I want to see what it looked like. With this extension you can do a hard reset (make sure that your latest changes are committed to a remote repository). Then you can run the site like it was at that point. When you are done, you just pull the latest change from your remote repository, and you are back to where you were.

Highlight Matching Tag (vincaslt)

This does exactly what it says, if your cursor is on <div> it will find the matching </div> and highlight it. This is another one that VS Code has some built in functionality for, but I just like how this one looks.

html-entities (christopherstyles)

There is no bigger pain than writing <pre> content, to find out that everything you wrote in it was rendered as HTML on your page. With this extension, you can type it out, highlight your code, then run this extension. Now all your < and > (and others) are translated into HTML entities; < and > respectively.

Live Sass Compiler (Ritwick Dey)

I am fortunately finding alternatives for this, but in some projects it is so helpful to just have a free Sass compiler. You hit a button in the bottom of the window, and all your Sass files in your project are rendered (except the ones prefixed with _). If your project doesn't have some sort of sass compiler built in, give this a try.

Live Server (Ritwick Dey)

This will turn your project into a hot-reloaded server. As long as you have an HTML page with a <body> it will open the page in a new tab and refresh it whenever you change a file. One thing I like about it is if you have a project that doesn't have an HTML file, but something else you want to hot reload, you can combine this with the Chrome extension (made by the same person, and named the same thing), and you can connect your two sites so when you make updates to a file, it tells another tab with a specific web address to refresh.

This extension is limited For example, you can't use a subdirectory as the root. You can look into Five Server (Yannick) which is maintained and gives you different options. I haven't tried it yet, but it looks promising.

Markdown All in One (Yu Zhang)

This helps me keep my markdown files formatted well. Also, it gives you a live preview of it, which I don't use much. The formatting is really what I use it for.

Material Icon Theme (Philipp Kief)

The default VS Code icons are ugly. Use this theme and they look much better. I especially don't like the default Vue icon. It doesn't have the right colors. Maybe it was a Vue 1.0 logo?

Nunjucks for VS Code (ExE Boss)

This isn't perfect, but it is the best Nunjucks extension in my opinion (I mostly use it with Eleventy). It doesn't have code snippets, or auto formatting, so you have to configure that a different way.

Path Autocomplete (Mihai Vilcu)

In most of my projects, the files I am trying to link to are in something like a pages directory. So my about.html file would be in /pages/about.html in my project, but the actual link should be to /about.html. When you try to link to the about file the intellisense doesn't pick it up because it is looking at the root of the project. With this extension, you can tell intellisense to also look in the pages directory. Typing /abo will pop up /about.html (you do need to configure that functionality).

Prettier (Prettier)

This if my favorite formatter. You can configure a lot of things in it, and even tell it to format one file type as another (like Nunjucks as HTML).

Project Manager (Alessandro Fragnani)

Workspaces are fine, but I prefer to keep my projects managed with this extension. Think of it as a shortcut to your project that you can open in the current window or a new window.

Vetur (Pine Wu)

If you use Vue, you already know about this. If you don't, then you probably don't need it or want it.

VsCode Action Buttons (Seun LanLege)

Some people might think this is unnecessary, but I absolutely love this extension! I don't love using the command line, but I end up using it a lot for things like npm run dev or bash deploy.sh. You can skip the typing, and set up an action button for a command (which will run that command in the command line).

vscode-pdf (tomoki1207)

If you have a PDF in your window, by default VS Code won't show it. With this extension it will open up in the window just like a browser.

Vue Peek (Dario Fuzinato)

This will let you command/control + click a component and it will open up that component. Or you can just look at it inline.

Host Website on GitHub Pages (The Easy Way)

Nathan Blaylock — Sat, 07 Aug 2021 05:44:45 +0000

Ever since my first class on web development, I have loved making websites. I loved the classes, I loved learning about HTML, CSS, and JavaScript. I loved everything about it, except when it came time for publishing a website. Sure, it was nice that you can make a site, but what good is it if you can't access it on any computer. Those classes went in to this big thing on how to get a free trial from some company, that has these complex server setups, and a FTP setup that you need to configure, and then after all these steps, which you are never going to remember, you have a website. So the purpose of this post is to publish a basic static website for beginners for free with minimal setup.

GitHub

If you aren't familiar with GitHub, you should look into it. I am not going to go in depth with it here, but just know that if you are writing code, it would be worth your while to set up some version control with Git. GitHub is like your cloud storage for your code, except that you can also choose to host a static website from it as well. So if you haven't set up your GitHub account, do that first.

Create a repository

When you are in GitHub, create a new repository. For those of you who are new to this, a repository is basically just a new project. If your end goal is to host one site, you probably want to host your website at the root of your account. The URL for your site will be <username>.github.io. When setting up your repository, your repository name should be <username>.github.io so GitHub knows that you want to host this file at the root. I would recommend this for the first site you create. You can always change this later. If you name your repository anything else, like easy-hosting your site will be hosted at <username>.github.io/easy-hosting. This second example could have some issues if you ever use absolute links (ex. <a href="/about">About</a>). That will be looking for the page <username>.github.io/about rather than <username>.github.io/easy-hosting/about. We will get to a fix for this in a second.

Whichever direction you go, make sure that you use a public repository. You cannot host a website on GitHub in the free tier using a private repository.

Adding code to GitHub

There are three pretty easy ways to add code to GitHub. The first way is not what I recommend, but you can still do it. You can upload your code from your computer and just stick it in the repository. This gets clunky very fast, and is a pain to work with. Don't do this.

GitHub Desktop

The second way is to use GitHub Desktop which is a desktop application that handles all of your git commands for you, and can link your local files on your computer to your GitHub account online. When I first started with Git, I didn't know a single thing about the command line like traditional Git courses teach you. I got along just fine for a few years because of GitHub Desktop.

If you go this route, and have GitHub Desktop setup, you can choose from GitHub's website to set this repository up on your local machine from GitHub Desktop. From there it is pretty much straight forward. The app will set up your repository on your local machine and you can put your code there. Then it is just a matter of pushing your code up to your GitHub repository online.

Visual Studio Code

The third way, and my preferred way is to use Visual Studio Code. I write all my code in VS Code and love it. VS Code has a built-in Git user interface, so like GitHub Desktop, you don't need to use the command line for simple things. In the bottom left corner of the window, you can log in to your GitHub account. Sign in there. The default editor will also have more icons on the top right, and you can manage your git integration on the third one down titled "Source Control". This is very similar to GitHub Desktop, except that you don't need to leave your editor to do anything.

From here you may just need to clone your repository using the command line. Follow the instructions in the GitHub repository that you set up.

A Little Background

Those steps were a little vague, so you may need some additional help from other blogs or videos to get your code online. The point was to get your HTML files and other assets in your online repository from your local machine. Now here is where I feel like this post is different than most other tutorials. A few years ago the only way to host a site on GitHub was to have a branch called gh-pages and if you set it up, it would use files on that branch for hosting. Then they let you use your master branch as well, but only what was in the /docs directory. That isn't the case anymore. You can now use any branch, and you can use the root of that branch or the docs directory. Unfortunately, at the time of this writing, you can't choose a specific folder for hosting.

Set up Hosting

At this point, you should have a repository, a branch (probably main), and at the very minimum an index.html file in the root of the repository.

Go to your repository's settings.
In the left navigation, near the bottom, click on "Pages".
Under the "Source", change it from none to your branch (probably main). Leave the folder at root.
Save the setting. You should see a new popup that says Your site is ready to be published at https://<username>.github.io/easy-hosting/.

Your site is now live! Any time that you commit and push your code to GitHub on the same branch, your website will automatically update. It's pretty slick.

The following sections are extra information that you may or may not need, but would be good to know about.

Custom Domain

This setup I just explained got me by for a while, but remember how I mentioned absolute links? Wouldn't it be nice to setup your own custom domain and subdomains rather than subfolders? Well, you can, and it is very easy.

If you use a custom domain, be prepared to pay for it every year. It is about $12 on the low end. It isn't much, but just be aware of this.

I choose to purchase my domains from Google Domains. Go find a domain and purchase it. Once you have it purchased, go into its configuration and find "DNS" in the left navigation. Enter the following configuration so that it matches:

Host Name	Type	TTL	Data
<domain>.com	A	1 hour	185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153
www.<domain>.com	CNAME	1 hour	<username>.github.io
<sub>.<domain>.com	CNAME	1 hour	<username>.github.io

In short, the first line is your domain mapped to GitHub's servers. The second uses the www subdomain, which is pretty common. The third is to have your own subdomain. This is especially helpful for repositories like our easy-hosting repository. If we host our site on easy-hosting.<domain>.com, we can use absolute links, which will point absolute links to where we would expect it.

There is one more step to get this to work. We need to go back to GitHub and in our Pages setting. Below the branch you entered earlier, there is a section for a Custom Domain. Enter your custom domain (<sub>.<domain>.com or <domain>.com) and save it. If you go back to your repository home page and look at your code, you will see that it created a CNAME file in it with your custom domain in it. That is really all the setup that you need. It might take 20 minutes to a few hours for GitHub to configure some things in the backend. So go take a walk or something.

Static Site Generators and Single Page Applications

Maybe you really don't want to spend a penny on this, but want to use absolute links in your project. Well, there is another workaround for this, but it takes a little more experience, and I won't really cover it much here. If you are building a serious website, you are hopefully at least using a static site generator like 11ty, Nuxt, or just a single page application tool like Vue. Each of these have ways to set the root of your project using a path prefix. Here is 11ty's configuration, Nuxt's configuration, and Vue's configuration. I am sure if you are using something else, it will have a similar configuration for you.

Changing those configurations will allow you to use absolute links, and still host your site on <username>.github.io/<repository>.

While we are talking about this, because GitHub will only allow you to host from the root or docs directory, you would also want to configure your tool to output your files to the docs directory. For example, 11ty will generate the files to the _site directory, and Nuxt will output the files to the dist directory. You can get around that with 11ty's configuration, Nuxt's configuration, and Vue's configuration.

Conclusion

Hopefully some parts of this have helped some of you out there. I can't say that GitHub pages is the best place to host a website, but for beginner projects, it is the perfect place to start. It is free, easy, and configurable. If you have any questions, just let me know if the comments.

Encrypt Static Nuxt Site

Nathan Blaylock — Fri, 30 Jul 2021 18:37:06 +0000

As a JAMStack developer, I often run into limitations in some of the projects that I am working on. I find that most of these limitations can be solved by using third-party tools, and actually work pretty well. However, these usually come with a price tag, which is totally fair and cool, but when I am not making money on a project, that seems overkill. This specific project I was working on needed to be password protected. That is pretty fair. A lot of projects need to have some content behind lock and key, but JAMStack sites may not be the best or easiest way to go about this. I set out to find a way that would make it possible to fully protect content on a page.

The first thing that I looked into was using vanilla JavaScript. A lot of you are thinking right now that it wouldn't be the best option, and you would be right. I have used front-end "Authentication" by having the user put in a password and it would toggle the visibility of the information. That works in some cases where you want the content protected from the public. To be fair, only 99% of people visiting the site would even know how to dig into the JavaScript code and figure out what is going on, and even less would care to spend a few hours figuring it out. For this specific project, I wanted a little more protection than that offered.

My next stop was looking at Firebase Authentication. This is pretty sweet, and is designed for JAMStack sites like what I was building. However, the more I thought about it, the authentication wouldn't protect my static content. Firebase Authentication will only protect the content stored in Firebase, such as Firestore or RealtimeDB. So my static HTML code could still be accessed by someone who really wanted to get the data.

Staticrypt

I kept searching and stumbled accross Staticrypt. This looked pretty promising. This is based on the crypto.js library and will take a full HTML page and encrypt it. The user will then need to enter the password for the script to un-encrypt it. It sounded pretty neat. I plugged in some HTML code and a password to the site to test it out, and sure enough, it spat out an encrypted page. It looked promising enough to look further into.

Website Build Tools

The next step was to look at what type of website building tools I wanted to use. I was testing Staticrypt with the CLI and thought for sure that I was going to need to use a single page application, because it would only encrypt one file. But then I found this little snippet and that changed a lot:

find . -type f -name "*.html" -exec staticrypt {} mypassword \;

That script when ran in the terminal will find each HTML file in your directory and encrypt it. With that, my first thought was to use Eleventy. I really am a big fan of Eleventy. I had a grandiose idea one day to make something that wasn't nearly as cool or easy to use as Eleventy. I started playing with some scripts and a test Eleventy page, and found an issue after a few hours of work. When you encrypt each HTML page, you need to pass in a password for each page you navigate to. So I tried a few workarounds like storing the password in the users localstorage, and on each page, populating the input and submitting the form. It was a little glitchy, and it certainly didn't have a good user experience with the quick flashes of a password page. So I tried something new.

Nuxt to the rescue!

I am a really big fan of Vue, but I really like developing with it using Nuxt. I especially like the auto-routing based on your directory structure, the auto-importing components, and a lot of other awesome modules that are easy to incorporate. This would have been a lot easier project to set up if I just created a Vue project, but I like developing with Nuxt so much that I went through some extra hassle with the setup that I want to share with others. Keep in mind, this is not the cleanest or best solution, and there is room for improvements. So if you find a better way of implementing it, let me know in the comments.

Starting a Nuxt Site

This assumes that you have some prior knowledge with Nuxt.

Create a standard Nuxt site: npx create-nuxt-app nuxt-encrypt (When asked for the deployment target, use static).
Create multiple Nuxt pages (ex. about.vue, cool.vue) and add some simple navigation.
Test out the site with npm run dev.

So that is the quickest Nuxt site I know how to setup for this. Running the project in development mode will hot reload the project.

Adding Staticrypt

Warning: I have only tested this on a Mac and Linux using the standard terminals. If you are on Windows, you may need some modifications. Let me know in the comments if there are better cross-operating system alternatives.

Install Staticrypt: npm i staticrypt.
Add a new file to the root of the project called remove-unencrypted.js.
Adjust the package.json scripts section.

package.json Snippet

{  
  "scripts": {
    "dev": "nuxt",
    "start": "nuxt start",
    "generate": "nuxt generate && npm run encrypt && npm run remove_unencrypted",
    "encrypt": "cd dist && find . -type f -name '*.html' -exec npx staticrypt {} custompassword \\;",
    "remove_unencrypted": "node remove-unencrypted"
  },
}

remove-unancrypted.js File

const path = require("path");
const fs = require("fs");

const listDir = (dir, fileList = []) => {
  let files = fs.readdirSync(dir);

  files.forEach((file) => {
    if (fs.statSync(path.join(dir, file)).isDirectory()) {
      fileList = listDir(path.join(dir, file), fileList);
    } else {
      if (/\.html$/.test(file)) {
        let src = path.join(dir, file);
        fileList.push(`./${src}`);
      }
    }
  });

  return fileList;
};

console.log("\nReplacing Encrypting Files...\n")

filesArray = listDir("./dist");
module.exports = filesArray.forEach((file) => {
  if (file.includes("_encrypted")) {
    console.log("Replaced ", file);
    fs.rename(file, file.replace("_encrypted", ""), (err) => {
      if (err) {
        console.error(err);
      }
    });
  }
});

Generating Static HTML Files

This works pretty good straight out of the box. When we run npm run generate it will do a little more than just generate static files. The first command, nuxt generate does the standard generate command, and turns everything into a static HTML page and places them in the dist directory.

The second command, npm run encrypt will encrypt each one of those HTML pages in the dist directory. Note that in the encrypt script, this example sets the password to coolpassword. You can change this to be whatever you want. It should be a string with no spaces.

The third script is to remove the unencrypted files. If you miss this step, what happens is it will encrypt the contents of one file, then save it as a copy. For example, index.html -> index_encrypted.html. This is what the remove-unencrypted.js file does. It will recursively go through your project, find any HTML file with _encrypted in it and rename it, which in turn replaces the original file. I don't have much experience writing Node files, so there might be a better script out there for this, but my script gets the job done.

Previewing your Files

Running npm run generate should leave a few cues in the console on what is going on. Hopefully you don't get any errors. Once those three commands are finished, then you can run npm run start. This starts the files in your dist directory in it's own server. You should see when you go to your localhost page that you are now prompted with a password. Enter the password you set in the encrypt script (in this case, coolpassword), and you should have access to your content! Just for fun, look at the source code for the file loaded in. There will be no trace of your original code. It will just be the password page, and a bunch of gobbledegook. That gobbledegook is your content.

Remember how I said that I tried this with 11ty first? My issue with 11ty was that on every page, we needed to put in a password? Well, with Nuxt, we don't need to worry about that. Nuxt does create an individual page for each file, but once you open the file, the SPA side of Nuxt takes over. That means that navigating to new pages doesn't do a new HTTP request, but loads in the content via JavaScript.

There is a caveat to this. Be sure that when you use page navigation, you use <nuxt-link> rather than an <a> tag. If you use the <a> tag, then you might as well just use something like 11ty, and figure out a workaround for the password prompt every time.

Limitations

There is always going to be some issues with everything. For example, since this page is loaded in via JavaScript, you will notice that the code for each page is technically in a JavaScript file, and that DOES NOT get encrypted (as well as images or other files). The JavaScript files are obscurely named, and I do not see them in the sources in a browser console, so I figure it is pretty safe. Staticrypt also mentions that it isn't flawless, so they don't recommend putting very sensitive things like banking on there. So take a deep look at what it is that you are protecting. Maybe you just need to pay a company for a better solution. For me, and my project, this works just fine.

Bonus: Customizing the Password Page

You can also modify the HTML password protected template page to your liking. Staticrypt's documentation shows this:

  -f, --file-template  Path to custom HTML template with password prompt.
                          [string] [default: "[...]/cli/password_template.html"]

If you go into your node-modules and find that password_template.html file, you can copy that to the root of your project and modify it. Then change your encrypt script to:

"encrypt": "cd dist && find . -type f -name '*.html' -exec npx staticrypt {} coolpassword -f=../password_template.html \\;",

Running npm run encrypt will then use your password template from the root of your project instead.

Conclusion

So, if you are looking for a simple way to password-protect your static website, consider using Staticrypt with Nuxt. It is easy to set up for basic usage, and produces a pretty secure website.