mkdocs.yml

site_name: Simplicity
site_url: https://docs.simplicity-lang.org/
site_description: A typed, combinator-based, smart contract language for Bitcoin-like blockchains.
plugins:
  - search:
  - git-revision-date-localized:
  - llms-source:
  - blog:
      blog_dir: news
  - git-committers:
      repository: BlockstreamResearch/simplicity-lang-org
      branch: main
theme:
  name: material
  custom_dir: overrides
  favicon: assets/logo-symbol.svg
  logo: assets/logo-symbol.svg
  features:
    - announce.dismiss
    - content.action.edit
    - content.code.annotate
    - content.code.copy
    - content.code.select
#   - content.footnote.tooltips
    - content.tooltips
    - navigation.expand
    - navigation.footer
    - navigation.indexes
    - navigation.instant
    - navigation.prefetch
    - navigation.sections
    - navigation.tabs
    - navigation.top
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: black # fallback, overridden by CSS
      accent: orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: orange
      toggle:
        icon: material/brightness-4
        name: Switch to system preference
markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - md_in_html:
  - attr_list:
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite:
  - pymdownx.snippets:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: youtube
          class: youtube
          format: !!python/name:pymdownx.superfences.fence_code_format
  - admonition:
  - pymdownx.details:
  - pymdownx.tabbed:
      alternate_style: true
  - tables:
  - def_list:

extra_css:
  - stylesheets/extra.css

  - stylesheets/runnable.css
extra_javascript:
  - javascript/webmcp.js
  - javascript/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  - javascript/simplicity-embed.js
    #  - https://polyfill.io/v3/polyfill.min.js?features=es6
    #  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
  - path: javascripts/runnable.js
    type: module
extra:
  generator: false
  annotate:
    # Lets a `# (1)!`-style annotation marker land in its own Comment.Special
    # (`.cs`) token, separate from preceding comment prose on the same line,
    # without Material's default `.c, .c1, .cm` annotation selector missing
    # it. See `hooks/simplicityhl_lexer.py` for why the split is needed.
    simplicityhl: [.cs]
  social:
    - icon: simple/youtube
      link: https://www.youtube.com/@Blockstream/search?query=simplicity
    - icon: simple/telegram
      link: https://t.me/simplicity_community
    - icon: fontawesome/brands/github
      link: https://github.com/BlockstreamResearch/simplicity
    - icon: fontawesome/brands/rust
      link: https://crates.io/crates/simplicity
    - icon: material/chat 
      link: https://matrix.to/#/#libera_##simplicity:bitcoin.ninja
    - icon: material/chat
      link: irc://irc.libera.chat/simplicity
  analytics:
    provider: google
    property: G-CPMC9XLPYJ
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: >-


            Thanks for your feedback! Help us improve this page by
            logging a documentation <a href="https://github.com/BlockstreamResearch/simplicity-lang-org/issues/new?body=I%20would%20like%20to%20improve%20the%20Simplicity%20documentation%20&labels=documentation&title=documentation%20fix:%20" target="_blank" rel="noopener">issue</a>.

copyright: Copyright &copy; 2026 Blockstream

repo_url: https://github.com/BlockstreamResearch/simplicity-lang-org
repo_name: "" # Hides the GitHub link/icon from title bar while keeping edit functionality
edit_uri: edit/main/docs/

hooks:
  - hooks/simplicityhl_lexer.py
  - hooks/runnable.py
  - includes/hooks/autolink_glossary.py

nav:
  - Get Started:
      - Try it in your browser: getting-started/try-it.md
      - Quickstart: getting-started/quickstart.md
      - Simplicity SDK (Simplex): documentation/simplex.md
  - Learn:
      - Core Concepts:
          - Execution Model: documentation/execution-model.md
          - Covenants & State Management: documentation/state.md
          - Constraining Destinations: documentation/destinations.md
          - Witnesses: documentation/witness.md
          - Oracles: documentation/oracle.md
          - Timelocks: documentation/timelocks.md
      - App Development:
          - Simplicity SDK (Simplex): documentation/simplex.md
          - Modules and Imports: documentation/modules.md
          - Ecosystem & Wallet Integration: documentation/wallet.md
          - txmanifest: documentation/txmanifest.md
      - Examples & Use Cases:
          - Use Cases Overview: use-cases/index.md
          - Example Contracts (Basic): https://github.com/BlockstreamResearch/SimplicityHL/tree/master/examples
          - Example Contracts (Advanced): https://github.com/BlockstreamResearch/simplicity-contracts
          - Simplicity DEX: use-cases/simplicity-dex.md
          - Lending Protocol: use-cases/lending-protocol.md
  - Reference:
      - Language Syntax:
          - Introduction: simplicityhl-reference/index.md
          - Types and Values: simplicityhl-reference/type.md
          - Type Aliases: simplicityhl-reference/type_alias.md
          - Type Casting: simplicityhl-reference/type_casting.md
          - Let Statements: simplicityhl-reference/let_statement.md
          - Match Expression: simplicityhl-reference/match_expression.md
          - Defining Functions: simplicityhl-reference/function.md
          - Modules and Imports Reference: simplicityhl-reference/modules.md
          - Programs: simplicityhl-reference/program.md
      - Libraries & Tooling:
          - Built-in Functions: simplicityhl-reference/builtin.md
          - Jets Reference: documentation/jets.md
          - Standard Library Reference: documentation/stdlib.md
          - .wit File Reference: documentation/witness-format.md
          - Toolchain Reference: documentation/toolchain.md
      - Formal Semantics:
          - Context: simplicityhl-reference/context.md
          - Environment: simplicityhl-reference/environment.md
          - Translation: simplicityhl-reference/translation.md
#      - Runnable tutorial example:
#        - tutorial/index.md
#        - Your first program: tutorial/your-first-program.md
#        - Reading data from an input: tutorial/reading-transaction-data.md
  - Resources:
      - Weekly Office Hours call: office-hours.md
      - Simplicity Telegram group: https://t.me/simplicity_community
      - Community forum: https://community.simplicity-lang.org/
      - FAQ: resources/faq.md
      - Glossary: glossary.md
      - Simplicity for EVM Developers: documentation/simplicity-for-evm-developers.md
      - Differences from Rust: documentation/rust-differences.md
      - Simplicity Compared: documentation/simplicity-compared.md
      - Codespace (run examples online): https://github.com/codespaces/new/blockstream/simplicity-codespace
      - Roadmap:
          - Roadmap Overview: resources/roadmap.md
          - Ecosystem/Wallet Connect Roadmap: documentation/road-to-ecosystem.md
      - Projects: resources/projects.md
      - Whitepaper: https://blockstream.com/simplicity.pdf
      - Technical Report: https://raw.githubusercontent.com/ElementsProject/simplicity/pdf/Simplicity-TR.pdf
  - Community: https://community.simplicity-lang.org/