mkdocs.yml

site_name: Binoc
site_description: The missing changelog for datasets — detect, classify, and render changes between dataset snapshots.
site_url: https://harvard-lil.github.io/binoc/
repo_url: https://github.com/harvard-lil/binoc
repo_name: harvard-lil/binoc
edit_uri: edit/main/docs/

docs_dir: docs
site_dir: site

theme:
  name: material
  custom_dir: docs/overrides
  features:
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - navigation.tracking
    - navigation.instant
    - content.code.copy
    - content.code.annotate
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

extra:
  status:
    in-design: in active design
  generator: false

# Site-level "in active design" banner. See ADR
# 2026-04-17-documentation_platform_and_info_design.md §7.
extra_css:
  - stylesheets/extra.css

markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.snippets
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.tasklist:
      custom_checkbox: true

plugins:
  - search
  - include-markdown
  # Renders `::: binoc` (and submodules) in authored pages from the
  # installed `binoc` package's docstrings. See ADR
  # 2026-04-17-documentation_platform_and_info_design.md §4 ("Python API" generator).
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            docstring_style: sphinx
            show_root_heading: true
            show_root_full_path: false
            show_source: false
            show_submodules: true
            members_order: source
            separate_signature: true
            show_signature_annotations: true
            signature_crossrefs: false
            merge_init_into_class: true
            docstring_section_style: list
            # Hide anything whose name starts with an underscore,
            # including __dunder__ methods. The acceptance criterion
            # is "private symbols (_foo) are not rendered".
            filters:
              - "!^_"

# Don't render the ADR template as a page; it's read raw by `just adr`.
exclude_docs: |
  adr/TEMPLATE.md

# Enforce no broken links / no orphan files at build time. See ADR §6.
strict: true

