how to escape the chains of the neocities ui in 2 weeks

let there be neocities

i experimented with different personal websites before settling on neocities. i first tried notion, which is a bit like publishing a giant google spreadsheet with links to all your notes. i didn’t love the lack of customization (beyond choosing different… emojis…?), either. github pages was also an obvious option; though i made an academic-ish profile, it felt sterile and i never felt like i had anything to post.

turns out i need a workflow

nonetheless, the neocities editor is clunky, slow, requires opening many, many tabs to be effective, and lacks shortcuts. i had a couple of priorities for creating a better neocities workflow:

• open files in vscode
• automatically sync edits to neocities dashboard
• private file repo
• render math / LaTex
• inject into html template instead of copy-pasting to each page
• dynamically generate navigation / toc for note browsing
• sidenote / footnote capability
• local testing ability

let there be workflow!

luckily, it turns out that all of these are simple tasks! here’s what i used to create a fast website-making workflow:

• github for version control:
  • i work on a separate branch and preview locally with the help of 11ty (see next bullet)
  • when i’m satisfied with my changes, i push to main and use a script to add all changed / new files and delete old ones from my neocities dashboard.
• using a static site generator like hugo, 11ty, or jekyll:
  • i used 11ty to generate from njk templates! this + github also lets me work in vscode and host locally to preview changes instantly, which is a game changer (sometimes edits in neocities don’t even show up because of cache issues…)
  • i use the KaTeX plugin to convert my markdown math into mathml
  • i use another 2 KaTeX plugins to add ids to all of my math headings and generate the navigation sidebar (though i’m still not great at css and it isn’t super great in structure / sizing)
• sidenotes:
  • i was inspired by a couple of other indie sites, which i credit on my main page’s resources list. i think sidenotes are way better than footnotes for the web, both visually and for ease-of-reference.

notably, the markdown KaTex plugin has security vulnerabilities, so i would recommend using microsoft’s secure version of it (on github).

and that’s it! i’m now writing from the safe, beautiful confines of VSCode (though, who knows, maybe i’ll move to another IDE when working on my site, just for aesthetic reasons). imo, it’s super worth it to make these changes, especially if you plan on editing your site often / in perpetuity…