zensical.toml

# ============================================================================
#
# The configuration produced by default is meant to highlight the features
# that Zensical provides and to serve as a starting point for your own
# projects.
#
# ============================================================================

[project]
docs_dir = "docs/content"
site_dir = "target/book"
site_name = "Martin Tile Server Documentation"
site_description = "Martin is a fast tile server that serves vector and raster tiles from PostGIS, PMTiles, MBTiles, COG, GeoJSON and DuckDB, along with sprites, fonts and styles."
repo_url = "https://github.com/maplibre/martin"
edit_uri = "edit/main/docs/content"
site_url = "https://maplibre.org/martin/"
site_author = "Maplibre Contributors"
copyright = "Copyright © 2026 MapLibre Contributors"

# Zensical supports both implicit navigation and explicitly defined navigation.
# If you decide not to define a navigation here then Zensical will simply
# derive the navigation structure from the directory structure of your
# "docs_dir". The definition below demonstrates how a navigation structure
# can be defined using TOML syntax.
#
# Read more: https://zensical.org/docs/setup/navigation/
nav = [
  { "Introduction" = "index.md" },
  { "Quick Start" = [
    "quick-start/index.md",
    {"On Linux" = "quick-start-linux.md"},
    {"On macOS" = "quick-start-macos.md"},
    {"On Windows" = "quick-start-windows.md"},
    {"View with QGIS" = "quick-start-qgis.md"}
  ]},
  {"Installation" = "installation.md"},
  {"Running" = [
    "run/index.md",
    {"Command Line Interface" = "run-with-cli.md"},
    {"Environment Variables" = "env-vars.md"},
    {"Hosting Environment-specific Guides" = [
        {"Docker" = "run-with-docker.md"},
        {"Docker Compose" = "run-with-docker-compose.md"},
        {"AWS Lambda" = "run-with-lambda.md"}
    ]},
    {"Reverse Proxies" = [
        "run-with-reverse-proxy/index.md",
        {"NGINX" = "run-with-nginx.md"},
        {"Apache" = "run-with-apache.md"}
    ]},
    {"Troubleshooting" = "troubleshooting.md"}
  ]},
  {"Configuration File" = [
    "config-file/index.md",
    {"Tile sources" = [
        "sources-tiles/index.md",
        {"MBTiles and PMTiles File Sources" = [
            "sources-files/index.md",
            {"MBTiles File Sources" = "sources-mbtiles.md"},
            {"PMTiles File Sources" = "sources-pmtiles.md"}
        ]},
        {"PostgreSQL Connections" = [
            "pg-connections/index.md",
            {"PostgreSQL Table Sources" = "sources-pg-tables.md"},
            {"PostgreSQL Function Sources" = "sources-pg-functions.md"}
        ]},
        {"Cloud Optimized GeoTIFF File Sources" = "sources-cog-files.md"},
        {"GeoJSON Sources" = "sources-geojson.md"},
        {"DuckDB Sources" = "sources-duckdb.md"},
        {"Passthrough Sources" = "sources-passthrough.md"}
    ]},
    {"Tile Serving" = [
        {"Composite Sources" = "sources-composite.md"},
        {"Tile Grids" = "tile-grids.md"}
    ]},
    {"Postprocessing" = [
        "postprocessing/index.md",
        {"MVT/MLT Conversion" = "postprocessing/mlt.md"},
        {"Hillshade" = "postprocessing/hillshade.md"},
        {"Contours" = "postprocessing/contour.md"}
    ]},
    {"Supporting Resources" = [
        {"Sprites" = "sources-sprites.md"},
        {"Styles" = [
            "sources-styles/index.md",
            {"Server-side raster tile rendering" = "sources-styles/rendering.md"}
        ]},
        {"Fonts" = "sources-fonts.md"}
    ]}
  ]},
  {"Available API Endpoints" = "using.md"},
  {"Guides" = [
    "using-guides/index.md",
    {"Self-hosting a basemap from scratch" = "recipe-basemap-selfhosted.md"},
    {"Map renderer specific" = [
        "using-with-renderer/index.md",
        {"MapLibre" = "using-with-maplibre.md"},
        {"Leaflet" = "using-with-leaflet.md"},
        {"deck.gl" = "using-with-deck-gl.md"},
        {"Mapbox" = "using-with-mapbox.md"},
        {"OpenLayers" = "using-with-openlayers.md"}
    ]},
    {"Tile source specific" = [
        "using-with-data/index.md",
        {"Using Hosted PostgreSQL" = "recipes.md"},
        {"Setting up a basemap and overlaying data" = "recipe-basemap-postgis.md"},
        {"Using PostgreSQL with SSL Certificates" = "pg-ssl-certificates.md"}
    ]},
    {"Bulk Tile Generation" = "martin-cp.md"},
    {"Working with MBTiles archives" = [
        "mbtiles/index.md",
        {"MBTiles Schemas" = "mbtiles-schema.md"},
        {"Accessing Metadata" = "mbtiles-meta.md"},
        {"Copying MBTiles" = "mbtiles-copy.md"},
        {"Diffing/Patching MBTiles" = "mbtiles-diff.md"},
        {"Validating MBTiles" = "mbtiles-validation.md"}
    ]}
  ]},
  {"Development" = [
    "development/index.md",
    {"Getting involved" = "getting-involved.md"},
    {"Provided Tools" = "tools.md"},
    {"Martin as a library" = "martin-as-a-library.md"},
    {"Architecture" = "architecture.md"}
  ]},
  {"Migration Guide" = "migration-guide.md"},
  {"Changelog" = "changelog.md"}
]

