The words Under construction in black text on a yellow background with diagonal black stipes surrounding it
I'm in the process of moving my site. It's still a work in progress. Please excuse the mess and broken links.

Things People Asked For In A Static Site Generator

TODO: Pull subtitle into page object


There's lots more to cover. I'll be pushing up a site with examples in the next week or so to give a better idea of how things work.

Debugging Stuff

I'm moving stuff around right now. All this below is helping me figure out where to put stuff

        -- title

Things People Asked For In A Static Site Generator

These responses are from when I asked what 
folks would look for in a new static site generator. My thoughts
are below each one.

-- list

- <<span|Get router/paging/pagination type stuff really solid|class: x>>

I spent a lot of time thinking about routing. Not just for Neopoligen, 
but for every site process I've used or built over the past two 
decades. My conclusion: let the computer do it. Give every page an
ID and use that instead of spending time working on directory 
structures that never quite work right. 

Among other things, it helps avoid link rot. You can move to other
systems and it's a lot easier to match the ID than try to 
map to some specific url structure or setting up redirects, or
just letting the old urls break.

- <<span|Author in markdown|class: x>>

This one got mentioned a few times. It is, of course, funny to me 
that no one said, "find something to replace markdown" seeing as
that's key to everything here. Quite possible I'm tilting 
at a windmill, but someone's gotta do it every now and then.

- <<span|Custom templates tied to directory structure 
(eg a default layout, with the ability to override them by 
associating a type of content with a template)|class: x>>

Continuing from above. I'm taking directory structure off the table.
Files can be stored locally in any structure that makes the source
content easy for you to maintain. When they're published, the 
computer takes over. The local directory structure is ignored and 
everything is put in a place by ID^custom-urls^^. 

Incidentally, it's tough to explain how much of a delight it's
been to be able to name, rename, and move files without
having to worry about breaking links or having to hunt down
ones that need changing. 

The template used to render the page is defined by a combination
of two attributes in a `-- metadata`` section. Specifically, 
`-- type`` and `-- status``. I use the type for the primary 
definition (e.g. "post", "review", "quote") and then use one
of three statuses "scratch", "draft", or "published". You end up
with things like `post-published``, `post-draft``, `quote-scratch``

Throw files anywhere you want and move them whenever works for you.
It won't matter. The output will always go to the same URL
and your links will keep working. 

Making custom urls/slugs is a built-in feature, but I find I 
use it very rarely. I'd really rather just not think about it.

- <<span|Easy way to access front matter inside templates|class: x>>

There's a `-- metadata`` section in Neopolitan. It's what houses
these stuff that would be in markdown front matter. I usually keep
it at the end of my documents though since I like seeing the 
content first. 

The primary values are limited to key/value pairs. You can also
flag the section as either JSON or YAML and throw data in those 
formats into it. (CVS is a possibility, but there's lots higher
on the priority list)

- <<span|Shortcodes/partials that can be used in both content and templates|class: x>>

You can't use the same MiniJinja tags in the templates or the Neopolitan
tags inside templates. Both sides are pretty flexible though. Everything
starts with the content and the tools for making decisions based on 
it are pretty robust. I'm curious to hear how things in this approach
stack up with expectations. 

- <<span|Some kind of plugin/extension api would be great|class: x>>

The way I view the project is with a strong separation of concerns
where the content is separate from the rendering. I see this
point more on the content side. I've been considering what it
would look like to just call out to other processes and have
them return JSON that gets fed to the templates along with 
the rest of the content. 

I really like the idea in terms of keeping things generic. 
It's also in line with the unix philosophy of do one thing
and do it well. But, there's some security concerns there that 
I don't know enough about yet. I'll be reaching out to folks
who know more about it than me. 

- <<span|The ability to generate individual pages from API data|class: x>>

