# Stubble

## Your Boilerplate Document Assistant

![Rust 1.73+](https://img.shields.io/badge/Rust-1.73+-orange) ![Eleventy](https://img.shields.io/badge/11ty-2.0+-005470) ![Markdown](https://img.shields.io/badge/Markdown-4a525a)

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](https://11ty.dev), but future versions could theoretically provide templates for a number of popular SSGs and/or user-defined templates.

Stubble is written in [Rust](https://www.rust-lang.org/).

## Usage

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

```shell
stubble "Hello, World!"
```

Stubble should output a message like this:

```shell

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:

```shell
stubble -
```

Which should output a message like this:

```shell
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:

```markdown
---
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:

```markdown
stubble "Hello Again, World!" /tmp
```

...and you should see:

```shell
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.

```shell
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.

```shell
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`.

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

...and you should see:

```shell
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`.

```shell
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`.

```shell
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`.

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

...and you should see:

```shell
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.

```shell
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](https://www.rust-lang.org/tools/install) on your computer, version 1.73 or later.

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

```shell
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.