markdown.ex

defmodule VutuvWeb.AgentDocs.Markdown do
  @moduledoc """
  Renders an agent doc (see `VutuvWeb.AgentDocs`) as Markdown: YAML
  frontmatter (the Cloudflare "markdown for agents" shape) plus a body per
  doc type. User-authored Markdown (headlines, post bodies) is passed
  through verbatim — it already is Markdown.

  Labels render through Gettext in the process locale, which
  `VutuvWeb.AgentDocs.negotiate/2` sets from the `?lang=` query parameter
  (default English). Structural metadata (frontmatter keys, the type
  names) stays English in every language.
  """

  use Gettext, backend: VutuvWeb.Gettext

  alias Vutuv.Accounts.User
  alias Vutuv.CodeStats
  alias Vutuv.Isbn
  alias VutuvWeb.AgentDocs.InvestorsDoc
  alias VutuvWeb.PostComponents
  alias VutuvWeb.UI

  # The per-user people lists (followers/following/connections) share one
  # clause; the set lives in ListDocs.
  @people_lists VutuvWeb.AgentDocs.ListDocs.people_list_types()

  def render(%{type: "profile"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.name}",
      doc.headline_markdown,
      blank_to_nil(doc.work_info),
      profile_facts(doc),
      section(
        gettext("Tags"),
        Enum.map(doc.tags, &entry_line("tags", &1))
      ),
      section(
        gettext("Experience"),
        Enum.map(doc.work_experiences, &entry_line("work_experiences", &1))
      ),
      section(
        gettext("Education"),
        Enum.map(doc.educations, &entry_line("educations", &1))
      ),
      section(
        gettext("Certificates & licenses"),
        Enum.map(doc.qualifications, &entry_line("qualifications", &1))
      ),
      # Published employment references (Zeugnisse). The profile card is public
      # for every viewer, and this document listed twelve sections and not this
      # one — so an agent reading the `.md` reported the member had none, about
      # the strongest credential a German profile carries.
      section(
        gettext("Employment references"),
        Enum.map(doc.job_references, &entry_line("job_references", &1))
      ),
      section(
        gettext("Languages"),
        Enum.map(doc.languages, &entry_line("languages", &1))
      ),
      section(gettext("Links"), Enum.map(doc.links, &entry_line("links", &1))),
      section(gettext("Media Kit"), Enum.map(doc.press_kit, &press_picture_line/1)),
      section(gettext("Contact"), Enum.map(doc.emails, &entry_line("emails", &1))),
      section(
        gettext("Profiles"),
        Enum.map(doc.social_media, &entry_line("social_media_accounts", &1))
      ),
      section(
        gettext("Messengers"),
        Enum.map(doc.messengers, &entry_line("messengers", &1))
      ),
      section(gettext("Code"), Enum.map(doc.code_stats, &code_stats_block/1)),
      section(
        gettext("Phone Numbers"),
        Enum.map(doc.phone_numbers, &entry_line("phone_numbers", &1))
      ),
      section(gettext("Addresses"), Enum.map(doc.addresses, &entry_line("addresses", &1))),
      section(
        gettext("Posts (%{count} total)", count: doc.counts.posts),
        Enum.map(doc.posts, &post_line/1)
      )
    ]
    |> join_blocks()
  end

  # The profile section pages (VutuvWeb.AgentDocs.SectionDocs) carry their
  # section in the doc map, so no inventory is kept here.
  def render(%{section: section, entries: entries} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      gettext("%{count} total", count: doc.total),
      Enum.map_join(entries, "\n\n", &entry_line(section, &1))
    ]
    |> join_blocks()
  end

  def render(%{section: section, entry: entry} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      entry_line(section, entry)
    ]
    |> join_blocks()
  end

  # A member's or a page's press kit (#2086). Deliberately above the section
  # clauses' shape rather than inside it: two shelves, no per-entry page, and a
  # picture is a file rather than a record.
  def render(%{type: "press_kit"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.rights,
      # The bios the owner wrote (#2101). Their own Markdown goes through
      # untouched — it is Markdown here as it is on the page. The heading names
      # the owner rather than saying "About": the bare msgid already exists here
      # with an organization's German ("Über die Organisation"), and a document
      # about a member wearing it is the fuzzy-fill trap by another route.
      section(gettext("About %{name}", name: doc.owner.name), Enum.map(doc.bios, &bio_block/1)),
      section(gettext("Press photos"), Enum.map(doc.photos, &press_picture_line/1)),
      section(gettext("Logo variants"), Enum.map(doc.logos, &press_picture_line/1))
    ]
    |> join_blocks()
  end

  def render(%{type: "post"} = doc) do
    author_link = md_link(doc.author.name, doc.author.url)

    [
      frontmatter(doc),
      "# #{gettext("Post by %{name}", name: author_link)} · #{doc.published_on}",
      doc.in_reply_to && in_reply_to_line(doc.in_reply_to),
      doc.body_markdown,
      verified_links_line(doc),
      review_line(doc.review),
      tags_line(doc.tags),
      engagement_line(doc),
      likers_line(doc),
      section(gettext("Images"), Enum.map(doc.images, &image_line/1)),
      video_line(doc[:video]),
      license_line(doc.license),
      # The whole conversation (issue #1006), like the HTML permalink: every
      # other thread post oldest first (the page's own post already reads in
      # full above), each naming its parent when it is one of them.
      section(
        "#{gettext("Conversation")} (#{length(doc.thread)})",
        doc.thread |> Enum.reject(&(&1.id == doc.id)) |> Enum.map(&thread_block/1)
      ),
      if(doc.thread_truncated, do: gettext("Only part of this long conversation is shown.")),
      # Replies written on other networks (issue #1069), in their own section so
      # a reader can tell which world answered — the same distinction the HTML
      # card draws with its skin. Public ones only; a reply addressed to the
      # member alone never leaves the page it was sent to (issue #1071).
      section(
        "#{gettext("Replies from other networks")} (#{length(doc.fediverse_replies)})",
        Enum.map(doc.fediverse_replies, &remote_reply_block/1)
      )
    ]
    |> join_blocks()
  end

  # A post an organization published (issue #1334). The same blocks as a
  # member's post, minus the one such a post cannot have: it is never itself a
  # reply, so there is no reply-to line. The conversation IS here (issue #1336
  # opened answering, #1334 already brought the remote replies), under the same
  # headings, so a reader parsing both meets the same field in the same place.
  def render(%{type: "organization_post"} = doc) do
    author_link = md_link(doc.author.name, doc.author.url)

    [
      frontmatter(doc),
      "# #{gettext("Post by %{name}", name: author_link)} · #{doc.published_on}",
      doc.body_markdown,
      review_line(doc.review),
      tags_line(doc.tags),
      engagement_line(doc),
      likers_line(doc),
      section(gettext("Images"), Enum.map(doc.images, &image_line/1)),
      video_line(doc[:video]),
      license_line(doc.license),
      section(
        "#{gettext("Conversation")} (#{length(doc.thread)})",
        doc.thread |> Enum.reject(&(&1.id == doc.id)) |> Enum.map(&thread_block/1)
      ),
      if(doc.thread_truncated, do: gettext("Only part of this long conversation is shown.")),
      section(
        "#{gettext("Replies from other networks")} (#{length(doc.fediverse_replies)})",
        Enum.map(doc.fediverse_replies, &remote_reply_block/1)
      )
    ]
    |> join_blocks()
  end

  def render(%{type: "post_archive"} = doc) do
    author_link = md_link(doc.author.name, doc.author.url)

    [
      frontmatter(doc),
      # doc.title already carries the period (PostDoc's period_suffix/1).
      "# #{doc.title}",
      gettext("%{count} posts by %{name}", count: doc.total, name: author_link) <>
        page_hint(doc.total, doc.posts, &paren_hint/1),
      Enum.map_join(doc.posts, "\n\n", &post_line/1)
    ]
    |> join_blocks()
  end

  # The signed-in member's personalized feed (VutuvWeb.AgentDocs.FeedDoc): a
  # page of timeline posts, same line shape as the archive (post_line/1).
  def render(%{type: "feed"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      feed_summary(doc, &paren_hint/1),
      Enum.map_join(doc.posts, "\n\n", &post_line/1)
    ]
    |> join_blocks()
  end

  def render(%{type: type} = doc) when type in @people_lists do
    [
      frontmatter(doc),
      "# #{doc.title}",
      gettext("%{count} total", count: doc.total) <>
        page_hint(doc.total, doc.people, &paren_hint/1),
      Enum.map_join(doc.people, "\n\n", &person_line/1),
      followed_organizations(doc)
    ]
    |> join_blocks()
  end

  # The per-tag endorser list is a people list with one extra fact per row:
  # when the endorsement was cast (ListDocs.build_tag_endorsers).
  def render(%{type: "tag_endorsers"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      gettext("%{count} total", count: doc.total) <>
        page_hint(doc.total, doc.people, &paren_hint/1),
      Enum.map_join(doc.people, "\n\n", &endorser_line/1)
    ]
    |> join_blocks()
  end

  def render(%{type: "tag"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.name}",
      doc.description,
      # The other names this topic answers to (issue #1338), so an agent that
      # met one of them elsewhere can tell this is the page for it.
      also_known_as(doc),
      section(
        gettext("Most endorsed members"),
        Enum.map(doc.most_endorsed_users, &person_line/1)
      ),
      section(gettext("Posts with this tag"), Enum.map(doc.posts, &post_line/1)),
      tag_open_positions(doc)
    ]
    |> join_blocks()
  end

  def render(%{type: "listing"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.people
      |> Enum.with_index(1)
      |> Enum.map_join("\n\n", fn {person, rank} -> "#{rank}. #{person_text(person)}" end)
    ]
    |> join_blocks()
  end

  # A verified organization page (issue #929).
  def render(%{type: "organization"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.name}",
      doc.description,
      [
        doc.kind && "- #{gettext("Kind")}: #{doc.kind}",
        doc.primary_domain && "- #{gettext("Verified via")}: #{doc.primary_domain}",
        also_known_as(doc),
        doc.website_url && "- #{gettext("Website")}: #{doc.website_url}",
        "- #{gettext("Address")}: #{doc.address_line}",
        fediverse_fact(doc[:fediverse])
      ]
      |> Enum.filter(&is_binary/1)
      |> Enum.join("\n"),
      organization_people(doc),
      organization_open_positions(doc),
      # The page's press kit (#2087), written by the same line builder the
      # profile document uses, so a press picture reads the same whoever offers
      # it.
      section(gettext("Media Kit"), Enum.map(doc[:press_kit] || [], &press_picture_line/1))
    ]
    |> join_blocks()
  end

  # A job posting (/jobs/:slug).
  def render(%{type: "job_posting"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      [
        "- #{gettext("Employer")}: #{job_employer(doc.employer)}",
        "- #{gettext("Employment type")}: #{doc.employment_type}",
        "- #{gettext("Workplace")}: #{doc.workplace_type}",
        job_location(doc),
        doc.salary_line && "- #{gettext("Salary")}: #{doc.salary_line}",
        doc.posted_on && "- #{gettext("Posted")}: #{doc.posted_on}",
        doc.expires_on && "- #{gettext("Expires")}: #{doc.expires_on}"
      ]
      |> Enum.filter(&is_binary/1)
      |> Enum.join("\n"),
      doc.description,
      job_tags(gettext("Required"), doc.required_tags),
      job_tags(gettext("Nice to have"), doc.nice_to_have_tags)
    ]
    |> join_blocks()
  end

  # The public job board (/jobs) — a listing of posting summaries, or, with no
  # posting at all, the two blocks the HTML board shows in its place.
  def render(%{type: "job_board"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.postings, "\n\n", &job_summary/1),
      board_reach(doc),
      doc.next && md_link(gettext("Next page"), doc.next)
    ]
    |> join_blocks()
  end

  # The verified-organization directory (/organizations).
  def render(%{type: "organizations"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.organizations, "\n", fn organization ->
        "- #{organization.name} (#{organization.kind}, #{organization.city}, #{organization.country}): #{organization.url}"
      end)
    ]
    |> join_blocks()
  end

  # The member directory overview (/members): the letter buckets with their
  # member counts and letter-page URLs.
  def render(%{type: "directory"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.letters, "\n\n", fn entry ->
        "- #{entry.letter} (#{entry.count}): #{entry.url}"
      end)
    ]
    |> join_blocks()
  end

  # The post calendar's overview (/system/posts): the months that have posts.
  def render(%{type: "post_calendar"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.months, "\n", fn month ->
        "- #{Calendar.strftime(month.date, "%Y-%m")} (#{month.count}): #{month.url}"
      end)
    ]
    |> join_blocks()
  end

  # One month of it: the days that have posts.
  def render(%{type: "post_calendar_month"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.days, "\n", fn day ->
        "- #{Date.to_iso8601(day.date)} (#{day.count}): #{day.url}"
      end)
    ]
    |> join_blocks()
  end

  # One day of it. A post whose author is not open to search engines is named
  # by its author alone — no link, no first line — exactly as on the page.
  def render(%{type: "post_calendar_day"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      Enum.map_join(doc.posts, "\n", &calendar_post_line/1)
    ]
    |> join_blocks()
  end

  # The /ads offer page (VutuvWeb.AgentDocs.AdsDoc). The rules and the facts
  # form one loose bullet list (blank-line separated, like every other list),
  # not several one-item lists.
  def render(%{type: "advertising"} = doc) do
    bullets =
      doc.rules ++
        [
          "#{gettext("Community guidelines")}: #{doc.community_guidelines_url}",
          "#{gettext("Price")}: #{doc.price.display}",
          "#{gettext("Booking window")}: #{doc.booking_window.from} – #{doc.booking_window.to}",
          doc.next_available_day &&
            "#{gettext("Next available day")}: #{doc.next_available_day}",
          doc.booked_days != [] &&
            "#{gettext("Already booked")}: #{Enum.join(doc.booked_days, ", ")}"
        ]

    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      bullets |> Enum.filter(&is_binary/1) |> Enum.map_join("\n\n", &("- " <> &1)),
      gettext("Book online (login required): %{url}", url: doc.booking_url)
    ]
    |> join_blocks()
  end

  # The investor page follows the reader's language (unlike the media kit below
  # it, which is English in every locale), so its headings go through gettext
  # like any other page. Every sentence of the argument comes out of the doc,
  # which `InvestorsDoc` built in that same language.
  def render(%{type: "investors"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.headline}",
      doc.description,
      "## #{gettext("Where we are")}",
      Enum.map_join(InvestorsDoc.figure_rows(doc.figures), "\n", fn {label, value} ->
        "- #{label}: #{value}"
      end),
      doc.people_sum,
      doc.counter_explainer,
      doc.growth_sentence,
      doc.reach_12_months_sentence,
      doc.reach_12_months_explainer && Enum.join(doc.reach_12_months_explainer, " "),
      "## #{gettext("Why this is worth building")}",
      Enum.map_join(doc.case_points, "\n\n", fn point ->
        ["### #{point.title}", point.body, case_source(point.source)]
        |> Enum.filter(&is_binary/1)
        |> Enum.join("\n\n")
      end),
      doc.contact_handle && "## #{gettext("Write to me")}",
      doc.contact_handle && doc.contact_note,
      doc.contact_profile_url && gettext("My profile: %{url}", url: doc.contact_profile_url),
      doc.contact_url && gettext("Write here: %{url}", url: doc.contact_url),
      gettext("Press material: %{url}", url: doc.media_kit_url)
    ]
    |> join_blocks()
  end

  def render(%{type: "media_kit"} = doc) do
    [
      frontmatter(doc),
      "# #{doc.title}",
      doc.description,
      "## About vutuv",
      "### Short\n\n#{doc.boilerplate.short}",
      "### Medium\n\n#{doc.boilerplate.medium}",
      "### Long\n\n#{doc.boilerplate.long}",
      "## Key facts",
      doc.facts
      |> Enum.sort_by(&elem(&1, 0))
      |> Enum.map_join("\n", fn {label, value} -> "- #{label}: #{value}" end),
      "## Brand assets",
      Enum.map_join(doc.assets, "\n", &"- #{md_link(&1.name, &1.url)} (#{&1.kind}) - #{&1.note}"),
      "## Link to your profile",
      doc.link_intro,
      Enum.map_join(doc.link_badges, "\n", &"- #{md_link(&1.name, &1.url)} - #{&1.note}"),
      Enum.map_join(doc.link_snippets, "\n\n", &link_snippet_md/1),
      "## Colours",
      Enum.map_join(doc.colors, "\n", &"- #{&1.name} `#{&1.hex}` - #{&1.note}"),
      "## Typography",
      Enum.map_join(doc.typography, "\n", &"- #{&1.role}: #{&1.name} - #{&1.note}"),
      "## Screenshots",
      Enum.map_join(doc.screenshots, "\n", &"- #{md_link(&1.name, &1.url)} - #{&1.note}"),
      "## Using all this",
      Enum.map_join(doc.usage, "\n", &("- " <> &1)),
      "## Press contact",
      [
        "#{doc.press_contact.name}, #{doc.operator.name}",
        doc.press_contact.email,
        doc.press_contact.profile_url &&
          "Profile (further contact details): #{doc.press_contact.profile_url}"
      ]
      |> Enum.filter(&is_binary/1)
      |> Enum.map_join("\n", &("- " <> &1))
    ]
    |> join_blocks()
  end

  # One media-kit link snippet: its name, what it is for, then the code in a
  # fence tagged with its language, so a reader — and the language model that is
  # the likeliest fetcher of this document — can tell the Markdown one from the
  # five HTML ones without reading them.
  defp link_snippet_md(snippet) do
    "### #{snippet.name}\n\n#{snippet.note}\n\n```#{snippet.language}\n#{snippet.code}\n```"
  end

  # One post of a calendar day. A row with no `url` is a post whose author is
  # not open to search engines: the controller has already put the line saying
  # so where the post's own words would be, so this only decides whether the
  # line is a link.
  defp calendar_post_line(%{url: nil} = post), do: "- #{post.author.name}: #{post.text}"

  defp calendar_post_line(post),
    do: "- #{post.author.name}: #{md_link(post.text, post.url)}"

  # The citation under an investor-page claim that rests on somebody else's
  # measurement. `nil` for the claims that stand on their own.
  defp case_source(nil), do: nil

  defp case_source(%{label: label, url: url}),
    do: gettext("Source: %{source}", source: md_link(label, url))

  # The pages this member follows (issue #1336), under their own heading rather
  # than among the people: a reader has to be able to tell a person from an
  # organization. Only the Following document carries the key, so every other
  # people list skips the block entirely.
  defp followed_organizations(%{organizations: [_ | _] = organizations}) do
    join_blocks([
      "## " <> gettext("Organizations"),
      Enum.map_join(organizations, "\n", &"- #{md_link(&1.name, &1.url)}")
    ])
  end

  defp followed_organizations(_doc), do: nil

  # An organization's alternative names (issue #930), or nil when it has none.
  defp also_known_as(%{also_known_as: [_ | _] = names}),
    do: "- #{gettext("Also known as")}: #{Enum.join(names, ", ")}"

  defp also_known_as(_doc), do: nil

  # The People section (issue #931): members whose linked work experience is at
  # this organization, current members first, a "(former)" note on past ones.
  defp organization_people(%{people: [_ | _] = people}) do
    [
      "## #{gettext("People")}",
      Enum.map_join(people, "\n", fn person ->
        "- #{md_link(person.name, person.url)}" <>
          if(person.title, do: " · #{person.title}", else: "") <>
          if(person.current, do: "", else: " (#{gettext("former")})")
      end)
    ]
    |> Enum.join("\n")
  end

  defp organization_people(_doc), do: nil

  defp job_employer(%{name: name, verified: verified, url: url}) do
    verified_mark = if verified, do: " (#{gettext("verified")})", else: ""
    md_maybe_link(name, url) <> verified_mark
  end

  defp job_location(%{location: %{city: city, country_name: country}}),
    do:
      "- #{gettext("Location")}: #{[city, country] |> Enum.reject(&(&1 in [nil, ""])) |> Enum.join(", ")}"

  defp job_location(%{remote_countries: [_ | _] = countries} = doc),
    do: "- #{gettext("Location")}: #{gettext("Remote")} (#{remote_where(doc, countries)})"

  defp job_location(_doc), do: "- #{gettext("Location")}: #{gettext("Remote")}"

  # The countries in full — an agent filters on them — with the poster's own
  # word in front when their selection is exactly a region, so the machine
  # formats say "EMEA" where the HTML page does.
  defp remote_where(%{remote_region: region}, countries) when is_binary(region),
    do: "#{region}: #{Enum.map_join(countries, ", ", & &1.name)}"

  defp remote_where(_doc, countries), do: Enum.map_join(countries, ", ", & &1.name)

  defp job_tags(_label, []), do: nil

  defp job_tags(label, tags) do
    "## #{label}\n" <> Enum.map_join(tags, "\n", &"- #{md_link(&1.name, &1.url)}")
  end

  # One posting summary block on the board (/jobs) or an "Offene Stellen" section.
  defp job_summary(entry) do
    [
      "## #{md_link(entry.title, entry.url)}",
      "- #{gettext("Employer")}: #{job_employer(entry.employer)}",
      "- #{gettext("Employment type")}: #{entry.employment_type}",
      "- #{gettext("Workplace")}: #{entry.workplace_type}",
      job_location(entry),
      entry.salary_line && "- #{gettext("Salary")}: #{entry.salary_line}",
      entry.posted_on && "- #{gettext("Posted")}: #{entry.posted_on}",
      job_summary_tags(entry.tags)
    ]
    |> Enum.filter(&is_binary/1)
    |> Enum.join("\n")
  end

  defp job_summary_tags([]), do: nil

  defp job_summary_tags(tags),
    do: "- #{gettext("Tags")}: " <> Enum.map_join(tags, ", ", &md_link(&1.name, &1.url))

  # The tag page's "Offene Stellen" section (#933): the postings carrying the
  # tag, then a link into the pre-filtered board.
  defp tag_open_positions(%{open_positions: [_ | _] = postings} = doc) do
    [
      "## #{gettext("Open positions")}",
      Enum.map_join(postings, "\n\n", &job_summary/1),
      doc[:jobs_url] && md_link(gettext("All jobs with this tag"), doc.jobs_url)
    ]
    |> Enum.filter(&is_binary/1)
    |> Enum.join("\n\n")
  end

  defp tag_open_positions(_doc), do: nil

  # An organization's "Offene Stellen" section (#933), or nil when it has none.
  defp organization_open_positions(%{open_positions: [_ | _] = postings}) do
    "## #{gettext("Open positions")}\n\n" <> Enum.map_join(postings, "\n\n", &job_summary/1)
  end

  defp organization_open_positions(_doc), do: nil

  # The YAML frontmatter every Markdown doc starts with.
  defp frontmatter(doc) do
    [
      "---",
      "title: #{yaml(doc.title)}",
      doc.description && "description: #{yaml(doc.description)}",
      "url: #{doc.url}",
      # Identity/media metadata for the doc types that carry it (the profile):
      # the handle and avatar live only in the structured formats otherwise, so
      # the frontmatter is where the human formats surface them.
      doc[:username] && "username: #{yaml(doc.username)}",
      doc[:avatar_url] && "avatar_url: #{doc.avatar_url}",
      "type: #{doc.type}",
      "schema_version: #{doc.schema_version}",
      "generated_at: #{DateTime.to_iso8601(doc.generated_at)}",
      # The page's opt-outs, embedded in the document body itself so a reader
      # that never sees the Content-Signal / X-Robots-Tag headers (a saved
      # file, a pasted snippet) still carries the member's choice.
      doc.noindex && "noindex: true",
      doc.noai && "noai: true",
      "---"
    ]
    # Keep only the emitted lines: a conditional whose flag is off is `nil`
    # *or* `false` (`false && "noindex: true"`), and a bare `false` would
    # otherwise stringify into the YAML as a keyless value (issue #924).
    |> Enum.filter(&is_binary/1)
    |> Enum.join("\n")
  end

  defp profile_facts(doc) do
    [
      # First fact, like the profile's first line under the name: a reader that
      # says the name out loud should meet the pronunciation before anything else.
      doc.name_pronunciation &&
        "- #{gettext("Name pronunciation")}: #{doc.name_pronunciation}",
      Enum.map(name_parts(doc), fn {label, value} -> "- #{label}: #{value}" end),
      doc.verified && "- " <> gettext("Verified profile: yes"),
      doc.employment_status &&
        "- #{gettext("Employment status")}: #{User.employment_status_label(doc.employment_status)}",
      User.desired_workplace_line(doc.desired_workplace_types) &&
        "- #{gettext("Preferred workplace")}: #{User.desired_workplace_line(doc.desired_workplace_types)}",
      doc.desired_salary && "- " <> User.desired_salary_agent_line(doc.desired_salary),
      fediverse_fact(doc[:fediverse]),
      count_facts(doc.counts),
      birthday_facts(doc)
    ]
    |> List.flatten()
    |> Enum.filter(& &1)
    |> Enum.join("\n\n")
  end

  @doc """
  The member's name broken into its labelled parts, `[{label, value}]`, with
  the empty ones dropped (so most profiles yield just a first and a last name).

  The heading prints the assembled name and nothing in it says which word is
  which, so a reader that has to address the member, sort them by family name
  or transliterate the name has to guess — and guesses wrong on every name
  that does not follow the given-name-first convention. The machine formats
  have carried the parts all along (the JSON/XML keys, the vCard's `N`), so
  this is md/txt catching up rather than a new disclosure.

  The labels are the ones the Basics form uses, so the document names each
  part with the same word the member filled it in under. Shared with the
  plain-text renderer, like `work_period/1` and friends.
  """
  def name_parts(doc) do
    [
      {gettext("Prefix"), doc.honorific_prefix},
      {gettext("First Name"), doc.first_name},
      {gettext("Middle Name"), doc.middle_name},
      {gettext("Last Name"), doc.last_name},
      {gettext("Suffix"), doc.honorific_suffix},
      {gettext("Nickname"), doc.nickname}
    ]
    |> Enum.reject(fn {_label, value} -> value in [nil, ""] end)
  end

  # The birthday granularity the member chose (`User.birthdate_mode/1`) puts at
  # most one of these three in the doc, so they travel as one group — and keep
  # `profile_facts/1` inside Credo's complexity budget.
  defp birthday_facts(doc) do
    [
      doc.birthdate && "- #{gettext("Birthday")}: #{doc.birthdate}",
      doc.birthday_month_day && "- #{gettext("Birthday")}: #{doc.birthday_month_day}",
      doc.age && "- #{gettext("Age")}: #{doc.age}"
    ]
  end

  # The member's Fediverse address, the same fact the profile's Subscribe card
  # shows; absent for the vast majority who do not federate. A moved account
  # names where it went, so a reader follows the new address, not the redirect.
  defp fediverse_fact(nil), do: nil

  defp fediverse_fact(%{moved_to: moved_to} = fediverse) when is_binary(moved_to) do
    "- #{gettext("Fediverse")}: #{fediverse.handle} " <>
      "(#{gettext("moved to %{address}", address: moved_to)})"
  end

  defp fediverse_fact(fediverse), do: "- #{gettext("Fediverse")}: #{fediverse.handle}"

  # The follower / following / connection counts, each shown only when non-zero.
  defp count_facts(counts) do
    [
      counts.followers > 0 && "- #{gettext("Followers")}: #{counts.followers}",
      counts.following > 0 && "- #{gettext("Following")}: #{counts.following}",
      counts.connections > 0 && "- #{gettext("Connections")}: #{counts.connections}"
    ]
  end

  # One entry of a profile section — the same line on the profile page and
  # on the section's own index / show pages.
  # An honor tag is an admin-granted badge, not a peer-vouched skill, so it shows
  # the "honor tag" marker in place of the endorsement count.
  defp entry_line("tags", %{honor: true} = tag),
    do: "- #{md_link(tag.name, tag.url)} (#{gettext("honor tag")})"

  defp entry_line("tags", tag),
    do: "- #{md_link(tag.name, tag.url)} (#{endorsements_label(tag)}#{endorser_names(tag)})"

  defp entry_line("work_experiences", work), do: work_line(work)
  defp entry_line("educations", edu), do: education_line(edu)
  defp entry_line("qualifications", qualification), do: qualification_line(qualification)

  defp entry_line("job_references", reference), do: job_reference_line(reference)

  defp entry_line("languages", language),
    do: "- #{md_text(language.name)}: #{language.level}#{language_preferred_gloss(language)}"

  defp entry_line("links", link), do: link_line(link)

  defp entry_line("emails", email),
    do: "- #{md_text(email.type)}: #{md_autolink(email.value)}"

  defp entry_line("social_media_accounts", account), do: social_line(account)
  defp entry_line("messengers", messenger), do: messenger_line(messenger)

  defp entry_line("phone_numbers", phone),
    do: "- #{md_text(phone.type)}: #{md_text(phone.value)}"

  # `address_line/1` and `code_stats_facts/1` are shared with the plain-text
  # renderer, which must not carry backslashes, so the Markdown side escapes
  # what it is handed rather than the fragment escaping itself.
  defp entry_line("addresses", address), do: "- " <> md_text(address_line(address))

  # One code-forge account of the profile's "Code" section (Vutuv.CodeStats):
  # the account line with its glanceable facts, then one indented line per top
  # repository. Returned as a single block (account line + tight nested repo
  # list) so the loose section join separates accounts, not an account from its
  # own repos.
  defp code_stats_block(account) do
    [
      "- #{md_text(account.provider)}: #{md_url(account.url)} (#{md_text(code_stats_facts(account))})"
    ]
    |> Kernel.++(Enum.map(account.top_repos, &code_repo_line/1))
    |> Enum.join("\n")
  end

  defp code_repo_line(repo) do
    linked = md_maybe_link(repo.name || "", repo.url)

    details =
      [
        repo.stars && "★ #{repo.stars}",
        repo.language,
        repo.description && md_text(repo.description)
      ]
      |> Enum.filter(&is_binary/1)
      |> Enum.join(" · ")

    if details == "", do: "  - #{linked}", else: "  - #{linked}: #{details}"
  end

  @doc """
  The facts inside a code-forge account line's parentheses — every fact the
  forge exposed, dot-separated. Shared with the text renderer so the two
  human-readable formats read the same.

  The counts stay **exact** here, where the card shows `compact_count/1`'s
  `2K`. These formats are written for agents (the frontmatter is the
  "markdown for agents" shape), and a reader that came for the figure is worse
  served by a rounded one — `user_profile_code_stats_test.exs` pins it.
  """
  def code_stats_facts(account) do
    [
      account.total_stars &&
        ngettext("%{count} star", "%{count} stars", account.total_stars),
      account.public_repos &&
        ngettext("%{count} repository", "%{count} repositories", account.public_repos),
      account.followers &&
        ngettext("%{count} follower", "%{count} followers", account.followers),
      account.member_since && gettext("since %{date}", date: account.member_since),
      code_dormant_fact(account),
      account.languages != [] && Enum.join(account.languages, ", ")
    ]
    |> Enum.filter(&is_binary/1)
    |> Enum.join(" · ")
  end

  # Mirrors the card: the last-activity date only appears once the account
  # has been quiet for over four weeks (a dormancy signal); JSON/XML always
  # carry the raw last_active_at.
  defp code_dormant_fact(account) do
    case CodeStats.dormant_since(account.last_active_at) do
      %Date{} = date -> gettext("last active %{date}", date: date)
      _ -> nil
    end
  end

  # Format-independent line content, shared with the text renderer (like
  # work_period/1 below).
  @doc false
  def endorsements_label(tag) do
    gettext("%{count} endorsements", count: tag.endorsements)
  end

  # The endorsers the tag list page names beside each tag (issue #895), as
  # links after the count. The profile's tag list carries no roster, so it
  # renders nothing there.
  defp endorser_names(%{endorsers: [_ | _] = people}),
    do: ": " <> Enum.map_join(people, ", ", &md_link(&1.name, &1.url))

  defp endorser_names(_tag), do: ""

  @doc """
  The trailing " (Preferred contact language)" gloss on the member's first
  language (issue #894), or `""` for the rest. Shared by both text renderers so
  the machine-readable intent reads the same in Markdown and plain text.
  """
  def language_preferred_gloss(%{preferred: true}),
    do: " (" <> gettext("Preferred contact language") <> ")"

  def language_preferred_gloss(_language), do: ""

  defp work_line(work) do
    period = work_period(work)
    kind_note = work_kind_note(work)
    description = Map.get(work, :description)
    page = Map.get(work, :organization_page)
    qualification_note = work_qualification_note(work)

    ["- ", Enum.join([work.title, work.organization] |> Enum.filter(& &1), " @ ")]
    |> Kernel.++(if page, do: [" (#{md_link(page.name, page.url)})"], else: [])
    |> Kernel.++(if kind_note, do: [" [#{kind_note}]"], else: [])
    |> Kernel.++(if period, do: [" (#{period})"], else: [])
    |> Kernel.++(if qualification_note, do: [" [#{qualification_note}]"], else: [])
    # The description is authored Markdown (#905), so it is emitted raw like the
    # title/organization above and a post's body — never md_text-escaped, which
    # would backslash a member's own `[label](url)` link into literal text (#927).
    |> Kernel.++(if description, do: [": #{description}"], else: [])
    |> Enum.join()
    |> indent_item_body()
  end

  # The credential the job was earned with (issue #858), mirroring the HTML
  # page's "With qualification: …" line. Shared with the text renderer.
  @doc false
  def work_qualification_note(work) do
    case Map.get(work, :qualification) do
      %{name: name} -> gettext("With qualification: %{name}", name: name)
      _none -> nil
    end
  end

  # The non-default CV categories (issue #840) are called out on the entry
  # line, mirroring the HTML pages' category headings; a plain job stays
  # unmarked, like the page's jobs-only timeline. Shared with the text
  # renderer, and one rule with the HTML rows — `kind_note/1` owns both which
  # kinds are worth naming and the wording (the form's category picker msgids).
  @doc false
  defdelegate work_kind_note(work), to: VutuvWeb.WorkExperienceHTML, as: :kind_note

  # Shares work_period/1 (the education entry carries the same :start / :end
  # keys). Degree + school lead, then the period, then field of study and
  # notes — both, like the HTML page shows them.
  defp education_line(edu) do
    period = work_period(edu)
    kind_note = education_kind_note(edu)
    title = Enum.join(Enum.filter([edu.degree, edu.school], & &1), ", ")

    # Field of study is a plain label emitted raw (like the title above); the
    # description is authored Markdown (#905), also raw, so a member's own
    # `[label](url)` link is not backslash-escaped into literal text (#927).
    detail =
      [edu.field_of_study, edu.description]
      |> Enum.filter(& &1)
      |> Enum.join(" — ")

    ["- ", title]
    |> Kernel.++(if kind_note, do: [" [#{kind_note}]"], else: [])
    |> Kernel.++(if period, do: [" (#{period})"], else: [])
    |> Kernel.++(if detail != "", do: [": #{detail}"], else: [])
    |> Enum.join()
    |> indent_item_body()
  end

  # The non-default education categories (issue #849) are called out on the
  # entry line, like work_kind_note/1 does for work experiences; a plain
  # degree stays unmarked. Shared with the text renderer.
  @doc false
  def education_kind_note(edu) do
    case Map.get(edu, :kind) do
      "apprenticeship" -> gettext("Vocational Training")
      "school" -> gettext("School Education")
      _university -> nil
    end
  end

  # A credential line: the name, then its facts, then the verification link as
  # an autolink. Blank facts drop out, so a bare-name entry is just "- Name".
  # The Zeugnis text is the point of the entry, so it goes on its own indented
  # line rather than into the fact list: it is prose, often several sentences,
  # and a reader (human or agent) came for its exact wording.
  defp job_reference_line(reference) do
    facts =
      [reference.employer, reference.kind_label, reference.issued_on]
      |> Enum.reject(&(&1 in [nil, ""]))
      |> Enum.join(" · ")

    base =
      if facts == "",
        do: "- #{md_text(reference.title)}",
        else: "- #{md_text(reference.title)}: #{md_text(facts)}"

    base
    |> append_if(
      reference.document,
      &(&1 <> " " <> md_link(gettext("document"), reference.document.url))
    )
    |> append_if(reference.text, &(&1 <> "\n\n  " <> md_text(reference.text)))
  end

  defp qualification_line(qualification) do
    facts = qualification_facts(qualification)

    base =
      if facts == "",
        do: "- #{md_text(qualification.name)}",
        else: "- #{md_text(qualification.name)}: #{md_text(facts)}"

    line =
      base
      |> append_if(qualification.url, &(&1 <> " " <> md_autolink(qualification.url)))
      |> append_if(
        qualification.document,
        &(&1 <> " " <> md_link(gettext("proof document"), qualification.document.url))
      )

    # The jobs the credential earned (issue #1109), one indented line each —
    # the same tight nested list the code-forge accounts use for their repos.
    Enum.join([line | Enum.map(citing_jobs(qualification), &citing_job_line/1)], "\n")
  end

  # The credential's citing roles, or [] for an entry that has none (or came
  # from a surface that did not preload them).
  @doc false
  def citing_jobs(qualification) do
    case Map.get(qualification, :jobs) do
      %{entries: [_ | _] = entries} -> entries
      _no_jobs -> []
    end
  end

  defp citing_job_line(job) do
    linked = md_maybe_link(job.title, job.url)
    facts = citing_job_facts(job)

    if facts == "", do: "  - #{linked}", else: "  - #{linked}: #{md_text(facts)}"
  end

  # One citing role's facts beside its title — the employer, its period and,
  # for anything but a plain job, the CV category. Shared with the plain-text
  # renderer so the two read the same.
  @doc false
  def citing_job_facts(job) do
    [job.organization, work_period(job), work_kind_note(job)]
    |> Enum.filter(& &1)
    |> Enum.join(" · ")
  end

  defp append_if(line, nil, _fun), do: line
  defp append_if(line, _present, fun), do: fun.(line)

  # The credential's facts joined with middots — shared with the plain-text
  # renderer (like work_period/1) so the wording stays in one place. Returns
  # plain text; each renderer applies its own escaping. Kind, issuer, the
  # awarded and "valid until" dates and the credential id.
  @doc false
  def qualification_facts(qualification) do
    ([
       qualification_kind_label(qualification.kind),
       qualification.issuer,
       qualification.awarded && gettext("awarded %{date}", date: qualification.awarded),
       qualification.expires && gettext("valid until %{date}", date: qualification.expires),
       qualification.credential_id && gettext("ID: %{id}", id: qualification.credential_id)
     ] ++ qualification_usage_facts(Map.get(qualification, :jobs)))
    |> Enum.filter(& &1)
    |> Enum.join(" · ")
  end

  # The usage facts (issue #1005) from the entry's `jobs` map, mirroring the
  # HTML badges: how many jobs the credential earned, and whether it is in
  # current use or when it was last used.
  defp qualification_usage_facts(nil), do: []

  defp qualification_usage_facts(jobs) do
    [
      ngettext("used for %{count} job", "used for %{count} jobs", jobs.count),
      jobs.in_use && gettext("currently in use"),
      # pgettext: the bare "last used %{date}" msgid already belongs to the
      # access-token list ("zuletzt benutzt am …"), whose grammar doesn't fit
      # a year-month value — a distinct context keeps the two independent.
      !jobs.in_use && jobs.last_used &&
        pgettext("qualification job usage", "last used %{date}", date: jobs.last_used)
    ]
  end

  @doc false
  def qualification_kind_label("license"), do: gettext("License")
  def qualification_kind_label(_certification), do: gettext("Certificate")

  @doc false
  def work_period(work) do
    case {work.start, work.end} do
      {nil, nil} -> nil
      {start, nil} -> "#{start} – #{gettext("today")}"
      {nil, ending} -> gettext("until %{date}", date: ending)
      {start, ending} -> "#{start} – #{ending}"
    end
  end

  defp link_line(%{description: nil, url: url} = link),
    do: "- " <> md_autolink(url) <> verified_suffix(link)

  defp link_line(%{description: description, url: url} = link),
    do: "- #{md_link(description, url)}" <> verified_suffix(link)

  # A verified link (proved to be the member's own webpage) carries the same
  # marker the profile's verified mark shows.
  defp verified_suffix(%{verified: true}), do: " (#{gettext("verified webpage")})"
  defp verified_suffix(_link), do: ""

  # The provider labels the link — the same [label](url) form as the Links
  # section. A provider without a canonical URL scheme (Snapchat) carries
  # only the account name, so there is no link to offer.
  defp social_line(%{provider: provider, url: "http" <> _ = url} = account),
    do: "- " <> md_link(provider, url) <> verified_profile_suffix(account)

  defp social_line(%{provider: provider, url: value} = account),
    do: "- #{md_text(provider)}: #{md_text(value)}" <> verified_profile_suffix(account)

  # A verified social account (proved to be the member's own) carries the same
  # marker its verified mark shows on the profile card.
  defp verified_profile_suffix(%{verified: true}), do: " (#{gettext("verified profile")})"
  defp verified_profile_suffix(_account), do: ""

  # A messenger: the provider, its contact (a phone number or handle), and the
  # deep link that opens the app at that contact. The test is whether there IS a
  # link, not what scheme it carries: `Messenger.url/1` already answers "" when
  # there is none (Session, a Signal username), while XMPP's link is an `xmpp:`
  # URI, which a scheme test dropped without a word. A contact link IS its own
  # address, so it is printed once rather than as a link labelled with itself.
  defp messenger_line(%{provider: provider, kind: "link", url: url}) when url != "",
    do: "- #{md_text(provider)}: " <> md_autolink(url)

  defp messenger_line(%{provider: provider, contact: contact, url: url}) when url != "",
    do: "- #{md_text(provider)}: #{md_link(contact, url)}"

  defp messenger_line(%{provider: provider, contact: contact}),
    do: "- #{md_text(provider)}: #{md_text(contact)}"

  @doc false
  def address_line(address) do
    [
      address.description && "#{address.description}: ",
      [
        address.line_1,
        address.line_2,
        address.line_3,
        address.line_4,
        address.zip_code,
        address.city,
        address.state,
        address.country
      ]
      |> Enum.filter(&(&1 not in [nil, ""]))
      |> Enum.join(", ")
    ]
    |> Enum.filter(& &1)
    |> Enum.join()
  end

  defp post_line(post) do
    line =
      "- #{post.published_on}#{pin_suffix(post)}#{repost_suffix(post)}: " <>
        md_link(entry_label(post), post.url) <> md_text(quote_suffix(post))

    Enum.join([line | Enum.map(thread_context(post), &thread_context_line/1)], "\n")
  end

  @doc false
  # The posts a feed row answers (issue #1880), oldest first. Absent on an
  # archive entry and on a row from another network, so the shared reader
  # answers `[]` rather than each call site guarding.
  def thread_context(post), do: Map.get(post, :thread) || []

  # Indented under the entry it belongs to, and naming its author — which is
  # what tells it apart from an entry line, since those carry no author.
  defp thread_context_line(post) do
    "  - #{post.published_on} #{md_link(post.author, post.url)}: " <>
      md_text(entry_label(post))
  end

  @doc false
  # What a timeline entry reads as. Normally its excerpt — but a post from
  # another network can be a photograph and nothing else (issue #1163), and its
  # stored body is then genuinely the empty string, on purpose: the inbox that
  # wrote it has no locale, so any sentence built there would freeze the English
  # one into the row. The fact that there is a picture is therefore stated
  # here instead, where the reader's language is known.
  def entry_label(post) do
    case {String.trim(post.excerpt || ""), Map.get(post, :pictures, 0)} do
      {excerpt, 0} -> excerpt
      {"", count} -> picture_note(count)
      {excerpt, count} -> excerpt <> " " <> picture_note(count)
    end
  end

  defp picture_note(count), do: ngettext("(a picture)", "(%{count} pictures)", count)

  @doc false
  # What the entry quotes (issue #1609), shared with the plain-text renderer.
  # The card on the page shows the quoted post's author and words; an agent gets
  # the same two facts as a sentence, because an entry that only reacts to
  # something ("exactly this") is unreadable without it.
  #
  # Both halves are the quoting server's. The escaping is the Markdown caller's
  # (the plain-text renderer must not carry backslashes), and it escapes the
  # whole assembled sentence — the surrounding words are ours and hold none of
  # the three characters `md_text/1` touches.
  def quote_suffix(%{quote: %{url: url, author: nil}}),
    do: " — " <> gettext("Quotes %{url}", url: url)

  def quote_suffix(%{quote: %{url: url, author: author}}),
    do: " — " <> gettext("Quotes %{name}: %{url}", name: author, url: url)

  def quote_suffix(_post), do: ""

  @doc false
  # The post the member showcases on their profile (issue #1110). Only the
  # profile doc's entries carry the flag, so every other post list is unchanged.
  def pin_suffix(%{pinned: true}), do: " (#{gettext("pinned post")})"
  def pin_suffix(_post), do: ""

  # "(reposted by A)" for a lone reposter, "(reposted by A and 3 more)" once a
  # post carries a whole roster (the feed's follow-scoped reposters, newest
  # first). Falls back to the single `reposted_by` name for docs that carry
  # only that (the profile posts section).
  @doc false
  def repost_suffix(post) do
    case repost_names(post) do
      [] ->
        ""

      [name] ->
        " (#{gettext("reposted by %{name}", name: name)})"

      [name | rest] ->
        " (#{gettext("reposted by %{name} and %{count} more", name: name, count: length(rest))})"
    end
  end

  @doc false
  def repost_names(post) do
    cond do
      is_list(post[:reposters]) and post[:reposters] != [] -> post[:reposters]
      post[:reposted_by] -> [post[:reposted_by]]
      true -> []
    end
  end

  # The empty board's companion blocks (see `VutuvWeb.AgentDocs.JobBoardDoc`):
  # the members who said they are available, and the fields members carry.
  # Absent on a board with postings, where the doc carries neither key.
  defp board_reach(%{open_to_offers: available, fields: fields}) do
    [
      "## #{gettext("Who you would reach")}",
      ngettext(
        "One random vutuv account that is open to offers.",
        "%{formatted} random vutuv accounts that are open to offers.",
        length(available),
        formatted: to_string(length(available))
      ),
      Enum.map_join(available, "\n", &person_line/1),
      "## #{gettext("What members here work on")}",
      Enum.map_join(fields, "\n", fn field ->
        "- #{md_link(field.name, field.url)} (#{field.members})"
      end)
    ]
    |> join_blocks()
  end

  defp board_reach(_doc), do: nil

  defp person_line(person), do: "- #{person_text(person)}"

  defp person_text(person) do
    md_link(person.name, person.url) <>
      if(person.work_info, do: " — " <> md_text(person.work_info), else: "") <>
      tags_suffix(Map.get(person, :tags))
  end

  # The follower / following lists and the directory's letter pages carry a
  # per-person tag summary; the connection and tag-endorser lists leave it nil
  # and the suffix is empty.
  defp tags_suffix(nil), do: ""

  defp tags_suffix(%{top: top, total: total}) do
    links = Enum.map_join(top, ", ", fn tag -> md_link(tag.name, tag.url) end)
    " · #{gettext("Tags")}: #{links} (#{gettext("%{count} total", count: total)})"
  end

  defp endorser_line(person),
    do: "- #{person_text(person)}" <> endorsed_suffix(person.endorsed_at)

  @doc false
  # Shared with the plain-text renderer (VutuvWeb.AgentDocs.Text), like
  # work_period/1, address_line/1 and endorsements_label/1, so the translated
  # label and date format stay in one place.
  def endorsed_suffix(nil), do: ""

  def endorsed_suffix(at),
    do: " (" <> gettext("endorsed %{date}", date: Calendar.strftime(at, "%Y-%m-%d %H:%M")) <> ")"

  defp in_reply_to_line(%{author: nil}), do: "> " <> gettext("In reply to a deleted post.")

  defp in_reply_to_line(%{url: nil, author: author}),
    do: "> " <> gettext("In reply to a deleted post by %{name}.", name: author)

  defp in_reply_to_line(%{url: url, author: author} = ref) do
    author_link = md_link(author, url)
    "> " <> gettext("In reply to a post by %{name}.", name: author_link) <> answered_words(ref)
  end

  # The words of the post answered, when the document carries them — an answer
  # to another network (issue #1165), whose HTML page draws that post as a card
  # above the answer. Inside the same blockquote, so it cannot be read as this
  # post's own body, and escaped as text like every other stranger's writing
  # here: it must not be able to mint links in our document.
  defp answered_words(%{content_warning: warning} = ref) when is_binary(warning) do
    "\n>\n> " <> gettext("Content warning") <> ": " <> md_text(warning) <> answered_text(ref)
  end

  defp answered_words(ref), do: answered_text(ref)

  defp answered_text(%{text: text}) when is_binary(text) and text != "",
    do: "\n>\n" <> Enum.map_join(String.split(text, "\n"), "\n", &("> " <> md_text(&1)))

  defp answered_text(_ref), do: ""

  defp tags_line([]), do: nil
  defp tags_line(tags), do: "Tags: " <> Enum.map_join(tags, ", ", &"##{&1}")

  # The public engagement counters, mirroring the HTML action bar: one figure
  # per act, vutuv's own and the other networks' together (issues #1068, #1069).
  # What arrived from out there follows as a breakdown of those totals — the
  # same split the card's expandable panel shows, down to the closing sentence
  # that it is not additional — and is omitted at zero exactly as the HTML
  # omits the whole panel.
  @doc false
  def engagement_line(doc) do
    counts =
      "#{gettext("Likes")}: #{doc.like_count} · #{gettext("Reposts")}: #{doc.repost_count} · " <>
        "#{gettext("Bookmarks")}: #{doc.bookmark_count}"

    case fediverse_share(doc) do
      [] -> counts
      parts -> Enum.join([counts | parts], " · ")
    end
  end

  @doc """
  The members the HTML page names under the like count (issue #1233), as their
  own line rather than a clause on the counts line: a roster grows, and the
  plain-text renderer hard-wraps at 80 columns, so hanging it off the figures
  would rewrap that line differently for every post. nil when nobody may be
  named — a post whose likers all keep their names to themselves reads exactly
  as it did before this existed.

  Capped like the row, with the like count above it staying the true total, so
  the line never claims to be the whole list. Shared with the plain-text
  renderer.
  """
  def likers_line(doc) do
    case doc[:likers] || [] do
      [] -> nil
      likers -> gettext("Liked by") <> ": " <> Enum.map_join(likers, ", ", & &1.name)
    end
  end

  # The "from other networks" clauses: how much of the counts above came from
  # there, who reacted, and that it is already included.
  defp fediverse_share(doc) do
    reactions = doc[:fediverse_reaction_count] || 0
    replies = doc[:fediverse_reply_count] || 0

    [
      reactions > 0 &&
        gettext("Reactions from other networks") <> ": #{reactions}#{reaction_names(doc)}",
      replies > 0 && gettext("Replies from other networks") <> ": #{replies}",
      (reactions > 0 or replies > 0) && gettext("Already counted in the numbers above.")
    ]
    |> Enum.filter(& &1)
  end

  # The accounts behind those reactions, the same ones the HTML line names as
  # chips. Parenthesised after the count so the figure stays first and a doc for
  # a post nobody reacted to is unchanged.
  defp reaction_names(doc) do
    case doc[:fediverse_reactions] || [] do
      [] -> ""
      entries -> " (" <> Enum.map_join(entries, ", ", &reaction_name/1) <> ")"
    end
  end

  defp reaction_name(%{kind: "announce", handle: handle}),
    do: gettext("%{handle} shared this", handle: handle)

  defp reaction_name(%{handle: handle}), do: gettext("%{handle} liked this", handle: handle)

  @doc """
  The emerald ✓ the HTML post marks a link with when it points at a webpage
  the author proved is their own (issue #1246), as one fact line — a reader
  of the `.md`/`.txt` sibling cannot see an icon. Nil when the post links to
  none. Shared with the text renderer.

  Each entry names the proven address and how far the proof reaches: the
  whole host, or that one page and nothing beside it.
  """
  def verified_links_line(%{verified_author_links: [_ | _] = links}) do
    gettext("Verified webpages of the author linked here: %{addresses}",
      addresses: Enum.map_join(links, ", ", &verified_link_label/1)
    )
  end

  def verified_links_line(_doc), do: nil

  defp verified_link_label(%{scope: "host"} = link),
    do: gettext("%{address} (whole website)", address: link.address)

  defp verified_link_label(link),
    do: gettext("%{address} (this page only)", address: link.address)

  @doc """
  The post's review sidecar as one fact line (what the HTML review card
  shows), nil when the post carries none. Shared with the text renderer.
  """
  def review_line(nil), do: nil

  def review_line(review) do
    label =
      if review.kind == "movie", do: gettext("Film review"), else: gettext("Book review")

    isbn =
      if review.kind == "book" and review.identifier,
        do: "ISBN #{Isbn.format(review.identifier)}"

    details =
      [
        review.title,
        review.creator,
        review.year,
        PostComponents.review_medium_label(review.medium),
        review.publisher,
        PostComponents.review_pages_label(review),
        PostComponents.review_duration_label(review),
        isbn,
        review.link
      ]
      |> Enum.reject(&is_nil/1)
      |> Enum.join(" · ")

    "#{label}: #{details}"
  end

  # The pager / feed-summary / cursor hints are shared with the plain-text
  # renderer (VutuvWeb.AgentDocs.Text) like the other helpers above; only the
  # separator wrapping differs per format, so it is passed in as `wrap` (like
  # endorsed_suffix/1's fixed form): Markdown parenthesizes " (…)", plain text
  # dash-prefixes " — …". Keep both outputs byte-identical (a drift test guards them).
  defp paren_hint(inner), do: " (" <> inner <> ")"

  @doc false
  def page_hint(total, listed, wrap) when total > length(listed),
    do: wrap.(gettext("%{count} on this page, use ?page=N", count: length(listed)))

  def page_hint(_total, _listed, _wrap), do: ""

  @doc false
  def feed_summary(%{posts: []}, _wrap), do: gettext("Your feed is empty.")

  def feed_summary(doc, wrap) do
    gettext("%{count} posts on this page", count: length(doc.posts)) <> cursor_hint(doc, wrap)
  end

  # The feed is cursor-paginated: when older posts remain, point at the next
  # page via the signed, opaque `?cursor=` token (FeedDoc carries next_cursor).
  @doc false
  def cursor_hint(%{more: true, next_cursor: cursor}, wrap) when is_binary(cursor),
    do: wrap.(gettext("more posts available, append ?cursor=%{cursor}", cursor: cursor))

  def cursor_hint(_doc, _wrap), do: ""

  # A photo with everything the HTML page shows about it (issue #1104): the
  # picture, its caption, the camera settings when the author published them
  # and the download when the author opened it — each on its own indented line
  # so a reader (human or machine) can tell the facts apart.
  # The clip (issue #1906): one line naming the file, its length and its
  # description, under its own heading.
  defp video_line(nil), do: nil

  defp video_line(video) do
    [
      "## #{gettext("Video")}",
      "",
      "- " <>
        md_link(video.alt || gettext("Video"), video.url) <> " (#{video.duration_seconds} s)",
      "- " <> md_image(gettext("Cover"), video.cover_url)
    ]
    |> Enum.join("\n")
  end

  defp image_line(image) do
    [
      "- " <> md_image(image.alt || "image", image_url(image)),
      image[:caption] && "  #{md_text(image.caption)}",
      camera_line(image),
      image[:download_url] &&
        "  " <> md_link(gettext("Download the original"), image.download_url)
    ]
    |> Enum.reject(&is_nil/1)
    |> Enum.join("\n")
  end

  defp camera_line(image), do: camera_text(image)

  @doc """
  The camera settings of one photo as an indented line, or `nil` when the
  author did not publish them. Shared with the plain-text renderer so both
  formats say the same thing.
  """
  def camera_text(image) do
    [
      image[:camera],
      image[:lens],
      image[:focal_length_mm] && "#{image.focal_length_mm} mm",
      image[:aperture] && "f/#{image.aperture}",
      image[:shutter] && "#{image.shutter} s",
      image[:iso] && "ISO #{image.iso}"
    ]
    |> Enum.reject(&(&1 in [nil, ""]))
    |> case do
      [] -> nil
      parts -> "  " <> Enum.join(parts, " · ")
    end
  end

  # The rights line, rendered only when the author granted something — the
  # same rule the HTML page follows, so the formats cannot disagree about
  # whether a post says anything about reuse.
  defp license_line(%{spdx: spdx, name: name, url: url}) when is_binary(spdx) do
    "**#{gettext("Photos:")}** #{md_link(name, url)}"
  end

  defp license_line(_license), do: nil

  # Shared with the plain-text renderer: prefer the feed-size variant, else any.
  @doc false
  def image_url(image), do: image.urls[:feed] || image.urls |> Map.values() |> List.first()

  # A reply is a subsection of the post it answers, so the entry's heading level
  # carries its nesting depth (`###` at the top of the thread, one `#` deeper
  # per level, floored at Markdown's `######`) — the document form of the
  # indentation the HTML page draws.
  defp thread_block(entry) do
    reply_to =
      entry.in_reply_to_author &&
        "> " <> gettext("In reply to a post by %{name}.", name: entry.in_reply_to_author)

    heading = String.duplicate("#", min(3 + entry.depth, 6))

    [
      "#{heading} #{md_link(entry.author, entry.url)} · #{entry.published_on}",
      reply_to,
      entry.body_markdown
    ]
    |> Enum.reject(&is_nil/1)
    |> Enum.join("\n\n")
  end

  # A reply from another network: who wrote it, where the authoritative original
  # lives (ours is a cache and says so), and the plain text. Escaped as text
  # rather than emitted as Markdown — it is a stranger's writing, and it must
  # not be able to mint links in our document.
  defp remote_reply_block(entry) do
    [
      "### #{md_text(entry.author)} (#{md_text(entry.handle)})",
      entry.content_warning &&
        "> " <> gettext("Content warning") <> ": " <> md_text(entry.content_warning),
      md_text(entry.text),
      md_link(gettext("View the original"), entry.url)
    ]
    |> Enum.reject(&is_nil/1)
    |> Enum.join("\n\n")
  end

  # One press picture: what it is, then the lines a journalist acts on — who to
  # credit, how big the file is and where it is (#2086). The caption is the
  # member's own Markdown and passes through as it stands, indented **four**
  # columns rather than two because it hangs off a nested list item: a
  # continuation paragraph at the wrong indent breaks out of the list, which is
  # the same trap issue #926 fixed one level up.
  # One written bio (#2101): its length as a sub-heading, then the member's own
  # Markdown as a block of its own rather than a list item — this is prose meant
  # to be copied whole, and a `- ` in front of it would have to be taken back
  # out again.
  defp bio_block(bio), do: "### #{bio.label}\n\n#{bio.text}"

  # The label is a **link only while there is a file behind it** (issue #2182):
  # a picture whose download cannot be handed over carries no `download_url`,
  # the way it already carries no `size_bytes`, and an agent reading this
  # document fetches every address in it.
  defp press_picture_line(picture) do
    [
      "- " <> press_picture_label(picture),
      picture[:credit] && "  - " <> gettext("Credit: %{credit}", credit: picture.credit),
      "  - " <> press_picture_size(picture),
      picture[:png_download_url] &&
        "  - " <> md_link(gettext("PNG version"), picture.png_download_url),
      picture[:caption] && "  - " <> indent_item_body(md_text(picture.caption), "    ")
    ]
    |> Enum.reject(&is_nil/1)
    |> Enum.join("\n")
  end

  defp press_picture_label(%{download_url: url} = picture), do: md_link(picture.label, url)
  defp press_picture_label(picture), do: md_text(picture.label)

  @doc false
  # The facts that decide whether a journalist downloads a picture, from the
  # fields both renderers already hold — the doc map carries the numbers, not a
  # rendered line, so nothing in `VutuvWeb.AgentDocs` depends on a component.
  #
  # Each number names its own file (issue #2140): a raster's pixels and bytes
  # are one file's, while a vector hands over an SVG that has no pixel size and
  # offers a PNG rendering that does — so the doc map carries the second file's
  # dimensions under their own keys and this labels them. Same line the page's
  # own `PressKitComponents.facts_line/2` draws.
  def press_picture_size(picture) do
    [
      picture[:width] && picture[:height] && UI.dimensions(picture.width, picture.height),
      picture[:size_bytes] && UI.file_size(picture.size_bytes),
      picture[:png_width] && picture[:png_height] &&
        "PNG " <> UI.dimensions(picture.png_width, picture.png_height)
    ]
    |> Enum.reject(&is_nil/1)
    |> Enum.join(" · ")
  end

  defp section(_title, []), do: nil
  # A blank line between items (a "loose" CommonMark list) so every entry gets
  # the same vertical rhythm — the one a multi-paragraph entry already forces
  # anyway (issues #925/#926). Each `line` may itself be a multi-line block (a
  # code account with its nested repos, a reply with its body); those join in
  # tight internally and only the blocks are blank-line separated.
  defp section(title, lines), do: "## #{title}\n\n" <> Enum.join(lines, "\n\n")

  @doc false
  # Shared with the plain-text renderer, like the other helpers above.
  def blank_to_nil(""), do: nil
  def blank_to_nil(value), do: value

  # A `- ` list item whose content (a work/education description) runs to
  # several paragraphs: the first line rides the marker, every later line is
  # indented by `pad` (the marker width, two columns for a top-level item and
  # four for one nested inside another) so the whole thing stays one list
  # item instead of the continuation paragraphs breaking out to the left margin
  # (issue #926). Blank lines stay truly empty (no trailing spaces), and CRLF /
  # CR line endings normalize to LF so the indent lands on real line breaks.
  defp indent_item_body(text, pad \\ "  ") do
    case text
         |> String.replace("\r\n", "\n")
         |> String.replace("\r", "\n")
         |> String.split("\n") do
      [single] -> single
      [first | rest] -> Enum.join([first | Enum.map(rest, &indent_line(&1, pad))], "\n")
    end
  end

  defp indent_line("", _pad), do: ""
  defp indent_line(line, pad), do: pad <> line

  # A YAML double-quoted scalar: escape backslash and double-quote, fold
  # newlines/tabs to spaces. (inspect/1 was wrong here — it emits `\#{` for a
  # literal `#{`, which is not a legal YAML escape, and truncates at 4096.)
  defp yaml(nil), do: ~s("")

  defp yaml(value) do
    escaped =
      value
      |> to_string()
      |> String.replace("\\", "\\\\")
      |> String.replace("\"", "\\\"")
      |> String.replace(["\n", "\r", "\t"], " ")

    ~s(") <> escaped <> ~s(")
  end

  # One Markdown link, both halves escaped. A link assembled at the call site is
  # a place the next author has to remember md_text/1 and md_url/1 again, and a
  # dozen of them had already forgotten one or both: a member's own free text
  # (an employer name, a display name, a tag) closed the `]` and forged a second
  # link, and a remote server's URL closed the `)`.
  defp md_link(label, url), do: "[" <> md_label(label) <> "](" <> md_url(url) <> ")"

  # `[label](url)` for a label that may be absent a destination, which three
  # sections need: a code repository, a job that cites a credential, an employer.
  defp md_maybe_link(label, nil), do: md_text(label)
  defp md_maybe_link(label, url), do: md_link(label, url)

  # `![alt](url)`. The `!` is the only thing between an image and a link, so it
  # belongs beside the function that owns the rest of the shape.
  defp md_image(alt, url), do: "!" <> md_link(alt, url)

  # `<url>`, the other link syntax. Same reason as `md_link/2`: the angle
  # brackets were written out at four call sites and one of them had forgotten
  # the escaper.
  defp md_autolink(url), do: "<" <> md_url(url) <> ">"

  # A link label is one line by definition, so a newline in it does not merely
  # read oddly — it ends the list item the link sits in and hands the rest of a
  # member's name to the document as structure of its own. `md_text/1` cannot
  # do this for everyone: it also escapes post bodies and remote replies, where
  # a line break is the author's.
  defp md_label(value), do: value |> to_string() |> fold_lines() |> md_text()

  defp fold_lines(value), do: String.replace(value, ~r/\s*[\r\n]+\s*/u, " ")

  # Escape the Markdown link-syntax characters in user-controlled link *text*
  # (names, excerpts), so a value like `x](http://evil)` cannot break out of
  # `[text](url)` and forge a link.
  defp md_text(value) do
    value
    |> to_string()
    |> String.replace("\\", "\\\\")
    |> String.replace("[", "\\[")
    |> String.replace("]", "\\]")
  end

  # Percent-encode the characters that delimit a Markdown link *destination*
  # in a user-controlled URL, so a value like `http://x/) [evil](http://evil`
  # cannot close the `(...)` (or the `<...>` autolink) and forge a second link.
  # Real URLs survive — these chars are URL-encodable without changing meaning.
  defp md_url(value) do
    value
    |> to_string()
    |> String.replace("\\", "%5C")
    |> String.replace(" ", "%20")
    |> String.replace("\t", "%09")
    |> String.replace("\n", "%0A")
    |> String.replace("\r", "%0D")
    |> String.replace("(", "%28")
    |> String.replace(")", "%29")
    |> String.replace("<", "%3C")
    |> String.replace(">", "%3E")
    |> String.replace("\"", "%22")
  end

  defp join_blocks(blocks) do
    blocks
    |> List.flatten()
    |> Enum.filter(&(&1 not in [nil, ""]))
    |> Enum.join("\n\n")
    |> Kernel.<>("\n")
  end
end