novel-stats-fork/README.md

novel-stats produces word count statistics for novels written in Markdown
format, including total word count, word count by status, and optionally
per-chapter and per-act word counts. You might find this useful if you're
already using tools like Git and Markdown processing as part of your writing
workflow (or are looking to start) and want some basic statistics about your
novel as you're writing it.

novel-stats is fairly particular about the format of the novel and doesn't
currently include much in the way of error checking. Word counts may not be
exact.

Example output without any flags:

```bash
$ novel-stats example.md 
drafted: 237 words (~43%)
dev edited: 82 words (~15%)
total: 539 words
```

Example output with chapter data:

```bash
$ novel-stats example.md -c
chapter 1: 103 (drafted)
chapter 2: 83 (dev edited)
chapter 3: 115
chapter 4: 96
chapter 5: 136 (drafted)

drafted: 237 words (~43%)
dev edited: 82 words (~15%)
total: 539 words
```

Example with multi-file markdown:

```bash
$ novel-stats multi_file.mdpp -pp -c -a
chapter 1 Lorem:
         203 (drafted)
         303 (dev edited)
         506 words (total)
chapter 2 Ipsum: 84 (dev edited)
chapter 3 Dolor: 116
chapter 4 Sit: 97
chapter 5 Amet: 137 (drafted)

act 1: 591 words (~62%)
act 2: 214 words (~22%)
act 3: 138 words (~14%)

drafted: 336 words (~35%)
dev edited: 385 words (~40%)
total: 946 words
```

## Installation

Start by cloning the project with git. Then install it with Python's `pip`.
Example:

```bash
pip3 install /path/to/novel-stats
```

Or, if you'd like to install it "editable" (making development/updates
easier):

```bash
pip3 install --editable /path/to/novel-stats
```

## Usage

novel-stats takes a single argument: The path to your novel file in markdown
format. For instance:

```bash
novel-stats /path/to/your/novel.md[pp] [-c/--chapter] [-a/--act] [-pp]
```

### Optional flags

* `-c` or `--chapter` — output chapter-by-chapter breakdown of word counts,
including how many words in each chapter are tagged with which status
* `-a` or `--act` — output act-by-act breakdown of word counts (total only)
* `--pp` — run markdown pre-processor, this allows for a multi-file input
(e.g. each chapter in its own file), but requires the MarkdownPP python
library.

## Markdown format

You'll need to format your novel in the expected format for novel-stats to
work.

### Title and author

Use `#` for the title and `###` for author name. Example:

```yaml
# Title of the Novel 
### Author Name
```

These lines are generally ignored, although they do show up in the total word
count.

### Chapters

novel-stats expects chapters to start with `##` and to have a numeric title
(no "Chapter", etc.). Example:

```yaml
## 1

Once upon a time ...
```

### Chapter status

Chapter "status" is an optional feature that lets you indicate certain
chapters as "drafted", "dev edited", etc. and then get word count totals for
each status. This is useful for tracking the progress of your novel
chapter-by-chapter as you write or revise.

Example:

```yaml
## 3

[status]: # (drafted)
```

Other Markdown processing tools should ignore these "comments", so they
shouldn't show up in the processed contents of your novel. If you do use this
feature, you should set the status at the top of each chapter, before the
actual chapter contents.

There are no set values for the chapter status. Use the statuses that make
sense for your writing workflow.


### Acts

Acts are an optional feature that let you indicate certain chapters as part of
a particular act number and then get word count totals for each act. This is
useful for keeping an eye on how big your acts are in relation to one another.

Example:

```yaml
## 8

[act]: # (2)
```

You only need to set the act for the *first* chapter in the act. Subsequent
chapters are assumed to be in the same act unless otherwise indicated.

If you do use this feature, you should set the status at the top of each
chapter, before the actual chapter contents (and after any chapter status).


### Comments

Comments, such as outlining notes for yourself, can be added anywhere using:

```yaml
[//]: # This text is completely ignored.
```

These words will not count towards the word count


### Multi-file support

Splitting your novel into multiple files is supported using the `MarkdownPP`
python library. To include a secondary file inside the main one, simply use

```yaml
!INCLUDE "OtherFile.md"
```

and add the `-pp` flag to novel-stats.

### Example novel

novel-stats includes two examples:

1. Markdown file `example.md` that illustrates the expected Markdown format
for a single file. Try it out:

```bash
$ novel-stats example.md
```

2. A 6 file example in the `example` folder with the main file
`multi_file.mdpp`. You can try this one out with

```bash
$ cd example
$ novel-stats multi_file.mdpp -pp
```