This is similar to the one before it. I was thinking 
specifically of making a call out to `curl`` for this, 
but lots of APIs require some sort of key and I'm not
at a point where I want to get into that mix. 

That brings me back to the idea of calling out to 
external process that are basically black boxes. The
page asks for some data, the process does something, 
then some JSON comes back and you get to use it
in the template for rendering.

- <<span|Powerful directory structure to lay out content|class: x>>

Oh yeah, I should point out that page title style slugs
are still in the URLs. They're in the query string 
portion of the URL and can change to whatever because 
the pages are static and the server doesn't care
about query strings. They're just there to make things easier
to look at for us humans. 

(All the references I've seen say they don't think
URLs have much of an influence over SEO. Even if they
have a little, I'm not worried about it making
a significant difference. Not having to worry about
directory structures and linking is well worth it
to me even if there is a little hit.)

- <<span|Two types of pages: Static pages - Blog posts (ordered by ISO8601 formatted date prefix)|class: x>>

Page types are defined in a config file, you can have as 
many as you want. In the past I would have called the
difference between static and blog posts the difference
between URL styles where static would be like `/neopoligen``
and blot posts would be like `/2024/01/18/some-title/``. 

You can still make those URLs, and I do them for landing 
pages (like `/neopoligen``, but the other pages are 
based off ID). 

I've found the overall approach freeing. I no longer 
think about if a page is a post static. I just think
about what type I want it to be (e.g. example, quote,
post) and then add that to the config^config^^ that controls
which ones are available.

As for ordering, that's built in with a few different 
approaches. You can currently call by page type either
inclusive or exclusive. So, you can make a list of
just "example", and "post" pages, or a list of everything 
except those two. In either case, you can sort 
alphabetically or chronologically. 

Those same lists will be able to power "previous/next"
links for pagination as well. 

- <<span|Nav generation Including something useful for 
blog posts (keep in mind there may be thousands eventually)|class: x>>

I'm addressing this on two fronts. The first one is the
page lists. Template can be made that limit the responses 
to the most recent 10 or whatever to limit nav. I'm also
making menus that can be defined by JSON in content files
and then used anywhere on the site. There's more work to 
do with this. 

The good news is my site has 2k+ posts on it, so I've got
a big one to play with. 

- <<span|Pagination|class: x>>

I'm still thinking about this, but I'm pretty sure it'll
be a combination of the page lists and javascript. 
You'll request the page set you want and then use JS
in query strings to navigate around. Still more research 
to do on this one though. 

- <<span|IDs and classes on every page element to make custom CSS easy.|class: x>>

An example site ships with Neopoligen with an 
expansive set of templates. All of them have lots
of IDs and classes. And the templates are 
straight forward to edit. So, any style could
be added and adapted to. 

- <<span|Image resizing and zoom for inline images|class: x>>

This is a phase two thing for me. It's high on the priority list tough. 
I used to be a photographer and one of the things I want to solve for
is image so I can enjoy posting them instead of fighting with the software 
to do so. 

One thing I'm looking to add is the ability to pull alt text directly from
the metadata of an image. I really like the idea of writing in the 
alt text one time and then having it be applied wherever I use the image. 

- <<span|Code highlighting|class: x>>

I'm using the syntect highlighter. It's set up to add classes instead of inline
styles for each token. Six style sheets are included. I'm not sure how
they were made yet, but I'm sure others could be generated from
existing style sets.

- <<span|Some form of third-party comment integration|class: x>>

This goes back to the external process calls. I expect 

- <<span|Author profile pages with gravatar|class: x>> 

Totally doable. I'd approach this by adding an author name
to the metadata and then matching on it for the template to call
an image. That would just be another template in the mix to 
create the URL. 

- <<span|Git post-commit hooks for publishing|class: x>>

This will be a later phase thing, but I'm into the idea. For me, 
for now, my publishing is simply a matter of pushing main
up to GitHub and letting Netlify pick it up and deploy it.

- <<span|Templating with some sort of context (maybe a json file to 
provide key/value?) so you can change out variables over time|class: x>>

Yep. That's built in. In fact, you can add multiple JSON sections
with different content and you'll also be able to centralize
JSON in one file and include it in others. 

-- h2


There's lots more to cover. I'll be pushing up a site
with examples in the next week or so to give a better
idea of how things work. 

-- footnote
-- id: custom-urls

You can also define explicit url/slug paths when you want. 
I do this for landing pages for different projects, but
only for the those. Any other page for a project, I let
the computer handle the location and linking for me. 

-- footnote
-- id: config

More docs coming on the config and what you can do with

-- css

.x {
  font-size: var(--size-4);
  font-family: var(--heavy);
  font-weight: 700;
  font-style: italic;

-- metadata
-- date: 2024-01-18 04:56:26
-- id: 2b7gyfsb
-- type: neopoligen
-- status: draft