wiwi blog

My Neocities workflow: using Eleventy and the CLI to speed up development

Table of contents

Introduction

I see so many people on Neocities build their websites by editing their files directly in the Neocities.org text editor. Anytime they need to change their layout, they painstakingly copy and paste the changes across each individual page file. If this is you, then you may be wondering if there is a faster way to do things. And I'm here to tell you that there is! It's MUCH faster and will probably only take you a few hours of initial setup. IMO, that is worth it to save you countless hours in the future.

I'm going to walk you my personal Neocities workflow from the perspective of a total beginner to Eleventy, because that's what I was when I started using it! It might seem intimidating, but once everything "clicks," you will be so glad you made the switch. At least I was, because I can spend less time editing menial things and more time writing my actual content.

The advantages to this workflow include:

The disadvantages to this workflow include:

Please note that this blog post assumes you already have some familiarity with HTML and CSS. You don't need to be an expert, but you must understand the basic structure of a web page and the common tags that are used.

If you'd like to proceed, then let's get started! 💪

WTF is Eleventy?

Eleventy is a Static Site Generator (SSG). It works something like this:

  1. You create a layout template (or several!) for your site. It will contain everything except for the actual main content of the page. The <head> contents, navigation, header & footer, scripts...etc.
  2. You create a bunch of Markdown or HTML files containing the main content for each page of your site. You add a bit of front matter to those files telling it which layout template to use.
  3. You tell Eleventy to smack those two things together. It inserts the content into the appropriate spot in your layout template and spits out a bunch of finished HTML files.
  4. Your site is ready! Now you just have to upload the files.

Anytime you want to make changes to your site layout, you only have to edit that one template, and then the changes are reflected across every page using it! Like magic. 🪄

There are many other SSGs out there, such as Hugo and Jekyll, that you may wish to try for yourself if Eleventy doesn't jive with you. But I tried a few and found that Eleventy was the easiest to figure out. Unlike some other SSGs, it allows you to use whatever file structure you want, and you can save your local site directory pretty much anywhere on your computer. I have mine in my Documents; you may want to use your desktop or another location. With Eleventy, it doesn't matter!

Stuff to install

Setting up Eleventy

If you'd prefer to follow the official Eleventy documentation, that can be found right here. I'm going to repeat a lot of the same information, but explained much slower and in simpler terms based on my own experience trying to figure it all out. The official documentation is best for people who already know what they're doing; this guide is super hand-holdy and will tell you what you need to know from the average Neocities user's perspective (ie. a self-taught, hobbyist developer). I am basically writing down the documentation I wish I had when I got started to make it easier for others, if that makes sense!

Most things in this section of the post will only need to be done once. Later, I will cover the basic workflow that you'll use every time you go to edit your site.

Creating your site directory

First, if you already have a Neocities site, download everything. You can do this by clicking "Download entire site" at the bottom of the page on your Dashboard. Unzip the downloaded site and save it somewhere accessible; you'll be copying and pasting a lot from your old files to convert everything to Eleventy. (This also creates a backup for you in case anything goes wrong with the conversion.)

Next, create your new website directory (the local folder where your site lives from now on). As mentioned, this can have any name and be saved anywhere. I called mine whionadotme and saved it to my Documents folder.

Open up your new directory and copy the full local address. You can do this by clicking inside the little folder trail at the top of your file explorer window, highlighting all the text, and pressing CTRL+C. On Windows it will look something like this:

An example of a directory address in Windows

I recommend saving that directory address to a sticky note or a text file on your desktop for later access.

Now, open your command line interface (CLI) of choice. There will probably be a program called Terminal on your computer by default. If you're on Windows, you may have installed PowerShell 7 earlier. Open either of those, or a different CLI if you prefer.

If you've never worked in the command line before, it might seem really intimidating, but don't worry! I will tell you exactly what to type. There are only a small handful of commands you need to know to use Eleventy.

