Site Generation Overview

The toolchain that I use for generating this website is the following:

  • Geany text editor with MarkDown plug-in.
  • Python with MkDocs
  • Neocitizen python library.

All are FOSS, simple text, terminal and command line tools.

The work stream is as follows:

  • Geany is used to compose content in MarkDown format. The Geany MarkDown plug-in provides a sideframe to view the .md files as .html format.
  • Files are saved with the .md suffix in the MkDocs site template.
  • MkDocs converts the .md files to .html and includes a server to preview the website.
  • Neocitizen is used to upload the changed .html
  • TaDa!

Why? Simple small static web sites should be simple to make and maintain. I prefer to write pages as MarkDown. Writing html with all those brackets is painful. The MkDocs and Neocitizen python libraries automate the process of generating and uploading.

The gritty details

Python venv for mkdocs website preview and Neocities.org upload

Modern python (python3) encourages you to work in a virtual python environement. The advantages to this are that you have an isolated stable environment in which to develop and run programs. Doing this is easy. This guide is based on linux using the standard terminal. My distribution of linux has python3 and pip3 included.

Create and activate a python virtual environement

  • Make a directory for your project. (myproject)
  • Start a terminal in your project directory.

  • At the prompt (user@machine:~/myproject$) enter

    python3 -m venv venv

  • Check to make sure a directory called venv has been created in your project.

  • At the prompt (user@machine:~/myproject$) enter

    source venv/bin/activate

  • If all goes well you should have a venv prompt in your terminal ( (venv) user@machine:~/myproject$ ) indicating that the virtual environement has been activated.

  • When done, close the python venv at the prompt enter.

    deactivate

Add the mkdocs module to your venv using pip3

  • With the venv active, at the prompt ( (venv) user@machine:~/myproject$ ) enter

    pip3 install mkdocs

  • If all goes well mkdocs and markdown as well as a number of dependencies should be added to your venv/bin directory.

Using mkdocs to make a new website

  • At the prompt ( (venv) user@machine:~/myproject$ ) enter (mywebsite is my website)

    mkdocs new mywebsite

  • Change to the website directory.

    cd mywebsite

  • You should see a directory called docs and a .yml file that tells mkdocs how to build and display the website.

To display the website locally

MkDocs converts .md files to .html on the fly and displays them via the mkdocs web server.

  • At the prompt ( (venv) user@machine:~/myproject/mywebsite$ ) enter

    mkdocs serve

  • You should receive a response indicating that the website is built, the server is started and the URL is 127.0.0.1:8000.

  • Start a web browser and view the website.
  • Changes made to the markdown files in the docs directory are immediately available to the web server and browser when the document is saved.
  • To stop the web server in the terminal in which it is running type Ctrl-c.

To build a local copy of your website.

  • At the prompt ( (venv) user@machine:~/myproject/mywebsite$ ) enter

    mkdocs build

  • A local copy of your website is built and placed in the "site" directory.

To upload your website to Neocities.org

Neocities.org provides a Ruby gem to automate the upload process from a local repository. As most of the process thus far been using a simple text editor and python, my preference is to use a python package rather than a Ruby gem. As python3 is available in the Raspberry Pi operating system by default, it makes sense to use a python library. (https://pypi.org/project/neocitizen/)

  • At the prompt ((venv) user@machine:~/myproject$ ) enter

    pip3 install neocitizen

  • Neocitizen should install in /venv/bin

  • To install files to Neocities you need to login and go to userID (upper right) > Settings > Manage Site Settings > API. Copy your API Key for use in the following commands.

  • Check to see that you can list your site pages.

  • At the prompt ((venv) user@machine:~/myproject$ ) enter

    neocitizen --key NeocitiesAPIkey list

  • A list of the website pages should print to the terminal.

  • To upload your website the following should work.
  • At the prompt ((venv) user@machine:~/myproject/mywebsite$ ) enter neocitizen --key NeocitiesAPIkey upload --dir site

I use Geany with a markdown plugin to edit my .md files.