Produce word count statistics for novels written in Markdown format.
Go to file
Dan Helfman bd875013b2
continuous-integration/drone/push Build is passing Details
Fix formatting.
2022-01-10 11:49:05 -08:00
example Changed multi-file example name 2021-10-22 19:22:29 +02:00
novel_stats Fix formatting. 2022-01-10 11:49:05 -08:00
tests Add continuous integration + license. 2021-10-22 13:59:21 -07:00
.drone.yml Drop support for Python 3.6 (end-of-lifed). Add support for Python 3.10. 2022-01-09 21:56:13 -08:00
.gitignore .gitignore. 2021-09-11 15:40:39 -07:00
LICENSE Add continuous integration + license. 2021-10-22 13:59:21 -07:00
README.md Readme cleanup order of arguments 2021-10-23 14:22:21 +02:00
example.md Add example file. 2021-09-11 17:13:16 -07:00
pyproject.toml Tests! And code formatting. 2021-10-22 13:44:56 -07:00
setup.cfg Tests! And code formatting. 2021-10-22 13:44:56 -07:00
setup.py Drop support for Python 3.6 (end-of-lifed). Add support for Python 3.10. 2022-01-09 21:56:13 -08:00
test_requirements.txt Drop support for Python 3.6 (end-of-lifed). Add support for Python 3.10. 2022-01-09 21:56:13 -08:00
tox.ini Drop support for Python 3.6 (end-of-lifed). Add support for Python 3.10. 2022-01-09 21:56:13 -08:00

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:

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

Example output with chapter data:

$ novel-stats -c example.md
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:

$ novel-stats -pp -c -a multi_file.mdpp
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:

pip3 install /path/to/novel-stats

Usage

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

novel-stats [-c/--chapter] [-a/--act] [-pp] /path/to/your/novel.md[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:

# 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:

## 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:

## 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:

## 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:

[//]: # 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

!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:
$ novel-stats example.md
  1. A 6 file example in the example folder with the main file multi_file.mdpp. You can try this one out with
$ cd example
$ novel-stats multi_file.mdpp -pp

Contributing

novel-stats is licensed under the GNU General Public License version 3 or any later version.

If you'd like to contribute to development, please feel free to submit a Pull Request or open an issue first to discuss your idea.

Source code

To get set up to hack on novel-stats, first clone master via HTTPS or SSH:

git clone https://projects.torsion.org/witten/novel-stats.git

Or:

git clone ssh://git@projects.torsion.org:3022/witten/novel-stats.git

Then, install novel-stats "editable" so that you can run novel-stats commands while you're hacking on them to make sure your changes work.

cd novel-stats/
pip3 install --editable --user .

Note that this will typically install the novel-stats commands into ~/.local/bin, which may or may not be on your PATH. There are other ways to install novel-stats editable as well, for instance into the system Python install (so without --user, as root), or even into a virtualenv. How or where you install novel-stats is up to you, but generally an editable install makes development and testing easier.

Automated tests

Assuming you've cloned the novel-stats source code as described above, and you're in the novel-stats/ working copy, install tox, which is used for setting up testing environments:

pip3 install --user tox

Finally, to actually run tests, run:

cd novel-stats
tox

Code formatting

novel-stats code uses the Black code formatter, the Flake8 code checker, and the isort import orderer, so certain code style requirements will be enforced when running automated tests. See the Black, Flake8, and isort documentation for more information.

If when running tests, you get an error from the Black code formatter about files that would be reformatted, you can ask Black to format them for you via the following:

tox -e black

And if you get a complaint from the isort Python import orderer, you can ask isort to order your imports for you:

tox -e isort

Continuous integration

Each pull request triggers a continuous integration build which runs the test suite. You can view these builds on build.torsion.org, and they're also linked from the commits list on each pull request.

Build Status