# With the "extra_css" option you can add your own CSS styling to customize
# your Zensical project according to your needs. You can add any number of
# CSS files.
#
# The path provided should be relative to the "docs_dir".
#
# Read more: https://zensical.org/docs/customization/#additional-css
#
#extra_css = ["stylesheets/extra.css"]

# With the `extra_javascript` option you can add your own JavaScript to your
# project to customize the behavior according to your needs.
#
# The path provided should be relative to the "docs_dir".
#
# Read more: https://zensical.org/docs/customization/#additional-javascript
extra_javascript = ["javascripts/keys.js"]

# ----------------------------------------------------------------------------
# Section for configuring theme options
# ----------------------------------------------------------------------------
[project.theme]

# Zensical allows you to override specific blocks, partials, or whole
# templates as well as to define your own templates. To do this, uncomment
# the custom_dir setting below and set it to a directory in which you
# keep your template overrides.
#
# Read more:
# - https://zensical.org/docs/customization/#extending-the-theme
#
custom_dir = "docs/overrides"
favicon = "images/favicon.ico"
logo = "images/logo.svg"

# Zensical supports more than 60 different languages. This means that the
# labels and tooltips that Zensical's templates produce are translated.
# The "language" option allows you to set the language used. This language
# is also indicated in the HTML head element to help with accessibility
# and guide search engines and translation tools.
#
# The default language is "en" (English). It is possible to create
# sites with multiple languages and configure a language selector. See
# the documentation for details.
#
# Read more:
# - https://zensical.org/docs/setup/language/
#
language = "en"

