silk.markdown.text.

When to use#

Use MarkdownText.plainTextOwned to extract text and MarkdownText.outline to collect headings. Use MarkdownSlugger for unique GitHub-style anchors across a sequence of headings.

Details#

Text extraction omits raw HTML and frontmatter. Image children contribute their alternative text. Slugs use Unicode lowercase, remove punctuation except hyphens and underscores, and replace spaces with hyphens.

Examples#

Collect unique heading anchors#

import silk.markdown.document { MarkdownDocument }
import silk.markdown.text { MarkdownText, MarkdownHeading }
import silk.collections.list { List }
import silk.text.string { String }
import silk.core.effect { Effect }
import silk.mem.allocator { Allocator, OutOfMemoryError }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let document = run MarkdownDocument.parse("# Hello\n\n# Hello")
    |> Effect.provideMut<Allocator>(&mut allocator)
  let headings = run MarkdownText.outline(&document) |> Effect.provideMut<Allocator>(&mut allocator)
  let rows = List<MarkdownHeading>.asSlice(&headings)
  if rows.length != 2 || String.view(&rows[1].slug) != "hello-1" {
    return 1
  }
  return 0
}

Import as MarkdownText with import silk.markdown.text { MarkdownText }.

Public declarations: 3.

MarkdownText#

pub struct MarkdownText

The owner of visible-text, slug, and outline operations over the public Markdown tree.

MarkdownHeading#

pub struct MarkdownHeading

One heading in document order, with owned visible text and a unique slug.

Field node#

pub node: MarkdownNodeId

The heading's node id in the source document.

Field level#

pub level: u8

The heading level from one through six.

Field text#

pub text: String

The visible heading text without inline markup or raw HTML.

Field slug#

pub slug: String

The unique GitHub-style anchor for this heading.

MarkdownSlugger#

pub struct MarkdownSlugger

Reusable state for unique GitHub-style slugs. Repeated slugs receive -1, -2, and later available suffixes. Explicit suffixed names also reserve their spelling. Create separate state for each document.

Implementation MarkdownSlugger#

impl MarkdownSlugger

Associated function make#

pub fn make() -> MarkdownSlugger

Creates empty slug state without allocation.

Method clear#

pub fn clear(self: &mut Self)

Removes all reserved slugs and retains allocated capacity.

Method slug#

pub effect fn slug(self: &mut Self, value: string) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns a lowercase slug unique within this state, reserving its spelling. Removes punctuation except - and _, replaces ASCII spaces with -, and preserves repeated spaces.

Errors#

• OutOfMemoryError if slug storage cannot grow. Earlier reserved slugs remain reserved.

Implementation MarkdownText#

impl MarkdownText

Associated function plainTextInto#

pub effect fn plainTextInto(
    document: &MarkdownDocument<'_>,
    id: MarkdownNodeId,
    out: &mut Bytes,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends visible text from subtree id to out. Invalid ids append nothing. Text, code, and image alternatives contribute text. Breaks and block boundaries contribute newlines; table cells use tabs. Raw HTML and frontmatter contribute no text. Footnote references contribute their number; nested definitions are skipped.

Errors#

• OutOfMemoryError if out cannot grow. Text already appended remains in out.

Associated function plainTextOwned#

pub effect fn plainTextOwned(document: &MarkdownDocument<'_>, id: MarkdownNodeId) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns owned visible text for subtree id. Invalid ids return empty text. Text, code, and image alternatives contribute text. Breaks and block boundaries contribute newlines; table cells use tabs. Raw HTML and frontmatter contribute no text. Footnote references contribute their number; nested definitions are skipped.

Errors#

• OutOfMemoryError if the allocator cannot supply the result.

Associated function slugOwned#

pub effect fn slugOwned(value: string) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns a GitHub-style slug without duplicate tracking. Uses Unicode lowercase, removes punctuation except - and _, and replaces ASCII spaces with -. Tabs and control characters are removed. Non-ASCII letters, combining marks, and numbers remain.

Errors#

• OutOfMemoryError if the allocator cannot supply the result.

Associated function outline#

pub effect fn outline(document: &MarkdownDocument<'_>) -> List<MarkdownHeading>
    ! OutOfMemoryError
    ? &mut Allocator

Returns headings in document order with owned visible text and unique slugs. Duplicate tracking starts empty for each call. The returned ids belong to document. Headings inside footnote definitions are excluded because definitions are not part of the document outline.

Errors#

• OutOfMemoryError if the allocator cannot supply the outline or its strings.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.