Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[add] show rule on raw for examples #35

Merged
merged 9 commits into from
Nov 21, 2024
Merged

[add] show rule on raw for examples #35

merged 9 commits into from
Nov 21, 2024

Conversation

Mc-Zen
Copy link
Owner

@Mc-Zen Mc-Zen commented Nov 21, 2024

This adds a show rule for raw elements with the languages

  • example (for Typst markup)
  • examplec (for Typst code mode)
    that will transform them into the code displayed side-by-side with the rendered output.

This addresses the third point in #32 .

Usage in documentation

In doc-comments, these languages are by default available. Note that the preamble is only applied to the markup version example and not the code version examplec since there is no good way to automatically convert the preamble between the two.

Hidden code

It is possible to add hidden code that will be executed but not shown on lines starting with >>>. This is useful for import statements, wrapping everything inside a container of a fixed size and other things.

>>> #let read(filename) = "Content of a file we cannot access. " // This line is executed but not shown 
#read("my-file.txt")

This is inspired by the Typst documentation.

Standalone usage

This show rule can be used standalone via the function render-examples().

#import "@preview/tidy:0.4.0": render-examples
#show: render-examples

```example
#rect()
```

```examplec
rect()
```

Scope

It also features a scope argument, that can be pre-set

#show: render-examples.with(scope: (answer: 42))

```example
#answer
```

Customization

The output format of the example can be customized through the parameter layout of render-examples. This parameter takes a function with two positional arguments: the raw element and the preview.

#show: render-examples.with(layout: (code, preview) => grid(code, preview))

Breaking change

In #15, this standalone example rendering was suggested. Before this PR, it was possible to write

#show raw: show-example.show-example

```typ
Hello world
```

This now breaks and should be replaced with the versions above.

@Mc-Zen Mc-Zen mentioned this pull request Nov 21, 2024
3 tasks
@Mc-Zen Mc-Zen merged commit 4f411ec into main Nov 21, 2024
@Mc-Zen Mc-Zen deleted the example-raws branch November 21, 2024 15:30
Mc-Zen added a commit that referenced this pull request Nov 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant