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
Selector conditions such as code[:lang<python>] run in the CLI today. The
written rule for them is in the next revision of the specification.
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.
A clean result means the file passes the enabled rules. In strict mode, warnings make the command exit with code 1.
Where it lives
The command ships inside the podlite package, next to the parser, in
packages/core.