# Zensical provides a number of feature toggles that change the behavior
# of the documentation site.
features = [
    # Zensical includes an announcement bar. This feature allows users to
    # dismiss it when they have read the announcement.
    # https://zensical.org/docs/setup/header/#announcement-bar
    "announce.dismiss",

    # If you have a repository configured and turn on this feature, Zensical
    # will generate an edit button for the page. This works for common
    # repository hosting services.
    # https://zensical.org/docs/setup/repository/#content-actions
    "content.action.edit",

    # If you have a repository configured and turn on this feature, Zensical
    # will generate a button that allows the user to view the Markdown
    # code for the current page.
    # https://zensical.org/docs/setup/repository/#content-actions
    #"content.action.view",

    # Code annotations allow you to add an icon with a tooltip to your
    # code blocks to provide explanations at crucial points.
    # https://zensical.org/docs/authoring/code-blocks/#code-annotations
    "content.code.annotate",

    # This feature turns on a button in code blocks that allow users to
    # copy the content to their clipboard without first selecting it.
    # https://zensical.org/docs/authoring/code-blocks/#code-copy-button
    "content.code.copy",

    # Code blocks can include a button to allow for the selection of line
    # ranges by the user.
    # https://zensical.org/docs/authoring/code-blocks/#code-selection-button
    "content.code.select",

    # Zensical can render footnotes as inline tooltips, so the user can read
    # the footnote without leaving the context of the document.
    # https://zensical.org/docs/authoring/footnotes/#footnote-tooltips
    "content.footnote.tooltips",

    # If you have many content tabs that have the same titles (e.g., "Python",
    # "JavaScript", "Cobol"), this feature causes all of them to switch to
    # at the same time when the user chooses their language in one.
    # https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs
    "content.tabs.link",

    # With this feature enabled users can add tooltips to links that will be
    # displayed when the mouse pointer hovers the link.
    # https://zensical.org/docs/authoring/tooltips/#improved-tooltips
    "content.tooltips",

    # With this feature enabled, Zensical will automatically hide parts
    # of the header when the user scrolls past a certain point.
    # https://zensical.org/docs/setup/header/#automatic-hiding
    "header.autohide",

    # Turn on this feature to expand all collapsible sections in the
    # navigation sidebar by default.
    # https://zensical.org/docs/setup/navigation/#navigation-expansion
    "navigation.expand",

    # This feature turns on navigation elements in the footer that allow the
    # user to navigate to a next or previous page.
    # https://zensical.org/docs/setup/footer/#navigation
    "navigation.footer",

    # When section index pages are enabled, documents can be directly attached
    # to sections, which is particularly useful for providing overview pages.
    # https://zensical.org/docs/setup/navigation/#section-index-pages
    "navigation.indexes",

    # When instant navigation is enabled, clicks on all internal links will be
    # intercepted and dispatched via XHR without fully reloading the page.
    # https://zensical.org/docs/setup/navigation/#instant-navigation
    "navigation.instant",

    # With instant prefetching, your site will start to fetch a page once the
    # user hovers over a link. This will reduce the perceived loading time
    # for the user.
    # https://zensical.org/docs/setup/navigation/#instant-prefetching
    "navigation.instant.prefetch",

    # In order to provide a better user experience on slow connections when
    # using instant navigation, a progress indicator can be enabled.
    # https://zensical.org/docs/setup/navigation/#progress-indicator
    "navigation.instant.progress",

    # When navigation paths are activated, a breadcrumb navigation is rendered
    # above the title of each page
    # https://zensical.org/docs/setup/navigation/#navigation-path
    "navigation.path",

    # When pruning is enabled, only the visible navigation items are included
    # in the rendered HTML, reducing the size of the built site by 33% or more.
    # https://zensical.org/docs/setup/navigation/#navigation-pruning
    "navigation.prune",

    # When sections are enabled, top-level sections are rendered as groups in
    # the sidebar for viewports above 1220px, but remain as-is on mobile.
    # https://zensical.org/docs/setup/navigation/#navigation-sections
    "navigation.sections",

    # When tabs are enabled, top-level sections are rendered in a menu layer
    # below the header for viewports above 1220px, but remain as-is on mobile.
    # https://zensical.org/docs/setup/navigation/#navigation-tabs
    "navigation.tabs",

    # When sticky tabs are enabled, navigation tabs will lock below the header
    # and always remain visible when scrolling down.
    # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs
    "navigation.tabs.sticky",

    # A back-to-top button can be shown when the user, after scrolling down,
    # starts to scroll up again.
    # https://zensical.org/docs/setup/navigation/#back-to-top-button
    "navigation.top",

    # When anchor tracking is enabled, the URL in the address bar is
    # automatically updated with the active anchor as highlighted in the table
    # of contents.
    # https://zensical.org/docs/setup/navigation/#anchor-tracking
    "navigation.tracking",

    # When search highlighting is enabled and a user clicks on a search result,
    # Zensical will highlight all occurrences after following the link.
    # https://zensical.org/docs/setup/search/#search-highlighting
    "search.highlight",

    # When anchor following for the table of contents is enabled, the sidebar
    # is automatically scrolled so that the active anchor is always visible.
    # https://zensical.org/docs/setup/navigation/#anchor-following
    "toc.follow",

    # When navigation integration for the table of contents is enabled, it is
    # always rendered as part of the navigation sidebar on the left.
    # https://zensical.org/docs/setup/navigation/#navigation-integration
    "toc.integrate",
]

# ----------------------------------------------------------------------------
# In the "palette" subsection you can configure options for the color scheme.
# You can configure different color # schemes, e.g., to turn on dark mode,
# that the user can switch between. Each color scheme can be further
# customized.
#
# Read more:
# - https://zensical.org/docs/setup/colors/
# ----------------------------------------------------------------------------
[[project.theme.palette]]
media = "(prefers-color-scheme)"
toggle.icon = "lucide/sun-moon"
toggle.name = "Switch to light mode"

