Deploy to Neocities 🐈

There's a github action by bcomnes called "Deploy to Neocities". What it does is copy a whole folder, and everything in it, to Neocities automatically when you update it. It's very useful for creating and maintaining Neocities sites. Especially because the drag-and-drop uploader on Neocities often deletes files or messes up the folder structure.

For people like me who don't read good or do tech good, it might be a little hard to follow the guide. M1ssM0ss's template is an easier to understand guide! I'm unga bunga caveman brained, and need pictures for myself though. So I wrote the tutorial on this page on how to parse the guides linked above, so we can all get it to work even with limited tech knowledge.

Why use Deploy To Neocities?

Da Guide

I will break down the steps in bcomnes guide step-by-step, and explain it in a way that folks with a limited grasp on tech (like me!) can better understand.

Before you start:

I'm assuming you know how to navigate and create folders in your computer. I'm using Windows as my operating system, and working on a desktop computer. This tutorial may not work on mobile.

  1. You need to be editing your site on your computer, and not in the Neocities editor. Make sure your site's files are in one folder.
  2. Sign up for a Github account. If you don't want to make a Github account, I can't help you. But it's understandable to avoid it since Github is owned by Microsoft. Let me know if you find similar solutions outside of Github.
  3. It will make syncing files between your computer and Github easier if you're using VScode as your text editor, because it comes with integration with Github. I will be using VScode in my tutorial.

  4. After signing up for Github, make a new repository. The repository is basically the folder that holds your website.

  5. Name it whatever you want. I've named mine neocities. Set it to private if you need to. Then create it.

Step 1: Create the workflow file

Create a workflow .yml file in your repository's .github/workflows directory.

What this means is: In your site's folder, create a new folder called ".github". Then create another folder in it named "workflows".

In the "workflows" folder, right click anywhere in the window and create a text document.

Once created, it will ask you to name the file. Delete the default text and name it "neocities.yml". The name "neocities" doesn't matter, but the file type extension "yml" matters.

Open the neocities.yml file with your text editor. Paste the following code (from m1ssm0ss's template) into the file:

name: Deploy to neocities

# only run on changes to main
      - main

    runs-on: ubuntu-latest

      - uses: actions/checkout@v1
      # When the dist_dir is ready, deploy it to neocities
      - name: Deploy to neocities
        uses: bcomnes/deploy-to-neocities@v1
          api_token: ${{ secrets.NEOCITIES_API_TOKEN }}
          cleanup: false
          dist_dir: public

Save your file.

Step 2: Find your Neocities API token

You'll need the API token for your site. Go to:{{your-sitename}}#api_key

Get your site's API token. In your GitHub repository, set a secret called NEOCITIES_API_TOKEN. Set the api_token input on your deploy-to-neocities action to ${{ secrets.NEOCITIES_API_TOKEN }} as in the example above.

What this means is: You'll need a token from neocities to use as a password, in order for neocities and github to work together.

In Neocities, find your site settings in the top right corner.

Click the API tab, and you'll find your API key. It will be a random string of numbers and letters. For this tutorial, we'll pretend that the API key is "ilovewillemdafoe".

Go to your github account. Find your repository. Click on "settings". Then click on "secrets and variables". Then click on "actions". Press "New Repository Secret".

Name the secret "NEOCITIES_API_TOKEN". It must sbe exact. For the Secret, enter your Neocities API key, exactly the same as it is in your Neocities API page. We'll pretend that the API key is 'ilovewillemdafoe'. Then press "Add secret" to save it.

You should now have a NEOCITIES_API_TOKEN secret. If you happen to try to edit it again, the token will not show. Don't worry about it.

Step 3: Put your files in a folder

During your workflow, generate the files you want to deploy to Neocities into a directory. Set this as the dist_dir directory in your workflow (the default is public). You can use any tools to generate your site that can be installed or brought into the Github actions environment.

What this means: You need to put all your site files into a folder on your computer. That folder should be named "public", and it should be in the same folder as your ".github" folder.

This is what the inside of my "public" folder looks like. You will probably have different files. Just make sure all your site files are in here.

You can change the name of this folder to anything you want if you edit the "neocities.yml" file. The part in that file that says "dist_dir: public" controls what the folder name should be. Make sure that those folder names match if you do anything.

Step 4: Uploading your site

Once the build is complete, deploy-to-neocities will efficiently upload all new and all changed files to Neocities. Any files on Neocities that don't exist in the dist_dir are considered 'orphaned' files. To destructively remove these 'orphaned' files, set the cleanup input to true.

What this means: When you upload new files to your Github repository, it should also update your Neocities site automatically. By default, anything in your Neocities folder will stay the same. If you want your Neocities folder to delete extra files that are NOT in your github repository, you have to edit the "neocities.yml" file.

I'm going to be assuming you're using VScode to upload your files. If you're not using VScode, I can't help you.

Click the button that looks like circles connected to each other. That's the source control panel. Connect VScode to your github account, and make sure you're uploading to a branch (folder) called "main". "main" should be the default when you connect your repository.

I need screenshots for this portion cuz I've already connected my account lol.

Type a message to yourself above the "commit" button. You need a message, or it won't save your changes. I usually write what I changed, like "edited CSS" or something simple. Press commit to save your changes. After that it'll ask you to "sync changes". Do it. That'll upload your saved changes to your Github folder.

Wait a bit, and your changes should appear in your Github repository! It should have your ".github/workflows" folder, as well as the "public" folder. Remember that the "branch" needs to be on the one called "main".

You should be done. This is how I set up my neocities to automatically update! Yay!

Da End

If you have any suggestions to improve this guide, please email me at

<--Back to resources