Neocities Coding Guide

01 What is Neocities?

Neocities is a free website hosting platform where you upload HTML, CSS, and JavaScript files to build your own site from scratch — no drag-and-drop builders, no templates. Just code.

Your site lives at yourname.neocities.org. You edit it through the Neocities dashboard editor or by uploading files from your computer.

TIP Every Neocities site starts with a file called index.html. That's the homepage — it's what loads when someone visits your URL.

02 The bare minimum HTML page

Every HTML file has the same skeleton. Paste this into your index.html to start:

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Neocities Site</title>
</head>
<body>
  <h1>Hello, World!</h1>
  <p>Welcome to my site.</p>
</body>
</html>

INFO <head> holds invisible settings (title, charset). <body> holds everything you see on the page.

03 Common HTML tags

HTML is made of tags — they describe what content is. Most come in pairs: an opening tag and a closing tag.

<!-- Headings (h1 is biggest, h6 is smallest) -->
<h1>Big Title</h1>
<h2>Subtitle</h2>

<!-- Paragraph -->
<p>Some text here.</p>

<!-- Bold and italic -->
<strong>Bold text</strong>
<em>Italic text</em>

<!-- Link -->
<a href="https://neocities.org">Visit Neocities</a>

<!-- Image -->
<img src="cat.png" alt="a cute cat">

<!-- Line break -->
<br>

<!-- Horizontal line -->
<hr>

TIP Images and links need attributes — extra info inside the tag. src tells the browser where the image file is. If the image is uploaded to your Neocities, just use the filename: src="cat.png".

04 Lists and divs

<ul> makes a bullet list. <ol> makes a numbered list. Each item is a <li> tag.

<!-- Bullet list -->
<ul>
  <li>Cats</li>
  <li>Dogs</li>
  <li>Fish</li>
</ul>

<!-- Numbered list -->
<ol>
  <li>First step</li>
  <li>Second step</li>
</ol>

<!-- div is a container for grouping things -->
<div class="box">
  <h2>About Me</h2>
  <p>I like making websites.</p>
</div>

INFO <div> is the workhorse of HTML. It doesn't do anything visually on its own — but you can style it with CSS to make cards, boxes, sidebars, and layouts.

05 Adding CSS to your page

CSS controls how your page looks — colors, fonts, spacing, layout. You can write it in a <style> tag in your HTML, or in a separate style.css file.

<!-- Option 1: inline in your HTML -->
<head>
  <style>
    body {
      background-color: #1a1a2e;
      color: #eee;
      font-family: sans-serif;
    }
    h1 {
      color: hotpink;
    }
  </style>
</head>

<!-- Option 2: link a separate CSS file -->
<link rel="stylesheet" href="style.css">

TIP For Neocities, a separate style.css file keeps things tidy. Upload it alongside your index.html.

06 Selectors, properties & values

CSS rules follow a simple pattern: selector { property: value; }. You pick what to target, then describe how it should look.

/* Target by tag name */
p { color: white; }

/* Target by class (use a dot) */
.box {
  background: #222;
  padding: 20px;
  border-radius: 8px;
}

/* Target by id (use a hash) */
#header { font-size: 2em; }

/* Multiple selectors at once */
h1, h2, h3 { font-family: Georgia, serif; }

/* Hover state */
a:hover { color: hotpink; }

07 The box model

Every HTML element is a box. Understanding the box model is the key to controlling spacing and layout.

.my-box {
  /* content size */
  width: 300px;
  height: 200px;

  /* padding: space INSIDE the border */
  padding: 20px;         /* all sides */
  padding: 10px 20px;   /* top/bottom left/right */

  /* border */
  border: 2px solid hotpink;

  /* margin: space OUTSIDE the border */
  margin: 30px auto;    /* auto centers horizontally */

  /* prevent border from adding to width */
  box-sizing: border-box;
}

GOTCHA Put * { box-sizing: border-box; } at the top of your CSS — it makes sizing way more predictable. Almost every modern site does this.

08 Adding JavaScript

JavaScript makes your page interactive. Add a <script> tag at the bottom of your <body>:

<body>
  <h1 id="title">Hello!</h1>
  <button onclick="changeTitle()">Click me</button>

  <script>
    function changeTitle() {
      document.getElementById('title').textContent = 'You clicked it!';
    }
  </script>
</body>

INFO document.getElementById() finds an element on the page. .textContent reads or changes its text. This is the foundation of almost every interactive effect.

09 Google Fonts on Neocities

Want a cool font? Google Fonts are free and easy to add. Copy the link from fonts.google.com and paste it in your <head>:

<head>
  <!-- Paste the Google Fonts link -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link href="https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap"
        rel="stylesheet">
</head>

/* Then use it in CSS */
body {
  font-family: 'Press Start 2P', cursive;
}

10 Linking between pages

To have multiple pages, create more HTML files (e.g. about.html, links.html) and link to them with the <a> tag:

<!-- In your index.html navbar -->
<nav>
  <a href="index.html">Home</a>
  <a href="about.html">About</a>
  <a href="links.html">Links</a>
</nav>

<!-- Open a link in a new tab -->
<a href="https://neocities.org" target="_blank">
  Visit Neocities
</a>

TIP Use relative paths like about.html for pages on your own site. Use full URLs (with https://) for links to other sites.