← Back

The Neocities logo: a cat wearing a hard hat with a wrench in one hand and a paintbrush in the other.

How to build a Website on Neocities.

This site is hosted on neocities.org. The name is a callback to geocities, which was a web host popular in the 1990s and early 2000s that allowed people to make free personal websites, At the time, this was the main way people had an online presence. Everything was written by hand in HTML, so every site looked quirky and different and was laid out in its own way. People had control over their experience using the web. But it was not long before the invisible hand of Mammon took hold of the web that was, to be devoured and replaced with the corporatized, ad-ridden, algorithmically-filtered, AB-tested, SEOed, surveilled web that is.

Neocities is an attempted revival of the old web which incorporates some features from Web 2.0 such as profiles with comments and followers. Otherwise it’s basically the same as geocities: you can make a website for free in plain HTML.

What to put on your website

Your website can contain just about anything: essays, art, memes, short quippy jokes… whatever.

If you want to make a website but don’t have anything in particular you want to put on it, the easiest thing to do is to curate links to other content online (for example). This helps reduce people’s dependency on algorithms for discovery.


Neocities hosts static websites. This means that you produce the HTML yourself, you upload it, and then Neocities serves exactly what you upload. This way of hosting contrasts with the more common dynamic hosting, where you write some code in a language like PHP or python which the server executes to produce HTML pages on request.

Static websites have a major advantage, which is that they’re fast and they work anywhere, with no config. But they pose some challenges. For instance, what do you do if you want a header to appear on every page on your site? Do you just copy and past code a bunch of times, and then manually edit every page when you want to change something? That sounds laborious.

A lot of programmers these days handle this using static site generators. These are programs that put together a bunch of pages according to rules and save them to HTML files that you can upload to a static host. This is a great way to make websites, but I recommend against using them on Neocities (edit: when starting out. See the addendum). Why? Well, they go against the spirit of a web host like Neocities, which is about reviving the feeling of the old web, where everything was weird, a little ugly, and written by hand.

On Neocities, you should write your html my hand in a text editor. So is my suggestion to just copy code all over the place like I said? No. You don’t necessarily need uniform pages. For instance, I think it’s much better that my Song of Satan poem is styled differently than my satirical fanfiction. And when you do want consistant style, you should just keep your pages simple enough that you can accomplish it by including one css file across pages on your site with just one line: <link rel="stylesheet" type="text/css" href="style.css">.

This can be a little hard to keep organized, but one trick is to just keep all the pages in your site on the top-level. So every page should have a url like https://{username}.neocities.org/{page}.html. Then you can link to any other page on your site by name, and you can link you your home with just index.html. This also makes it easy to keep a working copy of your site on your own hard drive, because most servers will do special tricks to serve /page/index.html when given the url /page, but your filesystem isn’t that smart. If you always link directly to html files though, that’s no problem.

Addendum February 2022

I’ve started using a static site generator for this site, because I maintain other sites using one and am feeling the need to adopt a consistent workflow. However, I’m trying to maintain the virtues of hand-written HTML that I discussed above.

There are also some improvements that would have been inconvenient to implement manually, such as an atom feed – one that shows new posts instead of edits.

I still recommend that you write html by hand to start out with. If it becomes a pain once you reach a couple dozen pages, then you can consider switching to an SSG.