mkdocs.yml

site_name: Pony Tutorial
site_description: A tutorial for the Pony programming language.

copyright: Copyright © 2025 The Pony Developers
edit_uri: edit/main/docs/
repo_url: https://github.com/ponylang/pony-tutorial/
site_url: https://tutorial.ponylang.io/
use_directory_urls: false

extra:
  generator: false
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/ponylang
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/ponylang

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid-experimental
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.snippets:
      base_path: ['code-samples']
      check_paths: true
      dedent_subsections: true
  - smarty
  - toc:
      permalink: true

plugins:
  - search
  - ezlinks
  - llmstxt:
      full_output: llms-full.txt
      markdown_description: >-
        The Pony Tutorial is a comprehensive guide to the Pony programming
        language, an object-oriented, actor-model, capabilities-secure language.
        It covers the type system, reference capabilities, generics, C FFI,
        testing, and more. The target audience is programmers with some
        experience in another language.
      sections:
        Introduction:
          - index.md
        Getting Started:
          - getting-started/index.md
          - getting-started/what-you-need.md
          - getting-started/hello-world.md
          - getting-started/how-it-works.md
        Types:
          - types/index.md
          - types/at-a-glance.md
          - types/classes.md
          - types/primitives.md
          - types/actors.md
          - types/traits-and-interfaces.md
          - types/structs.md
          - types/type-aliases.md
          - types/type-expressions.md
        Expressions:
          - expressions/index.md
          - expressions/literals.md
          - expressions/variables.md
          - expressions/ops.md
          - expressions/arithmetic.md
          - expressions/control-structures.md
          - expressions/match.md
          - expressions/as.md
          - expressions/methods.md
          - expressions/errors.md
          - expressions/equality.md
          - expressions/sugar.md
          - expressions/object-literals.md
          - expressions/partial-application.md
        Reference Capabilities:
          - reference-capabilities/index.md
          - reference-capabilities/reference-capabilities.md
          - reference-capabilities/guarantees.md
          - reference-capabilities/consume-and-destructive-read.md
          - reference-capabilities/recovering-capabilities.md
          - reference-capabilities/aliasing.md
          - reference-capabilities/passing-and-sharing.md
          - reference-capabilities/capability-subtyping.md
          - reference-capabilities/combining-capabilities.md
          - reference-capabilities/arrow-types.md
          - reference-capabilities/capability-matrix.md
        Object Capabilities:
          - object-capabilities/index.md
          - object-capabilities/object-capabilities.md
          - object-capabilities/derived-authority.md
          - object-capabilities/trust-boundary.md
        Generics:
          - generics/index.md
          - generics/generics-and-reference-capabilities.md
          - generics/generic-constraints.md
        Packages:
          - packages/index.md
          - packages/use-statement.md
          - packages/standard-library.md
        Testing:
          - testing/index.md
          - testing/ponytest.md
          - testing/ponycheck.md
        C-FFI:
          - c-ffi/index.md
          - c-ffi/calling-c.md
          - c-ffi/linking-c.md
          - c-ffi/c-abi.md
          - c-ffi/callbacks.md
        Runtime Basics:
          - runtime-basics/index.md
          - runtime-basics/scheduler.md
          - runtime-basics/program-lifecycle.md
          - runtime-basics/garbage-collection.md
          - runtime-basics/asio.md
          - runtime-basics/backpressure.md
          - runtime-basics/runtime-options.md
        Gotchas:
          - gotchas/index.md
          - gotchas/divide-by-zero.md
          - gotchas/garbage-collection.md
          - gotchas/scheduling.md
          - gotchas/side-effect-ordering-in-function-call-expressions.md
          - gotchas/recursion.md
        Where Next?:
          - where-next/index.md
        Appendices:
          - appendices/index.md
          - appendices/ponypath.md
          - appendices/lexicon.md
          - appendices/symbol-lookup-cheat-sheet.md
          - appendices/keywords.md
          - appendices/examples.md
          - appendices/whitespace.md
          - appendices/compiler-args.md
          - appendices/platform-dependent-code.md
          - appendices/error-messages.md
          - appendices/annotations.md
          - appendices/serialisation.md

theme:
  name: material

  favicon: assets/logo.png

  features:
    - content.code.copy
    - content.code.select
    - navigation.footer
    - navigation.instant
    - navigation.indexes
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest

  icon:
    repo: fontawesome/brands/github

  logo: assets/logo.png

  palette:
    # Light mode
    - scheme: default
      primary: brown
      accent: amber
      toggle:
        icon: material/brightness-4
        name: Switch to dark mode

    # Dark mode
    - scheme: slate
      primary: brown
      accent: amber
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

