Package: showman
ShowmanAutomagic tools to smooth the package documentation & development
process.Package your files for local typst installation or PR submission in
one commandProvide your readme in typst format with code block examples, and letshowmando the rest! In one command, it will the readme to markdown
and render code block outputs as included images.Bonus points – letshowmanknow your repository path and it will
ensure images will properly appear in your readme even after your
package has been distributed through typst’s registry.Execute non-typst code blocks and render their outputsInstallationPrerequisites: Make sure you havetypstandpandocavailable
from the command line. Then, in a python virtual environment, run:pipinstallshowmanConverting your readme to markdownCreate a typst file with```examplecode blocks that show the
output you want to include in your readme. For instance:#import "@preview/cetz:0.1.2"
// Just to avoid showing this heading in the readme itself
#set heading(outlined: false)

= Hello, world!
Let's do something complicated:

#cetz.canvas({
  import cetz.plot
  import cetz.palette
  cetz.draw.set-style(axes: (tick: (length: -.05)))
  // Plot something
  plot.plot(size: (3,3), x-tick-step: 1, axis-style: "left", {
      for i in range(0, 3) {
      plot.add(domain: (-4, 2),
      x => calc.exp(-(calc.pow(x + i, 2))),
      fill: true, style: palette.tango)
    }
  })
})Then, run the following command:showmanmd<path-to-typst-file>Congrats, you now have a readme with inline images 🎉You can optionally specify your workspace root, output file name, image
folder, etc. These options are visible undershowman md --help.Note: You can customize the appearance of these images by providingshowmanthe template to use when creating them. In your file to be
rendered, create a variable calledshowman-configat the outermost
scope:// Render images with a black background and red text
#let showman-config = (
  template: it => {
    set text(fill: red)
    rect(fill: black, it)
  }
)Behind the scenes, showman imports your file as a module and looks for
this variable. If it is found, your template and a few other options are
injected into the example rendering process.Note: If every example has the same setup (package imports, etc.),
and you don’t want the text to be included in your examples, you can
passeval-kwargsin this config as well to specify a string that gets
prefixed to every example. Alternatively, pass variables in a scope
directly:// Setup either through providing scope or import prefixes
#let my-variable = 5
#let showman-config = (
  eval-kwargs: (
    prefix: "#import \"@preview/cetz:0.1.2\"
  ),
  // Now you can use `my-var` in your examples
  scope: (my-var: my-variable)
)Caveatsshowmanuses the beautifulpandocto do most of the markdown
conversion heavy lifting. So, if your document can’t be processed by
pandoc, you may need to adjust your syntax until pandoc is happy
making a markdown document.Typst doesn’t allow page styling inside containers. Sinceshowmanmust use containers to extract each rendered example, you can’t use#set page(...)or#pagebreak()inside your examples.Rendering examples in typstIf you don’t care about converting your readme to markdown, it’s even
easier to have example rendered alongside their code. Simply add the
following preamble to your file:#import "@preview/showman:0.1.0"
#show: showman.formatter.template

The code below will be rendered side by side with its output:

``` typst
= Hello world!
```
![Example 2](https://www.github.com/ntjess/showman/raw/v0.1.0/assets/example-2.png)

Several keywords can be privded to customize appearance and more. See `showman.formatter.template` for more details.Publishing your packageYou’ve done the hard work of creating a beautiful, well-documented
manual. Now it’s time to share it with the world.showmancan help you
package your files for distribution in one command, after some minimal
setup.Make sure you have atypst.tomlfile that follows typstpackaging
guidelinesAdd a new block to your toml file as follows:[tool.packager]paths=[...]Wherepathsis a list of files and directories you want to include in
your package.Run the following command from the root of your repository:showmanpackage<path-to-toml-file>Without any other arguments, you’ve just installed your package in
your system’s local typst packages folder. Now you can import it
withtypst #import "@local/mypackage:<version>".You can alternatively specify the path to your fork oftypst/packagesto prep your files for a PR, or specify a--namespaceother thanlocal.Note: You can see the full list of command options withshowman package --help.Executing codeThis package also executes non-typst code (currently bash on
non-windows, python, and c++). You can useshowman execute ./path/to/file.typto execute code blocks in these
languages, and the output will be captured in a.coderunner.jsonfile
in the root directory you specified. To enable this feature, you need to
add the following preamble to your file:#import "@preview/showman:0.1.0": runner

#let cache = json("/.coderunner.json").at("path/to/file.typ", default: (:))
#let show-rule = runner.external-code.with(result-cache: cache)

// Now, apply the show rule
#show: show-ruleYou can optionally style<example-input>and<example-output>labels
to customize how input and output blocks appear.