CLI quickstart

Install

cargo install --git https://github.com/zachhannum/fleuron fleuron-cli
fleuron fixtures/corpus/pride-and-prejudice.md -c fixtures/styled.css -o book.pdf

fleuron: fixtures/corpus/pride-and-prejudice.md → book.pdf: 445 pages

Manuscript

⚙

Manuscript, as markdown## Chapter 1 It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife. However little known the feelings or views of such a man may be on his first entering a neighbourhood, this truth is so well fixed in the minds of the surrounding families, that he is considered the rightful property of some one or other of their daughters. "My dear Mr. Bennet," said his lady to him one day, "have you heard that Netherfield Park is let at last?" Mr. Bennet replied that he had not. "But it is," returned she; "for Mrs. Long has just been here, and she told me all about it." Mr. Bennet made no answer. "Do you not want to know who has taken it?" cried his wife impatiently. "You want to tell me, and I have no objection to hearing it." This was invitation enough. "Why, my dear, you must know, Mrs. Long says that Netherfield is taken by a young man of large fortune from the north of England; that he came down on Monday in a chaise and four to see the place, and was so much delighted with it, that he agreed with Mr. Morris immediately; that he is to take possession before Michaelmas, and some of his servants are to be in the house by the end of next week." "What is his name?" "Bingley." "Is he married or single?" "Oh! Single, my dear, to be sure! A single man of large fortune; four or five thousand a year. What a fine thing for our girls!" "How so? How can it affect them?" "My dear Mr. Bennet," replied his wife, "how can you be so tiresome! You must know that I am thinking of his marrying one of them." "Is that his design in settling here?" "Design! Nonsense, how can you talk so! But it is very likely that he may fall in love with one of them, and therefore you must visit him as soon as he comes." "I see no occasion for that. You and the girls may go, or you may send them by themselves, which perhaps will be still better, for as you are as handsome as any of them, Mr. Bingley may like you the best of the party." "My dear, you flatter me. I certainly have had my share of beauty, but I do not pretend to be anything extraordinary now. When a woman has five grown-up daughters, she ought to give over thinking of her own beauty." "In such cases, a woman has not often much beauty to think of." "But, my dear, you must indeed go and see Mr. Bingley when he comes into the neighbourhood." "It is more than I engage for, I assure you." "But consider your daughters. Only think what an establishment it would be for one of them. Sir William and Lady Lucas are determined to go, merely on that account, for in general, you know, they visit no newcomers. Indeed you must go, for it will be impossible for us to visit him if you do not." "You are over-scrupulous, surely. I dare say Mr. Bingley will be very glad to see you; and I will send a few lines by you to assure him of my hearty consent to his marrying whichever he chooses of the girls; though I must throw in a good word for my little Lizzy." "I desire you will do no such thing. Lizzy is not a bit better than the others; and I am sure she is not half so handsome as Jane, nor half so good-humoured as Lydia. But you are always giving her the preference." "They have none of them much to recommend them," replied he; "they are all silly and ignorant like other girls; but Lizzy has something more of quickness than her sisters." "Mr. Bennet, how can you abuse your own children in such a way? You take delight in vexing me. You have no compassion for my poor nerves." "You mistake me, my dear. I have a high respect for your nerves. They are my old friends. I have heard you mention them with consideration these last twenty years at least." "Ah, you do not know what I suffer." "But I hope you will get over it, and live to see many young men of four thousand a year come into the neighbourhood." "It will be no use to us, if twenty such should come, since you will not visit them." "Depend upon it, my dear, that when there are twenty, I will visit them all." Mr. Bennet was so odd a mixture of quick parts, sarcastic humour, reserve, and caprice, that the experience of three-and-twenty years had been insufficient to make his wife understand his character. Her mind was less difficult to develop. She was a woman of mean understanding, little information, and uncertain temper. When she was discontented, she fancied herself nervous. The business of her life was to get her daughters married; its solace was visiting and news.

‹page 1›

Page 1 of book.pdf, from the manuscript and the stylesheet the command above read. Edit the manuscript here and it is set again.

Multi-file books

Multiple markdown files can be passed to the CLI. The engine combines all of the files into a single output.

fleuron front.md ch01.md ch02.md ch03.md -o book.pdf

The tree records each file’s name, so a diagnostic points at the file the trouble is in.

Book metadata

One markdown file is a whole book, so its frontmatter is the book’s. Several are chapters, and a chapter’s frontmatter describes the chapter: its title: names that section, and the book is left unnamed. That leaves the work’s own title and author to the command line:

fleuron ch01.md ch02.md ch03.md -o book.pdf \
  --title "The Levant Papers" --author "E. Marsh"

A flag outranks frontmatter where the two overlap, so you can retitle a single file without editing it.

Where sections begin

A section is what the fragmenter opens a page on, so where sections begin decides the page count before any styling does. --split names the rule:

fleuron manuscript.md -o book.pdf --split 2

A heading at level 2 or shallower opens a section, which suits a manuscript that sets parts with # and chapters with ##. The default is --split 1. --split none opens no section at a heading at all, so in a vault of one chapter per file the file is the section.

--dialect sets which markdown is being read: fleuron, commonmark, gfm or obsidian. fleuron is the default: CommonMark, a frontmatter block and attribute lines. Under commonmark a brace run is prose. See the markdown mapping for what each construct becomes and which of them warn.

Adding your own styling

Stylesheets cascade in the order the command line gives them, over the built-in sheet rather than instead of it:

fleuron manuscript.md -o book.pdf -c house.css -c series.css

So house.css sets the press’s defaults and series.css overrides the handful of things this series does differently. Author CSS outranks the built-in sheet whatever the specificity of the built-in rule, so you never have to out-specify a default you are replacing.

@page {
  size: 5.5in 8.5in;
  margin: 48pt 40pt 56pt 60pt;
  @bottom-center { content: counter(page); font-size: 8pt; }
}

book { font-size: 12pt; line-height: 1.5; }
h1, h2, h3 { font-size: 20pt; }

The CSS subset is everything the engine supports. Anything else becomes a warning on stderr naming the line and column, and the PDF is written regardless.

Fonts

@font-face urls are resolved as paths: first against the directory of the stylesheet that asked for them, then against the working directory.

@font-face {
  font-family: "House Serif";
  src: url("faces/house.ttf");
}

A face that resolves nowhere warns and the text falls back. See fonts.

Writing an EPUB

If the output path ends in .epub, the CLI writes a reflowable EPUB rather than a PDF. The following example writes the fixture book as an EPUB, with the fixture stylesheet:

fleuron fixtures/gulliver-excerpt.md -o book.epub -c fixtures/styled.css

fleuron: fixtures/gulliver-excerpt.md → book.epub: 1 document

The summary counts documents rather than pages. There is one document for each section. The reading system on the device makes the pages. The other flags work the same as for a PDF.

The stylesheet goes into the EPUB, less the CSS that describes pages. Fleuron leaves out that CSS with no warning, because the PDF uses it. CSS in an EPUB lists that CSS. EPUB covers what the EPUB holds.

Reading the tree back

To see what the frontend made of a manuscript, which heading opened a section, or where a construct degraded, dump the content tree instead of laying it out:

fleuron manuscript.md --dump-tree

It goes to stdout, and the same manuscript dumps the same bytes every time.

What it prints

The summary line goes to stderr, so fleuron manuscript.md -o /dev/stdout is still a PDF on stdout. Warnings follow it, one per line, and then a count. The reference has the exit codes.