diff --git a/packages/preview/cmarker/0.1.10/LICENSE b/packages/preview/cmarker/0.1.10/LICENSE new file mode 100644 index 0000000000..6be1b0d13c --- /dev/null +++ b/packages/preview/cmarker/0.1.10/LICENSE @@ -0,0 +1,7 @@ +Copyright 2023 Sabrina Jewson + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/packages/preview/cmarker/0.1.10/README.md b/packages/preview/cmarker/0.1.10/README.md new file mode 100644 index 0000000000..698ada4dac --- /dev/null +++ b/packages/preview/cmarker/0.1.10/README.md @@ -0,0 +1,900 @@ +# cmarker.typ + + + +This package enables you to write CommonMark Markdown, +and import it directly into Typst. + + + + + + + + + + +
simple.typsimple.md
+ +```typ +#import "@preview/cmarker:0.1.10" + +#cmarker.render(read("simple.md")) +``` + + +```markdown +# We can write Markdown! + +*Using* __lots__ ~of~ `fancy` [features](https://example.org/). +``` +
+ + + +
simple.pdf
`simple.md` rendered as a PDF
+ +This document is available +in [Markdown](https://github.com/SabrinaJewson/cmarker.typ/tree/release#cmarker) +and [rendered PDF](https://github.com/SabrinaJewson/cmarker.typ/blob/release/README.pdf) +formats. + +## Contents + +2. [API](#api) +2. [References, labels, figures and citations](#references-labels-figures-and-citations) +2. [Supported Markdown syntax](#supported-markdown-syntax) +2. [Interleaving Markdown and Typst](#interleaving-markdown-and-typst) +2. [FAQ](#faq) +2. [Development](#development) + +## API + +We offer two functions: +1. [render](#render) +2. [render-with-metadata](#render-with-metadata) + +### render +```typc +render( + markdown, + smart-punctuation: true, + math: none, + task-list-marker: none, + h1-level: 1, + set-document-title: true, + raw-typst: true, + html: (:), + label-prefix: "", + prefix-label-uses: true, + heading-labels: "github", + scope: (:), + show-source: false, + blockquote: none, +) -> content +``` + +The `render` function renders the given Markdown and returns content. + +#### `markdown` + +The [CommonMark](https://spec.commonmark.org/0.30/) Markdown string to be processed. +Parsed with the [pulldown-cmark](https://docs.rs/pulldown-cmark) Rust library. +You can set this to `read("somefile.md")` to import an external markdown file; +see the +[documentation for the read function](https://typst.app/docs/reference/data-loading/read/). +- Accepted values: Strings and raw text code blocks. +- Required. + +#### `smart-punctuation` + +Whether to automatically convert ASCII punctuation to Unicode equivalents: +- nondirectional quotations (" and ') become directional (“” and ‘’); +- three consecutive full stops (...) become ellipses (…); +- two and three consecutive hypen-minus signs (-- and ---) + become en and em dashes (– and —). + +Note that although Typst also offers this functionality, +this conversion is done through the Markdown parser rather than Typst. +- Accepted values: Booleans. +- Default value: `true`. + +#### `math` + +A callback to be used when equations are encountered in the Markdown, +or `none` if it should be treated as normal text. +Because Typst does not support LaTeX equations natively, +the user must configure this. +- Accepted values: + Functions that take a boolean argument named `block` and a positional string argument + (often, the `mitex` function from + [the mitex package](https://typst.app/universe/package/mitex)), + or `none`. +- Default value: `none`. + +For example, to render math equation as a Typst math block, +one can use: +```typ +#import "@preview/mitex:0.2.7": mitex +#cmarker.render(`$\int_1^2 x \mathrm{d} x$`, math: mitex) +``` + + +#### `task-list-marker` + +A callback which can be used to render Markdown task lists, +or `none` if task lists are not supported. +The callback will be called with `true` if the checkbox is to be checked (`- [x]`), +and `false` if it is unchecked (`- [ ]`). + +- Accepted values: + Functions from booleans to content, or `none`. +- Default value: `none`. + +You may want to use [`cheq`](https://typst.app/universe/package/cheq) to provide the checkboxes: + +````typ +#import "@preview/cheq:0.3.1" + +#cmarker.render( + ```md + - [ ] Not checked + - [x] Checked + ```, + task-list-marker: checked => if checked { cheq.checked-sym() } else { cheq.unchecked-sym() }, +) +```` + +#### `h1-level` + +The level that top-level headings in Markdown should get in Typst. +When set to zero, +top-level headings are treated as titles, +`##` headings become `=` headings, +`###` headings become `==` headings, +et cetera; +when set to `2`, +`#` headings become `==` headings, +`##` headings become `===` headings, +et cetera. +- Accepted values: Integers in the range [-128, 127]. +- Default value: 1. + +#### `set-document-title` + +Whether to emit a `#set document(title: […])` line +for `#title()`s. + +If you encounter a “document set rules are not allowed inside of containers” error, +you should set this to `false`, +and potentially add a `#set document(title: […])` line manually. + +This has effect when [`h1-level`](#h1-level) is zero +and you have a top-level (i.e. `#`) heading. + +- Accepted values: Booleans. +- Default value: `true`. + +#### `raw-typst` + +Whether to allow raw Typst code to be injected into the document via HTML comments. +If disabled, the comments will act as regular HTML comments. +- Accepted values: Booleans. +- Default value: `true`. + +For example, when this is enabled, `` +will result in a circle in the document +(but only when rendered through Typst). +See also +[`` and ``](#interleaving-markdown-and-typst), +which is the inverse of this. + +#### `html` + +The dictionary of HTML elements that cmarker will support. +- Accepted values: + Dictionaries whose keys are the tag name (without the surrounding `<>`) + and whose values can be: + - `("normal", (attrs, body) => [/* … */])`: + Defines a normal element, + where `attrs` is a dictionary of strings, `body` is content, + and the function returns content. + - `("void", (attrs) => [/* … */])`: + Defines a void element (e.g. `
`, ``, `
`). + - `("raw-text", (attrs, body) => [/* … */])`: + Defines a raw text element (e.g. `