docs: fix list rendering and filename link text for Zensical (#190)

Author: omri374

README.md

@@ -37,6 +37,7 @@ python -m spacy download en_core_web_lg # for NER
 #### From source
 
 To install the package:
+
 1. Clone the repo
 2. Install all dependencies:
 
@@ -90,6 +91,7 @@ analyzing, modeling and evaluating data and models. Specifically,
 see [data_objects.py](presidio_evaluator/data_objects.py).
 
 The standardized structure, `List[InputSample]`, can be translated into different formats:
+
 - CoNLL
   - To CoNLL:
     ```python

docs/adr/ADR-002-entity-mapping.md

@@ -18,6 +18,7 @@ The core use case is **comparing multiple models against the same dataset**. The
 the evaluation contract; models are the variable.
 
 A flat `dict[str, str]` mapping is insufficient because:
+
 - Many labels are aliases for the same concept (`FIRST_NAME`, `NAME_GIVEN`, `GIVENNAME` → `NAME`). Maintaining a hand-crafted dict for hundreds of model vocabularies is burdensome.
 - Labels exist in a hierarchy — `NAME` is a sub-type of `PERSON`. A model predicting `PERSON` on a `NAME`-annotated token is partially correct, not wrong. A flat dict cannot express this.
 - Unresolved labels need to be surfaced and triaged before evaluation; a dict silently drops or mismaps them.
@@ -76,6 +77,7 @@ By default, issues at WARNING level and above are surfaced. The user can control
 
 `get_mapped_results_dataframe()` raises `IncompleteMapping` only if `UNRESOLVED` issues remain.
 To resolve:
+
 - `mapper.map({"MY_LABEL": "CANONICAL"})` — map to a known hierarchy entity
 - `mapper.map({"MY_LABEL": None})` — suppress from evaluation entirely
 

docs/adr/ADR-003-hierarchical-evaluation.md

@@ -72,13 +72,15 @@ At each level L, for each token:
 4. The prediction is **FP** if it is non-`O` when the annotation is `O`.
 
 This means:
+
 - A token annotated at depth 2 (`PERSON`) is evaluated at L2 using the depth-2 label — any prediction of `PERSON` or a descendant (`NAME`, `TITLE`, etc.) counts as TP.
 - A token annotated at depth 3 (`TITLE`) requires the prediction to be `TITLE` or a descendant to score TP at L2; a prediction of `PERSON` (ancestor) is FP+FN.
 
 Standard precision / recall / F1 apply at each level without modification. No new metric
 definitions are needed.
 
 The levels correspond to the natural structure of `EntityHierarchy`:
+
 - **L0**: PII vs. non-PII (binary)
 - **L1**: depth-2 branch node (PERSON, LOCATION, CONTACT, …)
 - **L2**: the annotation's own depth (depth-3 for depth-3 annotations; depth-2 for depth-2 annotations)

docs/entity_hierarchy.md

@@ -11,13 +11,15 @@ If you compare these labels directly, everything looks like a mismatch — even
 Presidio Evaluator solves this with a **shared vocabulary** of canonical entity names. Every label — from any model or dataset — gets mapped to one of these canonical names before evaluation using a **two-phase process**:
 
 **Phase 1 — Identify:** each label is matched to a canonical entity through five tiers (in priority order):
+
 1. Exact match in the alias map
 2. Country-prefix strip (e.g. `GERMANY_PASSPORT_NUMBER` → `PASSPORT`)
 3. Country-prefix fallback (tries removing leading country code)
 4. Fuzzy string match (≥0.80 similarity by default)
 5. `UNRESOLVED` — flagged for manual resolution
 
 Examples:
+
 - `EMAIL`, `email_address`, `EMAILADDRESS` → all become `EMAIL_ADDRESS`
 - `B-PERSON`, `PERSON-I` → BIO tags are stripped, both become `NAME`
 - `GERMANY_PASSPORT_NUMBER` → country prefix is recognized, becomes `PASSPORT`
@@ -51,7 +53,7 @@ The **evaluation depth is data-driven**: `CanonicalMapper` computes a weighted m
 annotation labels in your results DataFrame and selects depth 2 or 3 (capped at 3). Depth 3 is the most
 common outcome when a dataset uses fine-grained entity types like `EMAIL_ADDRESS`, `NAME`, or `SSN`.
 
-For more on why this approach was chosen over alternatives, see [why_canonical_entity_mapping.md](why_canonical_entity_mapping.md).
+For more on why this approach was chosen over alternatives, see [Why canonical entity mapping](why_canonical_entity_mapping.md).
 
 ## Typical workflow
 

docs/mapping_scenarios.md

@@ -111,6 +111,7 @@ The same string alias appears under multiple canonical entities in the hierarchy
 | `MRN` / `MEDICAL_RECORD_NUMBER` | `PHI → MRN` | alias of `PATIENT_ID` | Same concept, two canonical targets |
 
 **Issue types produced:**
+
 - `COLLISION_CROSS_BRANCH` (WARNING) — blocking. Raised when a label resolves to a canonical entity that has co-occurring labels on the same tokens mapping to a different hierarchy branch. Must be resolved with `map()` before extracting results.
 - `COLLISION_AMBIGUOUS` (WARNING) — blocking. Raised when a depth-2 ancestor maps to multiple depth-3 entities on the canonical surface (the top co-occurring candidate is shown in `overlap_counts`). Use `map({'LABEL': 'CANONICAL'})` to pick the right one.
 
@@ -131,6 +132,7 @@ The model finds PII types the dataset creators never labeled — every detection
 **Real example (Notebook 5):** After mapping, several Presidio predictions had no dataset counterpart.
 
 **Issue type produced:** `PREDICTION_ONLY` (WARNING) — blocking. These labels inflate precision with false positives. You have three resolution options:
+
 1. **Suppress** — `mapper.map({'CREDIT_CARD': None})` excludes the label from evaluation entirely
 2. **Remap** — `mapper.map({'CREDIT_CARD': 'FINANCIAL'})` counts detections against the `FINANCIAL` annotation set
 3. **Keep as FP** — if you want these counted as false positives deliberately, this isn't directly supported; suppression is the recommended path

docs/why_canonical_entity_mapping.md

@@ -1,6 +1,6 @@
 # Why canonical entity mapping?
 
-This document explains the design decisions behind the canonical entity mapping approach used in Presidio Evaluator. For the taxonomy structure and usage guide, see [entity_hierarchy.md](entity_hierarchy.md).
+This document explains the design decisions behind the canonical entity mapping approach used in Presidio Evaluator. For the taxonomy structure and usage guide, see [Entity hierarchy](entity_hierarchy.md).
 
 ## Approaches to entity label mapping