Pola referensi dan badan catatan kaki melalui Connect

Sekilas

Render referensi catatan kaki dan badan catatan kaki melalui Connect agar pohon struktur memuat peran catatan kaki PDF 2.0. Penanda inline dipetakan menjadi referensi footnote/endnote, sedangkan teks catatan kaki menjadi badan catatan, dengan referensi balik dua arah di antara keduanya. Tiga bentuk HTML menghasilkan keluaran yang sama: tautan dalam superscript, peran Accessible Rich Internet Applications (ARIA) eksplisit role="doc-noteref", dan kontainer badan <aside class="footnote">. Verifikasi dilakukan menggunakan alat aksesibilitas tingkat Pro. NextPDF menemukan alat tersebut dengan class_exists() dan hanya mendaftarkannya saat nextpdf/premium terpasang bersama server.

Status lulus dari alat aksesibilitas merupakan pemeriksaan aksesibilitas, bukan sertifikasi kesesuaian independen.

Pemasangan

composer require nextpdf/server

Pastikan alat aksesibilitas Pro tersedia melalui panggilan tools/list; lihat /connect/tool-catalog/.

Tinjauan konseptual

PDF 2.0 mendefinisikan tipe struktur footnote/endnote khusus serta hubungan antara referensi dan badannya (PDF/UA-2 §8.2.5). Referensi catatan kaki harus dikaitkan dengan badannya (PDF/UA-2 §8.2.5), sehingga pembaca layar dapat mengumumkan referensi tersebut dan mengikuti tautannya untuk membaca catatan itu. Referensi dan badan sama-sama harus dapat dijangkau melalui pohon struktur (PDF/UA-2 §8.2.4).

Pipeline mengenali tiga bentuk referensi:

<sup><a href="#fn-N">N</a></sup> — bentuk singkat berupa tautan dalam superscript.
<sup role="doc-noteref" aria-describedby="fn-N">N</sup> — peran eksplisit Digital Publishing Accessible Rich Internet Applications (DPUB-ARIA); aria-describedby diteruskan sebagai target referensi balik.
<aside class="footnote" id="fn-N">…</aside> (atau role="doc-footnote") — kontainer badan catatan, yang dihasilkan sebagai badan catatan dengan referensi internal kembali ke referensi yang cocok.

Permukaan API

Verifikasi nama alat terhadap registry yang sedang berjalan dengan tools/list. Katalog resmi ada di /connect/tool-catalog/. Resep ini menggunakan alat dokumen dan HTML inti beserta pemeriksaan aksesibilitas Pro, tanpa menyatakan ulang jumlah alat.

Contoh kode — Mulai cepat

Buat dokumen bertag dengan bahasa yang sudah ditetapkan, lalu tambahkan referensi bentuk singkat berupa tautan:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Footnote Patterns", "language": "en" }
  }
}

Contoh kode — Produksi

Hasilkan kedua referensi dan kedua badan dalam satu operasi penambahan HTML, lalu jalankan pemeriksaannya:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<p>Revenue grew 24%<sup><a href=\"#fn-1\">1</a></sup>.</p><p>Margin 33%<sup role=\"doc-noteref\" aria-describedby=\"fn-2\">2</sup>.</p><aside class=\"footnote\" id=\"fn-1\"><p>YoY vs prior year.</p></aside><aside class=\"footnote\" id=\"fn-2\" role=\"doc-footnote\"><p>(Revenue − OpEx) / Revenue.</p></aside>"
    }
  }
}

Pemeriksaan aksesibilitas melaporkan pasangan peran reference/body serta referensi balik dua arah.

Kasus tepi & jebakan

Referensi tanpa badan (atau badan tanpa referensi) akan dilaporkan oleh pemeriksaan; setiap referensi memerlukan badan yang cocok dan sebaliknya.
Ketidakcocokan id antara aria-describedby dan id badan membuat pasangan tersebut tidak terselesaikan (bersifat peka huruf besar-kecil).
Jangkar superscript yang mengarah ke URL eksternal menghasilkan tautan biasa, bukan referensi catatan kaki; gunakan peran eksplisit untuk target eksternal.
<aside> polos tanpa class/role diperlakukan sebagai landmark, bukan badan catatan. Tambahkan class="footnote" atau role="doc-footnote".
Alat tidak tersedia. Tanpa nextpdf/premium, alat aksesibilitas Pro tidak terdaftar, sehingga verifikasi gagal dengan galat alat tidak dikenal.

Kinerja

Anggaran pada frontmatter adalah batas dokumentasi; perakitan catatan kaki merupakan bagian dari proses struktur normal.

Catatan keamanan

Tidak ada ketentuan khusus di luar panduan transport Connect umum.

Kesesuaian

Pemetaan PDF/UA-2

Klaim	Klausa	reference_id
Tipe struktur footnote/endnote dan hubungan reference/body	PDF/UA-2 §8.2.5
Referensi catatan kaki dikaitkan dengan badannya	PDF/UA-2 §8.2.5
Referensi dan badan dapat dijangkau melalui pohon struktur	PDF/UA-2 §8.2.4

Referensi silang Tag → ISO 32000-2 §14.9

Referensi dan badan menggunakan tipe struktur standar footnote/endnote PDF 2.0. Referensi balik dua arah adalah kontrak catatan kaki yang aksesibel.

Pemetaan WCAG 2.2

Referensi catatan kaki dan badan terkait mendukung Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) dan SC 2.4.1 (Bypass Blocks) pada tingkat konten.

Status lulus dari alat aksesibilitas merupakan pemeriksaan aksesibilitas, bukan sertifikasi kesesuaian; kesesuaian tetap ditentukan oleh pemeriksa independen.

Konteks komersial

Alat pemeriksaan aksesibilitas berada pada tingkat Pro dan hanya terdaftar saat nextpdf/premium terpasang bersama server.

Hal khusus Connect

Ketersediaan transport (MCP / REST / gRPC)

create_pdf, add_html, dan pemeriksaan aksesibilitas dipanggil dengan cara yang sama melalui Model Context Protocol (MCP), REST, dan gRPC menggunakan eksekutor alat bersama.

Tingkat risiko HITL

Pembuatan dokumen dan ingesti HTML berada pada tingkat hati-hati; pemeriksaan aksesibilitas bersifat hanya baca. Tidak ada yang secara baku approval_required. Lihat /connect/hitl-risk-tiers/.

Amplop JSON gerbang konfirmasi

Alat-alat ini tidak memicu gerbang kecuali override oleh operator menaikkan salah satunya menjadi approval_required. Kontrak amplop dan token sekali-pakai ada di /connect/hitl-risk-tiers/.

Lihat juga

/cookbook/connect/aria-tagged-pdf/ — pemetaan peran landmark.
/cookbook/connect/figure-caption/ — struktur Figure / Caption bersarang.
/connect/tool-catalog/ — perhitungan set alat per tingkat.
/connect/hitl-risk-tiers/ — model risiko dan gerbangnya.