Skip to content Go to Sitemap

Neocities Tips

How to upload changes to Neocities automatically

Automatically upload your changed files to Neocities via a GitHub Deployment Action.

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

What to do if you want to use external widgets with a free Neocities account.

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.

The good news is that I found a way around that: you can use iframes. Specifially, you use the script you want to use on a different website not hosted on Neocities (instead hosted on e.g. github pages), in the center of an otherwise blank page with background: transparent; and then use this URL in an iframe on your neocities page. Here you can see an example of what an otherwise blank page with a widget may look like.

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.