Before you get started

You need to store a local copy of your neocities website, and then upload or "push" your blog files every time you make changes to your blog posts, CSS stylesheets, scripts, templates or any other static files of your website. If you haven't downloaded your website files to your computer, you should sign in to your Neocities account and go to Edit Site → Page bottom → Download entire site.

It is also highly recommended to install Neocities CLI. It is a very useful tool to quickly upload your site files from the command line, instead of having to use the web interface. Nob is Neocities CLI-friendly.

Creating a blog

First, you need to open the directory where your website files are stored. For example, if your site files are in ~/web/my-neocities-website, run cd ~/web/my-neocities-website

Once you opened the directory, run the following command to create a new blog:

nob create <blog directory name>

It's highly recommended to specify the URL of your neocities blog too:

nob creeate <blog directory name> -u <url of your neocities blog>

Examples

nob create my-blog

nob create blog

nob create "dream-diary" --url "https://madotsuki.neocities.org/dream-diary"

nob create blog -u https://someone.neocities.org/

File structure

Once you've created a new blog, the following file structure will be generated:

📁 <your website root directory>
|_ 📁 <your blog root directory>
   |_ 📁 .nob
      |_ 📁 entries
      |_ 📁 templates
         |_ 📄 index.html
         |_ 📄 post.html
         |_ 📄 rss.xml
         |_ 📄 my_blog_link.txt

Files and their purpose

• root directory of your blog: The static files of your blog will be generated by nob in the root directory of your blog. This includes HTML, CSS, JS and other static files such as images. Please note that nob only generates the HTML files, you need to add images, styles and scripts by yourself.
• .nob/: This directory contains blog raw data and it's required for nob to generate your site static files.
• .nob/entries/: This directory will store all your editable blog entries in Markdown
• .nob/templates/: Mostly HTML templates of your blog static files

Templates

You can edit the templates to add CSS stylesheets, scripts, or change the layout of your blog.

• index.html: The index page of your blog. It contains a HTML list (<ul>, {{.entries}}) of your blog posts, which nob will sort by date. Please note that {{.entries}} is always a string that contains <li> elements, each one is a link to an entry you posted.
• post.html: This template will be used to generate the HTML pages for each of your blog posts. Every time you run nob build several copies of this file are generated in <your blog root directory>/ and they are filled with your entries' contents.
• rss.xml: The template of your blog RSS feed. It's editable in case you want to change something like the feed description or title.
• my_blog_link.txt: The URL of your neocities blog. Example: https://mysite.neocities.org/blog or https://myblog.neocities.org. This URL will be used to properly generate the RSS feed articles.