I love Neocities. It’s a great webhost that I can use to easily put my stuff up on the web! But if I don’t have a page to put online, it’s no fun! And although hand-coding a website with raw HTML is pretty fun and very powerful to customize, the more pages I have to make, the more tedious it becomes to copy and paste. So here’s how I easily made my site and put it up on Neocities.

Some notes before we begin: I am using Windows 10 and am comfortable with the command line.

I use Hugo to build my site. I chose it because it can generate HTML very quickly from Markdown, so I can build it live and change my pages in real-time and see how it updates on the local server.

To get started with Hugo (stolen from Hugo’s site):

1. Download Hugo

I already had Chocolatey on my Windows machine, so for me it was as easy as going into the command line and typing:

choco install hugo -confirm

But if you don’t use Chocolatey for package management, there are lots of options. For example, you can install their precompiled binary and put it somewhere in your PATH.

For Mac users, your PATH is /usr/local/bin or something.

For Windows users, your PATH can be found and edited by typing environment variable into your Windows search bar and clicking “Edit the system environment variables”.

Once you have the Hugo binary in that PATH folder, open your command prompt and type:

hugo version

to verify your new install. If you get an output like:

hugo v0.82.0-9D960784 windows/amd64 BuildDate=2021-01-01T00:00:00Z VendorInfo=gohugoio

then you are good to go!

2. Make a site with Hugo

Now, navigate to the folder where you want your Hugo site to live using cd. For example, I might do:

cd C:\Users\Me

so that I can then put my Hugo folder in there. After this, type:

hugo new site MySite

which will create a new Hugo site in a folder named “MySite” (full file path in my example would be C:\Users\Me\MySite)

3. Add a theme

I use Bearblog, a nice and minimal theme (that I have since customized the hell out of, sorry). In order to install this theme, I used Git:

git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog

However, if you don’t have Git and don’t want to install it, you can download the theme from https://github.com/janraasch/hugo-bearblog/archive/refs/heads/master.zip and then extract the .zip file, rename the directory to hugo-bearblog, and then manually move it to the themes/ directory of your Hugo folder.

There are loads of other themes available for Hugo, which you can find here. Explore them and have fun!

4. Edit your configuration

You will find a file called config.toml in your Hugo folder. Open it up, and it will contain the following:

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

If you installed the Bear theme, you should edit it to contain the following:

baseURL = "https://example.org"

# The name of this wonderful theme ;-).
theme = 'hugo-bearblog'

# Basic metadata configuration for your blog.
title = "Hugo ʕ•ᴥ•ʔ Bear Blog"
author = "Jane Doe"
copyright = "Copyright © 2020, Jane Doe."
languageCode = "en-US"

# Generate a nice robots.txt for SEO
enableRobotsTXT = true

# Generate "Bearblog"-like URLs !only!, see https://bearblog.dev/.
disableKinds = ["taxonomy"]
ignoreErrors = ["error-disable-taxonomy"]
[permalinks]
  blog = "/:slug/"
  tags = "/blog/:slug"

[params]
  # The "description" of your website. This is used in the meta data of your generated html.
  description = "Hugo + Bear = :heart:"

  # The path to your "favicon". This should be a square (at least 32px x 32px) png-file.
  # Hint: It's good practise to also put a "favicon.ico"-file into your "static"-folder.
  favicon = "images/favicon.png"

  # These "images" are used for the structured data templates. This will show up, when
  # services like Twitter or Slack want to generate a preview of a link to your site.
  # See https://gohugo.io/templates/internal#twitter-cards and
  # https://gohugo.io/templates/internal#open-graph.
  images = ["images/share.png"]

  # Another "title" :-). This one is used as the site_name on the Hugo's internal
  # opengraph structured data template.
  # See https://ogp.me/ and https://gohugo.io/templates/internal#open-graph.
  title = "Hugo ʕ•ᴥ•ʔ Bear"

  # This theme will, by default, inject a made-with-line at the bottom of the page.
  # You can turn it off, but we would really appreciate if you don’t :-).
  # hideMadeWithLine = true

  # By default, this theme displays dates with a format like "02 Jan, 2006", but
  # you can customize it by setting the `dateFormat` param in your site's config
  # file. See [Hugo's Format function docs](https://gohugo.io/functions/format/)
  # for details. An example TOML config that uses [ISO
  # 8601](https://en.wikipedia.org/wiki/ISO_8601) format:
  # dateFormat = "2006-01-02"