You want to type the following and then press Enter (don't include the square brackets):

cd [paste your local website directory address here]

For example, I wrote this in PowerShell 7 and pressed Enter:

An example of how to change to your site directory in PowerShell

"cd" stands for change directory. We are telling the CLI to open our website directory, so all of the changes we're about to make will affect that folder. Makes sense, right?

Now we have to create a file called package.json. You don't have to care about what it does; it just needs to exist. This can be easily done by typing the following into your CLI and pressing Enter:

npm init -y

Now, you can install Eleventy to your website folder by entering this:

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

Test out your installation by entering this:

npx @11ty/eleventy

If everything worked okay, the command line will tell you that 11ty wrote 0 files in however many seconds. Hooray! You're ready to start converting your existing site, or making a new one if you're starting from scratch.

The npx @11ty/eleventy command is one you'll want to remember. This is the basic Eleventy command that tells it to do what I explained earlier: smack all your content files and layout files together and spit out the site. Every time you want to generate your site, you will run this command (after changing into your site directory first! But I'll show you the basic workflow later, after all the setup stuff).

If you open your website directory in the file explorer, you should now see that it's no longer empty. (Looks like these folders don't get generated until you make your first HTML or Markdown file -- sorry for the earlier misinfo!) There's some stuff in there you won't ever have to touch or worry about, but DO make a note of these two folders:

  1. _site: This is your output folder. The finished files that you will upload to Neocities later go here. You won't need to manually edit anything in here unless you need to delete an old file; if you remove a page from your site, Eleventy will not "prune" the output folder for you. Otherwise, all your editing will happen inside your main directory and then Eleventy will automatically drop your completed website into _site for you.
  2. _includes: This is your layout folder. Anytime you create a new layout template to use with Eleventy, you will save the file in here.

A note on relative file paths

From now on, whenever you edit your website on your computer, you need to make sure you are using relative file paths instead of absolute file paths for any files within your Neocities site. (External websites and files can be linked as normal.) As always, w3schools has a guide that I would advise reading.

When you link to a page, insert an image, include a stylesheet, etc., don't include your Neocities URL at the head of the file name. Instead of typing this:

<img src="https://mysite.neocities.org/images/picture.png">

You would type this:

<img src="/images/picture.png">

Why do we need to do this? Because when we're testing our website in the browser (more on that later), we want to load the up-to-date local files that we have just edited, not the old files that are currently uploaded to Neocities.org. Relative links will work on both your local preview and when the files get uploaded to Neocities; it just tells the browser where to go within the current URL. It's also good practice because your site won't break if your URL ever changes.

Tip: Need to create a relative link to your site's homepage? Just link to /! That little slash indicates the root, or the highest-level folder, of your site. That's also why, when using relative file paths, adding a slash at the beginning of the path tells the browser to go back to the root folder first and then look for the specified file. (If you don't include the slash at the beginning, then it will search for the file within the current folder.)

Bear in mind that if you're editing your site in Visual Studio Code and you link to a webpage, it might prompt you to add .md or .html at the end of the file path. You actually don't want to do that because of the way that Eleventy works.

In your output folder (_site) you will notice that Eleventy actually turns all of your pages into folders with a matching name and an index.html file inside. Why does it do this? Because the resulting URL will look cleaner in the browser. Instead of a URL that looks like this:

https://mysite.neocities.org/about.html

Eleventy will make your URL look like this:

https://mysite.neocities.org/about

It just looks a bit cleaner and nicer! So when you're creating your relative links, don't include .md or .html at the end of any pages. Just link to /about (or whatever the URL is) and it will work perfectly.

Creating your layout template

Go into the folder you downloaded from your Neocities dashboard--the one that has your existing site in it. Open any file that contains the layout you want to use as a template. Copy all of the HTML in that file. If you're making a brand-new site instead of converting a pre-existing one, now is the time to code yourself a layout or grab a free layout from the 'net. I have several mobile-friendly ones listed on my Web Developer Links page.

Go back to your new site directory and open the _includes folder. Create a new file and name it whatever you want, but give it a .njk extension (as opposed to .html or .md). For instance, my main layout template is called main.njk. We are using the Nunjucks templating language in this tutorial; you can also use Liquid if you prefer. It doesn't matter. (If you don't know what any of that means, don't worry about it, because I'll show you what to replace and where. I barely know Nunjucks and I got all this working. 🤷‍♀️)

