{"id":17026971,"url":"https://github.com/fenjalien/mdbook-typst-doc","last_synced_at":"2026-02-03T23:03:42.291Z","repository":{"id":226647788,"uuid":"769265558","full_name":"fenjalien/mdbook-typst-doc","owner":"fenjalien","description":"An mdbook preprocessor for writing Typst documentation","archived":false,"fork":false,"pushed_at":"2024-04-05T21:08:15.000Z","size":1251,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T03:08:13.057Z","etag":null,"topics":["mdbook-preprocessor","mdbook-typst","typst","typst-doc"],"latest_commit_sha":null,"homepage":"https://www.fenjalien.xyz/mdbook-typst-doc/main/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fenjalien.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-08T17:25:55.000Z","updated_at":"2024-03-23T17:38:46.000Z","dependencies_parsed_at":"2024-03-22T19:27:06.190Z","dependency_job_id":"dbc02a21-de44-425d-8623-8d1e077d5c32","html_url":"https://github.com/fenjalien/mdbook-typst-doc","commit_stats":null,"previous_names":["fenjalien/mdbook-typst"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fenjalien/mdbook-typst-doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenjalien%2Fmdbook-typst-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenjalien%2Fmdbook-typst-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenjalien%2Fmdbook-typst-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenjalien%2Fmdbook-typst-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fenjalien","download_url":"https://codeload.github.com/fenjalien/mdbook-typst-doc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenjalien%2Fmdbook-typst-doc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263176531,"owners_count":23425779,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mdbook-preprocessor","mdbook-typst","typst","typst-doc"],"created_at":"2024-10-14T07:45:27.363Z","updated_at":"2026-02-03T23:03:37.270Z","avatar_url":"https://github.com/fenjalien.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdbook Typst Doc Preprocessor\nA preprocess for mdbook's html renderer to aid in writing Typst documentation. This is currently still a work in progress.\n\n## Features\n- [x] Display Typst types as colored pills, like in the Typst documentation.\n- [x] Typst code block:\n  - [x] Highlighting\n  - [x] Rendering\n  - [x] Examples (highlighting code and rendering)\n- [x] Parameter descriptions\n- [ ] Function definitions\n\n## Setup\nInstall the preprocessor through `cargo`'s `--git` flag:\n```\ncargo install --git https://github.com/fenjalien/mdbook-typst-doc.git\n```\n\nIt is recommended to copy and include `example/typst-doc.css` in your book as it contains the recommended styling, feel free to modify it how you see fit. See `example/book.toml` for more recommeded setup.\n\n## Usage\n### Typst Types\nConverts `{{#type ...}}` into a link to the type's web page with the same styling as the official Typst documentation. You can add new types by adding them to the `preprocessor.typst-doc.types` key in the `book.toml`:\n```toml\n[preprocessor.typst-doc.types]\nint = {class = \"num\", link = \"https://typst.app/docs/reference/foundations/int/\"}\n```\n- `link`: The link to the type's definition. You can use a realtive url if you define your own types within the book (`\"/type_definition.html\"`). If no link is given the output HTML element will not be a link.\n- `class`: The text to append to `\"type-\"` to make up the CSS class of the HTML element. This is to aid in the styling of the element. This is required unless the key `default-type-class` is given, in which case the default class will be used.\n\nNormally the preprocessor will panic if a type is used that is not in the config table. That is, unless the `default-type-class` key has been given, in which case an element with the given class and no link will be placed.\n\nFor some reason having a link in the default template breaks when used within a heading. You can place an exclamation mark `!` between the hash and the type (`{{#!type ...}}`) to not use a link. If you know/find a way to fix this without having to turn off the link please let me know :)\n\n### Typst Code Blocks\nCode blocks that have a language `typ` or `typc` can be processed. A `typ` block is in markup mode while a `typc` block is in code mode.\n\nBy default syntax highlighting will be applied to the code and nothing else. To render the code instead you can include the `render` option on the code block like this:\n```typ,render\nHello, world!\n```\nTo show the code block and the rendered output include the `example` option instead of `render`.\n\nRendering Typst code blocks requires the Typst CLI 0.11.0 to be installed on the system. By default the `typst` command will be used but this can be changed by setting the `typst-command` option. The root folder will be the book's folder (`example/`) but the `root-arg` option will be given as the `--root` argument if present.\n\nRendered images are named after the first 5 characters of the md5 sum of their source code. They will first be rendered to `mdbook-typst-doc/` then moved all at once into `src/mdbook-typst-doc/`. This will trigger a re-render if the `serve` or `watch` command is being used. However if the file already exists in `src/mdbook-typst-src/` the file it will not be rendered and moved again.\n\n### Parameter Defintions\nStylised and formatted parameter descriptions! It should be written as an html block like so:\n```html\n\u003cparameter-definition name=\"name\" types=\"int,float\" default=\"default\"\u003e\nSome description\n\u003c/parameter-definition\u003e\n```\n\nThe `name` attribute and text inside the tags will be left alone. The `types` attribute will be split on commas and formatted to use the `{{#type ...}}` preprocessor. The `default` attribute will be highlighted.\n\n\n## Custom Templates\nYou can override the default look of the above features by providing handlebar templates in `themes/typst-doc` with the following names. The keys and values of the data passed to the template is also described:\n- `type.hbs`: Template for the Typst types.\n  - `link` The url to the type's definition\n  - `class` The css class to apply to the type\n  - `name` The name of the type.\n  - `use_link` A boolean that is false when `!` is added after the hash. It should not use the link if false.\n- `code.hbs`: Template for a Typst code block with no options.\n  - `source` The highlighted code block.\n- `render.hbs`: Template for a rendered Typst code block.\n  - `image` The markdown link to the generated image.\n- `example.hbs`: Template for a Typst code block with a rendered image.\n  - `source` The highlighted code block.\n  - `image` The markdown link to the generated image.\n- `parameter.hbs`: Template for the parameter description.\n  - `name` The string given by the `name` attribute.\n  - `types` An array of strings formatted to use the type preprocessor feature given by splitting the `types` attribute on commas.\n  - `default` The default value given by the `default` attribute.\n  - `description` The text between the tags.\n\n The default templates are kept in `/src/themes/`.\n\nYou can also specify a code template to use before a Typst code block is rendered. They should be stored in a table with the key `code-templates`. You can specify a unique template for `typ` code and `typc` code. The `{{input}}` will be replaced by the source code to be rendered. See the example book toml for more details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffenjalien%2Fmdbook-typst-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffenjalien%2Fmdbook-typst-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffenjalien%2Fmdbook-typst-doc/lists"}