The Neocities Algorithm

Welcome to my Website!

Finding The Neocities "Algorithm"

NEOCITIES! I love personal websites. I think they are the best way to have digital presence online, especially compared to centralized, corporate, algorithmically driven social media. Neocities is really great, giving everyone the ability to host small personal websites like the older Geocities, without any dynamic content or tracking codes or algorithmic content. But Neocities is still Social Media.

Hosted By Neocities

While websites hosted on Neocities are available on the public internet, there are a few more traditional social media-esque features locked away behind signing into an account. You can follow sites and have their updates show up in your feed. You can leave comments on updates, or post statuses that other people can like and comment on that only ever show up in the feed and never on your site.

The Follow feature on Neocities is particularly interesting because when you follow a site, you don't only get their updates on your feed. You also see whenever anyone else follows that same account. Or when they post a comment on another site, you get to see it, even if you don't follow that other site. This is pretty chaotic and can really clutter your feed if you follow one of the big sites on Neocities. From the perspective of mainstream social media this is really bad design... imagine a celebrity on social media and then getting notified whenever someone else also follows them!

But this chaos actually works in favor of Neocities since the random noise created by all of this exposes you to new and interesting sites all the time. Without using any sophisticated recommendation algorithms, purely through the random chaos of people following and commenting on each other's profiles, I always have new websites pop up onto my feed all the time that I can easily explore. And that's awesome!