[[project.theme.palette]]
media = "(prefers-color-scheme: light)"
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"
primary = "deep purple"
accent = "purple"

[[project.theme.palette]]
media = "(prefers-color-scheme: dark)"
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to system preference"
primary = "deep purple"
accent = "pink"

# ----------------------------------------------------------------------------
# In the "font" subsection you can configure the fonts used. By default, fonts
# are loaded from Google Fonts, giving you a wide range of choices from a set
# of suitably licensed fonts. There are options for a normal text font and for
# a monospaced font used in code blocks.
# ----------------------------------------------------------------------------
#[project.theme.font]
#text = "Inter"
#code = "Jetbrains Mono"

# ----------------------------------------------------------------------------
# You can configure your own logo to be shown in the header using the "logo"
# option in the "icons" subsection. The logo can be a path to a file in your
# "docs_dir" or it can be a path to an icon.
#
# Likewise, you can customize the logo used for the repository section of the
# header. Zensical derives the default logo for this from the repository URL.
# See below...
#
# There are other icons you can customize. See the documentation for details.
#
# Read more:
# - https://zensical.org/docs/setup/logo-and-icons
# - https://zensical.org/docs/authoring/icons-emojis/#search
# ----------------------------------------------------------------------------
[project.theme.icon.admonition]
note = "octicons/tag-16"
abstract = "octicons/checklist-16"
info = "octicons/info-16"
tip = "octicons/squirrel-16"
success = "octicons/check-16"
question = "octicons/question-16"
warning = "octicons/alert-16"
failure = "octicons/x-circle-16"
danger = "octicons/zap-16"
bug = "octicons/bug-16"
example = "octicons/beaker-16"
quote = "octicons/quote-16"

# https://zensical.org/docs/setup/social-cards/
[project.plugins.social]
cards_layout_options.background_color = "#ffffff"
cards_layout_options.color = "#3f3576"

[project.plugins.llmstxt]
full_output = "llms-full.txt"
markdown_description = """
Martin is a tile server and a set of tools able to generate vector tiles on the fly from large
PostgreSQL databases, and serve tiles from PMTiles, MBTiles, Cloud Optimized GeoTIFF, GeoJSON and
DuckDB files. It can combine multiple tile sources into one, and also serves sprites, fonts and
MapLibre styles. It is written in Rust and optimized for speed and heavy traffic.
The `martin-cp` tool generates tiles in bulk, and the `mbtiles` tool inspects, copies, diffs,
patches and validates MBTiles archives.
"""