Open your new .njk file in your code editor. Paste in the HTML from your existing layout. There are just two sections we are going to replace with a bit of Nunjucks code: the page title and the main content of the page.

First, find the <title> tag in your site's <head>. You are just going to replace whatever the page title is with {{ title }}. Like so:

<title>
{{ title }} | Your Site Name
</title>

You don't have to add a pipe (or another separator) and your site's name after the page title, but it's a good idea. It will make it easier for your visitors to tell what website the page belongs to when they see it in their tabs, browser history, or bookmarks.

Next, find the main content section of your page. If you're using semantic HTML, this will be the body text inside your <main> tag. If you're not using semantic HTML, this is a great opportunity to start! It's a very easy conversion if you're already using <div>s to contain your major site components. Our bestie w3schools has an introductory guide, and I wrote more about its importance and converting your existing content in a previous post. But anyway, back to Nunjucks--find the content inside your <main> tag (or other main content element) and replace it with {{ content | safe }}. Like so:

<main>
{{ content | safe }}
</main>

That's it! Everything else left in your .njk document now becomes your layout template. You can edit your header, navigation, and footer all in this one file and have it update on every page when you build your site. You can replace even more stuff with Nunjucks code, but for my site this was all that was necessary.

At this point, if you have multiple site layouts, you can go ahead and create even more templates using the process I described above. For instance, I created layouts for my WoL's section of my website and my fanfiction pages. Remember: they must be stored in the _includes folder of your site directory, and they must use a .njk extension (if you're using Nunjucks, as in this tutorial).

Creating your pages