(That being said... you also get notified if any random person comments on the profile of someone you're following. On a big account this has the potential to be abused really easily and I've seen it done before. Neocities, please remove that one if you haven't already.)

June 2023 Update: Neocities has removed some of the "noise" you see on your feed, so the main way of discovering new sites now is just to browse and check the global activity page. On one hand, it's way easier to see updates from sites you follow! On the other hand, no more site discoverabilty through that random noise. :(

But... is there an algorithm???

Note: The following section is for educational purposes only. Please do not intentionally try to game "the algorithm" on Neocities.

Have you ever been on the Global Activity page on Neocities? I've noticed that whenever I publish an update to my site, or any other sites I follow get updated for that matter, it only seems to show up sometimes. What's up with that? Also, have you ever used the "Special Sauce" sorting setting on the website directory? That (along with its permanent "alpha" status) sounds suspiciously algorithmic to me! Well thankfully, Neocities is open source, so we can actually look into the code and figure out for ourselves... is there an algorithm at play?

The Global Activity Page

The Global Activity page is a great way to find new sites. But how does it work??? Well... it's actually quite simple! For the most part, this page works pretty much how you'd expect it to. It displays the latest updates to sites across Neocities. ...But there is a bit more going on here.

First, it apparently only shows websites with at least 3000 views. I assume they do this so the global activity feed isn't just filled with brand new sites that are still under construction, but instead sites that probably have something on them at this point. The feed also filters out sites that are marked 18+, which you can mark on your site's profile. It will also filter out sites that have less than two followers, probably to promote users who actually use the site rather than empty and new websites. The code to Neocities has the concept of "Jerks", which are sites that have been blocked by multiple users, and these users are filtered out of the global activity feed as well. The global activity feed also makes sure to only ever display your site once at a time, so that all sites on the page are unique.

There's one final thing to the activity page: It only actually updates every hour, and caches the results until the next regeneration. So if you update your site and then immediately go over to that page... you probably won't actually see anything! If you come back an hour later, and your site meets all the other criteria, you should see your site on the page... though you might have to scroll a bit depending on how long it took between updating your site and updating the activity page!

There is one bit of functionality that is currently disabled, but remnants of it exist in the code. You know how Neocities will generate little screenshots of your site for updates and profile pages? Well, code exists to filter out any pages that were so slow they caused the screenshot bot to break! The screenshot worker code has been updated to stop marking sites as slow... however... technically if you have an old site (like... from around 2016 or earlier?) and it was slow to load, your site could have been marked in this way, and might still be filtered out of results! I'm not sure if they've updated the database to unset the "breaks our screenshot bot" flag on old sites!

To review, here are the rules to the Global Activity page. It grabs all the updates from around Neocities and filters them like this:

  • Remove sites below 3000 views
  • Remove sites marked 18+ (NSFW)
  • Remove sites that are too slow to load for the screenshot bot
  • Remove multiple occurrences of the same site in the list
  • Removes jerks[1]
  • Removes sites with less than two followers

And then it only updates every hour, so changes may take a while to show up on the feed!

The main areas where you can find this information for yourself are in app/activity.rb and models/event.rb of the Neocities source code.

The Special Sauce

What does the "Special Sauce" sort mode do on the search page? To me it always sounded like some kind of algorithmic recommendation magic. Well... it does use an algorithm, since any computer system uses algorithms, but it isn't a magic machine learning one like Twitter or TikTok. The Special Sauce sort mode sorts websites by their Site Score, from greatest to least. That's it!

... wait... what's a site score?!?!

A score is generated behind-the-scenes for every Neocities site, and this score is used in the Special Sauce sorting mode, as well as a few other places. Generally, the score tries to prioritize popular sites that are also currently active on Neocities. Relying solely on follower count or page views might push sites that are popular but mostly abandoned, so a variety of factors are all put into calculating site score to get the most out of all data points. Let's explain how the score calculation algorithm works!

For a given site, compute its score by starting at 0 points and then doing the following:

  1. For every follower the account has, add 30 points.
  2. For every comment on the site's profile, add 1 point.
  3. For every 1000 views[2], add 1 point.
  4. If the site has ever been featured on the Neocities homepage, add 20 points.

After these steps, some penalties will completely set scores to zero if conditions are met:

  1. If a site has less than two total updates over two different days, clear out all points to zero.
  2. If a site has credentials for the Neocities API and has hit endpoints over 1000 times[3], clear out all points to zero.

And then a final (and a bit more complex) calculation is done to prioritize more recently updated sites.

  1. Compute the "recent update score":
    1. Take the number of seconds between now and whenever the last update to the site was.
    2. Divide that value by 604800 (this is not arbitrary, it's the number of seconds in one week!)
    3. Raise the divided value to the power of 1.8.
  2. Divide the points we have computed previously by the "recent update score".
  3. Round the final value to four decimal places.

... and that's how you compute a site score! It gets pretty complicated near the end, but what really matters is that sites that haven't been updated for a long time get their scores penalized even if they have a lot of followers and views and stuff.

The "Special Sauce" sort mode will rank sites by their scores starting with the highest scores. But that's not the only place where the site score is used! Whenever you see the "This Site Follows" and "Followers" sections on a user's profile, those sites are also sorted by score! Neat!

Neocities Followers
These sites are sorted by their super secret score!

So There Is An Algorithm! Kind Of!

These two things, the global activity page and the concept of "site scores", are the only features of the site I could find that kind of match the description of "algorithms to suggest content on Neocities". But even then, they're not the kind of mysterious machine learning black boxes we see on other sites like Youtube, TikTok, or Twitter. They're just... handwritten pieces of open source code that use the data available to hopefully pick out new and interesting sites for you to find. It's kind of refreshing in a world where more corporate algorithms are controlling how people interact with each other.

I once saw a post online about younger people, who are used to their interactions on TikTok and other algorithm-driven apps, joining a much more basic fanfiction website and assuming that there was an algorithm on that site as well since engagement algorithms are just the new normal now.

A tumblr post showing younger people hoping to be "blessed by the algorithm" on AO3, a fanfiction website without any suggestion algorithms.
The post in question. By the way I don't actually go on fanfic sites lol.

I'm of glad that Neocities doesn't have "a real algorithm" because I think those "real algorithms" are scary. I love how Neocities encourages curious exploration. It will not spoonfeed you content the way TikTok's For You Page does. You have to click things, and find sites that you like. And that takes time and effort. But I think the process feels a bit more rewarding in a way. When you find a really cool site on Neocities, or anywhere on the Indie Web for that matter, it feels all the more special because you found it. Not some corporate machine that has an alarming amount of personal data it is attempting to market to.

Websites like Twitter only care about engagement. Whether you are comforted by the content or angered by the content, it doesn't care... and actually your anger, rage, and fear tend to be more valuable to Twitter than your comfort. Doomscrolling is a feature of modern social media, not a bug. So, Twitter will push things that will upset you, because when you're angry and want to tear down someone's bad take... you'll post and engage more with the platform.

On Neocities and the Indie Web, your exploration is entirely controlled by you. You can choose where you want to go on the web, and if you don't like the content of a site you can back away slowly and there is no algorithm taking notes on how you emotionally respond to something. It's very mundane, and really a sign of the horrible futuristic dystopia we live in... but it's honestly what makes Neocities so special to me.

... That being said, I feel like by spelling out these rules of the barebones Neocities algorithm is almost encouraging people to abuse them so that they can get more followers and boost engagement with their own site. Thankfully it seems like the main way to "game the algorithm" on Neocities is to just... be an active member. Still. If you're reading this I hope you use this information responsibly. Unlearn the attention-hungry bullshit that social media has taught you. You'll be better off without it.

Oh.. and Neocities? Please let me use your API for automated deployments without supressing my account in search results. lol.

To learn more HTML/CSS, check out these tutorials!


1: "Jerks" are sites who have been blocked by at least four other accounts. That is what they are actually called in the code.

2: The code uses views / 1000 to compute this part of the score, but I believe the views value here is an integer, so in Ruby (what Neocities runs on) this will be handled with Integer Division. No decimal points or remainders.

3: Wait... but... I use the Neocities API to deploy this website... oh god, are you telling me I only have a limited number of deploys before I get completely supressed by the algorithm? According to what I've found in the Neocities source code, each API call is tracked in the database and I can't find a place where that value is ever reset...? (Maybe this is to encourage API key rotation???)