nav:
  - Home: index.md
  - Start here: start-here.md
  - Tutorial: tutorial.md
  - Examples: users/explanation/test-vectors-gallery.md
  - Browser demo: users/explanation/browser-demo.md
  - Visual replays: users/explanation/replays.md
  - For Binoc Users:
      - How-to:
          - Diff two snapshots: users/howto/diff-two-snapshots.md
          - Save and render changesets: users/howto/save-and-render-changesets.md
          - Extract changed data: users/howto/extract-changed-data.md
          - Install and use plugins: users/howto/install-and-use-plugins.md
      - Reference:
          - users/reference/index.md
          - CLI: users/reference/cli.md
          - Dataset config: users/reference/dataset-config.md
          - Performance tuning: users/reference/performance-tuning.md
          - Changeset JSON schema: users/reference/changeset-schema.md
          - Third-party plugins: users/reference/third-party-plugins.md
      - Explanation:
          - Why Binoc exists: users/explanation/why-binoc-exists.md
          - Vocabulary: users/explanation/vocabulary.md
          - Significance classification: users/explanation/significance-classification.md
          - Security and trust: users/explanation/security-and-trust.md
  - For Plugin Developers:
      - How-to:
          - Write a Python renderer: plugin-developers/howto/write-a-python-renderer.md
          - Write a Rust rule pack: plugin-developers/howto/write-a-rust-rule-pack.md
          - Publish a plugin: plugin-developers/howto/publish-a-plugin.md
          - Test a plugin with vectors: plugin-developers/howto/test-a-plugin-with-vectors.md
      - Reference:
          - Python API: plugin-developers/reference/python.md
          - Rust SDK: plugin-developers/reference/sdk.md
          - Plugin discovery: plugin-developers/reference/plugin-discovery.md
      - Explanation:
          - Architecture overview: plugin-developers/explanation/architecture.md
          - Plugin model: plugin-developers/explanation/plugin-model.md
          - IR and changesets: plugin-developers/explanation/ir-and-changesets.md
          - Artifacts and composition: plugin-developers/explanation/artifacts-and-composition.md
          - Dispatch model: plugin-developers/explanation/dispatch-model.md
          - Extract and provenance: plugin-developers/explanation/extract-and-provenance.md
          - Test vectors: plugin-developers/explanation/test-vectors.md
  - For Core Developers:
      - How-to:
          - Cut a release: core-developers/howto/cut-a-release.md
          - Contribute to binoc: core-developers/howto/contribute-to-binoc.md
          - Work on performance optimization: core-developers/howto/performance-optimization.md
          - Write and maintain docs: core-developers/howto/write-docs.md
      - Research:
          - Prior art and architecture precedents: core-developers/research/precedents.md
          - Format-aware diff tools, a field survey: core-developers/research/format-aware-diff-tools.md
          - Edit lists, edit distance, and compaction: core-developers/research/edit-list-compaction.md
          - Nurturing a plugin ecosystem under an unstable SDK: core-developers/research/plugin-ecosystem-precedents.md
          - The data.gov format landscape: core-developers/research/data-gov-inventory-analysis.md
          - Revision-prone datasets, a cross-field catalog: core-developers/research/revision-prone-datasets.md
          - Polyglot text extraction, a survey: core-developers/research/polyglot-text-extraction.md
          - CSV/plain-text table extraction (ExtracTable, Pytheas): core-developers/research/csv-table-extraction.md
      # The block below is regenerated by `just docs-adr-index` from each
      # ADR's H1 + filename. Don't hand-edit between the sentinels; add new
      # ADRs with `just adr <title>`.
      - Architectural decisions:
          # BEGIN-ADR-NAV
          - adr/README.md
          - 'Fat-binoc Distribution and the ABI Canary': adr/2026-06-30-fat_binoc_distribution_and_abi_canary.md
          - 'The Vintage Audience: a Kept Benchmark for Metadata-Over-Data Reading': adr/2026-06-22-vintage_audience_and_metadata_only_benchmark.md
          - 'Tiered Artifact Metadata: Column, Table, and a `parser_metadata_v1` Artifact': adr/2026-06-15-tiered_artifact_metadata.md
          - 'The Engine Overhaul, Told Whole: Single-Tree to Correspondence-First': adr/2026-06-15-engine_overhaul_retrospective.md
          - 'Partition Identities: a JIT, Format-Owned Capability for N↔M Correspondence (CFM-72)': adr/2026-06-15-partition_identities_jit_format_capability.md
          - 'Multi-Input Claims: Grouping Sibling Files into One Logical Dataset': adr/2026-06-15-multi_input_file_sets_and_shapefile_fusion.md
          - 'Composable Per-Artifact Writers: the Artifact Is the Rendering Unit': adr/2026-06-15-composable_per_artifact_writers.md
          - 'Typed Records: a Greenfield `tabular` Artifact and a Generic `structured_document`': adr/2026-06-14-typed_record_tabular_and_structured_document.md
          - 'Parsed Children and Decompose Boundaries (CFM-69)': adr/2026-06-14-parsed_children_and_decompose_boundaries.md
          - 'Default Markdown Is A Changelog, Not An IR Dump': adr/2026-06-14-default_markdown_changelog_policy.md
          - 'Stable ABI Tier Assessment for CFM-27b': adr/2026-06-13-stable_abi_tier_cfm_27b.md
          - 'Derive Parse-Rule Link Gating from Pair Reads': adr/2026-06-13-derived_requires_link.md
          - 'CFM-44 Measured Correspondence Performance': adr/2026-06-13-cfm_44_measured_correspondence_performance.md
          - 'Tiered Plugin Surface During Pre-1.0: In-Process Proposed Tier, ABI Stable Tier': adr/2026-06-12-tiered_plugin_surface_pre_1_0.md
          - 'Invariant and Lint Tiers: Harness, Mechanical, Agent': adr/2026-06-12-invariant_and_lint_tiers.md
          - 'Correspondence-First Engine: Two Trees, Links, and Edit-List Compaction': adr/2026-06-12-correspondence_first_engine.md
          - 'Binoc: the architecture, told as a story': adr/2026-06-12-historical_single_tree_architecture_story.md
          - 'Inline Pure-Reorder Judgment; Retire Tag-Handoff Layering': adr/2026-06-11-inline_pure_reorder_judgment.md
          - 'Declared Write-Sets on TransformerDescriptor': adr/2026-06-11-declared_write_sets_on_transformer_descriptor.md
          - 'Transformer-Initiated Recompare as a Correspondence Contract': adr/2026-06-03-transformer_initiated_recompare.md
          - 'Structured Summary Segments': adr/2026-06-03-structured-summary-segments.md
          - 'Progressive Renderer Annotations': adr/2026-06-03-progressive_renderer_annotations.md
          - 'Error Diagnostics Are Reportable Findings': adr/2026-06-03-error_diagnostics_are_reportable_findings.md
          - 'Markdown Renderer Groups Replace Significance-Map Grouping': adr/2026-06-02-renderer_groups.md
          - 'Unified Dataset Config and Identity Policy': adr/2026-06-01-unified_dataset_config_and_identity.md
          - 'Tabular Collection Artifact Model': adr/2026-06-01-tabular_collection_artifact_model.md
          - 'Single-stream gzip as an expanding comparator': adr/2026-06-01-single_stream_gzip_as_expanding_comparator.md
          - 'Optional First-Party Plugins and `binoc[all]`': adr/2026-06-01-optional_first_party_plugins.md
          - 'Example Verbosity and Plugin-Supplied Details': adr/2026-06-01-example_verbosity.md
          - 'Diagnostics Channel for Non-Fatal Warnings and Suggestions': adr/2026-06-01-diagnostics_channel.md
          - 'Rename-and-modify detection: fuzzy correlation + transformer-initiated re-dispatch': adr/rename_modify_detection.md
          - 'Documentation Platform and Information Design': adr/2026-04-17-documentation_platform_and_info_design.md
          - 'Transient Fields Are Wire-Visible; Output Stripping Is a Boundary Concern': adr/2026-04-16-transient_fields_on_wire.md
          - 'Transformer dispatch: bottom-up by default, Root for tree-wide walkers': adr/2026-04-16-transformer_scope_yagni.md
          - 'Test vector materialization: plugin trait, not a runtime plugin point': adr/2026-04-16-test_vector_materialization.md
          - 'Opportunistic ItemRef Metadata, Transformer-Hydrated for Correlation': adr/2026-04-16-opportunistic_itemref_metadata.md
          - 'Security posture and how to audit Binoc (core and plugins)': adr/2026-04-10-security_posture_and_auditing.md
          - 'Rust MSRV and dependency update policy': adr/2026-04-10-rust_msrv_and_dependency_update_policy.md
          - 'Independent release tags and published version policy': adr/2026-04-10-independent_release_tags_and_published_version_policy.md
          - 'Release Surface And Automated Publishing': adr/2026-04-08-release_surface_and_automated_publishing.md
          - 'Transformer Dispatch Refinement': adr/2026-03-20-transformer_dispatch_refinement.md
          - 'Transformer Composition and Artifact Flow': adr/2026-03-20-transformer_composition_and_artifact_flow.md
          - 'Published artifacts for cross-plugin composition': adr/2026-03-19-published_artifacts_for_cross_plugin_composition.md
          - 'Terminology': adr/2026-03-18-terminology.md
          - 'Plugin SDK, ABI Safety, and Native Plugin Loading': adr/2026-03-12-plugin_sdk_and_abi.md
          - 'Test Vector Root Defaults and Plugin Test Vectors': adr/2026-03-09-test_vector_defaults_and_plugin_vectors.md
          - 'Standard Library Boundary Policy': adr/2026-03-09-stdlib_boundary.md
          - 'Shared Test-Vector Harness for Plugins': adr/2026-03-09-plugin_test_vector_harness.md
          - 'Per-Renderer Config and Significance as a Renderer Concern': adr/2026-03-09-renderer_config.md
          - 'Output Routing and CLI UX': adr/2026-03-09-output_routing_and_cli_ux.md
          - 'Deferred Performance Optimizations': adr/2026-03-09-deferred_optimizations.md
          - '`just` as the Canonical Task Runner': adr/2026-03-06-just_as_task_runner.md
          - 'Tutorial Regeneration Is a Build Step, Not a Test': adr/2026-03-06-tutorial_regeneration_lifecycle.md
          - 'Plugin Discovery and the Rust/Python Boundary': adr/2026-03-06-plugin_discovery.md
          - 'Snapshot Testing for Test Vectors': adr/2026-03-05-snapshot_testing_for_test_vectors.md
          - 'Provenance Tracking and the Extract Chain': adr/2026-03-05-provenance_and_extract.md
          - 'Media Type Detection and Content-Aware Dispatch': adr/2026-03-05-media_type_detection.md
          - 'Full Comparison Tree and Content Hash Propagation': adr/2026-03-05-full_comparison_tree_and_content_hashes.md
          - 'Cross-Phase Data Cache in CompareContext': adr/2026-03-05-cross_phase_data_cache.md
          # END-ADR-NAV