Skip to content Go to Sitemap

Neocities Tips

How to upload changes to Neocities automatically


Using an amazing GitHub Action you can automatically deploy your changes to Neocities without manually uploading any files. It only updates the files that were actually changed, don't worry about your feed. Prerequisite for this is that you have a GitHub repository for your project!

How to do it:

  1. Make sure all the files in your project that should be uploaded to Neocities are in a folder called public.
  2. Create the following file in the root of your project (NOT in the public folder):
    .github/workflows/neocities.yml
    Make sure you spell it correctly! Don't forget the "." at the start of the first folder name.
  3. Insert the code shown here into your file.
  4. If your branch is called 'main' instead of 'master' make sure to change that on line 7.
  5. Comment out (= add a # at the start of the lines) or delete lines 21 to 28. You don't need them.
  6. If you want to you can set cleanup to true. This means that files that are still in your Neocities but not in your project anymore are deleted from Neocities. (I recommend this, otherwise you will eventually run out of space in your Neocities account.)
  7. Get your API Key for your Neocities account. (It can be found in your Site Settings on Neocities under "API").
  8. Open your repository on GitHub, go to its "Settings", then "Secrets and Variables" -> "Actions". Add a secret with the name NEOCITIES_API_TOKEN and set your Neocities API Key as the value.

Done! Now whenever you push to your master/main branch, the changed/added files will automatically be uploaded to your Neocities site.

External Widgets for Neocities Free Accounts


Unfortunately, if you have a free website on Neocities created after ~2022 you are not allowed to use external scripts, such as guestbooks, shoutboxes, status/mood widgets, and even hit counters unless they are iFrames:

iFrames, and any widgets that use them, do work. For guestbooks I recommend using smartgb (which is what I use for my guestbook iframe) because it is very customizable and looks good in an iframe. For a chatbox you can use cbox, because it works via an iframe.

I have also created some other iFrame widgets you can use with a free account, e.g. status.cafe and last.fm. Check them out here.