Rye logoRyelanguage

Cookbook

Markdown

Rye has a markdown value for working with Markdown text. The examples on this page use the built-in Markdown support and ordinary file operations; they don’t need a battery subcontext. They require a build with Markdown enabled (the no_markdown build tag disables these functions).

Each recipe is independent. Create a notes.md file in the working directory before trying the file-based examples, for instance:

# Sprint notes

A short update for the team.

## Next steps

See the [issue tracker](https://example.org/issues).

Inspect a document without changing it

Use markdown to wrap a string read from disk, then display to show a formatted, non-interactive terminal preview.

What’s new: markdown display text

doc: Read %notes.md |^check "could not read notes.md" |markdown

doc |display
print [ "Source has" doc |text |length? "characters" ]

display prints the entire document and returns the original Markdown value; it doesn’t prompt for input. text retrieves the raw Markdown string when you need to edit or save it. If you just want the source rather than a preview, use Read %notes.md without wrapping it in markdown.

Make a heading and paragraph inventory

For a quick overview of a document, extract its headings and paragraph text without parsing it yourself line by line.

What’s new: headings paragraphs

source: Read %notes.md |^check "could not read notes.md"
doc: markdown source

titles: doc |headings
print [ "Headings found:" titles |length? ]
titles |print

doc |paragraphs |print

Both headings and paragraphs return lists of strings. Headings are in document order but their levels (H1, H2, etc.) are not included. Paragraph extraction is deliberately simple: inline elements such as links can leave gaps in the extracted text. Use the original source or an HTML conversion if you need to preserve rich formatting.

links finds explicit Markdown links such as [issue tracker](https://example.org/issues). It returns a list of dictionaries with text and url fields, which is handy for reviewing a page before publishing it.

What’s new: links

source: Read %notes.md |^check "could not read notes.md"
doc: markdown source

found: doc |links
print [ "Links found:" found |length? ]
found |print

For the sample document, this shows one link with the text issue tracker and URL https://example.org/issues. Relative links remain relative; links extracts them but does not fetch or validate destinations.

Write an HTML preview

Convert Markdown to HTML and write it next to the source file. This is useful when preparing a small report or checking how headings and links will render.

What’s new: markdown->html to-html Write

source: Read %notes.md |^check "could not read notes.md"
html: markdown->html source
Write %notes.html html |^check "could not write notes.html"
print "Preview written to notes.html"

markdown->html accepts a string. If you already have a Markdown value, use doc |to-html instead:

doc: Read %notes.md |^check "could not read notes.md" |markdown
html: doc |to-html
Write %notes.html html |^check "could not write notes.html"

Write creates or overwrites notes.html. The converter supports common GitHub-flavored Markdown features, including tables and task lists. For a public website, treat user-supplied HTML and URLs according to your site’s sanitization and security rules; converting Markdown is not a publishing policy.

See also