The Makefile has a target to create a virtual environment in the current
directory. To set up the virtual environment:
make venv
And to run the Pelican development server:
. .venv/bin/activate
make devserver
Use Docker to build the static site:
make dockerbuild
Get the size of the repo (minus git metadata, output dir, etc)
make reposize
Alternately, you can install Pelican via [pipx] and still make use of the Makefile targets:
pipx install pelican[markdown]
Images are generally a maximum of 640 pixels wide.
Easily the most annoying part of writing content for this is handling the images. Oh, markdown has ways of inserting images into a document, but there are "issues" If you want to style article images in some way differently from the other images on the page, good luck because unless you write your own extension, the parser only outputs the barest of plain HTML, which makes writing CSS targeting these images difficult to impossible. (This is totally reasonable behavior on the part of the parser, but is highly inconvenient when using markdown for publishing.)
The markdown parser that Pelican uses (and probably most others) allow for an image to have a title, which most browsers render as a tool-tip when hovering over the image. If you want a caption above or below (which is more useful than a tool-tip), there is no markdown for that, without an extension.
For reference, this is the syntax for inserting an image:
And this is how you would use an image as a link (to another page or image):
[]({static}/images/x0x-2/x0x1-1.JPG "x0xb0x r0x ur s0x")flywire/caption looks interesting and claims to do pretty much what I want, but the project is not under very active development and might even be a little broken in its current state. The rest are hacky in various ways.
Someday, I may write my own markdown extension to do this. Today is not that day.
If Pelican had a way to write Jinja2 macros in the markdown content, this would work for me even if it meant making the content somewhat less future-proof. However, this isn't possible. There is an extension that does this but it's not heavily maintained and has some caveats.
This is what we're left with. Carving out our ideas into stone tablets with a hammer and chisel. These are all of the permutations that I use:
A regular image:
<figure>
<img src="{static}/images/article-name/image.png">
</figure>An image with a title (tooltip):
<figure>
<img src="{static}/images/article-name/image.png" title="title for the image">
</figure>An image as a link (usually a thumbnail to a full-size image):
<figure>
<a href="{static}/images/image.png">
<img src="{static}/images/thumbnail.png">
</a>
</figure>An image with a caption:
<figure>
<img src="{static}/images/article-name/image.png">
<figcaption>This is a caption.</figcaption>
</figure>An image as a link with a caption:
<figure>
<a href="{static}/images/image.png">
<img src="{static}/images/thumbnail.png">
</a>
<figcaption>This is a caption</figcaption>
</figure>