How to
Neocities

Days 1–2 Working in Neocities Directly

For your first two days, you'll work directly in Neocities. This keeps things simple and helps you understand exactly what's happening with your code.

Getting Started

1. Go to neocities.org and create a free account
2. Choose a site name (this will be yourname.neocities.org)
3. You'll see a dashboard with your files—click on index.html to edit
4. Make a small change and click Save
5. Click View to see your site live!

Neocities Survival Tips

File Management

Neocities file management is basic. Here's how to cope:

• Creating files: Click "New File" and type the full name with extension (e.g., about.html)
• Creating folders: Click "New Folder" and give it a name (e.g., images)
• Uploading: Drag and drop files directly onto the file list
• No "Move": To move a file, download it, delete the original, then upload to the new location
• Renaming: Click the file, then "Rename"—this works well

Your First Site Structure

By end of Day 2, aim to have:

yoursite.neocities.org/
├── index.html        ← Your homepage
├── style.css         ← All your styles
├── images/           ← Folder for images
│   └── (your images here)
└── old_not_used/     ← Archive old versions here
    └── (backup files)

Versioning Strategy: Manual Backups

Since Neocities has no undo, create your own version history:

1. On your computer, create a folder called my-site-backups
2. Each time you finish a working version, copy all your code into a text file
3. Name it with the date: index-2026-01-16.html
4. If disaster strikes, you can copy the backup back into Neocities

Days 3–4 Level Up: Local Development

Now that you understand HTML and CSS basics, it's time to work like a pro. We'll set up a proper workspace on your computer.

Why Switch to Local Development?

Setting Up VS Code

1. Download VS Code
   Go to code.visualstudio.com and download the free editor
2. Install Live Server Extension
   Open VS Code → Click the Extensions icon (4 squares) → Search "Live Server" → Install it
3. Install Neocities Extension (optional)
   Search "Neocities" → Install the Neocities extension
   This lets you upload directly to Neocities from VS Code
4. Create Your Site Folder
   On your computer, create a folder called my-neocities-site
5. Open Folder in VS Code
   File → Open Folder → Select your folder
6. Download Your Entire Neocities Site
   Go to Neocities Dashboard → Click Settings → Scroll to Download Entire Site → Click the button to get a .zip file → Unzip it into your folder
7. Start Live Server
   Right-click on index.html → "Open with Live Server"
   A browser window opens showing your site

Alternative: Mount Neocities as a Drive

Neocities supports WebDAV, which lets you mount your site as a folder on your computer.

This is useful for quick edits, but we still recommend working locally with VS Code for the best experience.

Better File Structure

Now you can organise properly:

my-neocities-site/
├── index.html
├── about.html
├── work.html
├── contact.html
├── blog.html
├── css/
│   └── style.css
├── images/
│   ├── hero.jpg
│   ├── project1.jpg
│   └── profile.jpg
├── old_not_used/
│   └── (archive old versions here)
└── backups/
    └── (your version snapshots)

Easy Versioning

Now versioning is simple:

1. Before big changes, copy your whole folder
2. Name it with the date: my-site-backup-jan16
3. If things break, just copy files back from the backup

Uploading to Neocities

When you're ready to publish:

1. Go to your Neocities dashboard
2. Delete old files you're replacing (optional but cleaner)
3. Drag and drop your whole folder's contents onto Neocities
4. Check your live site

Day 5 Polish and Publish

Final day. Time to polish your 5-page site and make sure everything works perfectly.

Pre-Launch Checklist

• All 5 pages created and linked together
• Navigation works on every page
• All images load correctly
• Styles look good on different screen sizes
• No broken links (check every link)
• Spelling and content reviewed
• Site title and favicon set
• Final backup saved locally

Check Your Navigation

Every page should have links to every other page:

<nav>
  <a href="index.html">Home</a>
  <a href="about.html">About</a>
  <a href="work.html">Work</a>
  <a href="blog.html">Blog</a>
  <a href="contact.html">Contact</a>
</nav>

Test on Mobile

In VS Code with Live Server running:

1. Open Chrome DevTools (F12 or right-click → Inspect)
2. Click the phone/tablet icon (Toggle Device Toolbar)
3. Test different screen sizes
4. Fix any layout issues

Final Upload

1. Make sure all files are saved locally
2. Test everything one more time with Live Server
3. Go to Neocities dashboard
4. Upload all your files (drag and drop the contents of your folder)
5. Visit your live site and test every page
6. Share your URL with the class

Troubleshooting Common Mistakes and Fixes

My CSS isn't working

Check these things:

• Is the <link> tag in your <head>?
• Is the path correct? href="style.css" or href="css/style.css"
• Did you save both the HTML and CSS files?
• Clear your browser cache (Ctrl+Shift+R / Cmd+Shift+R)

My image won't show

• Check the file path: src="images/photo.jpg"
• Check the file extension: .jpg vs .jpeg vs .png
• Make sure the image was uploaded to Neocities
• File names are case-sensitive: Photo.jpg ≠ photo.jpg
• No spaces in file names — my photo.jpg breaks online. Use my-photo.jpg or my_photo.jpg instead

I broke everything

1. Don't panic
2. Do you have a backup? Copy the code back in
3. No backup? Try to remember what you changed
4. Use the browser's "View Page Source" on your live site to see the last working version
5. Ask for help—we've all been there

My links don't work on Neocities but work locally

• Check file names match exactly (case-sensitive)
• Make sure you uploaded ALL files
• Check folder structure matches your local setup

Beyond Neocities This Workflow Works Everywhere

The skills you're learning aren't just for Neocities. This exact workflow—local development → version control → upload/deploy—works with almost any web hosting.

Other Places to Host Your Sites

Want to Level Up?

After this course, consider learning:

• Git and GitHub — professional version control (never lose work again)
• GitHub Pages — free hosting that auto-updates when you push code
• Netlify/Vercel — modern hosting with features like forms and functions

Reference Quick Reference

Essential HTML Structure

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Page Title</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <!-- Your content here -->
</body>
</html>

Linking Between Pages

<!-- Same folder -->
<a href="about.html">About</a>

<!-- Up one folder -->
<a href="../index.html">Home</a>

<!-- External link -->
<a href="https://example.com" target="_blank">External Site</a>

Adding Images

<!-- Basic image -->
<img src="images/photo.jpg" alt="Description of image">

<!-- With figure and caption -->
<figure>
  <img src="images/photo.jpg" alt="Description">
  <figcaption>Caption text here</figcaption>
</figure>

Keyboard Shortcuts