You should also have it contain the general information you want your site to have, so make sure to change the title, base URL, author, and so on. If you don’t want to enable robots.txt or want to change other values, you can go ahead and do that here too.

5. Make some stuff for your website to have

But what is a website without any pages?

Your Hugo folder will look something like this:

📁 Your cool website folder that you set up with Hugo
├─ 📁 archetypes
├─ 📁 content
├─ 📁 data
├─ 📁 layouts
├─ 📁 public
├─ 📁 resources
├─ 📁 static
├─ 📁 themes
├─ 📁 whatever else you have in there
├─ 📄 .gitmodules
├─ 📄 config.toml
└─ 📄 whatever else there is

All your website posts will live in the content folder. Navigate there and open it up. If you’re using the Bearblog format, you want to have one file in there named _index.md, another one named about.md, and finally a folder called blog which will contain all your blog posts. Other themes will have different structures that pair well with them, but the tutorial for that will be on each theme’s individual Github page. Go wild!

But now that you have your empty Markdown files, what goes in them?

Each Hugo site page requires something called “front matter” which, understandably, goes in the front of your file.

Well, actually, my _index.md file doesn’t need to have it, but every other one does. Let’s just go through each type of file and I’ll give you an example of what to put in.

_index.md

My index page is actually really simple. All I have for it is the following:

# Welcome to my Webzone

Please steal my tweets, copy my content, and say it's yours. You are spreading my mind virus, thus making me more powerful and strong...

![Captain Haddock saying Hahaha Oh Wow](/images/haddock.jpg)

That’s it! That’s the whole file that I literally use for the front page of my website!

By the way, if you want to host images on your site, you just keep them in the static folder. I actually keep my images in static/images/, and then I can refer to them with /images/myfile.jpg when I’m writing in Markdown.

about.md

Now here is where you find the dreaded “Front Matter”. It’s not that bad really, though. You just have to put it at the beginning of the file:

+++
title="About"
menu="main"
+++
# About Me
Some stuff about me, blah blah blah, etc

All “top level” stuff that goes in the main “menu” of links at the top of your site can have this sort of format. So if you want to add a gallery, or a link to your contact information, or a guestbook, or whatever you want, you can put it in here!

blog/blogpost.md

The front matter gets a little more involved here. If you are using the Bearblog layout, you need to have the following for your blog to work nicely: title, description, date, and tags.

+++
title="My first blog post"
description="I'm using a static site generator to make my website! Yay!"
tags=["firsttag","secondtag"]
date="2022-01-19"
+++
# Here is my first blog post
Oh wow, look at this photo of a dog I took today. What a cool dog.
![Picture of a dog](/images/dog.jpg)

I hope you are having as good a day as this dog.

Please note that the tags live inside a set of brackets. This is slightly annoying because it’s always like this, even if you only just use one tag. Beware!

If you just want to make your page a draft, you can add draft=true to the front matter.

Now whenever you make a new blog post, you can put it in this folder and it will go live there.

6. Customize your blog style

You can add your own styling to your site by navigating to the layouts/partials/ directory and creating a new file called custom_head.html. There, you can either add a <style> tag directoy or add a <link> tag that references your own .css file. Either way, it will show your style!

The custom theme will have its own style.html file in its own layouts/partials/ folder (inside the themes folder) that you can use as a reference to see what elements have styles applied to them. Or you can do what I do, and use Inspect Element to inspect every single element, haha.

7. Generate a site

Ok, so now you have a collection of Markdown files living in a folder with a bunch of othre stuff. But how do you turn it into a website?

We will return to the command line to do this. First, you should go into your Hugo folder and run the command

hugo server -D

This creates a local instance of your website. Navigate to http://localhost:1313 to see your site in action! When you edit your site, it will refresh to show you the changes nearly instantaneously. How convenient.

“But Mr. Haddock,” you say, “I hate opening my command prompt and navigating to my folder path every single time. This is not convenient at all!”

Well don’t worry, because with the magic of batch files, you don’t even have to do that (if you are a Windows user).

Simply make a file called something like testsite.bat inside your main Hugo website folder and include the following code:

