GitHub tag (latest SemVer) Actions Status Deploy to neocities Marketplace link Neocities

Efficiently deploy a website to Neocities using Github actions. Uses content aware diffing to only update files that changed.


name: Deploy to neocities

# only run on changes to main. Use main or master depending on whatever your default branch is called.
      - main

concurrency: # prevent concurrent deploys doing strange things
  group: deploy-to-neocities
  cancel-in-progress: true

    runs-on: ubuntu-latest

    - uses: actions/checkout@v3
    # Set up any tools and build steps here
    # This example uses a Node.js toolchain to build a site
    - name: Use Node.js
      uses: actions/setup-node@v3
        node-version: lts/*
    - name: Install deps and build
      run: |
        npm i
        npm run build
    # When the dist_dir is ready, deploy it to neocities
    - name: Deploy to neocities
      uses: bcomnes/deploy-to-neocities@v2
        api_token: $
        cleanup: false
        dist_dir: public

Create a workflow .yml file in your repository’s .github/workflows directory. An example workflow is available above. For more information, reference the GitHub Help Documentation for Creating a workflow file.

You’ll need the API token for your site. Go to:

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 $ as in the example above.

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.

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.

You most likely only want to run this on the master branch so that only changes committed to master result in website updates. Running a test build that does not deploy on all branches and PRs can help catch changes that will break the build.





Why should I deploy to Neocities?

Neocities offers a bunch of nice properties:

What are some of the drawbacks compared to Netlify/Vercel?

Sites using deploy-to-neocities

See also