pupate-tool
v1.0.0
Published
Simple static site generator for text-only blogs that invites code-injection as an editing tool
Downloads
3
Readme
Pupate
Simple static site generator for text-only blogs that invites code-injection as an editing tool
Background
Pupate creates websites with absolutely no frills and barely any features. Pupate prioritizes your experience writing entries, giving you just enough control to express yourself through text. If you need more, inject it yourself by writing some HTML.
- Write plaintext entries in a simplified, Markdown-like WYSRDWYG format
- Specify display options in a human-readable text file
- Pupate compiles your text files into a website with an index and a page for each entry
Pupate is rock-simple but allows you a lot of creativity when you really need it. Just write, then watch your ideas emerge fully formed and beautiful.
Install
sudo npm install -g pupate
Run puate help
to make sure pupate was installed correctly.
Updating
sudo npm update -g pupate
Usage
pupate
Commands:
pupate check check that the current working directory is a valid
Pupate-shaped directory
pupate spawn create necessary pupate files in the current working directory
pupate eclose build the site in the output directory based on the content of
the larva directory
Options:
--version Show version number [boolean]
-o, --output minimum importance-level of messages to display
[string] [choices: "ERROR", "WARN", "INFO", "DEBUG"] [default: "INFO"]
-q, --quiet run without any output [boolean] [default: false]
--help Show help [boolean]
Overview
Pupate needs to run in a Pupate-shaped directory. Here is the tree of one such directory:
pupate-site
├── larva
│ ├── entries
│ │ └── soup.txt
│ │ └── salad.txt
│ └── homepage.txt
├── options.txt
└── imago
├── index.html
├── soup
│ └── index.html
└── styles.css
Inside, there are two directories, larva/
and imago/
and an options file. Text files for entries,
plus a homepage file live in larva/
. Running Pupate
generates a site in imago/
. (The location where the site is generated can also
be customized.)
Editing entries
Each entry is a single text file in the larva/entries/
directory. The first
line in the file is the title. The second line is the date. Then there's a
blank line. All lines after that are the body of the entry. Each entry becomes a
page in the generated site.
How I make soup
2021/03/04
This is a post with my soup-making recipe.
First, make the soup.
Eclosion (Generating a site)
In a Pupate-shaped directory, run pupate eclose
(or just pupate
) to generate
css and html in the output directory based on the contents of the larva/
directory. Eclosion also generates an RSS file rss.xml
.
Eclosion deletes all files in the output directory and re-creates them. So don't
store stuff in there. A backup is made to pupate/.imagobackup/
in case you
did.
Embellishments
A modified subset of Markdown is available in Pupate to allow embellishing text. Embellishments in Pupate are designed to make reading and writing un-rendered text both easy and unambiguous, something Markdown attempts but doesn't quite nail. Luckily, we have a lot less to deal with here.
(Further reading: WYSRDWYG)
Available embellishments are hyperlinks, bold, italic, and text-color. Special characters can be escaped with \
.
Chicken soup is
*not* vegetarian.
Chicken soup is
<b>not</b> vegetarian.
Chicken soup is
not vegetarian.
Potato soup is
_usually_ cage-free.
Potato soup is
<i>usually</i> cage-free.
Potato soup is
usually cage-free.
First, add
{red}(red)
and
{green}(#00ff00)
peppers.
First, add
<span style="color: red">red</span>
and
<span style="color: #00ff00">green</span>
peppers.
First, add
red
and
green
peppers.
(but imagine the text is colored)
Check out my
[recipe](https://e.com)
for details.
Check out my
<a href="https://e.com/">recipe</a>
for details.
Check out my
recipe
for details.
Nesting
All embellishments besides links are allowed to be nested.
Options
The larva/options.txt
file defines options for the whole site. Each line
contains a camel-case option name followed by a space followed by the value for
that option. If an available option is not specified, its default is used.
If you ran pupate spawn
, an options file comes pre-populated with all
available options set to their defaults.
fontIs
monospace
sizeIs
16px
textColorIs
initial
linkColorIs
revert
backgroundColorIs
initial
showIndexWith
dates
(display each page's title with its date)noDates
(display each page's title only)dont
(don't display an index of pages. Useful if you'll make your own index)
dates
sortIndexBy
newest
(sort lexicographically by date, note: this won't work with most human-readable dates)oldest
filename
title
newest
pageURLsBasedOn
title
filename
date
filename
outputLocationIs
./imago/
RSSBaseURLIs
The base URL of your site, used by the RSS feed to link to your site and its pages. Must end in a slash! For example, if a certain page on your site has the address https://jerbix.com/crumble-university
, this option should be set to https://jerbix.com/
. If you don't use the RSS feature you can ignore or delete this option.
Valid URL ending in /
https://www.example.com/
You can also see an example options.txt in the example blog.
Contributing
PRs accepted! Fixes for existing issues appreciated. Small improvements and tweaks will be considered. New features should probably happen in a fork, unless you convince me ;)
Developing
Clone this repo
Install TypeScript stuff if you need it
sudo apt install node-typescript
Install types
npm i @types/node
Complile the TypeScript to JavaScript for the first time
npm run build
Install so you can use the command globally
sudo npm install -g ./
Run the build script after making changes to any
.ts
filenpm run build
This will compile TypeScript files in the
lib/
directory into JavaScript in thedist/
directory. The build script also automatically regenerates the example blog to keep it updated with the current source code.Run the tests
npm run test
Publishing a new version to npm
npm run build
to compile TypeScript and build the example blognpm run test
to make sure tests are passingnpm version (major|minor|patch)
to bump the version number depending on the changesnpm publish
git push --tags