@ECHO off
:start
ECHO lets do this
CALL hugo server -D

Now every time you want to test your site out, just double click the batch file. When you’re done, you can close it and it will stop running.

8. At long last, upload it to Neocities

For this, you’ll need to install the Neocities CLI. Because I use Microcock Winblows, I installed Ruby using the Ruby installer, and then ran the command

gem install neocities

to install the CLI. After that, I run the Neocities command and get my API key from my Neocities account (it’s going to be somewhere like https://neocities.org/settings/yourwebsite#api_key) and then it’s as easy as executing the following commands (inside my Hugo site folder)

hugo
neocities push public

But oh man! I hate typing the same shit all the time! Why should I be typing commands when I could be typing my blog? Well, that’s why I have written the following batch file (again, just for Windoes users)

@ECHO off
:start
ECHO congratulations
CALL hugo

CHOICE /N /C YN /M "Do you want to upload your site to Neocities? [Y/N]"
IF NOT errorlevel 2 IF errorlevel 1 GOTO Continue
GOTO :EOF

:Continue
CALL neocities push public
TIMEOUT 10

This way you can double click the batch file and type Y to confirm that yes, you do want to put your site up on to Neocities.

Or if you don’t want to do any more fancy code shit and you’re sick and tired of it, you can just upload the contents of the public folder to Neocities using their website.

All right! You’ve done it! Now you can just add pages as you please, and you have a very easy to update website!

If you have any trouble with my guide, please check out the following sites that I ripped off blatantly:

• Hugo Quickstart
• Bearblog Theme
• Neocities CLI

If you still need help, please contact me through my guestbook.

Other fun stuff that I put into my page

Everything fun I’ve put into my page is through the use of shortcodes! These are little snippets of HTML that I gleefully embed into my site. In order to make a shortcode, you can go to the layouts/shortcodes folder and create a little .html file. If you want dynamic shortcodes, you will have to use some Go for it, but it’s not too terrible.

For example, if I want to embed something from Bandcamp, I can grab their embed code and put it into bandcamp.html:

<iframe src="https://bandcamp.com/EmbeddedPlayer/v=2/{{ if .Get "track" }}track={{ .Get "track"}}{{else if .Get "album" }}album={{ .Get "album" }}{{ else }}track=3452415123{{ end }}/size=medium/linkcol=3273dc/tracklist=false" style="border:none;width:100%;height:120px;margin-top:.5em;margin-bottom:.5em;"></iframe>

and then I can put the following shortcodes into my site (remove spaces between curly braces and carats because I cannot comment them out without rendering the shortcode, lol):

{{ < bandcamp album=498751779 > }}
{{ < bandcamp track=1887896462 > }}

and get

The power of shortcodes feels pretty unlimited to be honest. If you want to read more about this, Hugo has a good guide on how to use them and how to make new ones.

My guestbook

I used a shortcode to embed my guestbook too. I signed up for HTML Comment Box’s free account and just pasted the Javascript (+styling to make it look like the rest of my site) into a shortcode! Then I embedded the shortcode into a top level page, and that’s it!

Something like this in the shortcode (code shouldn’t work unless you sign up though lol):

<!-- begin wwww.htmlcommentbox.com -->
 <div id="HCB_comment_box"><a href="http://www.htmlcommentbox.com">HTML Comment Box</a> is loading comments...</div>
 <link rel="stylesheet" type="text/css" href="https://www.htmlcommentbox.com/static/skins/bootstrap/twitter-bootstrap.css?v=0" />
 <script type="text/javascript" id="hcb"> /*<!--*/ if(!window.hcb_user){hcb_user={};} (function(){var s=document.createElement("script"), l=hcb_user.PAGE || (""+window.location).replace(/'/g,"%27"), h="https://www.htmlcommentbox.com";s.setAttribute("type","text/javascript");s.setAttribute("src", h+"/jread?page="+encodeURIComponent(l).replace("+","%2B")+"&opts=16798&num=10&ts=1642634793631");if (typeof s!="undefined") document.getElementsByTagName("head")[0].appendChild(s);})(); /*-->*/ </script>
<!-- end www.htmlcommentbox.com -->

and then this in the markdown file:

+++
title="Guestbook"
menu="main"
+++
{{ < guestbook > }}

And bam! You have a free guestbook.