nav:
  - Home: "index.md"
  - Getting Started:
      - Overview: "getting-started/index.md"
      - What You Need: "getting-started/what-you-need.md"
      - Hello World -- Your First Pony Program: "getting-started/hello-world.md"
      - Hello World -- How It Works: "getting-started/how-it-works.md"
  - Types:
      - Overview: "types/index.md"
      - The Pony Type System at a Glance: "types/at-a-glance.md"
      - Classes: "types/classes.md"
      - Primitives: "types/primitives.md"
      - Actors: "types/actors.md"
      - Traits and Interfaces: "types/traits-and-interfaces.md"
      - Structs: "types/structs.md"
      - Type Aliases: "types/type-aliases.md"
      - Type Expressions: "types/type-expressions.md"
  - Expressions:
      - Overview: "expressions/index.md"
      - Literals: "expressions/literals.md"
      - Variables: "expressions/variables.md"
      - Operators: "expressions/ops.md"
      - Arithmetic: "expressions/arithmetic.md"
      - Control Structures: "expressions/control-structures.md"
      - Match Expressions: "expressions/match.md"
      - As Operator: "expressions/as.md"
      - Methods: "expressions/methods.md"
      - Errors: "expressions/errors.md"
      - Equality in Pony: "expressions/equality.md"
      - Sugar: "expressions/sugar.md"
      - Object Literals: "expressions/object-literals.md"
      - Partial Application: "expressions/partial-application.md"
  - Reference Capabilities:
      - Overview: "reference-capabilities/index.md"
      - Reference Capabilities: "reference-capabilities/reference-capabilities.md"
      - Reference Capability Guarantees: "reference-capabilities/guarantees.md"
      - Consume and Destructive Read: "reference-capabilities/consume-and-destructive-read.md"
      - Recovering Capabilities: "reference-capabilities/recovering-capabilities.md"
      - Aliasing: "reference-capabilities/aliasing.md"
      - Passing and Sharing References: "reference-capabilities/passing-and-sharing.md"
      - Capability Subtyping: "reference-capabilities/capability-subtyping.md"
      - Combining Capabilities: "reference-capabilities/combining-capabilities.md"
      - Arrow Types aka Viewpoints: "reference-capabilities/arrow-types.md"
      - Reference Capability Matrix: "reference-capabilities/capability-matrix.md"
  - Object Capabilities:
      - Overview: "object-capabilities/index.md"
      - Object Capabilities: "object-capabilities/object-capabilities.md"
      - Derived Authority: "object-capabilities/derived-authority.md"
      - Trust Boundary: "object-capabilities/trust-boundary.md"
  - Generics:
      - Overview: "generics/index.md"
      - Generics and Reference Capabilities: "generics/generics-and-reference-capabilities.md"
      - Constraints: "generics/generic-constraints.md"
  - Packages:
      - Overview: "packages/index.md"
      - Use Statement: "packages/use-statement.md"
      - Standard Library: "packages/standard-library.md"
  - Testing:
      - Overview: "testing/index.md"
      - Testing with PonyTest: "testing/ponytest.md"
      - Testing with PonyCheck: "testing/ponycheck.md"
  - C-FFI:
      - Overview: "c-ffi/index.md"
      - Calling C from Pony: "c-ffi/calling-c.md"
      - Linking to C Libraries: "c-ffi/linking-c.md"
      - C ABI: "c-ffi/c-abi.md"
      - Callbacks: "c-ffi/callbacks.md"
  - Runtime Basics:
      - Overview: "runtime-basics/index.md"
      - The Scheduler: "runtime-basics/scheduler.md"
      - Program Lifecycle: "runtime-basics/program-lifecycle.md"
      - Garbage Collection: "runtime-basics/garbage-collection.md"
      - The ASIO Subsystem: "runtime-basics/asio.md"
      - Backpressure: "runtime-basics/backpressure.md"
      - Runtime Options: "runtime-basics/runtime-options.md"
  - Gotchas:
      - Overview: "gotchas/index.md"
      - Divide by Zero: "gotchas/divide-by-zero.md"
      - Garbage Collection: "gotchas/garbage-collection.md"
      - Scheduling: "gotchas/scheduling.md"
      - Function Call Side Effects: "gotchas/side-effect-ordering-in-function-call-expressions.md"
      - Recursion: "gotchas/recursion.md"
  - Where Next?:
      - Overview: "where-next/index.md"
  - Appendices:
      - Overview: "appendices/index.md"
      - PONYPATH: "appendices/ponypath.md"
      - Lexicon: "appendices/lexicon.md"
      - Symbol Lookup Cheat Sheet: "appendices/symbol-lookup-cheat-sheet.md"
      - Keywords: "appendices/keywords.md"
      - Examples: "appendices/examples.md"
      - Whitespace: "appendices/whitespace.md"
      - Compiler Arguments: "appendices/compiler-args.md"
      - Platform-dependent Code: "appendices/platform-dependent-code.md"
      - A Short Guide to Pony Error Messages: "appendices/error-messages.md"
      - Program Annotations: "appendices/annotations.md"
      - Serialisation: "appendices/serialisation.md"