Robot Deal Documents: Read Markdown Reference Links

Reference links let a Markdown document keep visible link wording separate from a destination definition elsewhere in the text. That convenience can also make a robot deal-room note harder to review when readers inspect only the rendered wording. This article proposes a read-only exercise with a fictional document. It does not open a deal room, visit a seller link, or assess any software delivery. The task is to explain how the prepared note identifies a destination.

Find the visible wording before judging the destination

Begin by identifying what the reader sees as link text. Ask what promise that wording appears to make. A label referring to a technical document does not prove which file the link reaches, whether the file is current, or whether it belongs to the proposed delivery.

Keep the visible wording as one item in the exercise rather than treating it as the destination itself. This makes the later reading step meaningful: the learner must locate how the document associates that wording with a target. No actual link needs to be followed to explain this distinction.

Locate the reference definition in the prepared source

The CommonMark specification describes link reference definitions and reference links. A reader working with a prepared source document should look for the relevant definition, rather than assume the destination appears immediately beside the visible wording.

The instructor can provide a conceptual source excerpt without real commercial addresses. Ask the learner to distinguish the text shown to the reader, the reference label used in the source, and the destination supplied by the definition. These have different roles even when a short example makes them look similar.

If the prepared source does not provide enough information to identify the definition, retain that gap. Do not invent a target from the label’s meaning. A document-review exercise is useful precisely because it reveals where an intuitive reading goes beyond the available source.

Check ambiguity against the applicable parsing rules

A learner may encounter more than one apparent definition while reading a prepared document. Consult the applicable Markdown rules rather than choose the destination that sounds most plausible. CommonMark specifies how matching reference definitions are used, including the significance of the first matching definition.

The exercise should identify the actual rendering convention assumed. CommonMark is a useful specified reference, but a particular publishing system may provide additional behavior. Without knowing the system, the learner should not present a generic reading rule as an observed result from that platform.

This article renders no prepared Markdown and reports no resolved destination. It teaches how to formulate the parsing question before claiming that a link points to a particular artifact. A later authorized review should record the convention and document actually examined.

Keep relative paths attached to their document context

GitHub’s writing documentation explains relative links in rendered repository files. Its description makes the current file and repository context relevant. A path copied into another context should not be assumed to retain the same meaning automatically.

For the fictional note, identify whether a destination is described relative to a document location. Keep that location beside the path in the review explanation. The aim is not to calculate a real destination here, but to identify what information such a calculation would need.

Separate destination identification from document authority

Knowing how a reference resolves is narrower than establishing the authority or suitability of the resulting document. A link could identify an explanatory page without making that page part of an agreed delivery. Those commercial and technical relationships need their own actual basis.

Ask the learner to write a statement about the link mechanism and a separate question about the document’s role. This prevents a clean rendering from turning into an unsupported conclusion about supplier support, software provenance, or the condition of equipment.

No file is downloaded in this lesson. If an actual deal review later requires examining a supplied artifact, its ownership, intended purpose, and relationship to the transaction should be established separately. Reading Markdown syntax cannot supply those facts by itself.

Leave a short explanation another reviewer can reconstruct

A colleague should be able to identify the visible wording, the relevant reference definition, and the context needed to interpret its destination. If the explanation skips a role, revise it rather than ask the colleague to trust the rendered appearance.

More examples appear in our robot deal-document section and the reading directory. Both original illustrations organize the proposed reading exercise; they contain no real repository, seller address, resolved destination, downloaded artifact, or completed commercial review.