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

    1.1.2 • 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

    Install

    npm i pupate

    DownloadsWeekly Downloads

    2

    Version

    1.1.2

    License

    GPL-3.0-or-later

    Unpacked Size

    99.2 kB

    Total Files

    43

    Last publish

    Collaborators

    • qubist