pupate-tool
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

Pupate

standard-readme compliant

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.

  1. Write plaintext entries in a simplified, Markdown-like WYSRDWYG format
  2. Specify display options in a human-readable text file
  3. 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 \.

Embellishment details
Embellishment Pupate plaintext Generated HTML Rendered
Bold
Chicken soup is
*not* vegetarian.
Chicken soup is
<b>not</b> vegetarian.

Chicken soup is
not vegetarian.

Italic
Potato soup is
_usually_ cage-free.
Potato soup is
<i>usually</i> cage-free.

Potato soup is
usually cage-free.

Color
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)

Links
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.

Option name Description Allowed values Default value

fontIs

Font family for all text on the site Arbitrary CSS value (only web-safe fonts work I think?)

monospace

sizeIs

Font size for all text Arbitrary CSS value

16px

textColorIs

Default color for all text Arbitrary CSS value

initial

linkColorIs

Default text color for links Arbitrary CSS value

revert

backgroundColorIs

Background color for all pages Arbitrary CSS value

initial

showIndexWith

How or whether to display the index of pages on the homepage
  • 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

Order in which to sort pages in the index

newest

pageURLsBasedOn

How to derive the URLs for entry pages. (All values are unembellished and sanitized before use in a URL.)
  • title
  • filename
  • date

filename

outputLocationIs

Path at which to generate the site Valid path string

./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

  1. Clone this repo

  2. Install TypeScript stuff if you need it

    sudo apt install node-typescript
  3. Install types

    npm i @types/node
  4. Complile the TypeScript to JavaScript for the first time

    npm run build
  5. Install so you can use the command globally

    sudo npm install -g ./
  6. Run the build script after making changes to any .ts file

    npm run build

    This will compile TypeScript files in the lib/ directory into JavaScript in the dist/ directory. The build script also automatically regenerates the example blog to keep it updated with the current source code.

  7. Run the tests

    npm run test

Publishing a new version to npm

  1. npm run build to compile TypeScript and build the example blog
  2. npm run test to make sure tests are passing
  3. npm version (major|minor|patch) to bump the version number depending on the changes
  4. npm publish
  5. git push --tags

See also

License

GPL

Versions

Current Tags

VersionDownloads (Last 7 Days)Tag
1.0.01latest

Version History

VersionDownloads (Last 7 Days)Published
1.0.01

Package Sidebar

Install

npm i pupate-tool

Weekly Downloads

1

Version

1.0.0

License

GPL-3.0-or-later

Unpacked Size

69.6 kB

Total Files

19

Last publish

Collaborators

  • resiship