Correct and idiomatic ways to use the <mds-bibliography> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in agents/variants.md and the shared component rules in agents/conventions.md.

Basic APA Citation (Default Format)

The default format is 'apa'. Supply author, date, name, location, and publisher to produce a correctly punctuated APA reference line. APA places the date in parentheses immediately after the author list.

<mds-bibliography
  author="Mario Rossi"
  date="2021-03-15"
  name="Fondamenti di diritto amministrativo"
  location="Milano"
  publisher="Maggioli Editore"
></mds-bibliography>

APA Citation With a Linked Title

When both name and url are provided the title renders as a hyperlink opening in a new tab. The rel prop defaults to 'external'; change it to 'author' only when the URL points to an author profile.

<mds-bibliography
  author="Mario Rossi"
  date="2021-03-15"
  name="Fondamenti di diritto amministrativo"
  location="Milano"
  publisher="Maggioli Editore"
  url="https://www.maggioli.com/catalogo/fondamenti"
></mds-bibliography>

MLA Format

Set format="mla" for Modern Language Association style. The date moves to the end, after the publisher, and author names are formatted with the full first name rather than initials.

<mds-bibliography
  format="mla"
  author="Mario Rossi"
  date="2021-03-15"
  name="Fondamenti di diritto amministrativo"
  location="Milano"
  publisher="Maggioli Editore"
></mds-bibliography>

Turabian Format

format="turabian" follows the Kate Turabian style - same field order and punctuation as MLA when a publisher is given; without a publisher, the location ends with a comma instead of a period.

<mds-bibliography
  format="turabian"
  author="Mario Rossi"
  date="2021-03-15"
  name="Fondamenti di diritto amministrativo"
  location="Milano"
  publisher="Maggioli Editore"
></mds-bibliography>

Multiple Authors

Separate multiple authors with a comma, writing each name first name first. The parser does not trim: put no space after a comma that precedes an unquoted name, or the following name breaks. Composite first or last names that contain spaces must be wrapped in single or double quotation marks so the parser groups them correctly. The component joins authors with the format-appropriate separator (APA and Turabian: &, MLA: e).

<!-- Two authors, both single-word first and last names -->
<mds-bibliography
  author="Mario Rossi,Luigi Verdi"
  date="2019-06-01"
  name="Gestione del territorio"
  publisher="Giuffre Editore"
></mds-bibliography>

<!-- Composite first name and composite last name -->
<mds-bibliography
  author="'Maria Grazia' Bianchi, Enrico 'De Luca'"
  date="2020-11-20"
  name="Appalti pubblici"
  publisher="Il Sole 24 Ore"
></mds-bibliography>

Date From a Numeric Timestamp

date accepts either an ISO date string or a numeric Unix timestamp (milliseconds as a string). The component parses both forms identically and renders the result inside a semantic <time> element.

<!-- ISO string -->
<mds-bibliography
  author="Luca Ferrari"
  date="2018-09-10"
  name="Intelligenza artificiale e diritto"
  publisher="Giuffre Editore"
></mds-bibliography>

<!-- Numeric timestamp (milliseconds) -->
<mds-bibliography
  author="Luca Ferrari"
  date="1536537600000"
  name="Intelligenza artificiale e diritto"
  publisher="Giuffre Editore"
></mds-bibliography>

Adjusting Typography

The typography prop controls the text role ('caption', 'detail' [default], 'label', 'option', 'paragraph', 'tip'). Use variant to apply a style variant inside that role. Change these when the citation must match its surrounding body copy.

<!-- Use paragraph size inside a long-form article -->
<mds-bibliography
  format="apa"
  author="Francesca Conti"
  date="2022-05-18"
  name="Sociologia del lavoro pubblico"
  publisher="Laterza"
  typography="paragraph"
  variant="read"
></mds-bibliography>

Styling Customization

Style the link color and underline through the documented --mds-bibliography-* CSS custom properties. Use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.riferimenti mds-bibliography {
  --mds-bibliography-color: rgb(var(--magma-accent-fg));
  --mds-bibliography-text-decoration: rgb(var(--magma-accent-border));
  --mds-bibliography-text-decoration-hover: rgb(var(--magma-accent-fg));
}