Module markdown 

Turning documentation written for another reader into Markdown.

Two kinds of prose reach a generated page: clap’s help text and rustdoc doc comments. Neither is Markdown a page can paste verbatim — help text is soft-wrapped for a terminal, and a doc comment links with [Item] shortcuts that mean nothing outside rustdoc. Both conversions live here so that all three generators do them the same way.

A third conversion joined them at M7.D9b, and it is the mirror image of the first two: a doc comment that cites the guide must spell an absolute site URL, because docs.rs renders the same text and a relative path there means nothing — but a page on this site republishing that URL would send a reader of /0.1/reference/catalog/ to /latest/, and would be a string mkdocs build --strict never checks. site_links_page_relative is the one place that resolves it.

Constants

DOCS_DIR 🔒

The directory a generated page must live under for its links to be rewritable.

INLINE_LINK_OPEN 🔒

The only spelling from which a site URL can be made page-relative: the target half of a Markdown inline link.

SITE_PAGE_PREFIX

This site’s own pages, absolute, as a doc comment has to spell them.

SITE_ROOT

The published site’s root, one segment above SITE_PAGE_PREFIX.

SITE_VERSION

The version segment the rewrite and the checkers require prose to cite.

Functions

code_span

Wraps text in a code span that survives backticks inside it.

definition 🔒

Splits a [label]: target line into its two halves.

demote_headings

Adds one # to every heading in a section’s body.

is_item_path 🔒

Does target name a Rust item rather than a document?

is_markdown

Is path a Markdown page?

one_line

Collapses one paragraph’s soft wrapping into a single line.

page_relative 🔒

One site URL’s path, as a Markdown link target relative to a page at prefix.

paragraphs

Splits prose into paragraphs, each collapsed onto one line.

relative_prefix 🔒

The run of ../ that reaches docs/ from the directory holding page.

resolve_reference_links

Resolves rustdoc’s reference-style link definitions, then removes them.

sections

Splits a doc comment into its #-headed sections.

site_links_page_relative

Rewrites this site’s absolute page URLs into page-relative Markdown links.

site_version_segment

Splits the tail of a SITE_ROOT match into its version segment and the rest.

strip_intra_doc_links

Rewrites rustdoc’s intra-doc links into plain text.

surviving_path_link 🔒

The byte offset of a ](…::…) link target that survived the rewrite.

url_slug 🔒

The URL path characters following a site or repository prefix, up to whatever ends the link.