pdfmd-cli 3.29.8__tar.gz → 3.29.24__tar.gz

{pdfmd_cli-3.29.8/pdfmd_cli.egg-info → pdfmd_cli-3.29.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfmd-cli
-Version: 3.29.8
+Version: 3.29.24
 Summary: One command from Markdown to a good-looking PDF: a Pandoc wrapper with smart defaults, project-file discovery and a multi-engine fallback chain
 Author: Ali Perdekhan
 License-Expression: MIT AND Apache-2.0
@@ -1359,6 +1359,12 @@ Water,18.015,1.20
   `---`, `:--`, `:-:`, `--:` as in a pipe table; `align=` wins. If such a row is really data, say `separator="none"`.
   `widths="5,1,1"` sets relative widths, and a second row with unequal dashes does too. Without either, pdfmd picks
   widths that suit the contents.
+- **A spreadsheet** (v3.29) works as the file: `::: {.csv file="results.xlsx" sheet="Run 2"}` (`.xlsx`, `.xlsm`, `.xls`, `.ods`;
+  `sheet=` is a name or a number counted from 1, the first sheet when it is left out). The sheet is read by `openpyxl` (xlsx and
+  xlsm: the values the file stores, so a cell shown as `1.50` is `1.5`, a date is `2026-01-02`), else by `pandas`, else by
+  LibreOffice (the sheet by number); none of them is a `WARN` that says what to install (`pip install openpyxl`). The converted
+  CSV is kept in pdfmd's cache by the file's content, the attached source carries the spreadsheet itself, and
+  `--expand-tables` reads it too.
 - The first row is the header unless you add `header="false"`.
 - Large files are capped at 10 rows × 7 columns, so a huge CSV can't
   silently fill 40 pages. A cut table keeps both ends: the first 7 rows, a row
@@ -1434,6 +1440,15 @@ article class, and never over a document that formats its headings itself: a `ti
 `\section` of its own, in the preamble, the `header-includes` or a metadata file, is named in a `CSS` note and nothing is added
 (and when `titlesec` is not installed, one LaTeX warning says so). A family needs XeLaTeX or LuaLaTeX.
 
+### A cover: `cover`
+
+`pdfmd-options: {cover: true}` puts the title block (title, subtitle, author, date) on a page of its own and starts the text
+on the next (v3.29): LaTeX's `titlepage` class option (for the article, report and book classes and KOMA's; another class is
+left alone), and a page break after the title block of an HTML-family PDF (WeasyPrint, a browser, Calibre) or an HTML page.
+`cover: picture.png` (relative to the document) puts that picture on the first page of such a PDF, before the title, and is the
+cover of an EPUB, so of the Kindle book Calibre makes from it (Pandoc's own `cover-image:` does the same for an EPUB). A
+Word, OpenDocument or Typst file says once that the key was not applied. Off by default: the title block stays on page 1.
+
 ### Code: wrapping and line numbers
 
 With a LaTeX engine a long line of code wraps at the margin instead of running off the page (a long path or option list
@@ -1574,6 +1589,79 @@ It is off unless asked (the document, a metadata file, or `pdfmd --setup` under
 [KIND ...]` and `--no-pagebreak` decide for one run. A spelling already in the output's own language stays as written,
 and slides leave a break out with a note. The built-in renderer (no Pandoc) reads the comment and TeX spellings anyway.
 
+**Callouts in every format** (v3.29, the first kind of *universal markup* after page breaks). GitHub's and Obsidian's
+`> [!NOTE]`, a fenced `::: note` and Quarto's `::: callout-tip` are a block quote or a div to Pandoc, and print as plain text.
+Ask for them and each becomes a box of the writer's own: LaTeX a `tcolorbox` (a plain indented quote when that package is not
+installed), Typst a tinted block, HTML, EPUB and the HTML engines' PDFs a `div.callout` with its style, every other writer
+(Word, OpenDocument, Markdown ...) a block quote with a bold title:
+
+```yaml
+pdfmd-options:
+  markup: callouts             # or: markup: true (every kind there is)
+```
+
+```markdown
+> [!warning] Mind the gap
+> The title is the rest of the first line, the body the lines after it.
+
+::: {.tip title="Another way"}
+A fenced div takes `note`, `tip`, `important`, `warning` or `caution` as its class, `title=` for the title.
+:::
+```
+
+The five kinds are GitHub's (`note`, `tip`, `important`, `warning`, `caution`); Obsidian's others map to them (`info`, `todo`,
+`example`, `abstract` to note; `success`, `check`, `hint` to tip; `question`, `help`, `faq` to important; `failure`, `danger`,
+`error`, `bug` to caution; `attention` to warning), and an unknown name is a note titled with it. A fold marker (`[!tip]-`) is
+dropped. Off unless asked (the document, a metadata file, or `pdfmd --setup` under *Universal markup*); `--markup [KIND ...]` and
+`--no-markup` decide for one run. The built-in renderer (no Pandoc) does not read it yet, and there is no Word shaded box yet.
+
+**A table of contents where you put it** (v3.29, `markup: toc`). `[TOC]`, `[[_TOC_]]` and `<!-- toc -->` alone in a paragraph, or
+a raw `\tableofcontents` for a writer that is not LaTeX, become the contents at that place: LaTeX's `\tableofcontents` (filled in
+one build, with the page numbers), Typst's `#outline()`, a Word TOC field (Word offers to update it when the file is opened) and,
+for every other writer (HTML, EPUB, Markdown, OpenDocument ...), a nested list of links to the headings down to level 3, with a
+bold "Contents" above it. `markup: [callouts, toc]` or `markup: true` for both; `--markup toc` for one run. A marker inside a
+sentence is text.
+
+**Centred text** (v3.29, `markup: center`). `<center>` ... `</center>` around blocks (the closing tag in its own paragraph),
+`<div align="center">`, `<div style="text-align: center">`, a fenced `::: center` and, for writers that are not LaTeX, a raw
+`\begin{center}` ... `\end{center}` all centre what they hold: LaTeX's `center` environment, Typst's `#align(center)[...]`, a
+`text-align` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text as it is and say so once (no
+centring for a block there yet). `markup: [callouts, toc, center]` or `true` for all; `--markup center` for one run.
+
+**Highlighted text** (v3.29, `markup: highlight`). `==marked text==` (across several words, with emphasis inside, over a line
+break) is highlighted: LaTeX with `soul`'s `\hl` in a pale yellow (plain text when `soul` is not installed), Typst with
+`#highlight[...]`, HTML, EPUB and `--to gfm` with `<mark>`; Pandoc's own Markdown output keeps `==...==`, and Word and OpenDocument
+keep the text and say once that it is not highlighted. A lone `==` or one inside code stays as written; a closing `==` followed by
+punctuation (`==end==.`) works. `markup: [callouts, toc, center, highlight]` or `true` for all; `--markup highlight` for one run.
+
+**Blocks kept on one page** (v3.29, `markup: keep`). A fenced `::: keep` (also `nobreak`, `keep-together`), a div with
+`style="break-inside: avoid"` and, for writers that are not LaTeX, a raw `\begin{samepage}` ... `\end{samepage}` hold what they
+contain on one page where it fits: LaTeX's `samepage` environment, Typst's `#block(breakable: false)[...]`, a `break-inside:
+avoid` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text and say once that it is not held.
+`--markup keep` for one run.
+
+**Landscape pages** (v3.29, `markup: landscape`). A fenced `::: landscape`, a div with `style="page: landscape"` and, for writers
+that are not LaTeX, a raw `\begin{landscape}` ... `\end{landscape}` put what they hold on pages turned sideways, the document
+going back to portrait after it: LaTeX with `pdflscape` (the page is rotated in the PDF; `lscape`, or no turning, when it is not
+installed), Typst with `#page(flipped: true)[...]`, WeasyPrint and the browsers with a named page (`@page landscape`: the browsers
+get the document's paper turned; WeasyPrint's is its own A4 unless your own `@page landscape` says otherwise). Calibre's PDF cannot
+name page types, and Word and OpenDocument have no sections made from here: they keep the text and say once that no landscape page
+was made. `--markup landscape` for one run.
+
+**Where the appendix starts** (v3.29, `markup: appendix`). A raw `\appendix`, `<!-- appendix -->` or a heading with the class
+`{.appendix}` marks the start: the sections after it are lettered (A, B, A.1) in LaTeX (`\appendix`) and Typst (a heading
+numbering of letters and a counter reset). It matters for a document that numbers its sections (`--number-sections`); without
+numbers Typst gets nothing and LaTeX's `\appendix` changes nothing visible. Other writers keep their own numbering and say once
+that the lettering is not made.
+
+**Showing the comments of the text** (v3.29, `show-comments`). An `<!-- HTML comment -->` is invisible in every output. With
+`pdfmd-options: {show-comments: true}` (or `--show-comments` for one run, `--no-show-comments` to switch it off; also a row in
+`pdfmd --setup`) each one is shown: a box labelled *Comment* in LaTeX, Typst, HTML, EPUB and the HTML engines' PDFs, a real Word
+comment in a `.docx` (anchored on the paragraph after it, so Word's review pane lists them), `[comment: ...]` in italics for one
+inside a paragraph. The Markdown family (`--to gfm`, `markdown`) keeps the comment as it is; OpenDocument and PowerPoint drop
+it, with a note once. pdfmd's own markers stay invisible (`<!-- pdfmd: ... -->`, `<!-- pagebreak -->`, `<!-- toc -->`,
+`<!-- appendix -->`), and so does an empty comment. It is off unless asked and is not one of the kinds `markup: true` turns on.
+
 **PDF images in HTML.** A browser does not show a PDF in `<img>`, an SVG it does. For an HTML build (a web page, an
 EPUB, a PDF through WeasyPrint) every image that is a PDF, `![fig](plot.pdf)` or `<img src="plot.pdf">`, is converted to
 an SVG with poppler's `pdftocairo` (or `mutool`, `pdf2svg`, `inkscape`) and stays vector; the first page is used and the
