Stubble

Your Boilerplate Document Assistant

Stubble is a command-line tool for quickly generating markdown files for use by static site generators. Given a title, it will generate a date-stamped markdown file with pre-populated YAML front-matter.

Currently Stubble leans specifically to Eleventy, but future versions could theoretically provide templates for a number of popular SSGs and/or user-defined templates.

Stubble is written in Rust.

Usage

Run stubble with the string to use as the title of your new document:

stubble "Hello, World!"

Stubble should output a message like this:

Created new file ./2023-11-02-hello-world.md!

(The date defaults to the current date.)

You may also omit the title by passing - like so:

stubble -

Which should output a message like this:

Created new file ./2023-11-02.md!

Stubble generates basic front-matter for you, so you can just start writing. Open the file in your editor of choice, and it should look more or less like this:

---
title: "Hello, World!"
permalink: hello-world
date: 2023-11-02
uuid: 3b17e9f7-6334-4bf1-a063-9174a2b1eedb
---
# {{ title }}


<!-- Generated by Stubble v0.2.3 -->

Specifying the output directory

By default, Stubble generates files in the current working directory. If you want it to write files somewhere else, add the output directory after the title:

stubble "Hello Again, World!" /tmp

...and you should see:

Created new file /tmp/2023-11-02-hello-again-world.md!

Specifying the permalink slug

By default, Stubble uses the title as the slug. If you want to use something else you can use the slug flag -s or --slug followed by the desired slug.

stubble "Hello, World!" -s hello

Applying tags

Stubble supports adding any number of tags to your post, using the tag flag -t or --tag. One flag for each tag.

stubble "Hello, World!" -t rust
stubble "Hello, World!" -t rust -t programming

Override the post date

To use a date other than the current date, use the date flag -D or --date.

stubble "Hello, World!" -D 1988-08-10

...and you should see:

Created new file 1988-08-10-hello-world.md!

Add a description to your post

If you want to populate the front matter description field, you can use the description flag -d or --description.

stubble "Hello, World!" -d "This is my first post generated with Stubble!"

Specifying the post author

By default Stubble with try to populate the author field in the front-matter for you. It will first ask the OS for your "Real Name" and if that fails it will default to your username. To specify something else you can use the author flag -a or --author.

stubble "Hello, World!" -a "Joey Pardella"

Changing the filename on output

By default, stubble will generate a filename for you from the date followed by the slug. To override this behaviour you can use the output flag -o or --output.

stubble "Hello, World!" -o draft-post.markdown

...and you should see:

Created new file draft-post.md!

Open in your editor

Stubble can optionally open your newly generated stub in the editor of your choice. The flag -e or --editor takes up to 1 argument. Providing an argument will open the file in that program, while omitting the argument will attempt to open the file with the executable defined in the environment variable $EDITOR.

Built in help

At any time you can check the available options and their use from the command line.

stubble -h
Stubble is a command-line tool for quickly generating markdown files for use by static site generators. Given a title, it will generate a date-stamped markdown file with pre-populated YAML front-matter.

Usage: stubble [OPTIONS] <TITLE> [DEST]

Arguments:
  <TITLE>  Title of the post
  [DEST]   Output destination [default: .]

Options:
  -s, --slug <SLUG>                Optional slug to be used for the permalink
  -t, --tag [<TAG>...]             Tag(s) to apply to the post. Separate multiple tags with spaces
  -D, --date <DATE>                Override the post date: YYYY-MM-DD
  -d, --description <DESCRIPTION>  Post description
  -a, --author [<AUTHOR>]          The name of the author
  -f, --format [<FORMAT>]          The output format that should be used to render the stub. [default: md]
  -o, --output <OUTPUT>            Override the default filename
  -e, --editor [<EDITOR>]          Open in <EDITOR>
  -y, --yes                        Automatically answer 'Y' to all prompts (including existing file warnings)
  -h, --help                       Print help (see more with '--help')
  -V, --version                    Print version

And slightly more verbose help is available using the flag --help

Installation

With Cargo

Cargo is Rust's package manager. To install Stubble with cargo, you will need to install Rust on your computer, version 1.73 or later.

One you have Rust installed, open a terminal and run:

cargo install stubble

Assuming everything builds correctly and your local ~/.cargo/bin directory is in your PATH, you should now be able to run stubble.