Creating a new page with Eleventy is extremely easy. Just create a new .md or .html file in your site directory (not the _site folder--remember, that's for output only) depending on whether you'd like to write your content in Markdown or HTML. Be sure to name it according to what you want the URL path to be. So if you want this to be your /about page, name the file about.md.

If you want to organize your pages into subfolders, just create a new folder inside your site directory with the appropriate name and drop your files in there. Remember that this will be reflected in the URL path; a page called music.md in your my-creations folder will turn into /my-creations/music on your website.

Open your new file in your code editor. We will just need to add a little bit of front matter to tell Eleventy which template to use and what the page title is. All the front matter is contained between two rows of three dashes:

---
title: About
layout: main.njk
---

Replace the title with whatever you want to appear in the title bar of the user's tab/window, and the layout with the appropriate file name from your _includes folder. If you have multiple layout templates in there, this is where you tell Eleventy which one you want to use. (Even if you only have one layout, though, you still have to declare it in the front matter.)

Then, pop in a level 1 header with your page title and get writing! Use Markdown or HTML to craft your page content as desired. Everything will be parsed to HTML and inserted wherever you placed {{ content | safe }} in your layout template earlier.

If you're using Markdown, you can still add HTML and Javascript snippets to your page. Just make sure that any differing types of code are separated by two line breaks. Here's what an example page might look like in Markdown, with HTML snippets added:

---
title: About
layout: main.njk
---

# About
I am a knitter and dog-lover who lives by the sea.

## My favourite shows
- Breaking Bad
- The Sopranos
- Bluey

<details style="text-align:center;">

<summary><strong>Show more</strong></summary>

Oooo I can combine **markdown** with *HTML* oooo

</details>

Thanks for visiting my site!

This is where magic of Eleventy truly becomes apparent! Anytime you want to create a new page, you just need to add those couple of lines of front matter and start writing. No hassle, no fuss. And IMO, Markdown files are much easier to edit than HTML when it comes to text-heavy content. You can even edit your content in a dedicated Markdown editor of your choice (I'm a fan of Deepdwn and IA Writer) and paste it in once you're done.

Here's another cool thing: you actually don't have to add any front matter if you want to directly include an HTML file in your site as-is. For instance, my Pets page on my website uses a unique layout that isn't replicated anywhere else on the site. It's kind of pointless to go through all the effort to create a layout template that will only be used once. So instead, I coded it as a standalone HTML file with no front matter and dropped it in my website directory. Eleventy will transfer any HTML files without front matter as-is and include them in your _site output folder. Nifty!

At this stage in the tutorial, you can copy & paste any main body content from your existing site into new page files in your site directory. Remember to include the front matter if you want to use a layout template! I opted to re-format my content from HTML to Markdown at this point for easier future editing, but you don't have to. It might be more of a hassle than it's worth if you have a lot of pages to convert.

Including images, stylesheets, and other assets

This is the last major step in your Eleventy conversion, promise!

At this point, the last thing we need to add to our new site directory is...well, everything else. Your site probably has images, .css files, and perhaps some custom fonts or other assets that need to be imported. Eleventy will automatically include any .html and .md files saved to your site directory in the _site output folder, but for everything else, we need to tell it to include those too. It just requires a teeny bit of Javascript--and as always, I'll tell you exactly what to write. You don't have to actually know Javascript (I don't).

So first, drop any assets, stylesheets, etc. that you need into your site directory. You can sort them into whatever folders you want. I have all my images in a folder called--you won't believe this--/images and my fonts in--wait for it--/fonts. My main layout stylesheet just hangs out in the main directory, and other stylesheets are sorted into the appropriate folders for their section of the site. Organize things however it makes sense to you.

Now, in your main site directory (don't sort this one into its own folder) create a new file called .eleventy.js. Open it in your code editor.

Copy and paste this:

module.exports = function(eleventyConfig) {  

  eleventyConfig.addPassthroughCopy("style.css");
  eleventyConfig.addPassthroughCopy("fonts");
  eleventyConfig.addPassthroughCopy("images");
  eleventyConfig.addPassthroughCopy("robots.txt");
  
  };

See how I wrote that line that says "add passthrough copy" over and over? You just need to replace the text in quotations with whatever folders and files you want Eleventy to include in your _site output folder. You can write the folder name to include every file that's in there, or include individual files by adding the file name + the extension. Here are some examples of how you would format this:

eleventyConfig.addPassthroughCopy("folder");
eleventyConfig.addPassthroughCopy("folder/subfolder");
eleventyConfig.addPassthroughCopy("file.css");
eleventyConfig.addPassthroughCopy("folder/subfolder/anotherfile.mp3");

Remember, anything that's not a .html or .md file needs to be included. Images, fonts, stylesheets, text files, audio, videos, Javascript--pop them all in your .eleventy.js file. If you want, you could even create a big folder called "assets," dump everything you want to include in there, and tell Eleventy to add a passthrough copy of the folder. I just don't personally like that from an organization perspective, but it's up to you.

You do not need to tell Eleventy to include any .njk layout templates in your _includes folder. Those will be combined with your content files automatically and don't need to appear on your finished site.

Save your .eleventy.js file when you're done. At this point, we can actually start to build our site with Eleventy and test it in the browser! Hooray!! The setup is complete. Pat yourself on the back for making it this far.

Testing your site in the browser

It's time to hop back into the command line. Open your CLI and cd into your site directory. In case you need a refresher, you're typing this:

cd [paste your local website directory address here]

If you're using PowerShell 7, you might also notice that when you type cd, it suggests the rest of what you entered earlier! This is why I like it as my CLI. Just press the right arrow key to autocomplete with the suggested text and hit enter. No copy & pasting needed this time. 🙂

Now you'll run the main Eleventy command, with a little extra line at the end:

npx @11ty/eleventy --serve

By adding --serve we are telling Eleventy that we want to preview our site on a local server. After running the command it will tell you there's now a server at http://localhost:8080. Open that link in your browser to see your new site's live preview!

So long as you keep your CLI open, Eleventy will watch all of the files in your site directory for any changes. Whenever you hit Save on a file, the live preview will update with whatever you just wrote. I have a big monitor, so I like to tile my editor and my browser side-by-side to quickly watch my changes happen. It's a game-changer for editing your pages!!

It's very likely that you'll need to do some file cleanup at this point; some or all of the links, images, and stylesheets in your live preview might be broken because they've changed locations during the conversion process. You'll need to comb through your site files and make sure that all your file paths are correct. Remember what we discussed earlier with relative file paths! Make sure that everything points to the correct spots in your new site directory.

If you are having trouble getting images, stylesheets, etc. to work and you're certain you've used the correct file paths, make sure that you have configured your .eleventy.js file properly!

When you're satisfied with your new site and finished editing, go back to your CLI and press CTRL+C. This will tell Eleventy that you want to stop hosting the local server. If it asks "Terminate batch job?" just type Y and hit enter.

At this point I like to make sure I've saved any changes in my code editor and run the npx @11ty/eleventy command one more time. This makes sure everything in the output folder is good to go.

Now we can upload our finished site to Neocities! You can drag and drop the files, but there is an even easier way to do this. I'll show you how to set up your CLI so that you can upload your entire site with a single command.

Using the Neocities CLI

Firstly, if you were converting a pre-existing Neocities site to Eleventy, now is the time to remove all your old files from Neocities.org. Make sure you have a backup of your site saved before doing this.

As with the Eleventy tutorial, there is official documentation available from Neocities for this. I will be explaining the info in a more simplified, hand-holdy way.

Open a fresh CLI window. The first time we use the Neocities CLI, we'll have to install it by entering this. Make sure you installed Ruby earlier or it won't work.

gem install neocities

If you get a permission error, type this instead to run it as an administrator. It may prompt you to enter your computer account password.

sudo gem install neocities

Now, when you enter neocities into the CLI, it will give you a list of commands to manage your site. Run a random one for now so it will prompt you to enter your Neocities username and password. You can just do neocities info or something.

After you've entered your Neocities login, you're ready to go! Here's how to upload your entire _site output folder to Neocities in one go:

neocities push [your site local directory address]/_site

For instance, my command looks like this:

An example of how to push your site folder to Neocities

It's very important to include /_site at the end of your directory address. We don't want to push those raw Markdown files and template files to Neocities; we only want to upload the completed files where our content and our layouts are joined together.

Wait a couple of minutes for everything to upload--you can watch the progress in your CLI. Once it's all done, congrats!!! Your new site is uploaded.

Finally: The basic workflow!

Now that I've exhaustively explained everything (sorry for the length...) here is a list of the steps I take every time I edit my site.

  1. Open the CLI and cd into my site directory.
  2. Run npx @11ty/eleventy --serve and open http://localhost:8080 in my browser.
  3. Optional: I like to tile VS Code and Firefox side-by-side to watch my changes happen anytime I save a file.
  4. To create new pages, I just make a new .md or .html file in my directory. To edit my layouts, I open their .njk files in the _includes folder and make whatever changes I'd like.
  5. When finished, press CTRL+C in the CLI and respond Y to the prompt.
  6. Save everything in my code editor and run npx @11ty/eleventy again to make sure all changes are reflected.
  7. Use the neocities push command to upload my site.

That's it! All that setup may have been a chore, but now the process of making new pages or changing my layout is way faster. Not only that, but I can test all of my changes on my machine before letting the WWW see them.

Conclusion

I hope that this beast of a post was useful to at least somebody out there. If you're a Neocities user with any further questions, feel free to email me and I'll see if I can help. I'm no expert, but I managed to get all this stuff working, so I guess that's something??? I'd rather not provide tech support for the wider internet, though--sorry.

You can also feel free to email me if anything in this post is egregiously wrong. Disclaimer that I'm not a pro, I'm just recording what I personally do, and what ought to work for fellow hobbyists on Neocities.

Like this post? Leave a kudos:

Recent posts