@@ -1831,6 +1919,17 @@ document or its metadata files say (the command line beats all of them);
 `translit:` is the romanization packs of the name lookup. `PDFMD_CONFIG=other.yaml`
 uses another file, `PDFMD_CONFIG=` (empty) none.
 
+**Settings for a folder** (v3.29): a `.pdfmd/config.yaml` in a document's folder, or in any folder above it, has the same
+`options:` for everything under it. The order, strongest first: the command line, the document's `pdfmd-options`, its metadata
+files, the folder settings (the nearest folder first, then the ones above it), your global `config.yaml`, pdfmd's own defaults.
+`inherit: false` in a folder's file stops the walk upward there. A folder cannot set what belongs to this computer (`translit`,
+`setup-ui`, `disabled`): they are ignored with a `WARN`. A mapping such as `stamp:` or `backup:` in a folder's file stays off
+until it says `enabled: true`, as in the global file. A build lists the folder files it used on its `FOUND` line
+(`--verbose`: `AUTO SETTINGS`). A folder's options cannot name code (a Lua filter or a preamble is read from the document's own
+front matter only), a `.pdfmd/config.yaml` owned by another user (a shared `/tmp`) is not read, and a path in it (`css: house.css`)
+is relative to the document, as everywhere, not to the folder file. Writing the file from `pdfmd --setup DIR`, and carrying it in
+an attached source, are not done yet.
+
 ```yaml
 translit: [greek, hangul]
 options:

{pdfmd_cli-3.29.8 → pdfmd_cli-3.29.24}/README.md

@@ -1324,6 +1324,12 @@ Water,18.015,1.20
   `---`, `:--`, `:-:`, `--:` as in a pipe table; `align=` wins. If such a row is really data, say `separator="none"`.
   `widths="5,1,1"` sets relative widths, and a second row with unequal dashes does too. Without either, pdfmd picks
   widths that suit the contents.
+- **A spreadsheet** (v3.29) works as the file: `::: {.csv file="results.xlsx" sheet="Run 2"}` (`.xlsx`, `.xlsm`, `.xls`, `.ods`;
+  `sheet=` is a name or a number counted from 1, the first sheet when it is left out). The sheet is read by `openpyxl` (xlsx and
+  xlsm: the values the file stores, so a cell shown as `1.50` is `1.5`, a date is `2026-01-02`), else by `pandas`, else by
+  LibreOffice (the sheet by number); none of them is a `WARN` that says what to install (`pip install openpyxl`). The converted
+  CSV is kept in pdfmd's cache by the file's content, the attached source carries the spreadsheet itself, and
+  `--expand-tables` reads it too.
 - The first row is the header unless you add `header="false"`.
 - Large files are capped at 10 rows × 7 columns, so a huge CSV can't
   silently fill 40 pages. A cut table keeps both ends: the first 7 rows, a row
@@ -1399,6 +1405,15 @@ article class, and never over a document that formats its headings itself: a `ti
 `\section` of its own, in the preamble, the `header-includes` or a metadata file, is named in a `CSS` note and nothing is added
 (and when `titlesec` is not installed, one LaTeX warning says so). A family needs XeLaTeX or LuaLaTeX.
 
