how to set up the blog, publish an entry, make styling changes, etc.
written on 2023-01-15i've gone two years without writing a single line of code (more or less) and need to relearn how to run this blog. this will be a very scrappy how-to for me in the future who will probably forget again :) as of writing this, i'm using flask to dynamically generate static pages, with git/github for version control and neocities for hosting. what does that all mean even...who knows
while in the correct directory
venv with source venv/bin/activateapp/pages/pub/\{insert rest of directory here\} with template.md as the template. naming convention is entry_#_yearmonthday.mdpython3 app/sitebuilder.py build; this takes the markdown and locally builds the pages for you (eg: the post page itself as well as tags and the home page)neocities push ../docs, this way you only publish the static/generated pages that have been updated and not republish the entire site + its backendthese are just things you should make sure you have set up before moving forward
cd /mnt/c/ to get to the directory where all your stuff is.... (lol is it a security risk to post this? who cares, i have like 1 reader)==TODO:== configure bash to start off in that directory, and build in shortcuts for myself. also set up neocities CLI integration for easier publishing
what is this...why did i do this? anyhow, you should make sure all three of these things work! i ran into a bunch of errors trying to set up virtualenv again so i ended up uninstalling it entirely...yeesh...
sudo do-release-upgrade.sudo apt-get install python3) and package manager pip (pip install --upgrade pip or sudo apt install python-pip if it's gone, which i'm not sure if it was for me...apparently pip ships with some verisons of python). i think the idea is that python and pip run globally and then the virtualenv will manage things like flask. is this the best way to do things? probably not, but we can revisit this later==TODO:== is there a functional difference between python3 pip and python pip? for the time being, i'll stick to python3 and pip3.
3. now set up a virtual environment! make sure you run sudo pip3 install virtualenv, otherwise you'll run into a command not found error. if everything goes smoothly you can create a virtualenv (named venv) with virtualenv -p python3 venv and you should be able to activate venv with source venv/bin/activate if you are in the working directory.
4. install any requirements listed in requirements.txt with pip3-install -r requirements.txt. for me, those included flask, frozen-flask, and other dependencies like markdown.
5. pray it works!
since i'm no longer using github pages to host this blog, i don't need to be tied to github for version control. i don't think i should move away from using remote version control altogether...but this is a thing to think through another time. in any case, just remember to run git pull origin main probably. what would be a safe way to keep everything up to date is to start a new git branch (git checkout -b <name of new branch>), and then push that branch to github remote (git push origin <name of new branch>). (currently my blog is being pushed on to remote branch new-leaf.)
==TODO:== how to merge onto main? do i even need to do that?
you can do this running subl . once you're in the directory of choice.
so having done all the steps above, i was able to run python3 sitebuilder.py while in venv. sitebuilder.py happens to be the name of our flask app, and holds a lot of the basic logic for routing us to the static pages. this guide i linked in an earlier entry seems to be something i referenced a lot making this blog and it seems pretty comprehensive so far. however, i ran into some errors trying to compile my blog as-is...
the blog is currently setup to use flask-flatpages, which essentially grabs markdown files and then converts them into static HTML. i kept running into a problem where the YAML metadata (eg: entry title, entry date, tags) wasn't being attached to each FlatPages Page object, but it turns out the issue was that my YAML metadata was formatted incorrectly. also, i was writing dates incorrectly! the YAML metadata should (generally, not sure if this has changed) look like this:
title: starting again
subtitle: how to: set up the blog, publish an entry, make styling changes, etc.
date: 2023-01-15
tags: [update, process, meta]
---
entry contents......
apppub (eg: not in a date/month/ directory)/ but it shows up?