[project.plugins.llmstxt.sections]
"Getting Started" = [
  { "index.md" = "What Martin is and what it can do" },
  { "quick-start/index.md" = "Choosing a quick start guide" },
  { "quick-start-linux.md" = "Serving a first tileset on Linux" },
  { "quick-start-macos.md" = "Serving a first tileset on macOS" },
  { "quick-start-windows.md" = "Serving a first tileset on Windows" },
  { "quick-start-qgis.md" = "Viewing Martin tiles in QGIS" },
  { "installation.md" = "Installing Martin from binaries, package managers, Docker or source" },
]
Running = [
  { "run/index.md" = "How Martin discovers sources from the command line and configuration file" },
  { "run-with-cli.md" = "Command line arguments and options" },
  { "env-vars.md" = "Environment variables understood by Martin" },
  { "run-with-docker.md" = "Running Martin in Docker" },
  { "run-with-docker-compose.md" = "Running Martin and PostGIS with Docker Compose" },
  { "run-with-lambda.md" = "Running Martin on AWS Lambda" },
  { "run-with-reverse-proxy/index.md" = "Putting Martin behind a reverse proxy" },
  { "run-with-nginx.md" = "NGINX reverse proxy and caching setup" },
  { "run-with-apache.md" = "Apache reverse proxy setup" },
  { "troubleshooting.md" = "Diagnosing common problems" },
]
Configuration = [
  { "config-file/index.md" = "The configuration file format and global options" },
  { "sources-tiles/index.md" = "Overview of the supported tile sources" },
  { "sources-files/index.md" = "Serving tiles from MBTiles and PMTiles files" },
  { "sources-mbtiles.md" = "MBTiles file source options" },
  { "sources-pmtiles.md" = "PMTiles file source options, including remote and S3 archives" },
  { "pg-connections/index.md" = "PostgreSQL connection settings and auto-publishing" },
  { "sources-pg-tables.md" = "Serving PostGIS tables and views as vector tiles" },
  { "sources-pg-functions.md" = "Serving tiles generated by PostgreSQL functions" },
  { "sources-cog-files.md" = "Serving raster tiles from Cloud Optimized GeoTIFF files" },
  { "sources-geojson.md" = "Serving GeoJSON files as vector tiles" },
  { "sources-duckdb.md" = "Serving tiles from DuckDB databases and GeoParquet files" },
  { "sources-passthrough.md" = "Proxying tiles from an upstream HTTP tile server" },
  { "sources-composite.md" = "Combining multiple sources into one tile" },
  { "tile-grids.md" = "Tile grids and tile matrix sets" },
  { "postprocessing/index.md" = "Transforming tiles after they are read from a source" },
  { "postprocessing/mlt.md" = "Converting between MVT and MapLibre Tiles (MLT)" },
  { "postprocessing/hillshade.md" = "Generating hillshade tiles from elevation data" },
  { "postprocessing/contour.md" = "Generating contour lines from elevation data" },
  { "sources-sprites.md" = "Serving sprites generated from SVG icons" },
  { "sources-styles/index.md" = "Serving MapLibre styles" },
  { "sources-styles/rendering.md" = "Rendering styles to raster tiles on the server" },
  { "sources-fonts.md" = "Serving font glyphs generated from font files" },
]
"API and Usage" = [
  { "using.md" = "HTTP API endpoints served by Martin" },
  { "using-guides/index.md" = "Overview of the available guides" },
  { "recipe-basemap-selfhosted.md" = "Self-hosting a fully styled basemap from scratch" },
  { "using-with-renderer/index.md" = "Using Martin with map renderers" },
  { "using-with-maplibre.md" = "Displaying Martin tiles with MapLibre" },
  { "using-with-leaflet.md" = "Displaying Martin tiles with Leaflet" },
  { "using-with-deck-gl.md" = "Displaying Martin tiles with deck.gl" },
  { "using-with-mapbox.md" = "Displaying Martin tiles with Mapbox" },
  { "using-with-openlayers.md" = "Displaying Martin tiles with OpenLayers" },
  { "using-with-data/index.md" = "Guides specific to a tile source" },
  { "recipes.md" = "Connecting to hosted PostgreSQL providers" },
  { "recipe-basemap-postgis.md" = "Generating a basemap and overlaying points from PostGIS" },
  { "pg-ssl-certificates.md" = "Connecting to PostgreSQL with SSL certificates" },
]
Tools = [
  { "martin-cp.md" = "Generating tiles in bulk with martin-cp" },
  { "mbtiles/index.md" = "Working with MBTiles archives using the mbtiles CLI" },
  { "mbtiles-schema.md" = "The flat, flat-with-hash and normalized MBTiles schemas" },
  { "mbtiles-meta.md" = "Reading and writing MBTiles metadata" },
  { "mbtiles-copy.md" = "Copying and merging MBTiles archives" },
  { "mbtiles-diff.md" = "Diffing and patching MBTiles archives" },
  { "mbtiles-validation.md" = "Validating the integrity of MBTiles archives" },
]
Development = [
  { "development/index.md" = "Developing Martin" },
  { "getting-involved.md" = "How to contribute" },
  { "tools.md" = "Tools provided alongside the Martin server" },
  { "martin-as-a-library.md" = "Embedding martin-core in a Rust application" },
  { "architecture.md" = "Martin's components and design decisions" },
]
Optional = [
  { "migration-guide.md" = "Migrating between major versions" },
  { "changelog.md" = "Release history" },
]

# ----------------------------------------------------------------------------
# The "extra" section contains miscellaneous settings.
# ----------------------------------------------------------------------------
[[project.extra.social]]
icon = "fontawesome/brands/github"
link = "https://github.com/maplibre/martin"

[project.markdown_extensions.pymdownx.emoji]
emoji_generator = "zensical.extensions.emoji.to_svg"
emoji_index = "zensical.extensions.emoji.twemoji"

[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true

[project.markdown_extensions.pymdownx.inlinehilite]

[project.markdown_extensions.pymdownx.snippets]
base_path = ["docs/content", "docs/snippets"]

[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }
]

[project.markdown_extensions.admonition]

[project.markdown_extensions.pymdownx.tabbed]
alternate_style = true

[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.attr_list]
[project.markdown_extensions.md_in_html]