+### A cover: `cover`
+
+`pdfmd-options: {cover: true}` puts the title block (title, subtitle, author, date) on a page of its own and starts the text
+on the next (v3.29): LaTeX's `titlepage` class option (for the article, report and book classes and KOMA's; another class is
+left alone), and a page break after the title block of an HTML-family PDF (WeasyPrint, a browser, Calibre) or an HTML page.
+`cover: picture.png` (relative to the document) puts that picture on the first page of such a PDF, before the title, and is the
+cover of an EPUB, so of the Kindle book Calibre makes from it (Pandoc's own `cover-image:` does the same for an EPUB). A
+Word, OpenDocument or Typst file says once that the key was not applied. Off by default: the title block stays on page 1.
+
 ### Code: wrapping and line numbers
 
 With a LaTeX engine a long line of code wraps at the margin instead of running off the page (a long path or option list
@@ -1539,6 +1554,79 @@ It is off unless asked (the document, a metadata file, or `pdfmd --setup` under
 [KIND ...]` and `--no-pagebreak` decide for one run. A spelling already in the output's own language stays as written,
 and slides leave a break out with a note. The built-in renderer (no Pandoc) reads the comment and TeX spellings anyway.
 
+**Callouts in every format** (v3.29, the first kind of *universal markup* after page breaks). GitHub's and Obsidian's
+`> [!NOTE]`, a fenced `::: note` and Quarto's `::: callout-tip` are a block quote or a div to Pandoc, and print as plain text.
+Ask for them and each becomes a box of the writer's own: LaTeX a `tcolorbox` (a plain indented quote when that package is not
+installed), Typst a tinted block, HTML, EPUB and the HTML engines' PDFs a `div.callout` with its style, every other writer
+(Word, OpenDocument, Markdown ...) a block quote with a bold title:
+
+```yaml
+pdfmd-options:
+  markup: callouts             # or: markup: true (every kind there is)
+```
+
+```markdown
+> [!warning] Mind the gap
+> The title is the rest of the first line, the body the lines after it.
+
+::: {.tip title="Another way"}
+A fenced div takes `note`, `tip`, `important`, `warning` or `caution` as its class, `title=` for the title.
+:::
+```
+
+The five kinds are GitHub's (`note`, `tip`, `important`, `warning`, `caution`); Obsidian's others map to them (`info`, `todo`,
+`example`, `abstract` to note; `success`, `check`, `hint` to tip; `question`, `help`, `faq` to important; `failure`, `danger`,
+`error`, `bug` to caution; `attention` to warning), and an unknown name is a note titled with it. A fold marker (`[!tip]-`) is
+dropped. Off unless asked (the document, a metadata file, or `pdfmd --setup` under *Universal markup*); `--markup [KIND ...]` and
+`--no-markup` decide for one run. The built-in renderer (no Pandoc) does not read it yet, and there is no Word shaded box yet.
+
+**A table of contents where you put it** (v3.29, `markup: toc`). `[TOC]`, `[[_TOC_]]` and `<!-- toc -->` alone in a paragraph, or
+a raw `\tableofcontents` for a writer that is not LaTeX, become the contents at that place: LaTeX's `\tableofcontents` (filled in
+one build, with the page numbers), Typst's `#outline()`, a Word TOC field (Word offers to update it when the file is opened) and,
+for every other writer (HTML, EPUB, Markdown, OpenDocument ...), a nested list of links to the headings down to level 3, with a
+bold "Contents" above it. `markup: [callouts, toc]` or `markup: true` for both; `--markup toc` for one run. A marker inside a
+sentence is text.
+
+**Centred text** (v3.29, `markup: center`). `<center>` ... `</center>` around blocks (the closing tag in its own paragraph),
+`<div align="center">`, `<div style="text-align: center">`, a fenced `::: center` and, for writers that are not LaTeX, a raw
+`\begin{center}` ... `\end{center}` all centre what they hold: LaTeX's `center` environment, Typst's `#align(center)[...]`, a
+`text-align` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text as it is and say so once (no
+centring for a block there yet). `markup: [callouts, toc, center]` or `true` for all; `--markup center` for one run.
+
+**Highlighted text** (v3.29, `markup: highlight`). `==marked text==` (across several words, with emphasis inside, over a line
+break) is highlighted: LaTeX with `soul`'s `\hl` in a pale yellow (plain text when `soul` is not installed), Typst with
+`#highlight[...]`, HTML, EPUB and `--to gfm` with `<mark>`; Pandoc's own Markdown output keeps `==...==`, and Word and OpenDocument
+keep the text and say once that it is not highlighted. A lone `==` or one inside code stays as written; a closing `==` followed by
+punctuation (`==end==.`) works. `markup: [callouts, toc, center, highlight]` or `true` for all; `--markup highlight` for one run.
+
+**Blocks kept on one page** (v3.29, `markup: keep`). A fenced `::: keep` (also `nobreak`, `keep-together`), a div with
+`style="break-inside: avoid"` and, for writers that are not LaTeX, a raw `\begin{samepage}` ... `\end{samepage}` hold what they
+contain on one page where it fits: LaTeX's `samepage` environment, Typst's `#block(breakable: false)[...]`, a `break-inside:
+avoid` div in HTML, EPUB and the HTML engines' PDFs. Word and OpenDocument keep the text and say once that it is not held.
+`--markup keep` for one run.
+
+**Landscape pages** (v3.29, `markup: landscape`). A fenced `::: landscape`, a div with `style="page: landscape"` and, for writers
+that are not LaTeX, a raw `\begin{landscape}` ... `\end{landscape}` put what they hold on pages turned sideways, the document
+going back to portrait after it: LaTeX with `pdflscape` (the page is rotated in the PDF; `lscape`, or no turning, when it is not
+installed), Typst with `#page(flipped: true)[...]`, WeasyPrint and the browsers with a named page (`@page landscape`: the browsers
+get the document's paper turned; WeasyPrint's is its own A4 unless your own `@page landscape` says otherwise). Calibre's PDF cannot
+name page types, and Word and OpenDocument have no sections made from here: they keep the text and say once that no landscape page
+was made. `--markup landscape` for one run.
+
+**Where the appendix starts** (v3.29, `markup: appendix`). A raw `\appendix`, `<!-- appendix -->` or a heading with the class
+`{.appendix}` marks the start: the sections after it are lettered (A, B, A.1) in LaTeX (`\appendix`) and Typst (a heading
+numbering of letters and a counter reset). It matters for a document that numbers its sections (`--number-sections`); without
+numbers Typst gets nothing and LaTeX's `\appendix` changes nothing visible. Other writers keep their own numbering and say once
+that the lettering is not made.
+
+**Showing the comments of the text** (v3.29, `show-comments`). An `<!-- HTML comment -->` is invisible in every output. With
+`pdfmd-options: {show-comments: true}` (or `--show-comments` for one run, `--no-show-comments` to switch it off; also a row in
+`pdfmd --setup`) each one is shown: a box labelled *Comment* in LaTeX, Typst, HTML, EPUB and the HTML engines' PDFs, a real Word
+comment in a `.docx` (anchored on the paragraph after it, so Word's review pane lists them), `[comment: ...]` in italics for one
+inside a paragraph. The Markdown family (`--to gfm`, `markdown`) keeps the comment as it is; OpenDocument and PowerPoint drop
+it, with a note once. pdfmd's own markers stay invisible (`<!-- pdfmd: ... -->`, `<!-- pagebreak -->`, `<!-- toc -->`,
+`<!-- appendix -->`), and so does an empty comment. It is off unless asked and is not one of the kinds `markup: true` turns on.
+
 **PDF images in HTML.** A browser does not show a PDF in `<img>`, an SVG it does. For an HTML build (a web page, an
 EPUB, a PDF through WeasyPrint) every image that is a PDF, `![fig](plot.pdf)` or `<img src="plot.pdf">`, is converted to
 an SVG with poppler's `pdftocairo` (or `mutool`, `pdf2svg`, `inkscape`) and stays vector; the first page is used and the
@@ -1796,6 +1884,17 @@ document or its metadata files say (the command line beats all of them);
 `translit:` is the romanization packs of the name lookup. `PDFMD_CONFIG=other.yaml`
 uses another file, `PDFMD_CONFIG=` (empty) none.
 
+**Settings for a folder** (v3.29): a `.pdfmd/config.yaml` in a document's folder, or in any folder above it, has the same
+`options:` for everything under it. The order, strongest first: the command line, the document's `pdfmd-options`, its metadata
+files, the folder settings (the nearest folder first, then the ones above it), your global `config.yaml`, pdfmd's own defaults.
+`inherit: false` in a folder's file stops the walk upward there. A folder cannot set what belongs to this computer (`translit`,
+`setup-ui`, `disabled`): they are ignored with a `WARN`. A mapping such as `stamp:` or `backup:` in a folder's file stays off
+until it says `enabled: true`, as in the global file. A build lists the folder files it used on its `FOUND` line
+(`--verbose`: `AUTO SETTINGS`). A folder's options cannot name code (a Lua filter or a preamble is read from the document's own
+front matter only), a `.pdfmd/config.yaml` owned by another user (a shared `/tmp`) is not read, and a path in it (`css: house.css`)
+is relative to the document, as everywhere, not to the folder file. Writing the file from `pdfmd --setup DIR`, and carrying it in
+an attached source, are not done yet.
+
 ```yaml
 translit: [greek, hangul]
 options: