https://github.com/quadnucyard/typst-hypraw
A lightweight package for creating headless code blocks for html export
https://github.com/quadnucyard/typst-hypraw
code-highlight html typst
Last synced: 10 days ago
JSON representation
A lightweight package for creating headless code blocks for html export
- Host: GitHub
- URL: https://github.com/quadnucyard/typst-hypraw
- Owner: QuadnucYard
- License: mit
- Created: 2025-06-13T14:04:13.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-12-07T14:24:38.000Z (3 months ago)
- Last Synced: 2025-12-09T23:39:46.681Z (3 months ago)
- Topics: code-highlight, html, typst
- Language: Typst
- Homepage:
- Size: 62.5 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Hypraw
A lightweight package for creating headless code blocks optimized for HTML export. Inspired by [zebraw](https://github.com/hongjr03/typst-zebraw).
**Important**: This package does NOT and will NOT support non-HTML targets. In this case, it just takes no effect.
## Features
- Generates clean, semantic HTML structure
- CSS class deduplication for smaller output
- **Line numbers** — expressive-code styled gutter with proper accessibility
- **Line highlight** — expressive-code styled line highlight, customized with your CSS
- **Copy button support** — headless, accessible, and customizable
## Installation
- From [Typst Universe](https://typst.app/universe/package/hypraw)
- [typship](https://github.com/sjfhsjfh/typship) package manager
- Manual installation to local packages directory
- Git submodule in your project
## Usage
Import from `@preview/hypraw` and enable it with `#show: hypraw`.
```typst
#import "@preview/hypraw:0.1.0": *
#show: hypraw
```
Then write your code blocks as usual, and insert additional CSS styles if needed.
````typ
Here's inline code: `println!("Hello!")`
```rust
fn main() {
println!("Hello, world!");
}
```
#hypraw-styles(read("styles.css"))
````
See `examples/` directory for complete styling implementation.
We do not provide any official CSS styles to maintain a minimal package size. You can copy our example styles from `examples/` and adapt them to your needs.
**Important**: `hypraw` is stateless and should only be used once per document. It applies globally to all code blocks in the document. Multiple `#show: hypraw` calls are unnecessary and should be avoided.
## API
### `hypraw(..)`
Enables enhanced HTML code block rendering.
```typ
// Enable hypraw for entire document (use only once)
#show: hypraw
// Enable line numbers (expressive-code style)
#show: hypraw.with(line-numbers: true)
// To disable copy button for entire document
#show: hypraw.with(copy-button: false)
// Custom settings for entire document
#show: hypraw.with(dedup-styles: false, attach-styles: false)
```
### `hypraw-set(line-numbers: auto, highlight: auto, copy-button: auto)`
Override settings for the **next** code block only (`auto` denotes default). Resets after use.
```typ
// Disable line numbers for this block (when globally enabled)
#hypraw-set(line-numbers: none)
// Start from line 2
#hypraw-set(line-numbers: 2)
// Custom labels per line (e.g., for diff display)
#hypraw-set(line-numbers: ("+", "-"))
// Highlight specific lines (1-based index)
#hypraw-set(highlight: (1, 3)) // Lines 1 and 3
#hypraw-set(highlight: (1, (3, 5))) // Line 1 and lines 3-5
// Use specific highlight classes (ins/del/mark)
// You need to set styles for these classes in the css
#hypraw-set(highlight: (ins: (1, 3), del: (4,)))
```
### `additional-styles()`
Returns additional style strings when deduplication is enabled. Call this when you set `attach-styles` to `false`.
### `html-style(style)`
Adds custom CSS styles for HTML output. Accepts a CSS string or file content.
```typ
#html-style(".hypraw { background: #f5f5f5; }")
// Or read from file
#html-style(read("styles.css"))
```
### `html-script(script)`
Similar to `html-style`, it creates a `` element.
## HTML Output
Generates headless HTML structure that you can style with your own CSS:
```html
<div class="hypraw">
<button class="hypraw-copy-btn" aria-label="Copy code" data-copy="..." />
<pre><code data-lang="rust">
<span class="c0">fn</span> <span class="c1">main</span>...
</code></pre>
</div>
```
The copy button feature provides a `data-copy` attribute with the raw code content. You need to inject your scripts to output. You can refer to the example implementation in [copy-button.css](examples/copy-button.css).
### With Line Numbers
When `line-numbers: true` is enabled, the structure includes a gutter:
```html
<div class="hypraw has-line-numbers" style="--ln-width:3ch">
<pre><code data-lang="rust"><div class="ec-line"><div class="gutter"><div class="ln"><span aria-hidden="true">1</span></div></div><div class="code"><span class="c0">fn</span> <span class="c1">main</span>() {</div></div><!-- More lines... --></code></pre>
</div>
```
## Why Another Package
[zebraw](https://github.com/hongjr03/typst-zebraw) is a GREAT versatile package for code blocks. However, it tends to produce heavy output, which compromises load time and is hard to tweak from the outside. Therefore, I developed `hypraw`, a lightweight package where you can custom almost everything with CSS.
## License
MIT License — see [LICENSE](LICENSE) for details.