if you’re like me and you have way too much time on your hands, you might already know that neocities has developed a command-line interface (CLI) for using their API, which makes it easier than ever to manage your very own Personal Webbed Site. and if you’re like me, then you might also:
(also assuming you aren’t a paying supporter of neocities, and as such can’t host the files directly from your computer.)
so if that all sounds like you, then!! well!!! cool? i don’t actually know that anyone wants or needs this guide, but when i was screwing around trying to find a workable solution, i couldn’t find any resources that were both useful and understandable to my computer-illiterate ass. so now that i have the knowledge, i figured i may as well put it up for anyone else who’s interested in doing the same.
but also be careful in making changes to your computer and use your best judgement and all that.
materials needed:
Ruby is an interpreted, high-level, general-purpose programming language. It was designed with an emphasis on programming productivity and simplicity. In Ruby, everything is an object, including primitive data types. It was developed in the mid-1990s by Yukihiro “Matz” Matsumoto in Japan.
the neocities module is written in this language.
download the latest version of ruby installer from rubyinstaller.org and use it to install ruby. you'll need the version with the devkit (which will take up 900MB~1GB of disk space btw)
you can use a package manager (if you use linux, i assume you don’t need me to explain what that is) or select from a list of installers.
sorry but you’re shit out of luck man, i don’t have a mac
nah but there’s also installers for macOS. but you’re on your own from here. google it. idk.
disclaimer: i use windows 10. the entire guide will be written specifically with that in mind, but if you’re willing to do a bit of research, you should be able to adapt the instructions to whatever OS you’re on.
a term you might not be familiar with in this context is module. (you probably technically don’t need to know what that is, so you can keep scrolling cough cough)
anyway. there’s these things called modules – you might also see terms like library or package, and in ruby they’re called gems. they’re all referring to the same thing, more or less: a script or set of scripts used to avoid having to write everything out yourself, potentially multiple times.
imagine you’re trying to directly access the neocities API with node.js. here’s an example, taken directly from that page:
var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')
api.delete(['img1.jpg', 'img2.jpg'], function(resp) {
console.log(resp)
})
do you want to write this out every time you delete a file? fuck no!!!
this is what the module is for: someone else has already defined all the
functions for uploading, downloading, deleting, etc., so that you can call
each one by name. simply entering neocities delete img1.jpg
img2.jpg will yield the same end result, reducing 6 lines to 1. (but
we’re not there yet.)
(i’m not 100% sure this is how it works, i’m not an expert on programming but i think it’s a good definition for right now ok?)
for more information, see this wikipedia page on loadable kernel modules.
first, open the command prompt in administrator mode. on windows 10, you
can do this by right-clicking the windows icon in the bottom left and
selecting Command Prompt (Admin).
now enter this command:
gem install neocities
if there’s no issues, something like this should appear in the command prompt:
Successfully installed neocities-0.0.20
Parsing documentation for neocities-0.0.20
Done installing documentation for neocities after 1 seconds
1 gem installed
to test that the module is properly installed and working, try the command
neocities version, and it should respond with the version
number.
0.0.20
but before you can upload any files, you have to log in. use the command
neocities info; the module should ask for your username and
password, which you’ll have to type in manually.
after logging in, the command will run normally.
C:\Users\REDACTED>neocities info
Please login to get your API key:
sitename: trans-neptunian-object
password: REDACTED
The api key for trans-neptunian-object has been stored in C:\Users\REDACTED\AppData\Local/neocities/config.json.
sitename trans-neptunian-object
views 17191
hits 32698
created_at 2022-09-28 14:12:50 +0800
last_updated 2024-09-06 22:59:30 +0800
domain
tags ["personal", "writing"]
you might be a little cagey about giving your login info to this program, and rightly so. however, the module does not actually store your username and password. it instead uses these to retrieve the API key for your site, which is what allows you to upload new files and access existing ones from the command line, without having to verify your credentials every single time.
but if you really don’t want to enter your information, there’s another
option: manually adding your API key to the module’s configuration, which
is located at
C:\Users\.
edit the contents of the file, subsituting in your own API key and site
name:
{"API_KEY":"YOURAPIKEY","SITENAME":"YOURSITENAME"}
you can find your API key by going to your website settings
(https://neocities.org/).
(i haven’t actually tried this but i assume it works. lol)
keep in mind that if you share your API key with another person, they will have the ability to edit your site or delete everything.
ok i promise we’re done with the setup now. sorry for all the bold text. but this is the kinda shit you have have to keep in mind when you're messing with the command line......
if you don’t already have the files on your computer, you can get them by
going to your neocities dashboard and scrolling down to the link that
says Download Entire Site. you’ll get a zip file with the name
of your website: unzip it and place the contents wherever’s best for you. for
example, i have mine in
C:\.
and now that you have the files on your computer you can use another text editor, instead of the terrible, terrible web version! 💖 (and i’d recommend keeping a local backup of your site, in any case.)
ok, back to the command prompt. you might've noticed before, but the text
in front of all the commands you're typing in should read
C:\WINDOWS\ (or
C:\Users\ if you’re not in administrator
mode, which you should be), which is the directory you’re currently running
commands in. you’ll have to switch to the folder where you placed all the
files for your site in order to make use of them; use this command to do
so:
cd C:\PATH\TO\YOUR\SITE
and the prefix thingy will change:
C:\PATH\TO\YOUR\SITE>
cd commandcd changes the current directory (aka folder)
that you’re working from. it’s the same idea as going to your
Pictures folder to send someone an image, for example, except
that the way you get there is through typing a command, rather
than using the file explorer.
note: if any part of your path contains a space in one of the folder
names, e.g.
C:\Users\, you’ll have to wrap it in quotes, like so:
cd "C:\Users\YOURUSERNAME\Documents\neocities\my website"
or else it won’t work.
although it’s generally considered best practice to not use spaces to begin with.
now you can use the module! upload a file or something! just like with the web editor, you’ll have to do a hard refresh to see the changes in your browser.
the documentation (included with the module) offers an explanation of all the commands, so i’ll just provide a couple to help you get started.
| command | result |
|---|---|
neocities |
brings up a list of all the commands |
neocities COMMANDNAME |
explains the given command (e.g., neocities push) |
neocities push . |
uploads all files in the current directory |
neocities upload FILENAME |
uploads specified file(s) |
yeah i’m still yapping
i don’t know if having an exclusively text-based tutorial made things confusing, so i’m including some examples as well.
here’s a truncated excerpt of my file hierarchy:
Documents
neocities
trans-neptunian-object
about
- credits.html
- index.html
images
bg
- stars.gif
- index.html
- style.css
(items preceded by a dash are files, and the rest are folders.)
when i’m using the module to manage my site, i’ll navigate to the
directory with cd
C:\Users\.
this means the folder named trans-neptunian-object is now the
root directory. if i run the command neocities push ., it
will upload all files and folders in this directory (i.e., every
item under trans-neptunian-object in the excerpt).
if i wanted to only upload credits.html to my site, i would
do neocities upload misc/credits.html. since the file itself
isn’t located in the root directory, i have to append the misc/
to indicate the folder it’s in. (and remember, the note
about having spaces in your file or folder names still applies.)
* there are more notes i could add about using
upload and push but then i'd just be rehashing the
pre-existing documentation so. read that instead
oh yeah and you can use tab completion so you don’t have to type out the whole file name.
(link to official documentation)
git itself is a whole other beast, but in this context, all you need to
know is that a .gitignore file is a list of all the files and
folders you don’t want to upload.
for example, if you’re in the middle of completely rewriting your CSS, you might not want to update the CSS on the live version until you’re done. or maybe you have a screenshot or something in that folder that you don’t want to be uploaded either. iunno.
to do this, you have to create a file in your root directory called
.gitignore. yes, exactly like that: no name preceding the file
extension. you can create an empty .txt file and rename it, and
then open it in notepad or whatever.
so all you do is write in the names of the files you don’t want to include in your uploads, like so:
index.html
style.css
images/bg/stars.gif
the upload will not include
index.html,style.css, orstars.gif.
if you want to override a line without deleting it from the file, you can
add a # in front of it:
# index.html
# style.css
images/bg/stars.gif
the upload will not include
stars.gif. it will includeindex.htmlandstyle.css.
i honestly might make a tutorial for using git specifically for neocities at some point – it’s a fucking nightmare to figure out, but it’s worth the headache, imho.
that’s all! congratulations on getting to the end! i know using the command line can be a confusing hellscape when you’re first starting out, but what it lacks in comfort and convenience, it makes up for by streamlining your process.
as i said before, i wanted to make this guide so people could have something a little more beginner-friendly (well, relatively speaking, y’know) available, as i guess it’s a pretty specific niche. although i’m not sure how anyone’s going to find it. but anyway i hope this was helpful, if a bit rambling at times.
have fun with your fancy new CLI tools! don’t forget to like and subscribe