19 releases (8 stable)
3.0.0 | Nov 14, 2023 |
---|---|
2.2.1 | Jun 25, 2022 |
2.1.2 | Apr 2, 2021 |
2.1.1 | Dec 5, 2020 |
0.2.0 | Jun 12, 2019 |
#1409 in Command line utilities
190KB
1.5K
SLoC
Paper terminal
See paper.png to see what this looks like!
Writes a file to a paper in your terminal. Especially if that file is Markdown! Features supported include:
-
The usual text, and paragraphs with automatic line-wrapping. You can manually wrap with
hard breaks as expected.Otherwise, paragraphs will be nicely spaced.
-
Headings
-
Bold / Italic / Bold and Italic /
Strikethrough -
Lists
- Ordered
- Unordered
- Nested
-
Rules
-
Inline code
-
Code blocks, with syncat integration for syntax highlighting. Note that you must install syncat and make the syncat executable available on your path for this to work.
fn main() { println!("Hello world"); }
-
Blockquotes
Blockquotes
And even nested block quotes
-
And even images! Here's a photo of my cat
-
Task lists:
- Easy
- Hard
-
Footnotes[^ft]
[^ft]: This is the footnote!
-
Tables
Comparison with other command line Markdown renderers
Not a very good comparison... this is more of an example of a table!
Tool | CommonMark | Paper | Paging | Wrapping | Syntax | Images | Tables | Looks good* |
---|---|---|---|---|---|---|---|---|
foxfriends/paper-terminal | Yes | Yes | No | Yes | syncat | Pixelated | Yes | Yes |
ttscoff/mdless | Yes | No | Yes | No | pygmentize | Sometimes | Yes | No |
lunaryorn/mdcat | Yes | No | No | No | syntect | Sometimes | No | No |
* subjective
Styling
Paper uses syncat stylesheets to allow full customization of styling. See the default stylesheet (src/default.syncat
)
as an example of how this works. To override the default styles, create paper.syncat
in your active syncat theme.
-
Different scopes are represented as nodes, inspired by the corresponding HTML tag names.
h1
throughh6
strong
emphasis
strikethrough
code
blockquote
ul
,ol
,li
footnote-ref
,footnote-def
,footnote
table
caption
link
-
The paper and shadow can be matched with
paper
andshadow
. Styles applied topaper
are applied to everything. -
The
"prefix"
and"suffix"
tokens can be used to match the decorations- List item bullets
- Blockquote markers
- Code block margins
-
The
"lang-tag"
token matches the language name written in the bottom corner of the code block -
You can apply styles to code blocks with a specific language by using the language name as the token
For now, the prefix/suffix contents are not customizable, but this may be added in future if it is desired.
Installation
Paper can be installed from crates.io using Cargo:
cargo install paper-terminal
Usage
# Print the help
paper --help
# Render README.md
paper README.md
# Render README.md, with syntax highlighting
paper README.md -s
paper 0.1.0
Cameron Eldridge <cameldridge+git@gmail.com>
Prints papers in your terminal
USAGE:
paper [FLAGS] [OPTIONS] [file]...
FLAGS:
--dev Print in debug mode
--help Prints help information
-u, --hide-urls Hide link URLs
-i, --no-images Disable drawing images
-p, --plain Don't parse as Markdown, just render the plain text on a paper
-s, --syncat Use syncat to highlight code blocks. Requires you have syncat installed.
-V, --version Prints version information
OPTIONS:
-h, --h-margin <h-margin> Horizontal margin (overrides --margin)
-m, --margin <margin> Margin (shortcut for horizontal and vertical margin set to the same value) [default:
6]
-v, --v-margin <v-margin> Vertical margin (overrides --margin)
-w, --width <width> The width of the paper (including the space used for the margin) [default: 92]
ARGS:
<file>... Files to print
Dependencies
~12–21MB
~264K SLoC