Create A Static Site Using 11ty & Deploy to Neocities (2026 Refresh)
What’s going on, Internet? Way back in 2022 I wrote a guide on building a static site with 11ty and deploying it to Neocities . It’s been one of my most-read posts, but it’s also aged: Eleventy has moved to v3 with a brand new module system, the dev server changed, and my whole workflow has shifted away from GitHub toward Forgejo and Codeberg . So here’s the refresh. I haven’t hosted my own site on Neocities for years now, but it’s still home to a huge community of personal sites and homepages, especially folks in the 32-Bit Cafe , so this guide is still very much for them. This guide aims to help you create a homepage using the static site generator (SSG) 11ty , keep the code in version control, and deploy it to Neocities , first by hand, then automatically. The homepage that we are creating will take advantage of the Nunjucks templating language, allowing us to create a shared header, navigation and footer across all the pages on our homepage. We will be creating an about, links, and contact pages before diving in and creating the ability to add a blog and a list of all blog posts on the blog page! We will structure and style the page with a standard HTML5 boilerplate and some basic CSS that should allow you to add in your unique flavour that we all know you love to do. This guide assumes the following: First off, from a terminal, confirm that you have Node and NPM installed: Create a new directory and cd into it: Initiate a new project: Install 11ty: Once the 11ty installation is complete, open the project in your favourite code editor: You should now be in VSCodium with the following project structure: Open and update the scripts section to the following: We also need to tell Node that this is an ESM project. Add to . The file should look like this: The line lets us use modern / syntax in our config and JavaScript files. The script lets us run to serve our homepage with hot-reload, provided by Eleventy's built-in dev server. Every time you save a change in VSCodium, the browser reloads with your most recent changes, amazing! From the terminal (or VSCodium), create a new file at the project root: Open the file in VSCodium and add the following and save: This configuration file tells 11ty what to do. Setting the directory to tells 11ty where to look for changes, this is our working directory. When changes are detected, 11ty builds the site and outputs it to the directory which is where the static html/css/img files are served from, amazing! As we’re going to be keeping our homepage code in version control, create a file in the project root: Open the file in VSCodium and add the following and save: The .gitignore file is a text file that tells Git which files or folders to ignore in a project. In this case, our file tells git to ignore the directory and the directory where our static files are built locally. Now comes the fun part, building our homepage. 11ty supports a number of templating languages, but the two you’ll reach for most are Markdown and plain HTML. Markdown is the popular choice for content like blog posts: you just write, without tags getting in the way. HTML is handy when you need precise structure. The best part is you can drop HTML straight into a Markdown file and 11ty renders it correctly, so it’s never one or the other. For the pages that make up the site’s structure (home, about, links, contact) we’ll use HTML, because it maps neatly onto the layouts and partials we’re about to build. When we get to the blog, we’ll write the posts in Markdown, where it shines. Use whichever fits the job. Create a directory at the project root and cd into it: Create an file in the terminal or VSCodium: Open the file and add some content: Now from the terminal start 11ty: If everything has been configured right so far you should see the following: Now you can open up and check out your new 11ty homepage! It should look like this: A Basic Hello World HTML Page Amazing! But what we want to avoid is having to write out the and and tags on each and every page, and be able to include a site header, navigation and footer so we don’t have to copy and paste the changes across every page each time we update. Let’s checkout templating a layout! Create a new directory in the directory and cd into it: Create a file in the terminal or VSCodium: Open the file and add the following: We've created as a Nunjucks template file, hence the file extension. This means we can use Nunjucks' double curly braces for using frontmatter variables. In our layout template we're calling and . Now, head back to the file you created earlier, delete the contents and add some front matter and some content: If you’ve kept 11ty running and the browser running it should look like this: A Basic Hello World HTML Page Using a Template Amazing! Now lets create the additional pages for our homepage. Create the following pages in the directory with the terminal or VSCodium: Open each of them up and add in some front matter and content: about.html: links.html: contact.html: You should now be able to browse each of these pages if you kept 11ty running on the following urls: Great stuff, but that’s no use without a navigation! Let’s take a look at and create a shared , , and to bring our homepage together. In the terminal cd into and create three partial files: Open each of them up and add some content: header.njk: navigation.njk footer.njk: Once our partials are created, open again and update it to include our new elements and partials: If you’ve kept 11ty running and the browser running it should look like this: A Basic Hello World HTML Page Using a Template and Partials Amazing! Now lets add the blog. Blog posts are mostly prose, so this is where Markdown earns its keep. We’ll write the posts as files and let 11ty turn them into pages. Create a new directory in the directory and cd into it: Create the following files in the directory with the terminal or VSCodium: Awesome, Open each of them up in VSCodium and add the following: my-first-post.md : my-second-post.md : my-third-post.md We better create a blog layout so it renders! Head back to the directory to create a new layout file: Open up in VSCodium and add the following: Check that your blog posts are loading: Amazing right? But to make it a blog, we need a blog page that lists all of our blog posts. We can do this with a collection: Open again and add a key called with a value of : Now 11ty has created a collection called and all we have to do is list it. Head back to the directory and create a file: Open it and add the following: If you’ve kept 11ty running and the browser running it should look like this: A Basic Blog List Page Amazing huh? Great, so far we have a fully functional home page, but it doesn’t look quite right. We need a style sheet. You can use the one below as an example, it’s basic styling with some modern techniques, or just throw in your own! Create a new directory in , cd into it and create : Open in VSCodium and add the following: styles.css: Now we need to include the style sheet in our layout file. Open it up and add to the : _includes/base.njk: You would have noticed that the stylesheet hasn’t been applied, we have to do one more thing in , something called file passthrough copy. Open in VSCodium and add the following: Because this will come up we may as well create the directories and add in the configuration for our images, fonts and JavaScript files. Create the following directories in : Update again: Just make sure you put all your static files in the appropriate directory and you’ll be good. So finally, if you’ve kept 11ty running and the browser running it should look like this: A Nicely Styled Homepage Yours will look a little different depending on the colours and fonts you chose above. Now we have a homepage we’re happy with, let’s get it online. There are two ways to get your site onto Neocities. We’ll start with the simplest, pushing it from your terminal by hand, then automate it so a deploy happens every time you commit. Whichever method you choose, first build a fresh copy of your site: This writes the finished HTML, CSS and assets to the directory. That’s the folder we deploy. Neocities provides a command-line tool that lets you push your site straight from your terminal. It’s a Ruby gem, so you’ll need Ruby installed. The first time you run a command it’ll ask for your Neocities username and password, then store an API key locally so you don’t have to log in again. Push the contents of your directory: That’s it, your homepage is live. For a lot of people this is all you need. Build, push, done. Pushing by hand is fine, but it’s even nicer to have your site rebuild and deploy itself every time you commit a change. We can do that with Forgejo Actions , the built-in CI for Forgejo. If you self-host Forgejo this runs on your own runner; if you don’t self-host, Codeberg offers the same thing (more on that below). First, push your project to a repository on your Forgejo instance. Then grab your Neocities API key from your account settings (Manage Site Settings → API Key) and add it to your repository as a secret named (Repository → Settings → Actions → Secrets). Now create a workflow file at : A few things to note in this workflow: Commit and push the workflow file. From now on, every push to rebuilds your site and deploys it to Neocities automatically. If you don’t run your own Forgejo instance, Codeberg is a free, community-run home for your code and runs the very same Forgejo Actions. The workflow file above works as-is. Push your project to a Codeberg repo, add the secret in the repository settings, and you’re away. You may need to enable Actions for your repository first; see the Codeberg CI documentation for details. Already have a homepage you’ve been hand-coding on Neocities? You don’t have to start from scratch. Eleventy is happy to take what you’ve got and slot it into this structure. Copy each existing page into (your old becomes , and so on). Then move the parts every page repeats, the , header, nav and footer, into and the partials you built earlier. Delete that boilerplate from each page and add a little front matter at the top: Whatever’s left in the file is just that page’s own content, and the layout wraps it. Your CSS goes in , images in , and fonts in . The passthrough copy we set up earlier ships them straight to . If a page is mostly writing, paste the body into a file instead of . Any fiddly HTML, like an embed or some custom markup, can stay exactly as it is and 11ty will render the Markdown around it. Run , check looks the way you expect, then push it live with the Neocities CLI or your Forgejo Actions workflow. Same site you already had, now with layouts, partials and a build step doing the repetitive work for you. Reference: I created the original version of this guide based heavily on these existing guides, and they’re still well worth a read: Without these, I wouldn’t even know how to write down what I needed to. Hey, thanks for reading this post in your feed reader! Want to chat? Reply by email or add me on XMPP , or send a webmention . Check out the posts archive on the website. You have a basic understanding of HTML and CSS You have a basic understanding of the command line and terminal You have Node.js installed (version 18 or newer) You're using VSCodium as your editor You have a Neocities account You have somewhere to keep your code: a Forgejo instance or a Codeberg account http://localhost:8080/blog/my-first-post/ http://localhost:8080/blog/my-second-post/ http://localhost:8080/blog/my-third-post/ picks the runner label. This is the default on Forgejo and Codeberg. Actions are referenced by their full URL. The checkout and setup-node actions come from , so we stay off GitHub for those. The deploy step uses , which is hosted on GitHub. We're only using it. Your code still lives on Forgejo or Codeberg. The option removes remote files that aren't in your new build, the same as on the CLI. Create Your First Basic 11ty Website Itsiest, Bitsiest Eleventy Tutorial
Entertainment
Culture
Music
Books
Writing
CSS
HTML
Web Development
JavaScript
Tutorial
Open Source
C#
Design
iOS
Hardware