Podlite CLI

ask a document questions, from the terminal

Convert, render and query Podlite files. Ships inside the podlite package, so npx runs it without installing anything.

Grep does not know what a heading is

Open a folder of documentation and try to answer a plain question: which code samples are Python? Grep will find the word, and it will also find it in prose, in a comment, in a filename. It matches characters, because characters are all a plain-text file gives it.

A Podlite file gives more. Every block knows what it is and carries its own attributes, and the same query that would be a fragile regular expression becomes an exact question:

npx podlite query 'code[:lang<python>]' tutorials/*.podlite --to json

That is the command this page is really about. The other two are useful; this one has no counterpart in a Markdown toolchain.

Query

A selector picks blocks out of a document, and the matches come back in whatever format you ask for:

npx podlite query 'head1' docs/api.podlite
npx podlite query 'head1, head2' manual.podlite --to md

Selectors read attributes, so documents can be searched the way a database is queried rather than the way text is scanned:

npx podlite query '*[:applies-nfr~<N004>]' rules/*.podlite --fail-on-empty

--fail-on-empty turns an empty result into a non-zero exit. That is the step that turns a question into a check a build can run: if the rule stops being covered, the build says so.

Convert

npx podlite convert doc.podlite --to md
npx podlite convert *.podlite --to md -o output/

Markdown and HTML are the output formats. Without -o the result lands beside the source with a new extension. Relative file: image paths can be re-rooted with --base or the PODLITE_BASE environment variable, which is what makes a converted file usable outside the folder it came from.

Lint

npx podlite lint README.podlite
npx podlite lint docs/*.podlite --strict --format json

--strict promotes warnings to errors, --format json gives machine-readable output, and --config points at a .podlitelintrc file.

The tool calls this command a work in progress in its own help, and that is the honest reading: the rule set is still growing, so a clean result means the file passes the rules that exist today, not that it has been checked completely.

Where it lives

The command ships inside the podlite package, next to the parser, in packages/core.