knight/deploy-to-neocities
1
0
Fork 0
mirror of https://github.com/bcomnes/deploy-to-neocities.git synced 2026-01-16 22:56:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add FAQ section and tweak docs

Browse Source
This commit is contained in:
Bret Comnes 2020-02-18 10:19:26 -07:00
parent 028d293da6
commit b0dba38c69
No known key found for this signature in database
GPG Key ID: 3705F4634DC3A1AC
1 changed files with 52 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
README.md
View File

@ -6,26 +6,12 @@
Efficiently deploy a website to [Neocities][nc].
### Pre-requisites
Create a workflow `.yml` file in your repositories `.github/workflows` directory. An [example workflow](#example-workflow) is available below. For more information, reference the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
Get your sites API token and set a [secret][sec] called `NEOCITIES_API_TOKEN`. Set the `api_token` input on your `deploy-to-neocities` action to `NEOCITIES_API_TOKEN`.
```
https://neocities.org/settings/{{sitename}}#api_key
```
During your workflow, generate the files you want to deploy to [Neocities][nc] into a `dist_dir` directory. You can use any tools that can be installed or brought into the Github actions environment.
This `dist_dir` should be specified as the `dist_dir` input. Once the build is complete, the `deploy-to-neocities` action will efficiently upload all new and all changed files to Neocities. Any files on Neocities that don't exist in the `dist_dir` are considdered 'orphaned' files. To destrucively 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 commited to `master` result in website updates.
### Example workflow
## Usage
```yaml
name: Deploy to neociteis
name: Deploy to neocities
# only run on changes to master
on:
push:
branches:
@ -37,6 +23,8 @@ jobs:
steps:
- uses: actions/checkout@v1
# 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@v1
with:
@ -45,6 +33,7 @@ jobs:
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@v1
with:
@ -53,21 +42,64 @@ jobs:
dist_dir: public
```
Create a workflow `.yml` file in your repositories `.github/workflows` directory. An [example workflow](#example-workflow) is available below. For more information, reference the GitHub Help Documentation for [Creating a workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file).
Get your sites API token and set a [secret][sec] called `NEOCITIES_API_TOKEN`. Set the `api_token` input on your `deploy-to-neocities` action to `NEOCITIES_API_TOKEN`.
```
https://neocities.org/settings/{{sitename}}#api_key
```
During your workflow, generate the files you want to deploy to [Neocities][nc] into a `dist_dir` directory. You can use any tools 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.
### Inputs
- `api_token` (**REQUIRED**): The api token for your [Neocities][nc] website to deploy to.
- `api_token` (**REQUIRED**): The API token for your [Neocities][nc] website to deploy to.
- `dist_dir`: The directory to deploy to [Neocities][nc]. Default: `public`.
- `cleanup`: Boolean string (`true` or `false`). If `true`, `deploy-to-neocities` will destructively delete files found on [Neocoties][nc] not found in your `dist_dir`. Default: `false`.
- `cleanup`: Boolean string (`true` or `false`). If `true`, `deploy-to-neocities` will destructively delete files found on [Neocities][nc] not found in your `dist_dir`. Default: `false`.
### Outputs
None.
## FAQ
### Why should I deploy to Neocities?
[Neocities][nc] offers a bunch of nice properties:
- Neocities CDN uses a pure [anycast](https://en.wikipedia.org/wiki/Anycast) network providing efficient content serving no matter where your visitors are located around the world.
- Anycast doesn't require special DNS records to achieve geolocation routing characteristics. Simple `A` and `AAAA` records are all you need.
- Neocities owns its own [ARIN](https://en.wikipedia.org/wiki/American_Registry_for_Internet_Numbers) IP block and has its own [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol) peering agreements, eliminating entire layers of bureaucracy between your content and the rest of the Internet typical of all major Cloud providers.
- Far faster cold cache access than other popular static hosting services. Perfect for personal websites, projects and other infrequently accessed documents.
- Simple and understandable feature set. You can hand upload and edit files along side built/deployed assets.
- Fun, friendly, creative and organic community with an [interesting social network](https://neocities.org/browse).
- Independent, sustainable and altruistic service run by [@kyledrake](https://github.com/kyledrake/) and word on the street is that the service is profitable.
- Affordable and predictable pricing. There is a generous free tier and you can get custom domains and additional sites for $5/mo.
- Offers simple, Google-free site analytics.
- Makes accepting tips a breeze.
- Bring your own CI environment, or don't.
- Cute cat logo.
### What are some of the drawbacks compared to Netlify/Zeit?
- Not appropriate for hyper traffic commercial sites most likely.
- No concept of a Deploy or atomicity when changing files.
- Most features of these services are not included. Neocities is just static file hosting and a few basic features around that.
- Doesn't offer support.
- No deploy previews.
- No Github Deploys API support (yet).
## See also
- [async-neocities](https://ghub.io/async-neocities): diffing engine used for action.
- [Neocities API Docs](https://neocities.org/api)
- [neocities/neocities-node](https://github.com/neocities/neocities-node): Node api
- [neocities/neocities-node](https://github.com/neocities/neocities-node): Official Node API
[qs]: https://ghub.io/qs
[nf]: https://ghub.io/node-fetch