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?

Automatically upload files: Sometimes you just don't want to spend any amount of time finding files, or dragging and dropping them. With Deploy-To-Neocities, you can basically just edit files on your computer and your site will be automatically updated.
Accurately upload files: Neocities's uploader makes a lot of mistakes. I haven't gotten it to upload multiple folders at once, and when it does upload multiple files it often messes up the folder structure. By using Deploy-To-Neocities, all your files are uploaded in the exact folders they need to be in, and you won't have to wonder what went wrong during the uploading process.
Backup your Neocities site: I've accidentally deleted my folders and files from Neocities, and there is no way to recover them. There is also rarely a bug on Neocities where editing your files on the Neocities site will delete your entire site. By using Deploy-To-Neocities, you will have a backup of your Neocities site on your computer as well as on Github. More backups is good. Never put all your eggs in one basket.
Mirror your site on multiple hosts: I have many of my sites set up on Vercel, and want to mirror the exact same sites on Neocities as a backup. With the Deploy-To-Neocities action, I can make changes to my site on my computer, and have all my mirrors update at the same time with the same exact information. This is good for my ADHD because I often forget what files I've changed or uploaded between multiple sites. You can see an example of my Dafoe site mirror at my personal site, and 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.

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.
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.
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.
After signing up for Github, make a new repository. The repository is basically the folder that holds your website.
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
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      # When the dist_dir is ready, deploy it to neocities
      - name: Deploy to neocities
        uses: bcomnes/deploy-to-neocities@v1
        with:
          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:
https://neocities.org/settings/{{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 contact@scumsuck.com.

<--Back to resources