From 6cff69796388823d510f2abaf190c2f22ac48576 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Wed, 21 Feb 2024 17:26:32 +0100
Subject: [PATCH 01/30] Add docs.py to build docs

---
 docs.py | 343 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 343 insertions(+)
 create mode 100644 docs.py

diff --git a/docs.py b/docs.py
new file mode 100644
index 000000000..59578a820
--- /dev/null
+++ b/docs.py
@@ -0,0 +1,343 @@
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+from functools import lru_cache
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from importlib import metadata
+from multiprocessing import Pool
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import mkdocs.commands.build
+import mkdocs.commands.serve
+import mkdocs.config
+import mkdocs.utils
+import typer
+import yaml
+from jinja2 import Template
+
+logging.basicConfig(level=logging.INFO)
+
+app = typer.Typer()
+
+mkdocs_name = "mkdocs.yml"
+
+missing_translation_snippet = """
+{!../../../docs/missing-translation.md!}
+"""
+
+docs_path = Path("docs")
+en_docs_path = Path("docs/en")
+en_config_path: Path = en_docs_path / mkdocs_name
+site_path = Path("site").absolute()
+build_site_path = Path("site_build").absolute()
+
+
+@lru_cache
+def is_mkdocs_insiders() -> bool:
+    version = metadata.version("mkdocs-material")
+    return "insiders" in version
+
+
+def get_en_config() -> Dict[str, Any]:
+    return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
+
+
+def get_lang_paths() -> List[Path]:
+    return sorted(docs_path.iterdir())
+
+
+def lang_callback(lang: Optional[str]) -> Union[str, None]:
+    if lang is None:
+        return None
+    lang = lang.lower()
+    return lang
+
+
+def complete_existing_lang(incomplete: str):
+    lang_path: Path
+    for lang_path in get_lang_paths():
+        if lang_path.is_dir() and lang_path.name.startswith(incomplete):
+            yield lang_path.name
+
+
+@app.callback()
+def callback() -> None:
+    if is_mkdocs_insiders():
+        os.environ["INSIDERS_FILE"] = "../en/mkdocs.insiders.yml"
+    # For MacOS with insiders and Cairo
+    os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
+
+
+@app.command()
+def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
+    """
+    Generate a new docs translation directory for the language LANG.
+    """
+    new_path: Path = Path("docs") / lang
+    if new_path.exists():
+        typer.echo(f"The language was already created: {lang}")
+        raise typer.Abort()
+    new_path.mkdir()
+    new_config_path: Path = Path(new_path) / mkdocs_name
+    new_config_path.write_text("INHERIT: ../en/mkdocs.yml\n", encoding="utf-8")
+    new_config_docs_path: Path = new_path / "docs"
+    new_config_docs_path.mkdir()
+    en_index_path: Path = en_docs_path / "docs" / "index.md"
+    new_index_path: Path = new_config_docs_path / "index.md"
+    en_index_content = en_index_path.read_text(encoding="utf-8")
+    new_index_content = f"{missing_translation_snippet}\n\n{en_index_content}"
+    new_index_path.write_text(new_index_content, encoding="utf-8")
+    typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN)
+    update_languages()
+
+
+@app.command()
+def build_lang(
+    lang: str = typer.Argument(
+        ..., callback=lang_callback, autocompletion=complete_existing_lang
+    ),
+) -> None:
+    """
+    Build the docs for a language.
+    """
+    insiders_env_file = os.environ.get("INSIDERS_FILE")
+    print(f"Insiders file {insiders_env_file}")
+    if is_mkdocs_insiders():
+        print("Using insiders")
+    lang_path: Path = Path("docs") / lang
+    if not lang_path.is_dir():
+        typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
+        raise typer.Abort()
+    typer.echo(f"Building docs for: {lang}")
+    build_site_dist_path = build_site_path / lang
+    if lang == "en":
+        dist_path = site_path
+        # Don't remove en dist_path as it might already contain other languages.
+        # When running build_all(), that function already removes site_path.
+        # All this is only relevant locally, on GitHub Actions all this is done through
+        # artifacts and multiple workflows, so it doesn't matter if directories are
+        # removed or not.
+    else:
+        dist_path = site_path / lang
+        shutil.rmtree(dist_path, ignore_errors=True)
+    current_dir = os.getcwd()
+    os.chdir(lang_path)
+    shutil.rmtree(build_site_dist_path, ignore_errors=True)
+    subprocess.run(["mkdocs", "build", "--site-dir", build_site_dist_path], check=True)
+    shutil.copytree(build_site_dist_path, dist_path, dirs_exist_ok=True)
+    os.chdir(current_dir)
+    typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
+
+
+index_sponsors_template = """
+{% if sponsors %}
+{% for sponsor in sponsors.gold -%}
+<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
+{% endfor -%}
+{%- for sponsor in sponsors.silver -%}
+<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
+{% endfor %}
+{% endif %}
+"""
+
+
+def generate_readme_content() -> str:
+    en_index = en_docs_path / "docs" / "index.md"
+    content = en_index.read_text("utf-8")
+    match_pre = re.search(r"</style>\n\n", content)
+    match_start = re.search(r"<!-- sponsors -->", content)
+    match_end = re.search(r"<!-- /sponsors -->", content)
+    sponsors_data_path = en_docs_path / "data" / "sponsors.yml"
+    sponsors = mkdocs.utils.yaml_load(sponsors_data_path.read_text(encoding="utf-8"))
+    if not (match_start and match_end):
+        raise RuntimeError("Couldn't auto-generate sponsors section")
+    if not match_pre:
+        raise RuntimeError("Couldn't find pre section (<style>) in index.md")
+    frontmatter_end = match_pre.end()
+    pre_end = match_start.end()
+    post_start = match_end.start()
+    template = Template(index_sponsors_template)
+    message = template.render(sponsors=sponsors)
+    pre_content = content[frontmatter_end:pre_end]
+    post_content = content[post_start:]
+    new_content = pre_content + message + post_content
+    return new_content
+
+
+@app.command()
+def generate_readme() -> None:
+    """
+    Generate README.md content from main index.md
+    """
+    typer.echo("Generating README")
+    readme_path = Path("README.md")
+    new_content = generate_readme_content()
+    readme_path.write_text(new_content, encoding="utf-8")
+
+
+@app.command()
+def verify_readme() -> None:
+    """
+    Verify README.md content from main index.md
+    """
+    typer.echo("Verifying README")
+    readme_path = Path("README.md")
+    generated_content = generate_readme_content()
+    readme_content = readme_path.read_text("utf-8")
+    if generated_content != readme_content:
+        typer.secho(
+            "README.md outdated from the latest index.md", color=typer.colors.RED
+        )
+        raise typer.Abort()
+    typer.echo("Valid README ✅")
+
+
+@app.command()
+def build_all() -> None:
+    """
+    Build mkdocs site for en, and then build each language inside, end result is located
+    at directory ./site/ with each language inside.
+    """
+    update_languages()
+    shutil.rmtree(site_path, ignore_errors=True)
+    langs = [lang.name for lang in get_lang_paths() if lang.is_dir()]
+    cpu_count = os.cpu_count() or 1
+    process_pool_size = cpu_count * 4
+    typer.echo(f"Using process pool size: {process_pool_size}")
+    with Pool(process_pool_size) as p:
+        p.map(build_lang, langs)
+
+
+@app.command()
+def update_languages() -> None:
+    """
+    Update the mkdocs.yml file Languages section including all the available languages.
+    """
+    update_config()
+
+
+@app.command()
+def serve() -> None:
+    """
+    A quick server to preview a built site with translations.
+
+    For development, prefer the command live (or just mkdocs serve).
+
+    This is here only to preview a site with translations already built.
+
+    Make sure you run the build-all command first.
+    """
+    typer.echo("Warning: this is a very simple server.")
+    typer.echo("For development, use the command live instead.")
+    typer.echo("This is here only to preview a site with translations already built.")
+    typer.echo("Make sure you run the build-all command first.")
+    os.chdir("site")
+    server_address = ("", 8008)
+    server = HTTPServer(server_address, SimpleHTTPRequestHandler)
+    typer.echo("Serving at: http://127.0.0.1:8008")
+    server.serve_forever()
+
+
+@app.command()
+def live(
+    lang: str = typer.Argument(
+        None, callback=lang_callback, autocompletion=complete_existing_lang
+    ),
+) -> None:
+    """
+    Serve with livereload a docs site for a specific language.
+
+    This only shows the actual translated files, not the placeholders created with
+    build-all.
+
+    Takes an optional LANG argument with the name of the language to serve, by default
+    en.
+    """
+    # Enable line numbers during local development to make it easier to highlight
+    os.environ["LINENUMS"] = "true"
+    if lang is None:
+        lang = "en"
+    lang_path: Path = docs_path / lang
+    os.chdir(lang_path)
+    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8008")
+
+
+def get_updated_config_content() -> Dict[str, Any]:
+    config = get_en_config()
+    languages = [{"en": "/"}]
+    new_alternate: List[Dict[str, str]] = []
+    # Language names sourced from https://quickref.me/iso-639-1
+    # Contributors may wish to update or change these, e.g. to fix capitalization.
+    language_names_path = Path(__file__).parent / "../docs/language_names.yml"
+    local_language_names: Dict[str, str] = mkdocs.utils.yaml_load(
+        language_names_path.read_text(encoding="utf-8")
+    )
+    for lang_path in get_lang_paths():
+        if lang_path.name in {"en", "em"} or not lang_path.is_dir():
+            continue
+        code = lang_path.name
+        languages.append({code: f"/{code}/"})
+    for lang_dict in languages:
+        code = list(lang_dict.keys())[0]
+        url = lang_dict[code]
+        if code not in local_language_names:
+            print(
+                f"Missing language name for: {code}, "
+                "update it in docs/language_names.yml"
+            )
+            raise typer.Abort()
+        use_name = f"{code} - {local_language_names[code]}"
+        new_alternate.append({"link": url, "name": use_name})
+    new_alternate.append({"link": "/em/", "name": "😉"})
+    config["extra"]["alternate"] = new_alternate
+    return config
+
+
+def update_config() -> None:
+    config = get_updated_config_content()
+    en_config_path.write_text(
+        yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
+        encoding="utf-8",
+    )
+
+
+@app.command()
+def verify_config() -> None:
+    """
+    Verify main mkdocs.yml content to make sure it uses the latest language names.
+    """
+    typer.echo("Verifying mkdocs.yml")
+    config = get_en_config()
+    updated_config = get_updated_config_content()
+    if config != updated_config:
+        typer.secho(
+            "docs/en/mkdocs.yml outdated from docs/language_names.yml, "
+            "update language_names.yml and run "
+            "python ./scripts/docs.py update-languages",
+            color=typer.colors.RED,
+        )
+        raise typer.Abort()
+    typer.echo("Valid mkdocs.yml ✅")
+
+
+@app.command()
+def verify_docs():
+    verify_readme()
+    verify_config()
+
+
+@app.command()
+def langs_json():
+    langs = []
+    for lang_path in get_lang_paths():
+        if lang_path.is_dir():
+            langs.append(lang_path.name)
+    print(json.dumps(langs))
+
+
+if __name__ == "__main__":
+    app()

From 5e1a01ddcef68969f490c1bbeda3c412e3a5a2ed Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Wed, 21 Feb 2024 18:20:27 +0100
Subject: [PATCH 02/30] Adapt docs.py for our usage

This required to upgrade mkdocs in order to have the same API as FastAPI
---
 .gitignore              |   1 +
 docs.py                 |  48 +++---
 help/language_names.yml |   2 +
 mkdocs.yml              | 361 ++++++++++++++++++++--------------------
 requirements.txt        |   5 +-
 5 files changed, 210 insertions(+), 207 deletions(-)
 create mode 100644 help/language_names.yml

diff --git a/.gitignore b/.gitignore
index 0e4be4579..1de3851f9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 /site
+/site_build
 /hscout/site
 /env
 
diff --git a/docs.py b/docs.py
index 59578a820..443c777f3 100644
--- a/docs.py
+++ b/docs.py
@@ -1,3 +1,8 @@
+# Python script adapted from the fastapi project to manage translations
+# License: MIT
+# Source: https://github.com/tiangolo/fastapi/blob/master/scripts/docs.py
+# Original Author: Sebastián Ramírez
+
 import json
 import logging
 import os
@@ -29,21 +34,23 @@
 {!../../../docs/missing-translation.md!}
 """
 
-docs_path = Path("docs")
-en_docs_path = Path("docs/en")
-en_config_path: Path = en_docs_path / mkdocs_name
+docs_folder_name = "help"
+docs_path = Path("help")
+en_docs_path = Path("help/en")
+base_config_path: Path = Path(mkdocs_name)
 site_path = Path("site").absolute()
 build_site_path = Path("site_build").absolute()
 
 
 @lru_cache
 def is_mkdocs_insiders() -> bool:
-    version = metadata.version("mkdocs-material")
-    return "insiders" in version
+    return False
+    # version = metadata.version("mkdocs-material")
+    # return "insiders" in version
 
 
-def get_en_config() -> Dict[str, Any]:
-    return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
+def get_base_config_path() -> Dict[str, Any]:
+    return mkdocs.utils.yaml_load(base_config_path.read_text(encoding="utf-8"))
 
 
 def get_lang_paths() -> List[Path]:
@@ -77,16 +84,16 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     """
     Generate a new docs translation directory for the language LANG.
     """
-    new_path: Path = Path("docs") / lang
+    new_path: Path = docs_path / lang
     if new_path.exists():
         typer.echo(f"The language was already created: {lang}")
         raise typer.Abort()
     new_path.mkdir()
     new_config_path: Path = Path(new_path) / mkdocs_name
     new_config_path.write_text("INHERIT: ../en/mkdocs.yml\n", encoding="utf-8")
-    new_config_docs_path: Path = new_path / "docs"
+    new_config_docs_path: Path = new_path / folder_name
     new_config_docs_path.mkdir()
-    en_index_path: Path = en_docs_path / "docs" / "index.md"
+    en_index_path: Path = en_docs_path / folder_name / "index.md"
     new_index_path: Path = new_config_docs_path / "index.md"
     en_index_content = en_index_path.read_text(encoding="utf-8")
     new_index_content = f"{missing_translation_snippet}\n\n{en_index_content}"
@@ -108,7 +115,7 @@ def build_lang(
     print(f"Insiders file {insiders_env_file}")
     if is_mkdocs_insiders():
         print("Using insiders")
-    lang_path: Path = Path("docs") / lang
+    lang_path: Path = docs_path / lang
     if not lang_path.is_dir():
         typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
         raise typer.Abort()
@@ -146,7 +153,7 @@ def build_lang(
 
 
 def generate_readme_content() -> str:
-    en_index = en_docs_path / "docs" / "index.md"
+    en_index = en_docs_path / docs_folder_name / "index.md"
     content = en_index.read_text("utf-8")
     match_pre = re.search(r"</style>\n\n", content)
     match_start = re.search(r"<!-- sponsors -->", content)
@@ -267,17 +274,17 @@ def live(
 
 
 def get_updated_config_content() -> Dict[str, Any]:
-    config = get_en_config()
+    config = get_base_config_path()
     languages = [{"en": "/"}]
     new_alternate: List[Dict[str, str]] = []
     # Language names sourced from https://quickref.me/iso-639-1
     # Contributors may wish to update or change these, e.g. to fix capitalization.
-    language_names_path = Path(__file__).parent / "../docs/language_names.yml"
+    language_names_path = Path(__file__).parent / docs_folder_name / "language_names.yml"
     local_language_names: Dict[str, str] = mkdocs.utils.yaml_load(
         language_names_path.read_text(encoding="utf-8")
     )
     for lang_path in get_lang_paths():
-        if lang_path.name in {"en", "em"} or not lang_path.is_dir():
+        if lang_path.name == "en" or not lang_path.is_dir():
             continue
         code = lang_path.name
         languages.append({code: f"/{code}/"})
@@ -287,19 +294,18 @@ def get_updated_config_content() -> Dict[str, Any]:
         if code not in local_language_names:
             print(
                 f"Missing language name for: {code}, "
-                "update it in docs/language_names.yml"
+                f"update it in {docs_folder_name}/language_names.yml"
             )
             raise typer.Abort()
         use_name = f"{code} - {local_language_names[code]}"
         new_alternate.append({"link": url, "name": use_name})
-    new_alternate.append({"link": "/em/", "name": "😉"})
     config["extra"]["alternate"] = new_alternate
     return config
 
 
 def update_config() -> None:
     config = get_updated_config_content()
-    en_config_path.write_text(
+    base_config_path.write_text(
         yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
         encoding="utf-8",
     )
@@ -311,13 +317,13 @@ def verify_config() -> None:
     Verify main mkdocs.yml content to make sure it uses the latest language names.
     """
     typer.echo("Verifying mkdocs.yml")
-    config = get_en_config()
+    config = get_base_config_path()
     updated_config = get_updated_config_content()
     if config != updated_config:
         typer.secho(
-            "docs/en/mkdocs.yml outdated from docs/language_names.yml, "
+            f"{docs_folder_name}/en/mkdocs.yml outdated from {docs_folder_name}/language_names.yml, "
             "update language_names.yml and run "
-            "python ./scripts/docs.py update-languages",
+            "python ./docs.py update-languages",
             color=typer.colors.RED,
         )
         raise typer.Abort()
diff --git a/help/language_names.yml b/help/language_names.yml
new file mode 100644
index 000000000..b461eae69
--- /dev/null
+++ b/help/language_names.yml
@@ -0,0 +1,2 @@
+en: English
+fr: français
diff --git a/mkdocs.yml b/mkdocs.yml
index 58113f0a3..faf28384d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,204 +1,197 @@
 site_name: Grist Help Center
 site_dir: site
-site_description: "Tutorials and resources for Grist, to help you organize your data, your way."
-site_url: "https://support.getgrist.com"
-repo_name: "GitHub"
-repo_url: "https://github.com/gristlabs/grist-help"
-
-# use directory urls (for prettiness) unless running htmlproofing
-# (which is confused by them).
-use_directory_urls: !ENV [HTMLPROOFER_OVERRIDE_USE_DIRECTORY_URLS, true]
-
-docs_dir: './help/en/docs' # Add localization folder here for now, we'll handle i18n later
-# windmill is a theme maintained by Grist Labs in https://github.com/gristlabs/mkdocs-windmill
+site_description: Tutorials and resources for Grist, to help you organize your data, your way.
+site_url: https://support.getgrist.com
+repo_name: GitHub
+repo_url: https://github.com/gristlabs/grist-help
+use_directory_urls: true
+docs_dir: ./help/en/docs
 theme:
   name: windmill
   custom_dir: overrides
 nav:
-  - Welcome to Grist: index.md
-  - FAQ: FAQ.md
-  - How-To Tutorials:
-    - Create your own CRM: lightweight-crm.md
-    - Analyze and visualize: investment-research.md
-    - Manage business data: afterschool-program.md
-  - Managing documents:
-    - Creating a document: creating-doc.md
-    - Sharing a document: sharing.md
-    - Copying documents: copying-docs.md
-    - Importing more data: imports.md
-    - Exports & backups: exports.md
-    - Automatic backups: automatic-backups.md
-    - Document history: document-history.md
-    - Workspaces: workspaces.md
-  - Pages and Tables:
-    - Entering data: enter-data.md
-    - Pages & widgets: page-widgets.md
-    - Raw data page: raw-data.md
-    - Search, sort & filter: search-sort-filter.md
-    - Table widget: widget-table.md
-    - Card & Card List: widget-card.md
-    - Form: widget-form.md
-    - Chart: widget-chart.md
-    - Calendar: widget-calendar.md
-    - Custom: widget-custom.md
-    - Linking widgets: linking-widgets.md
-    - Custom layouts: custom-layouts.md
-    - Record Cards: record-cards.md
-    - Summary tables: summary-tables.md
-    - On-Demand tables: on-demand-tables.md
-  - Columns and data types:
-    - Columns & types: col-types.md
-    - Reference columns: col-refs.md
-    - Conditional Formatting: conditional-formatting.md
-    - Timestamp columns: timestamps.md
-    - Authorship columns: authorship.md
-    - Transformations: col-transform.md
-  - Using formulas:
-    - Intro to formulas: formulas.md
-    - References and Lookups: references-lookups.md
-    - Working with dates: dates.md
-    - Python versions: python.md
-    - Function reference: functions.md
-    - Formula Cheat Sheet: formula-cheat-sheet.md
-  - AI Assistant:
-    - AI Assistant: ai-assistant.md
-  - Team Sites:
-    - Creating team sites: teams.md
-    - Sharing team sites: team-sharing.md
-  - Access rules:
-    - Intro to access rules: access-rules.md
-  - Integrations:
-    - REST API usage: rest-api.md
-    - REST API reference: api.md
-    - Integrator Services: integrators.md
-    - Embedding: embedding.md
-    - Plugin API:
-      - Intro to Plugin API: code/README.md
-      - grist-plugin-api: code/modules/grist_plugin_api.md
-      - ... | flat | **/code/interfaces/**
-      - ... | flat | **/code/modules/**
-  - Self-Managed:
-    - Self-managed Grist: self-managed.md
-    - SAML: install/saml.md
-    - OIDC: install/oidc.md
-    - Forwarded headers: install/forwarded-headers.md
-    - Cloud storage: install/cloud-storage.md
-    - GristConnect: install/grist-connect.md
-    - AWS Marketplace: install/aws-marketplace.md
-    - Telemetry:
-      - Overview of Telemetry: telemetry.md
-      - Limited Telemetry: telemetry-limited.md
-      - Full Telemetry: telemetry-full.md
-  - News & updates:
-    - Newsletters: newsletters.md
-    - 2024/01: newsletters/2024-01.md
-    - 2023/12: newsletters/2023-12.md
-    - 2023/11: newsletters/2023-11.md
-    - 2023/10: newsletters/2023-10.md
-    - 2023/09: newsletters/2023-09.md
-    - 2023/08: newsletters/2023-08.md
-    - 2023/07: newsletters/2023-07.md
-    - 2023/06: newsletters/2023-06.md
-    - 2023/05: newsletters/2023-05.md
-    - 2023/04: newsletters/2023-04.md
-    - 2023/03: newsletters/2023-03.md
-    - 2023/02: newsletters/2023-02.md
-    - 2023/01: newsletters/2023-01.md
-    - 2022/12: newsletters/2022-12.md
-    - 2022/11: newsletters/2022-11.md
-    - 2022/10: newsletters/2022-10.md
-    - 2022/09: newsletters/2022-09.md
-    - 2022/08: newsletters/2022-08.md
-    - 2022/07: newsletters/2022-07.md
-    - 2022/06: newsletters/2022-06.md
-    - 2022/05: newsletters/2022-05.md
-    - 2022/04: newsletters/2022-04.md
-    - 2022/03: newsletters/2022-03.md
-    - 2022/02: newsletters/2022-02.md
-    - 2022/01: newsletters/2022-01.md
-    - 2021/12: newsletters/2021-12.md
-    - 2021/11: newsletters/2021-11.md
-    - 2021/10: newsletters/2021-10.md
-    - 2021/09: newsletters/2021-09.md
-    - 2021/08: newsletters/2021-08.md
-    - 2021/07: newsletters/2021-07.md
-    - 2021/06: newsletters/2021-06.md
-    - 2021/05: newsletters/2021-05.md
-    - 2021/04: newsletters/2021-04.md
-    - 2021/03: newsletters/2021-03.md
-    - 2021/02: newsletters/2021-02.md
-    - 2021/01: newsletters/2021-01.md
-    - 2020/12: newsletters/2020-12.md
-    - 2020/11: newsletters/2020-11.md
-    - 2020/10: newsletters/2020-10.md
-    - 2020/09: newsletters/2020-09.md
-    - 2020/08: newsletters/2020-08.md
-    - 2020/07: newsletters/2020-07.md
-    - 2020/06: newsletters/2020-06.md
-    - 2020/05: newsletters/2020-05.md
-  - More examples:
-      - More examples: examples.md
-      - Credit card expenses: examples/2020-06-credit-card.md
-      - Book club links: examples/2020-06-book-club.md
-      - Prefill emails: examples/2020-07-email-compose.md
-      - Prepare Invoices: examples/2020-08-invoices.md
-      - Track Payroll: examples/2020-09-payroll.md
-      - Print mailing labels: examples/2020-10-print-labels.md
-      - Treasure Hunt: examples/2020-11-treasure-hunt.md
-      - Map: examples/2020-12-map.md
-      - Task Management: examples/2021-01-tasks.md
-      - Lead List: examples/2021-03-leads.md
-      - Link Keys Guide: examples/2021-04-link-keys.md
-      - Reference Columns Guide: examples/2021-05-reference-columns.md
-      - Summary Tables Guide: examples/2021-06-timesheets.md
-      - Time and User Stamps: examples/2021-07-auto-stamps.md
-      - Restrict Duplicate Records: examples/2023-01-acl-memo.md
-      - Proposals & Contracts: examples/2023-07-proposals-contracts.md
-  - Reference:
-    - Shortcuts: keyboard-shortcuts.md
-    # The function reference (functions.md) is listed above; here is an intentionally non-standard
-    # link, so that only the above page item gets highlighted when the function reference is open.
-    - Function reference: /functions/
-    - Limits: limits.md
-    - Data Security: data-security.md
-    - Browser Support: browser-support.md
-    - Glossary: glossary.md
-
+- Welcome to Grist: index.md
+- FAQ: FAQ.md
+- How-To Tutorials:
+  - Create your own CRM: lightweight-crm.md
+  - Analyze and visualize: investment-research.md
+  - Manage business data: afterschool-program.md
+- Managing documents:
+  - Creating a document: creating-doc.md
+  - Sharing a document: sharing.md
+  - Copying documents: copying-docs.md
+  - Importing more data: imports.md
+  - Exports & backups: exports.md
+  - Automatic backups: automatic-backups.md
+  - Document history: document-history.md
+  - Workspaces: workspaces.md
+- Pages and Tables:
+  - Entering data: enter-data.md
+  - Pages & widgets: page-widgets.md
+  - Raw data page: raw-data.md
+  - Search, sort & filter: search-sort-filter.md
+  - Table widget: widget-table.md
+  - Card & Card List: widget-card.md
+  - Form: widget-form.md
+  - Chart: widget-chart.md
+  - Calendar: widget-calendar.md
+  - Custom: widget-custom.md
+  - Linking widgets: linking-widgets.md
+  - Custom layouts: custom-layouts.md
+  - Record Cards: record-cards.md
+  - Summary tables: summary-tables.md
+  - On-Demand tables: on-demand-tables.md
+- Columns and data types:
+  - Columns & types: col-types.md
+  - Reference columns: col-refs.md
+  - Conditional Formatting: conditional-formatting.md
+  - Timestamp columns: timestamps.md
+  - Authorship columns: authorship.md
+  - Transformations: col-transform.md
+- Using formulas:
+  - Intro to formulas: formulas.md
+  - References and Lookups: references-lookups.md
+  - Working with dates: dates.md
+  - Python versions: python.md
+  - Function reference: functions.md
+  - Formula Cheat Sheet: formula-cheat-sheet.md
+- AI Assistant:
+  - AI Assistant: ai-assistant.md
+- Team Sites:
+  - Creating team sites: teams.md
+  - Sharing team sites: team-sharing.md
+- Access rules:
+  - Intro to access rules: access-rules.md
+- Integrations:
+  - REST API usage: rest-api.md
+  - REST API reference: api.md
+  - Integrator Services: integrators.md
+  - Embedding: embedding.md
+  - Plugin API:
+    - Intro to Plugin API: code/README.md
+    - grist-plugin-api: code/modules/grist_plugin_api.md
+    - '... | flat | **/code/interfaces/**'
+    - '... | flat | **/code/modules/**'
+- Self-Managed:
+  - Self-managed Grist: self-managed.md
+  - SAML: install/saml.md
+  - OIDC: install/oidc.md
+  - Forwarded headers: install/forwarded-headers.md
+  - Cloud storage: install/cloud-storage.md
+  - GristConnect: install/grist-connect.md
+  - AWS Marketplace: install/aws-marketplace.md
+  - Telemetry:
+    - Overview of Telemetry: telemetry.md
+    - Limited Telemetry: telemetry-limited.md
+    - Full Telemetry: telemetry-full.md
+- News & updates:
+  - Newsletters: newsletters.md
+  - 2024/01: newsletters/2024-01.md
+  - 2023/12: newsletters/2023-12.md
+  - 2023/11: newsletters/2023-11.md
+  - 2023/10: newsletters/2023-10.md
+  - 2023/09: newsletters/2023-09.md
+  - 2023/08: newsletters/2023-08.md
+  - 2023/07: newsletters/2023-07.md
+  - 2023/06: newsletters/2023-06.md
+  - 2023/05: newsletters/2023-05.md
+  - 2023/04: newsletters/2023-04.md
+  - 2023/03: newsletters/2023-03.md
+  - 2023/02: newsletters/2023-02.md
+  - 2023/01: newsletters/2023-01.md
+  - 2022/12: newsletters/2022-12.md
+  - 2022/11: newsletters/2022-11.md
+  - 2022/10: newsletters/2022-10.md
+  - 2022/09: newsletters/2022-09.md
+  - 2022/08: newsletters/2022-08.md
+  - 2022/07: newsletters/2022-07.md
+  - 2022/06: newsletters/2022-06.md
+  - 2022/05: newsletters/2022-05.md
+  - 2022/04: newsletters/2022-04.md
+  - 2022/03: newsletters/2022-03.md
+  - 2022/02: newsletters/2022-02.md
+  - 2022/01: newsletters/2022-01.md
+  - 2021/12: newsletters/2021-12.md
+  - 2021/11: newsletters/2021-11.md
+  - 2021/10: newsletters/2021-10.md
+  - 2021/09: newsletters/2021-09.md
+  - 2021/08: newsletters/2021-08.md
+  - 2021/07: newsletters/2021-07.md
+  - 2021/06: newsletters/2021-06.md
+  - 2021/05: newsletters/2021-05.md
+  - 2021/04: newsletters/2021-04.md
+  - 2021/03: newsletters/2021-03.md
+  - 2021/02: newsletters/2021-02.md
+  - 2021/01: newsletters/2021-01.md
+  - 2020/12: newsletters/2020-12.md
+  - 2020/11: newsletters/2020-11.md
+  - 2020/10: newsletters/2020-10.md
+  - 2020/09: newsletters/2020-09.md
+  - 2020/08: newsletters/2020-08.md
+  - 2020/07: newsletters/2020-07.md
+  - 2020/06: newsletters/2020-06.md
+  - 2020/05: newsletters/2020-05.md
+- More examples:
+  - More examples: examples.md
+  - Credit card expenses: examples/2020-06-credit-card.md
+  - Book club links: examples/2020-06-book-club.md
+  - Prefill emails: examples/2020-07-email-compose.md
+  - Prepare Invoices: examples/2020-08-invoices.md
+  - Track Payroll: examples/2020-09-payroll.md
+  - Print mailing labels: examples/2020-10-print-labels.md
+  - Treasure Hunt: examples/2020-11-treasure-hunt.md
+  - Map: examples/2020-12-map.md
+  - Task Management: examples/2021-01-tasks.md
+  - Lead List: examples/2021-03-leads.md
+  - Link Keys Guide: examples/2021-04-link-keys.md
+  - Reference Columns Guide: examples/2021-05-reference-columns.md
+  - Summary Tables Guide: examples/2021-06-timesheets.md
+  - Time and User Stamps: examples/2021-07-auto-stamps.md
+  - Restrict Duplicate Records: examples/2023-01-acl-memo.md
+  - Proposals & Contracts: examples/2023-07-proposals-contracts.md
+- Reference:
+  - Shortcuts: keyboard-shortcuts.md
+  - Function reference: functions.md
+  - Limits: limits.md
+  - Data Security: data-security.md
+  - Browser Support: browser-support.md
+  - Glossary: glossary.md
 extra:
-  logo: 'images/logo.png'
+  logo: images/logo.png
   palette:
-    primary: 'blue grey'
-    accent: 'orange'
+    primary: blue grey
+    accent: orange
   font:
-    text: 'Roboto'
-    code: 'Roboto Mono'
-  homepage: '/help'
-  version: '1.0.2-dev'
+    text: Roboto
+    code: Roboto Mono
+  homepage: /help
+  version: 1.0.2-dev
   article_nav_bottom: false
   history_buttons: false
   home_links:
-    - href: https://community.getgrist.com
-      text: 'Community'
-    - href: https://www.getgrist.com
-      text: 'Back to Grist'
-      hide_on_small_screen: true
-  google_tag_manager: 'GTM-5FDHKQ9'
+  - href: https://community.getgrist.com
+    text: Community
+  - href: https://www.getgrist.com
+    text: Back to Grist
+    hide_on_small_screen: true
+  google_tag_manager: GTM-5FDHKQ9
+  alternate:
+  - link: /
+    name: en - English
 extra_css:
-  - css/grist.css
+- css/grist.css
 extra_javascript:
-  - js/grist.js
-
+- js/grist.js
 plugins:
-  - search
-  - awesome-pages
-  - htmlproofer:
-      enabled: !ENV [HTMLPROOFER_ENABLED, false]
-      validate_external_urls: false
-  - meta-descriptions
-
+- search
+- awesome-pages
+- htmlproofer:
+    enabled: false
+    validate_external_urls: false
+- meta-descriptions
 markdown_extensions:
   toc:
-      permalink: '#'
+    permalink: '#'
   admonition: {}
   smarty: {}
   extra: {}
diff --git a/requirements.txt b/requirements.txt
index d98953148..5311b906e 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -6,8 +6,8 @@ joblib==0.16.0
 livereload==2.6.2
 lunr==0.5.8
 Markdown==3.2.2
-MarkupSafe==1.1.1
-mkdocs==1.2.3
+MarkupSafe==2.0.1
+mkdocs==1.5.3
 mkdocs-awesome-pages-plugin==2.7.0
 mkdocs-htmlproofer-plugin==0.8.0
 mkdocs-meta-descriptions-plugin==2.0.0
@@ -19,3 +19,4 @@ requests==2.26.0
 six==1.15.0
 tornado==6.0.4
 tqdm==4.48.0
+typer >=0.6.1,<0.8.0

From 6d2a138f4d4a11cba91d87b3e9743187322fd294 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Wed, 21 Feb 2024 18:22:42 +0100
Subject: [PATCH 03/30] Fix documentation link after mkdocs upgrade

---
 help/en/docs/afterschool-program.md           | 10 +--
 help/en/docs/api.md                           |  2 +-
 help/en/docs/examples/2020-06-book-club.md    | 14 ++---
 help/en/docs/examples/2020-06-credit-card.md  |  4 +-
 .../en/docs/examples/2020-07-email-compose.md |  4 +-
 help/en/docs/examples/2020-08-invoices.md     | 60 +++++++++---------
 help/en/docs/examples/2020-09-payroll.md      | 16 ++---
 help/en/docs/examples/2020-10-print-labels.md | 20 +++---
 .../en/docs/examples/2020-11-treasure-hunt.md | 10 +--
 help/en/docs/examples/2020-12-map.md          | 10 +--
 help/en/docs/examples/2021-01-tasks.md        |  8 +--
 help/en/docs/examples/2021-03-leads.md        | 14 ++---
 .../examples/2023-07-proposals-contracts.md   | 62 +++++++++----------
 help/en/docs/investment-research.md           |  8 +--
 help/en/docs/lightweight-crm.md               |  2 +-
 help/en/docs/newsletters/2020-08.md           |  2 +-
 help/en/docs/newsletters/2020-09.md           |  2 +-
 help/en/docs/newsletters/2020-10.md           |  2 +-
 help/en/docs/newsletters/2020-11.md           |  2 +-
 help/en/docs/newsletters/2021-03.md           |  2 +-
 help/en/docs/newsletters/2023-10.md           |  2 +-
 help/en/docs/self-managed.md                  |  2 +-
 help/en/docs/widget-custom.md                 |  8 +--
 23 files changed, 133 insertions(+), 133 deletions(-)

diff --git a/help/en/docs/afterschool-program.md b/help/en/docs/afterschool-program.md
index a9a4d697e..29c07b8ba 100644
--- a/help/en/docs/afterschool-program.md
+++ b/help/en/docs/afterschool-program.md
@@ -39,14 +39,14 @@ instructor.
 When starting from scratch, you'll create a new empty document (see [Creating a
 document](creating-doc.md)), rename the initial empty table "Table1" to "Classes", add the columns
 you need, and type in some classes. To follow the steps of this tutorial, you can instead import
-[Classes.csv](/unlocalized-assets/afterschool-program/Classes.csv){: data-wm-adjusted=1 }
+[Classes.csv](./unlocalized-assets/afterschool-program/Classes.csv){: data-wm-adjusted=1 }
 (or simply refer to the "Afterschool Program" example document).
 
 ![add-classes](images/afterschool-program/add-classes.png)
 
 For the Staff table, click the "Add New" button and select "Add Empty Table". Rename it to
 "Staff", create some columns, and enter some data about instructors. Or import
-[Staff.csv](/unlocalized-assets/afterschool-program/Staff.csv) to use sample data and save a few steps.
+[Staff.csv](./unlocalized-assets/afterschool-program/Staff.csv) to use sample data and save a few steps.
 
 ![add-staff](images/afterschool-program/add-staff.png)
 
@@ -108,7 +108,7 @@ Next, we will continue with students and their enrollments.
 
 Each class has a number of students. So, we’ll need a table of students. Again, add a new empty
 table, rename it to "Students", and fill it with the students’ names, grade levels, etc. Or
-import [Students.csv](/unlocalized-assets/afterschool-program/Students.csv) to use sample data and save a few steps.
+import [Students.csv](./unlocalized-assets/afterschool-program/Students.csv) to use sample data and save a few steps.
 
 ![students-table](images/afterschool-program/students-table.png)
 
@@ -143,7 +143,7 @@ becomes this:
 {: .screenshot-half }
 
 So, let’s add a new table, name it "Enrollments", and add the columns we need. Here too, to follow
-along, you may import sample data from [Enrollments.csv](/unlocalized-assets/afterschool-program/Enrollments.csv).
+along, you may import sample data from [Enrollments.csv](./unlocalized-assets/afterschool-program/Enrollments.csv).
 
 ![enrollments-table](images/afterschool-program/enrollments-table.png)
 
@@ -271,7 +271,7 @@ will likely simplify your daily workflow.
 
 So, let’s add one more table: `Families`. We’ll include the parent name and contact info, and link
 each child to a record here. You can import sample data from
-[Families.csv](/unlocalized-assets/afterschool-program/Families.csv).
+[Families.csv](./unlocalized-assets/afterschool-program/Families.csv).
 
 ![families1](images/afterschool-program/families1.png)
 
diff --git a/help/en/docs/api.md b/help/en/docs/api.md
index 3b9b4a96c..a5588be6d 100644
--- a/help/en/docs/api.md
+++ b/help/en/docs/api.md
@@ -272,7 +272,7 @@ Also note that some query parameters alter this behavior.</p>
 </div></div></div></td></tr></tbody></table><div><h3 class="sc-fIxmyt DvFer">Responses</h3><div><button class="sc-htmcrh lbYftx"><svg class="sc-dIsUp dqYXmg" version="1.1" viewBox="0 0 24 24" x="0" xmlns="http://www.w3.org/2000/svg" y="0" aria-hidden="true"><polygon points="17.3 8.3 12 13.6 6.7 8.3 5.3 9.7 12 16.4 18.7 9.7 "></polygon></svg><strong class="sc-fWWYYk cMoEZ">200<!-- --> </strong><span class="sc-jcwpoC eDjFAZ"><p>The result set for the query.</p>
 </span></button></div></div></div><div class="sc-jSFjdj sc-gKAaRy bummOK gcushC"><div><h3 class="sc-kEqXSa iXmHCl"> <!-- -->Request samples<!-- --> </h3><div class="sc-cxNHIi gxohHo" data-rttabs="true"><ul class="react-tabs__tab-list" role="tablist"><li class="react-tabs__tab react-tabs__tab--selected" role="tab" id="react-tabs-98" aria-selected="true" aria-disabled="false" aria-controls="react-tabs-99" tabindex="0" data-rttab="true">Payload</li></ul><div class="react-tabs__tab-panel react-tabs__tab-panel--selected" role="tabpanel" id="react-tabs-99" aria-labelledby="react-tabs-98"><div><div class="sc-Arkif jojbRz"><span class="sc-cOifOu hlhNtL">Content type</span><div class="sc-bBjRSN kQSIAz">application/json</div></div><div class="sc-jgPyTC dSaTNC"><div class="sc-jNnpgg esZIbL"><div class="sc-giAqHp hMPeqJ"><button><div class="sc-carFqZ UksDl">Copy</div></button><button> Expand all </button><button> Collapse all </button></div><div class="sc-iJCRrE jCdxGr sc-dPaNzc gyljjx"><div class="redoc-json"><code><button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"sql"</span>: <span class="token string">&quot;select * from Pets where popularity &gt;= ?&quot;</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"args"</span>: <button class="collapser" aria-label="collapse"></button><span class="token punctuation">[</span><span class="ellipsis"></span><ul class="array collapsible"><li><div class="hoverable "><span class="token number">50</span></div></li></ul><span class="token punctuation">]</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"timeout"</span>: <span class="token number">500</span></div></li></ul><span class="token punctuation">}</span></code></div></div></div></div></div></div></div></div><div><h3 class="sc-kEqXSa iXmHCl"> <!-- -->Response samples<!-- --> </h3><div class="sc-cxNHIi gxohHo" data-rttabs="true"><ul class="react-tabs__tab-list" role="tablist"><li class="tab-success react-tabs__tab--selected" role="tab" id="react-tabs-100" aria-selected="true" aria-disabled="false" aria-controls="react-tabs-101" tabindex="0" data-rttab="true">200</li></ul><div class="react-tabs__tab-panel react-tabs__tab-panel--selected" role="tabpanel" id="react-tabs-101" aria-labelledby="react-tabs-100"><div><div class="sc-Arkif jojbRz"><span class="sc-cOifOu hlhNtL">Content type</span><div class="sc-bBjRSN kQSIAz">application/json</div></div><div class="sc-jgPyTC dSaTNC"><div class="sc-jNnpgg esZIbL"><div class="sc-giAqHp hMPeqJ"><button><div class="sc-carFqZ UksDl">Copy</div></button><button> Expand all </button><button> Collapse all </button></div><div class="sc-iJCRrE jCdxGr sc-dPaNzc gyljjx"><div class="redoc-json"><code><button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"statement"</span>: <span class="token string">&quot;select * from Pets ...&quot;</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"records"</span>: <button class="collapser" aria-label="collapse"></button><span class="token punctuation">[</span><span class="ellipsis"></span><ul class="array collapsible"><li><div class="hoverable "><button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"fields"</span>: <button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"id"</span>: <span class="token number">1</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"pet"</span>: <span class="token string">&quot;cat&quot;</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"popularity"</span>: <span class="token number">67</span></div></li></ul><span class="token punctuation">}</span></div></li></ul><span class="token punctuation">}</span>,</div></li><li><div class="hoverable "><button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"fields"</span>: <button class="collapser" aria-label="collapse"></button><span class="token punctuation">{</span><span class="ellipsis"></span><ul class="obj collapsible"><li><div class="hoverable "><span class="property token string">"id"</span>: <span class="token number">2</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"pet"</span>: <span class="token string">&quot;dog&quot;</span><span class="token punctuation">,</span></div></li><li><div class="hoverable "><span class="property token string">"popularity"</span>: <span class="token number">95</span></div></li></ul><span class="token punctuation">}</span></div></li></ul><span class="token punctuation">}</span></div></li></ul><span class="token punctuation">]</span></div></li></ul><span class="token punctuation">}</span></code></div></div></div></div></div></div></div></div></div></div></div></div><div class="sc-ellfGf HrYdq"></div></div></div>
     <script>
-    const __redoc_state = {"menu":{"activeItemIdx":-1},"spec":{"data":{"info":{"description":"An API for manipulating Grist sites, workspaces, and documents.\n\n# Authentication\n<SecurityDefinitions />\n","version":"1.0.1","title":"Grist API"},"openapi":"3.0.0","security":[{"ApiKey":[]}],"servers":[{"url":"https://{subdomain}.getgrist.com/api","variables":{"subdomain":{"description":"The team name, or `docs` for personal areas","default":"docs"}}}],"paths":{"/orgs":{"get":{"operationId":"listOrgs","tags":["orgs"],"summary":"List the orgs you have access to","description":"This enumerates all the team sites or personal areas available.","responses":{"200":{"description":"An array of organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orgs"}}}}}}},"/orgs/{orgId}":{"get":{"operationId":"describeOrg","tags":["orgs"],"summary":"Describe an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"An organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}}}},"patch":{"operationId":"modifyOrg","tags":["orgs"],"summary":"Modify an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/orgs/{orgId}/access":{"get":{"operationId":"listOrgAccess","tags":["orgs"],"summary":"List users with access to org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"Users with access to org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgAccessRead"}}}}}},"patch":{"operationId":"modifyOrgAccess","tags":["orgs"],"summary":"Change who has access to org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/OrgAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/orgs/{orgId}/workspaces":{"get":{"operationId":"listWorkspaces","tags":["workspaces"],"summary":"List workspaces and documents within an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"An org's workspaces and documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceWithDocsAndDomain"}}}}}}},"post":{"operationId":"createWorkspace","tags":["workspaces"],"summary":"Create an empty workspace","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"settings for the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceParameters"}}},"required":true},"responses":{"200":{"description":"The workspace id","content":{"application/json":{"schema":{"type":"integer","description":"an identifier for the workspace","example":155}}}}}}},"/workspaces/{workspaceId}":{"get":{"operationId":"describeWorkspace","tags":["workspaces"],"summary":"Describe a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"A workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceWithDocsAndOrg"}}}}}},"patch":{"operationId":"modifyWorkspace","tags":["workspaces"],"summary":"Modify a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}},"delete":{"operationId":"deleteWorkspace","tags":["workspaces"],"summary":"Delete a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/workspaces/{workspaceId}/docs":{"post":{"operationId":"createDoc","tags":["docs"],"summary":"Create an empty document","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"settings for the document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocParameters"}}},"required":true},"responses":{"200":{"description":"The document id","content":{"application/json":{"schema":{"type":"string","description":"a unique identifier for the document","example":"8b97c8db-b4df-4b34-b72c-17459e70140a"}}}}}}},"/workspaces/{workspaceId}/access":{"get":{"operationId":"listWorkspaceAccess","tags":["workspaces"],"summary":"List users with access to workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"Users with access to workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceAccessRead"}}}}}},"patch":{"operationId":"modifyWorkspaceAccess","tags":["workspaces"],"summary":"Change who has access to workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/WorkspaceAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}":{"get":{"operationId":"describeDoc","tags":["docs"],"summary":"Describe a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"A document's metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocWithWorkspace"}}}}}},"patch":{"operationId":"modifyDoc","tags":["docs"],"summary":"Modify document metadata (but not its contents)","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}},"delete":{"operationId":"deleteDoc","tags":["docs"],"summary":"Delete a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/move":{"patch":{"operationId":"moveDoc","tags":["docs"],"summary":"Move document to another workspace in the same org.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the target workspace","content":{"application/json":{"schema":{"type":"object","required":["workspace"],"properties":{"workspace":{"type":"integer","example":597}}}}}},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/access":{"get":{"operationId":"listDocAccess","tags":["docs"],"summary":"List users with access to document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Users with access to document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocAccessRead"}}}}}},"patch":{"operationId":"modifyDocAccess","tags":["docs"],"summary":"Change who has access to document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/DocAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/download":{"get":{"operationId":"downloadDoc","tags":["docs"],"summary":"Content of document, as an Sqlite file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"nohistory","schema":{"type":"boolean","description":"Remove document history (can significantly reduce file size)"},"required":false},{"in":"query","name":"template","schema":{"type":"boolean","description":"Remove all data and history but keep the structure to use the document as a template"},"required":false}],"responses":{"200":{"description":"A document's content in Sqlite form","content":{"application/x-sqlite3":{"schema":{"type":"string","format":"binary"}}}}}}},"/docs/{docId}/download/xlsx":{"get":{"operationId":"downloadDocXlsx","tags":["docs"],"summary":"Content of document, as an Excel file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A document's content in Excel form","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}}}}},"/docs/{docId}/download/csv":{"get":{"operationId":"downloadDocCsv","tags":["docs"],"summary":"Content of table, as a CSV file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"tableId","schema":{"type":"string","description":"Name of a table (normalized)."},"required":true},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A table's content in CSV form","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/docs/{docId}/download/table-schema":{"get":{"operationId":"downloadTableSchema","tags":["docs"],"summary":"The schema of a table","description":"The schema follows [frictionlessdata's table-schema standard](https://specs.frictionlessdata.io/table-schema/).","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"tableId","schema":{"type":"string","description":"Name of a table (normalized)."},"required":true},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A table's table-schema in JSON format.","content":{"text/json":{"schema":{"$ref":"#/components/schemas/TableSchemaResult"}}}}}}},"/docs/{docId}/tables/{tableId}/data":{"get":{"operationId":"getTableData","tags":["data"],"summary":"Fetch data from a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"}],"responses":{"200":{"description":"Cells from the table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}}}},"post":{"operationId":"addRows","tags":["data"],"summary":"Add rows to a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the data to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataWithoutId"}}},"required":true},"responses":{"200":{"description":"IDs of rows added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}},"patch":{"operationId":"modifyRows","tags":["data"],"summary":"Modify rows of a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the data to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}},"required":true},"responses":{"200":{"description":"IDs of rows modified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}}},"/docs/{docId}/tables/{tableId}/data/delete":{"post":{"operationId":"deleteRows","tags":["data"],"summary":"Delete rows of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the IDs of rows to remove","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}},"required":true},"responses":{"200":{"description":"Nothing returned"}}}},"/docs/{docId}/attachments":{"get":{"operationId":"listAttachments","tags":["attachments"],"summary":"List metadata of all attachments in a doc","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"}],"responses":{"200":{"description":"List of attachment metadata records. Note that the list may temporarily include records for attachments that are stored in the document but not referenced by any Attachments type cell.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentMetadataList"}}}}}},"post":{"operationId":"uploadAttachments","tags":["attachments"],"summary":"Upload attachments to a doc","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the files to add to the doc","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AttachmentUpload"}}},"required":true},"responses":{"200":{"description":"IDs of attachments added, one per file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}}},"/docs/{docId}/attachments/{attachmentId}":{"get":{"operationId":"getAttachmentMetadata","tags":["attachments"],"summary":"Get the metadata for an attachment","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"attachmentId","schema":{"$ref":"#/components/schemas/AttachmentId"},"required":true}],"responses":{"200":{"description":"Attachment metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentMetadata"}}}}}}},"/docs/{docId}/attachments/{attachmentId}/download":{"get":{"operationId":"downloadAttachment","tags":["attachments"],"summary":"Download the contents of an attachment","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"attachmentId","schema":{"$ref":"#/components/schemas/AttachmentId"},"required":true}],"responses":{"200":{"description":"Attachment contents, with suitable Content-Type."}}}},"/docs/{docId}/tables/{tableId}/records":{"get":{"operationId":"listRecords","tags":["records"],"summary":"Fetch records from a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"},{"$ref":"#/components/parameters/hiddenQueryParam"}],"responses":{"200":{"description":"Records from the table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsList"}}}}}},"post":{"operationId":"addRecords","tags":["records"],"summary":"Add records to a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the records to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithoutId"}}},"required":true},"responses":{"200":{"description":"IDs of records added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithoutFields"}}}}}},"patch":{"operationId":"modifyRecords","tags":["records"],"summary":"Modify records of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the records to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsList"}}},"required":true},"responses":{"200":{"description":"Success"}}},"put":{"operationId":"replaceRecords","tags":["records"],"summary":"Add or update records of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"},{"in":"query","name":"onmany","schema":{"type":"string","enum":["first","none","all"],"description":"Which records to update if multiple records are found to match `require`.\n  * `first` - the first matching record (default)\n  * `none` - do not update anything\n  * `all` - update all matches\n"}},{"in":"query","name":"noadd","schema":{"type":"boolean","description":"Set to true to prohibit adding records."}},{"in":"query","name":"noupdate","schema":{"type":"boolean","description":"Set to true to prohibit updating records."}},{"in":"query","name":"allow_empty_require","schema":{"type":"boolean","description":"Set to true to allow `require` in the body to be empty, which will match and update all records in the table."}}],"requestBody":{"description":"The records to add or update. Instead of an id, a `require` object is provided, with the same structure as `fields`. If no query parameter options are set, then the operation is as follows. First, we check if a record exists matching the values specified for columns in `require`. If so, we update it by setting the values specified for columns in `fields`. If not, we create a new record with a combination of the values in `require` and `fields`, with `fields` taking priority if the same column is specified in both. The query parameters allow for variations on this behavior.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithRequire"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables":{"get":{"operationId":"listTables","tags":["tables"],"summary":"List tables in a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"The tables in a document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesList"}}}}}},"post":{"operationId":"addTables","tags":["tables"],"summary":"Add tables to a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the tables to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTables"}}},"required":true},"responses":{"200":{"description":"The table created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesWithoutFields"}}}}}},"patch":{"operationId":"modifyTables","tags":["tables"],"summary":"Modify tables of a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the tables to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesList"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables/{tableId}/columns":{"get":{"operationId":"listColumns","tags":["columns"],"summary":"List columns in a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/hiddenQueryParam"}],"responses":{"200":{"description":"The columns in a table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColumnsList"}}}}}},"post":{"operationId":"addColumns","tags":["columns"],"summary":"Add columns to a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the columns to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateColumns"}}},"required":true},"responses":{"200":{"description":"The columns created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColumnsWithoutFields"}}}}}},"patch":{"operationId":"modifyColumns","tags":["columns"],"summary":"Modify columns of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the columns to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateColumns"}}},"required":true},"responses":{"200":{"description":"Success"}}},"put":{"operationId":"replaceColumns","tags":["columns"],"summary":"Add or update columns of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"in":"query","name":"noadd","schema":{"type":"boolean","description":"Set to true to prohibit adding columns."}},{"in":"query","name":"noupdate","schema":{"type":"boolean","description":"Set to true to prohibit updating columns."}},{"in":"query","name":"replaceall","schema":{"type":"boolean","description":"Set to true to remove existing columns (except the hidden ones) that are not specified in the request body."}}],"requestBody":{"description":"The columns to add or update. We check whether the specified column ID exists: if so, the column is updated with the provided data, otherwise a new column is created.\nAlso note that some query parameters alter this behavior.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateColumns"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables/{tableId}/columns/{colId}":{"delete":{"operationId":"deleteColumn","tags":["columns"],"summary":"Delete a column of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/colIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/webhooks":{"get":{"tags":["webhooks"],"summary":"Webhooks associated with a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"A list of webhooks.","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"object","$ref":"#/components/schemas/Webhooks"}}}}}}}},"post":{"tags":["webhooks"],"summary":"Create new webhooks for a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"an array of webhook settings","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"$ref":"#/components/schemas/WebhookPartialFields"}}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/WebhookId"}}}}}}}}}},"/docs/{docId}/webhooks/{webhookId}":{"patch":{"tags":["webhooks"],"summary":"Modify a webhook","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"webhookId","schema":{"type":"string"},"required":true}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPartialFields"}}}},"responses":{"200":{"description":"Success."}}},"delete":{"tags":["webhooks"],"summary":"Remove a webhook","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"webhookId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","example":true}}}}}}}}},"/docs/{docId}/webhooks/queue":{"delete":{"tags":["webhooks"],"summary":"Empty a document's queue of undelivered payloads","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Success."}}}},"/docs/{docId}/sql":{"get":{"tags":["sql"],"summary":"Run an SQL query against a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"q","schema":{"type":"string","description":"The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string."}}],"responses":{"200":{"description":"The result set for the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResultSet"}}}}}},"post":{"tags":["sql"],"summary":"Run an SQL query against a document, with options or parameters","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"Query options","content":{"application/json":{"schema":{"type":"object","required":["sql"],"properties":{"sql":{"type":"string","description":"The SQL query to run. Must be a single SELECT statement, with no trailing semicolon. WITH clauses are permitted. All Grist documents are currently SQLite databases, and the SQL query is interpreted and run by SQLite, with various defensive measures. Statements that would modify the database are not supported.","example":"select * from Pets where popularity >= ?"},"args":{"type":"array","items":{"oneOf":[{"type":"number"},{"type":"string"}]},"description":"Parameters for the query.","example":[50]},"timeout":{"type":"number","description":"Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced.","example":500}}}}}},"responses":{"200":{"description":"The result set for the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResultSet"}}}}}}}},"tags":[{"name":"orgs","description":"Team sites and personal spaces are called 'orgs' in the API."},{"name":"workspaces","description":"Sites can be organized into groups of documents called workspaces."},{"name":"docs","description":"Workspaces contain collections of Grist documents."},{"name":"records","description":"Tables contain collections of records (also called rows)."},{"name":"tables","description":"Documents are structured as a collection of tables."},{"name":"columns","description":"Tables are structured as a collection of columns."},{"name":"data","description":"Work with table data, using a (now deprecated) columnar format. We now recommend the `records` endpoints."},{"name":"attachments","description":"Documents may include attached files. Data records can refer to these using a column of type `Attachments`."},{"name":"webhooks","description":"Document changes can trigger requests to URLs called webhooks."}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Authorization: Bearer XXXXXXXXXXX","description":"Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key."}},"schemas":{"Org":{"type":"object","required":["id","name","domain","owner","createdAt","updatedAt","access"],"properties":{"id":{"type":"integer","format":"int64","example":42},"name":{"type":"string","example":"Grist Labs"},"domain":{"type":"string","nullable":true,"example":"gristlabs"},"owner":{"type":"object","$ref":"#/components/schemas/User","nullable":true},"access":{"type":"string","$ref":"#/components/schemas/Access"},"createdAt":{"type":"string","example":"2019-09-13T15:42:35.000Z"},"updatedAt":{"type":"string","example":"2019-09-13T15:42:35.000Z"}}},"Orgs":{"type":"array","items":{"$ref":"#/components/schemas/Org"}},"Webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"},"fields":{"$ref":"#/components/schemas/WebhookFields"},"usage":{"$ref":"#/components/schemas/WebhookUsage"}}},"WebhookFields":{"allOf":[{"$ref":"#/components/schemas/WebhookPartialFields"},{"$ref":"#/components/schemas/WebhookRequiredFields"}]},"WebhookRequiredFields":{"type":"object","required":["name","memo","url","enabled","unsubscribeKey","eventTypes","isReadyColumn","tableId"],"properties":{"unsubscribeKey":{"type":"string"}}},"WebhookPartialFields":{"type":"object","properties":{"name":{"type":"string","example":"new-project-email","nullable":true},"memo":{"type":"string","example":"Send an email when a project is added","nullable":true},"url":{"type":"string","format":"uri","example":"https://example.com/webhook/123"},"enabled":{"type":"boolean"},"eventTypes":{"type":"array","items":{"type":"string"},"example":["add","update"]},"isReadyColumn":{"type":"string","nullable":true,"example":null},"tableId":{"type":"string","example":"Projects"}}},"WebhookUsage":{"type":"object","nullable":true,"required":["numWaiting","status"],"properties":{"numWaiting":{"type":"integer"},"status":{"type":"string","example":"idle"},"updatedTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastSuccessTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastFailureTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastErrorMessage":{"type":"string","nullable":true,"example":null},"lastHttpStatus":{"type":"number","nullable":true,"example":200},"lastEventBatch":{"$ref":"#/components/schemas/WebhookBatchStatus"}}},"WebhookBatchStatus":{"type":"object","nullable":true,"required":["size","attempts","status"],"properties":{"size":{"type":"number","example":1},"attempts":{"type":"number","example":1},"errorMessage":{"type":"string","nullable":true,"example":null},"httpStatus":{"type":"number","example":200},"status":{"type":"string","example":"success"}}},"WebhookId":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Webhook identifier","example":"xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"}}},"WebhookRequiredProperties":{"type":"object","required":["size"],"properties":{"size":{"type":"number","example":1}}},"WebhookProperties":{"size":{"type":"number","example":1},"attempts":{"type":"number","example":1},"errorMessage":{"type":"string","nullable":true,"example":null},"httpStatus":{"type":"number","example":200},"status":{"type":"string","example":"success"}},"Workspace":{"type":"object","required":["id","name","access"],"properties":{"id":{"type":"integer","format":"int64","example":97},"name":{"type":"string","example":"Secret Plans"},"access":{"type":"string","$ref":"#/components/schemas/Access"}}},"Doc":{"type":"object","required":["id","name","isPinned","urlId","access"],"properties":{"id":{"type":"string","example":145},"name":{"type":"string","example":"Project Lollipop"},"access":{"type":"string","$ref":"#/components/schemas/Access"},"isPinned":{"type":"boolean","example":true},"urlId":{"type":"string","nullable":true,"example":null}}},"WorkspaceWithDocs":{"allOf":[{"$ref":"#/components/schemas/Workspace"},{"type":"object","required":["docs"],"properties":{"docs":{"type":"array","items":{"$ref":"#/components/schemas/Doc"}}}}]},"WorkspaceWithDocsAndDomain":{"allOf":[{"$ref":"#/components/schemas/WorkspaceWithDocs"},{"type":"object","properties":{"orgDomain":{"type":"string","example":"gristlabs"}}}]},"WorkspaceWithOrg":{"allOf":[{"$ref":"#/components/schemas/Workspace"},{"type":"object","required":["org"],"properties":{"org":{"$ref":"#/components/schemas/Org"}}}]},"WorkspaceWithDocsAndOrg":{"allOf":[{"$ref":"#/components/schemas/WorkspaceWithDocs"},{"$ref":"#/components/schemas/WorkspaceWithOrg"}]},"DocWithWorkspace":{"allOf":[{"$ref":"#/components/schemas/Doc"},{"type":"object","required":["workspace"],"properties":{"workspace":{"$ref":"#/components/schemas/WorkspaceWithOrg"}}}]},"User":{"type":"object","required":["id","name","picture"],"properties":{"id":{"type":"integer","format":"int64","example":101},"name":{"type":"string","example":"Helga Hufflepuff"},"picture":{"type":"string","nullable":true,"example":null}}},"Access":{"type":"string","enum":["owners","editors","viewers"]},"Data":{"type":"object","required":["id"],"properties":{"id":{"type":"array","items":{"type":"integer"}}},"additionalProperties":{"type":"array","items":{"type":"object"}},"example":{"id":[1,2],"pet":["cat","dog"],"popularity":[67,95]}},"DataWithoutId":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}},"example":{"pet":["cat","dog"],"popularity":[67,95]}},"RecordsList":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"number","example":1},"fields":{"type":"object","description":"A JSON object mapping column names to [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues)."}}}}},"example":{"records":[{"id":1,"fields":{"pet":"cat","popularity":67}},{"id":2,"fields":{"pet":"dog","popularity":95}}]}},"RecordsWithoutId":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"type":"object","description":"A JSON object mapping column names to [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues)."}}}}},"example":{"records":[{"fields":{"pet":"cat","popularity":67}},{"fields":{"pet":"dog","popularity":95}}]}},"RecordsWithoutFields":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"number","example":1}}}}},"example":{"records":[{"id":1},{"id":2}]}},"RecordsWithRequire":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["require"],"properties":{"require":{"type":"object","description":"keys are column identifiers, and values are [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues) we want to have in those columns (either by matching with an existing record, or creating a new record)\n"},"fields":{"type":"object","description":"keys are column identifiers, and values are [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues) to place in those columns (either overwriting values in an existing record, or in a new record)\n"}}}}},"example":{"records":[{"require":{"pet":"cat"},"fields":{"popularity":67}},{"require":{"pet":"dog"},"fields":{"popularity":95}}]}},"TablesList":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"string","example":"Table1"},"fields":{"type":"object"}}}}},"example":{"tables":[{"id":"People","fields":{"tableRef":1,"onDemand":true}},{"id":"Places","fields":{"tableRef":2,"onDemand":false}}]}},"TablesWithoutFields":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"Table1"}}}}},"example":{"tables":[{"id":"People"},{"id":"Places"}]}},"CreateTables":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["columns"],"properties":{"id":{"type":"string","example":"Table1"},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ColumnName"},"fields":{"type":"object"}}}}}}}},"example":{"tables":[{"id":"People","columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤"}}]}]}},"ColumnsList":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ColumnName"},"fields":{"$ref":"#/components/schemas/GetFields"}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}}]}},"CreateColumns":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Column identifier"},"fields":{"$ref":"#/components/schemas/CreateFields"}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}},{"id":"Order","fields":{"type":"Ref:Orders","visibleCol":2}},{"id":"Formula","fields":{"type":"Int","formula":"$A + $B","isFormula":true}},{"id":"Status","fields":{"type":"Choice","widgetOptions":"{\"choices\":[\"New\",\"Old\"],\"choiceOptions\":{\"New\":{\"fillColor\":\"#FF0000\",\"textColor\":\"#FFFFFF\"}}}"}}]}},"UpdateColumns":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"string","description":"Column identifier"},"fields":{"allOf":[{"$ref":"#/components/schemas/CreateFields"},{"type":"object","properties":{"colId":{"type":"string","description":"Set it to the new column ID when you want to change it."}}}]}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}}]}},"ColumnsWithoutFields":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"ColumnName"}}}}},"example":{"columns":[{"id":"pet"},{"id":"popularity"}]}},"Fields":{"type":"object","properties":{"type":{"type":"string","description":"Column type, by default Any. Ref, RefList and DateTime types requires a postfix, e.g. <code>DateTime:America/New_York</code>, <code>Ref:Users</code>","enum":["Any","Text","Numeric","Int","Bool","Date","DateTime:<timezone>","Choice","ChoiceList","Ref:<tableId>","RefList:<tableId>","Attachments"]},"label":{"type":"string","description":"Column label."},"formula":{"type":"string","description":"A python formula, e.g.: <code>$A + Table1.lookupOne(B=$B)</code>"},"isFormula":{"type":"boolean","description":"Use \"true\" to indicate that the column is a formula column. Use \"false\" for trigger formula column."},"widgetOptions":{"type":"string","description":"A JSON object with widget options, e.g.: <code>{\"choices\": [\"cat\", \"dog\"], \"alignment\": \"right\"}</code>"},"untieColIdFromLabel":{"type":"boolean","description":"Use \"true\" to indicate that the column label should not be used as the column identifier. Use \"false\" to use the label as the identifier."},"recalcWhen":{"type":"integer","description":"A number indicating when the column should be recalculated. <ol start='0'><li>On new records or when any field in recalcDeps changes, it's a 'data-cleaning'.</li><li>Never.</li><li>Calculate on new records and on manual updates to any data field.</li></ol>"},"visibleCol":{"type":"integer","description":"For Ref and RefList columns, the colRef of a column to display"}}},"CreateFields":{"allOf":[{"$ref":"#/components/schemas/Fields"},{"type":"object","properties":{"recalcDeps":{"type":"string","description":"An encoded array of column identifiers (colRefs) that this column depends on. If any of these columns change, the column will be recalculated. E.g.: <code>[2, 3]</code>"}}}]},"GetFields":{"allOf":[{"$ref":"#/components/schemas/Fields"},{"type":"object","properties":{"recalcDeps":{"type":"array","items":{"type":"integer"},"description":"An array of column identifiers (colRefs) that this column depends on, prefixed with \"L\" constant. If any of these columns change, the column will be recalculated. E.g.: <code>[\"L\", 2, 3]</code>"},"colRef":{"type":"integer","description":"Column reference, e.g.: <code>2</code>"}}}]},"RowIds":{"type":"array","example":[101,102,103],"items":{"type":"integer"}},"DocParameters":{"type":"object","properties":{"name":{"type":"string","example":"Competitive Analysis"},"isPinned":{"type":"boolean","example":false}}},"WorkspaceParameters":{"type":"object","properties":{"name":{"type":"string","example":"Retreat Docs"}}},"OrgParameters":{"type":"object","properties":{"name":{"type":"string","example":"ACME Unlimited"}}},"OrgAccessRead":{"type":"object","required":["users"],"properties":{"users":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Andrea"},"email":{"type":"string","example":"andrea@getgrist.com"},"access":{"$ref":"#/components/schemas/Access"}}}}}},"OrgAccessWrite":{"type":"object","required":["users"],"properties":{"users":{"type":"object","additionalProperties":{"type":"string","enum":["owners","editors","viewers","members",null]},"example":{"foo@getgrist.com":"owners","bar@getgrist.com":null}}}},"WorkspaceAccessRead":{"type":"object","required":["maxInheritedRole","users"],"properties":{"maxInheritedRole":{"$ref":"#/components/schemas/Access"},"users":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Andrea"},"email":{"type":"string","example":"andrea@getgrist.com"},"access":{"$ref":"#/components/schemas/Access"},"parentAccess":{"$ref":"#/components/schemas/Access"}}}}}},"WorkspaceAccessWrite":{"type":"object","properties":{"maxInheritedRole":{"$ref":"#/components/schemas/Access"},"users":{"type":"object","additionalProperties":{"type":"string","enum":["owners","editors","viewers","members",null]},"example":{"foo@getgrist.com":"owners","bar@getgrist.com":null}}}},"DocAccessWrite":{"$ref":"#/components/schemas/WorkspaceAccessWrite"},"DocAccessRead":{"$ref":"#/components/schemas/WorkspaceAccessRead"},"AttachmentUpload":{"type":"object","properties":{"upload":{"type":"array","items":{"type":"string","format":"binary"}}}},"AttachmentId":{"type":"number","description":"An integer ID"},"AttachmentMetadata":{"type":"object","properties":{"fileName":{"type":"string","example":"logo.png"},"fileSize":{"type":"number","example":12345},"timeUploaded":{"type":"string","example":"2020-02-13T12:17:19.000Z"}}},"AttachmentMetadataList":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"number","example":1},"fields":{"$ref":"#/components/schemas/AttachmentMetadata"}}}}}},"SqlResultSet":{"type":"object","required":["statement","records"],"properties":{"statement":{"type":"string","description":"A copy of the SQL statement.","example":"select * from Pets ..."},"records":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"type":"object"}}},"example":[{"fields":{"id":1,"pet":"cat","popularity":67}},{"fields":{"id":2,"pet":"dog","popularity":95}}]}}},"TableSchemaResult":{"type":"object","required":["name","title","schema"],"properties":{"name":{"type":"string","description":"The ID (technical name) of the table"},"title":{"type":"string","description":"The human readable name of the table"},"path":{"type":"string","description":"The URL to download the CSV","example":"https://getgrist.com/o/docs/api/docs/ID/download/csv?tableId=Table1&...."},"format":{"type":"string","enum":["csv"]},"mediatype":{"type":"string","enum":["text/csv"]},"encoding":{"type":"string","enum":["utf-8"]},"dialect":{"$ref":"#/components/schemas/csv-dialect"},"schema":{"$ref":"#/components/schemas/table-schema"}}},"csv-dialect":{"$schema":"http://json-schema.org/draft-04/schema#","title":"CSV Dialect","description":"The CSV dialect descriptor.","type":["string","object"],"required":["delimiter","doubleQuote"],"properties":{"csvddfVersion":{"title":"CSV Dialect schema version","description":"A number to indicate the schema version of CSV Dialect. Version 1.0 was named CSV Dialect Description Format and used different field names.","type":"number","default":1.2,"examples:":["{\n  \"csvddfVersion\": \"1.2\"\n}\n"]},"delimiter":{"title":"Delimiter","description":"A character sequence to use as the field separator.","type":"string","default":",","examples":["{\n  \"delimiter\": \",\"\n}\n","{\n  \"delimiter\": \";\"\n}\n"]},"doubleQuote":{"title":"Double Quote","description":"Specifies the handling of quotes inside fields.","context":"If Double Quote is set to true, two consecutive quotes must be interpreted as one.","type":"boolean","default":true,"examples":["{\n  \"doubleQuote\": true\n}\n"]},"lineTerminator":{"title":"Line Terminator","description":"Specifies the character sequence that must be used to terminate rows.","type":"string","default":"\r\n","examples":["{\n  \"lineTerminator\": \"\\r\\n\"\n}\n","{\n  \"lineTerminator\": \"\\n\"\n}\n"]},"nullSequence":{"title":"Null Sequence","description":"Specifies the null sequence, for example, `\\N`.","type":"string","examples":["{\n  \"nullSequence\": \"\\N\"\n}\n"]},"quoteChar":{"title":"Quote Character","description":"Specifies a one-character string to use as the quoting character.","type":"string","default":"\"","examples":["{\n  \"quoteChar\": \"'\"\n}\n"]},"escapeChar":{"title":"Escape Character","description":"Specifies a one-character string to use as the escape character.","type":"string","examples":["{\n  \"escapeChar\": \"\\\\\"\n}\n"]},"skipInitialSpace":{"title":"Skip Initial Space","description":"Specifies the interpretation of whitespace immediately following a delimiter. If false, whitespace immediately after a delimiter should be treated as part of the subsequent field.","type":"boolean","default":false,"examples":["{\n  \"skipInitialSpace\": true\n}\n"]},"header":{"title":"Header","description":"Specifies if the file includes a header row, always as the first row in the file.","type":"boolean","default":true,"examples":["{\n  \"header\": true\n}\n"]},"commentChar":{"title":"Comment Character","description":"Specifies that any row beginning with this one-character string, without preceeding whitespace, causes the entire line to be ignored.","type":"string","examples":["{\n  \"commentChar\": \"#\"\n}\n"]},"caseSensitiveHeader":{"title":"Case Sensitive Header","description":"Specifies if the case of headers is meaningful.","context":"Use of case in source CSV files is not always an intentional decision. For example, should \"CAT\" and \"Cat\" be considered to have the same meaning.","type":"boolean","default":false,"examples":["{\n  \"caseSensitiveHeader\": true\n}\n"]}},"examples":["{\n  \"dialect\": {\n    \"delimiter\": \";\"\n  }\n}\n","{\n  \"dialect\": {\n    \"delimiter\": \"\\t\",\n    \"quoteChar\": \"'\",\n    \"commentChar\": \"#\"\n  }\n}\n"]},"table-schema":{"$schema":"http://json-schema.org/draft-04/schema#","title":"Table Schema","description":"A Table Schema for this resource, compliant with the [Table Schema](/tableschema/) specification.","type":["string","object"],"required":["fields"],"properties":{"fields":{"type":"array","minItems":1,"items":{"title":"Table Schema Field","type":"object","oneOf":[{"type":"object","title":"String Field","description":"The field contains strings, that is, sequences of characters.","required":["name"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `string`.","enum":["string"]},"format":{"description":"The format keyword options for `string` are `default`, `email`, `uri`, `binary`, and `uuid`.","context":"The following `format` options are supported:\n  * **default**: any valid string.\n  * **email**: A valid email address.\n  * **uri**: A valid URI.\n  * **binary**: A base64 encoded string representing binary data.\n  * **uuid**: A string that is a uuid.","enum":["default","email","uri","binary","uuid"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `string` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"pattern":{"type":"string","description":"A regular expression pattern to test each value of the property against, where a truthy response indicates validity.","context":"Regular expressions `SHOULD` conform to the [XML Schema regular expression syntax](http://www.w3.org/TR/xmlschema-2/#regexs)."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"name\",\n  \"type\": \"string\"\n}\n","{\n  \"name\": \"name\",\n  \"type\": \"string\",\n  \"format\": \"email\"\n}\n","{\n  \"name\": \"name\",\n  \"type\": \"string\",\n  \"constraints\": {\n    \"minLength\": 3,\n    \"maxLength\": 35\n  }\n}\n"]},{"type":"object","title":"Number Field","description":"The field contains numbers of any kind including decimals.","context":"The lexical formatting follows that of decimal in [XMLSchema](https://www.w3.org/TR/xmlschema-2/#decimal): a non-empty finite-length sequence of decimal digits separated by a period as a decimal indicator. An optional leading sign is allowed. If the sign is omitted, '+' is assumed. Leading and trailing zeroes are optional. If the fractional part is zero, the period and following zero(es) can be omitted. For example: '-1.23', '12678967.543233', '+100000.00', '210'.\n\nThe following special string values are permitted (case does not need to be respected):\n  - NaN: not a number\n  - INF: positive infinity\n  - -INF: negative infinity\n\nA number `MAY` also have a trailing:\n  - exponent: this `MUST` consist of an E followed by an optional + or - sign followed by one or more decimal digits (0-9)\n  - percentage: the percentage sign: `%`. In conversion percentages should be divided by 100.\n\nIf both exponent and percentages are present the percentage `MUST` follow the exponent e.g. '53E10%' (equals 5.3).","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `number`.","enum":["number"]},"format":{"description":"There are no format keyword options for `number`: only `default` is allowed.","enum":["default"],"default":"default"},"bareNumber":{"type":"boolean","title":"bareNumber","description":"a boolean field with a default of `true`. If `true` the physical contents of this field must follow the formatting constraints already set out. If `false` the contents of this field may contain leading and/or trailing non-numeric characters (which implementors MUST therefore strip). The purpose of `bareNumber` is to allow publishers to publish numeric data that contains trailing characters such as percentages e.g. `95%` or leading characters such as currencies e.g. `€95` or `EUR 95`. Note that it is entirely up to implementors what, if anything, they do with stripped text.","default":true},"decimalChar":{"type":"string","description":"A string whose value is used to represent a decimal point within the number. The default value is `.`."},"groupChar":{"type":"string","description":"A string whose value is used to group digits within the number. The default value is `null`. A common value is `,` e.g. '100,000'."},"constraints":{"title":"Constraints","description":"The following constraints are supported for `number` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"number"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"number"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"number"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"field-name\",\n  \"type\": \"number\"\n}\n","{\n  \"name\": \"field-name\",\n  \"type\": \"number\",\n  \"constraints\": {\n    \"enum\": [ \"1.00\", \"1.50\", \"2.00\" ]\n  }\n}\n"]},{"type":"object","title":"Integer Field","description":"The field contains integers - that is whole numbers.","context":"Integer values are indicated in the standard way for any valid integer.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `integer`.","enum":["integer"]},"format":{"description":"There are no format keyword options for `integer`: only `default` is allowed.","enum":["default"],"default":"default"},"bareNumber":{"type":"boolean","title":"bareNumber","description":"a boolean field with a default of `true`. If `true` the physical contents of this field must follow the formatting constraints already set out. If `false` the contents of this field may contain leading and/or trailing non-numeric characters (which implementors MUST therefore strip). The purpose of `bareNumber` is to allow publishers to publish numeric data that contains trailing characters such as percentages e.g. `95%` or leading characters such as currencies e.g. `€95` or `EUR 95`. Note that it is entirely up to implementors what, if anything, they do with stripped text.","default":true},"constraints":{"title":"Constraints","description":"The following constraints are supported for `integer` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"integer"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"integer"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"age\",\n  \"type\": \"integer\",\n  \"constraints\": {\n    \"unique\": true,\n    \"minimum\": 100,\n    \"maximum\": 9999\n  }\n}\n"]},{"type":"object","title":"Date Field","description":"The field contains temporal date values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `date`.","enum":["date"]},"format":{"description":"The format keyword options for `date` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string of YYYY-MM-DD.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `date` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\"\n}\n","{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\",\n  \"constraints\": {\n    \"minimum\": \"01-01-1900\"\n  }\n}\n","{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\",\n  \"format\": \"MM-DD-YYYY\"\n}\n"]},{"type":"object","title":"Time Field","description":"The field contains temporal time values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `time`.","enum":["time"]},"format":{"description":"The format keyword options for `time` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string for time.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `time` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"appointment_start\",\n  \"type\": \"time\"\n}\n","{\n  \"name\": \"appointment_start\",\n  \"type\": \"time\",\n  \"format\": \"any\"\n}\n"]},{"type":"object","title":"Date Time Field","description":"The field contains temporal datetime values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `datetime`.","enum":["datetime"]},"format":{"description":"The format keyword options for `datetime` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string for datetime.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `datetime` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"timestamp\",\n  \"type\": \"datetime\"\n}\n","{\n  \"name\": \"timestamp\",\n  \"type\": \"datetime\",\n  \"format\": \"default\"\n}\n"]},{"type":"object","title":"Year Field","description":"A calendar year, being an integer with 4 digits. Equivalent to [gYear in XML Schema](https://www.w3.org/TR/xmlschema-2/#gYear)","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `year`.","enum":["year"]},"format":{"description":"There are no format keyword options for `year`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `year` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"integer"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"integer"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"year\",\n  \"type\": \"year\"\n}\n","{\n  \"name\": \"year\",\n  \"type\": \"year\",\n  \"constraints\": {\n    \"minimum\": 1970,\n    \"maximum\": 2003\n  }\n}\n"]},{"type":"object","title":"Year Month Field","description":"A calendar year month, being an integer with 1 or 2 digits. Equivalent to [gYearMonth in XML Schema](https://www.w3.org/TR/xmlschema-2/#gYearMonth)","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `yearmonth`.","enum":["yearmonth"]},"format":{"description":"There are no format keyword options for `yearmonth`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `yearmonth` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"month\",\n  \"type\": \"yearmonth\"\n}\n","{\n  \"name\": \"month\",\n  \"type\": \"yearmonth\",\n  \"constraints\": {\n    \"minimum\": 1,\n    \"maximum\": 6\n  }\n}\n"]},{"type":"object","title":"Boolean Field","description":"The field contains boolean (true/false) data.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `boolean`.","enum":["boolean"]},"format":{"description":"There are no format keyword options for `boolean`: only `default` is allowed.","enum":["default"],"default":"default"},"trueValues":{"type":"array","minItems":1,"items":{"type":"string"},"default":["true","True","TRUE","1"]},"falseValues":{"type":"array","minItems":1,"items":{"type":"string"},"default":["false","False","FALSE","0"]},"constraints":{"title":"Constraints","description":"The following constraints are supported for `boolean` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"boolean"}}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"registered\",\n  \"type\": \"boolean\"\n}\n"]},{"type":"object","title":"Object Field","description":"The field contains data which can be parsed as a valid JSON object.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `object`.","enum":["object"]},"format":{"description":"There are no format keyword options for `object`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints apply for `object` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"extra\"\n  \"type\": \"object\"\n}\n"]},{"type":"object","title":"GeoPoint Field","description":"The field contains data describing a geographic point.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `geopoint`.","enum":["geopoint"]},"format":{"description":"The format keyword options for `geopoint` are `default`,`array`, and `object`.","context":"The following `format` options are supported:\n  * **default**: A string of the pattern 'lon, lat', where `lon` is the longitude and `lat` is the latitude.\n  * **array**: An array of exactly two items, where each item is either a number, or a string parsable as a number, and the first item is `lon` and the second item is `lat`.\n  * **object**: A JSON object with exactly two keys, `lat` and `lon`","notes":["Implementations `MUST` strip all white space in the default format of `lon, lat`."],"enum":["default","array","object"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `geopoint` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"array"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"post_office\",\n  \"type\": \"geopoint\"\n}\n","{\n  \"name\": \"post_office\",\n  \"type\": \"geopoint\",\n  \"format\": \"array\"\n}\n"]},{"type":"object","title":"GeoJSON Field","description":"The field contains a JSON object according to GeoJSON or TopoJSON","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `geojson`.","enum":["geojson"]},"format":{"description":"The format keyword options for `geojson` are `default` and `topojson`.","context":"The following `format` options are supported:\n  * **default**: A geojson object as per the [GeoJSON spec](http://geojson.org/).\n  * **topojson**: A topojson object as per the [TopoJSON spec](https://github.com/topojson/topojson-specification/blob/master/README.md)","enum":["default","topojson"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `geojson` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"city_limits\",\n  \"type\": \"geojson\"\n}\n","{\n  \"name\": \"city_limits\",\n  \"type\": \"geojson\",\n  \"format\": \"topojson\"\n}\n"]},{"type":"object","title":"Array Field","description":"The field contains data which can be parsed as a valid JSON array.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `array`.","enum":["array"]},"format":{"description":"There are no format keyword options for `array`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints apply for `array` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"array"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"options\"\n  \"type\": \"array\"\n}\n"]},{"type":"object","title":"Duration Field","description":"The field contains a duration of time.","context":"The lexical representation for duration is the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) extended format `PnYnMnDTnHnMnS`, where `nY` represents the number of years, `nM` the number of months, `nD` the number of days, 'T' is the date/time separator, `nH` the number of hours, `nM` the number of minutes and `nS` the number of seconds. The number of seconds can include decimal digits to arbitrary precision. Date and time elements including their designator may be omitted if their value is zero, and lower order elements may also be omitted for reduced precision. Here we follow the definition of [XML Schema duration datatype](http://www.w3.org/TR/xmlschema-2/#duration) directly and that definition is implicitly inlined here.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `duration`.","enum":["duration"]},"format":{"description":"There are no format keyword options for `duration`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `duration` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"period\"\n  \"type\": \"duration\"\n}\n"]},{"type":"object","title":"Any Field","description":"Any value is accepted, including values that are not captured by the type/format/constraint requirements of the specification.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `any`.","enum":["any"]},"constraints":{"title":"Constraints","description":"The following constraints apply to `any` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"notes\",\n  \"type\": \"any\"\n"]}]},"description":"An `array` of Table Schema Field objects.","examples":["{\n  \"fields\": [\n    {\n      \"name\": \"my-field-name\"\n    }\n  ]\n}\n","{\n  \"fields\": [\n    {\n      \"name\": \"my-field-name\",\n      \"type\": \"number\"\n    },\n    {\n      \"name\": \"my-field-name-2\",\n      \"type\": \"string\",\n      \"format\": \"email\"\n    }\n  ]\n}\n"]},"primaryKey":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"string"}],"description":"A primary key is a field name or an array of field names, whose values `MUST` uniquely identify each row in the table.","context":"Field name in the `primaryKey` `MUST` be unique, and `MUST` match a field name in the associated table. It is acceptable to have an array with a single value, indicating that the value of a single field is the primary key.","examples":["{\n  \"primaryKey\": [\n    \"name\"\n  ]\n}\n","{\n  \"primaryKey\": [\n    \"first_name\",\n    \"last_name\"\n  ]\n}\n"]},"foreignKeys":{"type":"array","minItems":1,"items":{"title":"Table Schema Foreign Key","description":"Table Schema Foreign Key","type":"object","required":["fields","reference"],"oneOf":[{"properties":{"fields":{"type":"array","items":{"type":"string","minItems":1,"uniqueItems":true,"description":"Fields that make up the primary key."}},"reference":{"type":"object","required":["resource","fields"],"properties":{"resource":{"type":"string","default":""},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true}}}}},{"properties":{"fields":{"type":"string","description":"Fields that make up the primary key."},"reference":{"type":"object","required":["resource","fields"],"properties":{"resource":{"type":"string","default":""},"fields":{"type":"string"}}}}}]},"examples":["{\n  \"foreignKeys\": [\n    {\n      \"fields\": \"state\",\n      \"reference\": {\n        \"resource\": \"the-resource\",\n        \"fields\": \"state_id\"\n      }\n    }\n  ]\n}\n","{\n  \"foreignKeys\": [\n    {\n      \"fields\": \"state\",\n      \"reference\": {\n        \"resource\": \"\",\n        \"fields\": \"id\"\n      }\n    }\n  ]\n}\n"]},"missingValues":{"type":"array","items":{"type":"string"},"default":[""],"description":"Values that when encountered in the source, should be considered as `null`, 'not present', or 'blank' values.","context":"Many datasets arrive with missing data values, either because a value was not collected or it never existed.\nMissing values may be indicated simply by the value being empty in other cases a special value may have been used e.g. `-`, `NaN`, `0`, `-9999` etc.\nThe `missingValues` property provides a way to indicate that these values should be interpreted as equivalent to null.\n\n`missingValues` are strings rather than being the data type of the particular field. This allows for comparison prior to casting and for fields to have missing value which are not of their type, for example a `number` field to have missing values indicated by `-`.\n\nThe default value of `missingValue` for a non-string type field is the empty string `''`. For string type fields there is no default for `missingValue` (for string fields the empty string `''` is a valid value and need not indicate null).","examples":["{\n  \"missingValues\": [\n    \"-\",\n    \"NaN\",\n    \"\"\n  ]\n}\n","{\n  \"missingValues\": []\n}\n"]}},"examples":["{\n  \"schema\": {\n    \"fields\": [\n      {\n        \"name\": \"first_name\",\n        \"type\": \"string\"\n        \"constraints\": {\n          \"required\": true\n        }\n      },\n      {\n        \"name\": \"age\",\n        \"type\": \"integer\"\n      },\n    ],\n    \"primaryKey\": [\n      \"name\"\n    ]\n  }\n}\n"]}},"parameters":{"filterQueryParam":{"in":"query","name":"filter","schema":{"type":"string"},"description":"This is a JSON object mapping column names to arrays of allowed values.  For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{\"pet\": [\"cat\", \"dog\"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them.  For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{\"pet\": [\"cat\", \"dog\"], \"size\": [\"tiny\", \"outrageously small\"]}`.","example":"{\"pet\": [\"cat\", \"dog\"]}","required":false},"sortQueryParam":{"in":"query","name":"sort","schema":{"type":"string"},"description":"Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyFirst,owner`). Available options are: `choiceOrder`, `naturalSort`, `emptyFirst`. Without the `sort` parameter, the order of results is unspecified.","example":"pet,-age","required":false},"limitQueryParam":{"in":"query","name":"limit","schema":{"type":"number"},"description":"Return at most this number of rows.  A value of 0 is equivalent to having no limit.","example":"5","required":false},"sortHeaderParam":{"in":"header","name":"X-Sort","schema":{"type":"string"},"description":"Same as `sort` query parameter.","example":"pet,-age","required":false},"limitHeaderParam":{"in":"header","name":"X-Limit","schema":{"type":"number"},"description":"Same as `limit` query parameter.","example":"5","required":false},"colIdPathParam":{"in":"path","name":"colId","schema":{"type":"string"},"description":"The column id (without the starting `$`) as shown in the column configuration below the label","required":true},"tableIdPathParam":{"in":"path","name":"tableId","schema":{"type":"string"},"description":"normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`","required":true},"docIdPathParam":{"in":"path","name":"docId","schema":{"type":"string"},"description":"A string id (UUID)","required":true},"orgIdPathParam":{"in":"path","name":"orgId","schema":{"oneOf":[{"type":"integer"},{"type":"string"}]},"description":"This can be an integer id, or a string subdomain (e.g. `gristlabs`), or `current` if the org is implied by the domain in the url","required":true},"workspaceIdPathParam":{"in":"path","name":"workspaceId","description":"An integer id","schema":{"type":"integer"},"required":true},"noparseQueryParam":{"in":"query","name":"noparse","schema":{"type":"boolean"},"description":"Set to true to prohibit parsing strings according to the column type."},"hiddenQueryParam":{"in":"query","name":"hidden","schema":{"type":"boolean"},"description":"Set to true to include the hidden columns (like \"manualSort\")"},"headerQueryParam":{"in":"query","name":"header","schema":{"type":"string","enum":["colId","label"]},"description":"Format for headers. Labels tend to be more human-friendly while colIds are more normalized.","required":false}}}}},"searchIndex":{"store":["section/Authentication","tag/orgs","tag/orgs/operation/listOrgs","tag/orgs/operation/describeOrg","tag/orgs/operation/modifyOrg","tag/orgs/operation/listOrgAccess","tag/orgs/operation/modifyOrgAccess","tag/workspaces","tag/workspaces/operation/listWorkspaces","tag/workspaces/operation/createWorkspace","tag/workspaces/operation/describeWorkspace","tag/workspaces/operation/modifyWorkspace","tag/workspaces/operation/deleteWorkspace","tag/workspaces/operation/listWorkspaceAccess","tag/workspaces/operation/modifyWorkspaceAccess","tag/docs","tag/docs/operation/createDoc","tag/docs/operation/describeDoc","tag/docs/operation/modifyDoc","tag/docs/operation/deleteDoc","tag/docs/operation/moveDoc","tag/docs/operation/listDocAccess","tag/docs/operation/modifyDocAccess","tag/docs/operation/downloadDoc","tag/docs/operation/downloadDocXlsx","tag/docs/operation/downloadDocCsv","tag/docs/operation/downloadTableSchema","tag/records","tag/records/operation/listRecords","tag/records/operation/addRecords","tag/records/operation/modifyRecords","tag/records/operation/replaceRecords","tag/tables","tag/tables/operation/listTables","tag/tables/operation/addTables","tag/tables/operation/modifyTables","tag/columns","tag/columns/operation/listColumns","tag/columns/operation/addColumns","tag/columns/operation/modifyColumns","tag/columns/operation/replaceColumns","tag/columns/operation/deleteColumn","tag/data","tag/data/operation/getTableData","tag/data/operation/addRows","tag/data/operation/modifyRows","tag/data/operation/deleteRows","tag/attachments","tag/attachments/operation/listAttachments","tag/attachments/operation/uploadAttachments","tag/attachments/operation/getAttachmentMetadata","tag/attachments/operation/downloadAttachment","tag/webhooks","tag/webhooks/paths/~1docs~1{docId}~1webhooks/get","tag/webhooks/paths/~1docs~1{docId}~1webhooks/post","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1{webhookId}/patch","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1{webhookId}/delete","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1queue/delete","tag/sql","tag/sql/paths/~1docs~1{docId}~1sql/get","tag/sql/paths/~1docs~1{docId}~1sql/post"],"index":{"version":"2.3.9","fields":["title","description"],"fieldVectors":[["title/0",[0,5.068]],["description/0",[1,4.208,2,4.208]],["title/1",[3,2.418]],["description/1",[3,1.097,4,1.984,5,1.776,6,1.984,7,2.3,8,1.621,9,2.3]],["title/2",[3,1.739,10,1.946,11,2.068]],["description/2",[3,1.097,4,1.984,5,1.776,6,1.984,12,2.3,13,2.3,14,2.3]],["title/3",[3,2.023,15,3.275]],["description/3",[16,4.353]],["title/4",[3,2.023,17,2.264]],["description/4",[16,4.353]],["title/5",[3,1.525,10,1.706,11,1.814,18,2.468]],["description/5",[19,4.353]],["title/6",[3,1.739,11,2.068,20,2.569]],["description/6",[19,4.353]],["title/7",[21,2.294]],["description/7",[5,1.953,8,1.782,21,1.145,22,2.529,23,2.529,24,0.689]],["title/8",[3,1.358,10,1.519,21,1.288,24,0.775,25,2.845]],["description/8",[26,4.353]],["title/9",[21,1.65,27,2.815,28,2.815]],["description/9",[26,4.353]],["title/10",[15,3.275,21,1.919]],["description/10",[29,3.896]],["title/11",[17,2.264,21,1.919]],["description/11",[29,3.896]],["title/12",[21,1.919,30,2.988]],["description/12",[29,3.896]],["title/13",[10,1.706,11,1.814,18,2.468,21,1.447]],["description/13",[31,4.353]],["title/14",[11,2.068,20,2.569,21,1.65]],["description/14",[31,4.353]],["title/15",[32,3.914]],["description/15",[21,1.272,24,0.765,33,2.424,34,1.98,35,2.809]],["title/16",[24,0.993,27,2.815,28,2.815]],["description/16",[36,5.045]],["title/17",[15,3.275,24,1.155]],["description/17",[37,3.896]],["title/18",[17,1.706,24,0.87,38,2.468,39,2.08]],["description/18",[37,3.896]],["title/19",[24,1.155,30,2.988]],["description/19",[37,3.896]],["title/20",[3,1.223,21,1.161,24,0.698,40,2.564,41,2.564,42,2.564]],["description/20",[43,5.045]],["title/21",[10,1.706,11,1.814,18,2.468,24,0.87]],["description/21",[44,4.353]],["title/22",[11,2.068,20,2.569,24,0.993]],["description/22",[44,4.353]],["title/23",[24,0.87,39,2.08,45,3.196,46,2.252]],["description/23",[47,5.045]],["title/24",[24,0.87,39,2.08,46,2.252,48,3.196]],["description/24",[49,5.045]],["title/25",[39,2.08,46,2.252,50,0.833,51,3.196]],["description/25",[52,5.045]],["title/26",[50,1.105,53,3.658]],["description/26",[53,2.182,54,2.529,55,2.529,56,2.529,57,2.529,58,2.529]],["title/27",[59,2.294]],["description/27",[8,1.782,33,2.182,34,1.782,50,0.659,59,1.145,60,1.782]],["title/28",[50,0.95,59,1.65,61,3.144]],["description/28",[62,3.556]],["title/29",[50,0.95,59,1.65,63,2.209]],["description/29",[62,3.556]],["title/30",[17,1.946,50,0.95,59,1.65]],["description/30",[62,3.556]],["title/31",[50,0.833,59,1.447,63,1.937,64,2.757]],["description/31",[62,3.556]],["title/32",[50,1.321]],["description/32",[24,0.86,34,2.227,50,0.823,65,2.726]],["title/33",[10,1.946,24,0.993,50,0.95]],["description/33",[66,3.896]],["title/34",[24,0.993,50,0.95,63,2.209]],["description/34",[66,3.896]],["title/35",[17,1.946,24,0.993,50,0.95]],["description/35",[66,3.896]],["title/36",[67,2.706]],["description/36",[34,2.227,50,0.823,65,2.726,67,1.687]],["title/37",[10,1.946,50,0.95,67,1.946]],["description/37",[68,3.556]],["title/38",[50,0.95,63,2.209,67,1.946]],["description/38",[68,3.556]],["title/39",[17,1.946,50,0.95,67,1.946]],["description/39",[68,3.556]],["title/40",[50,0.833,63,1.937,64,2.757,67,1.706]],["description/40",[68,3.556]],["title/41",[30,2.569,50,0.95,67,1.946]],["description/41",[69,5.045]],["title/42",[70,3.572]],["description/42",[50,0.412,59,0.716,70,1.115,71,1.582,72,1.365,73,2.652,74,1.115,75,1.582,76,1.582,77,1.582,78,1.115]],["title/43",[50,0.95,61,3.144,70,2.569]],["description/43",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/44",[50,0.95,60,2.569,63,2.209]],["description/44",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/45",[17,1.946,50,0.95,60,2.569]],["description/45",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/46",[30,2.569,50,0.95,60,2.569]],["description/46",[90,5.045]],["title/47",[91,3.071]],["description/47",[24,0.46,46,1.189,59,0.764,67,0.901,70,1.189,72,1.456,91,1.696,92,1.687,93,1.687,94,1.687]],["title/48",[10,1.706,32,2.468,38,2.468,91,1.937]],["description/48",[95,4.353]],["title/49",[32,2.815,91,2.209,96,3.645]],["description/49",[95,4.353]],["title/50",[38,3.275,91,2.569]],["description/50",[97,5.045]],["title/51",[39,2.372,91,2.209,98,3.645]],["description/51",[99,5.045]],["title/52",[100,3.071]],["description/52",[8,1.621,20,1.621,24,0.626,100,1.394,101,2.3,102,2.3,103,2.3]],["title/53",[24,0.993,100,2.209,104,3.645]],["description/53",[105,4.353]],["title/54",[24,0.87,27,2.468,87,2.252,100,1.937]],["description/54",[105,4.353]],["title/55",[17,2.264,100,2.569]],["description/55",[106,4.353]],["title/56",[82,2.988,100,2.569]],["description/56",[106,4.353]],["title/57",[28,2.198,107,2.845,108,2.845,109,2.845,110,2.845]],["description/57",[111,5.045]],["title/58",[112,3.914]],["description/58",[]],["title/59",[24,0.775,112,2.198,113,2.455,114,2.455,115,2.455]],["description/59",[116,4.353]],["title/60",[24,0.636,112,1.802,113,2.013,114,2.013,115,2.013,117,2.334,118,2.334]],["description/60",[116,4.353]]],"invertedIndex":[["",{"_index":2,"title":{},"description":{"0":{}}}],["access",{"_index":11,"title":{"2":{},"5":{},"6":{},"13":{},"14":{},"21":{},"22":{}},"description":{}}],["add",{"_index":63,"title":{"29":{},"31":{},"34":{},"38":{},"40":{},"44":{}},"description":{}}],["against",{"_index":115,"title":{"59":{},"60":{}},"description":{}}],["anoth",{"_index":41,"title":{"20":{}},"description":{}}],["api",{"_index":9,"title":{},"description":{"1":{}}}],["area",{"_index":13,"title":{},"description":{"2":{}}}],["associ",{"_index":104,"title":{"53":{}},"description":{}}],["attach",{"_index":91,"title":{"47":{},"48":{},"49":{},"50":{},"51":{}},"description":{"47":{}}}],["authent",{"_index":0,"title":{"0":{}},"description":{}}],["avail",{"_index":14,"title":{},"description":{"2":{}}}],["better",{"_index":84,"title":{},"description":{"43":{},"44":{},"45":{}}}],["call",{"_index":8,"title":{},"description":{"1":{},"7":{},"27":{},"52":{}}}],["chang",{"_index":20,"title":{"6":{},"14":{},"22":{}},"description":{"52":{}}}],["collect",{"_index":34,"title":{},"description":{"15":{},"27":{},"32":{},"36":{}}}],["column",{"_index":67,"title":{"36":{},"37":{},"38":{},"39":{},"40":{},"41":{}},"description":{"36":{},"47":{}}}],["columnar",{"_index":75,"title":{},"description":{"42":{}}}],["consid",{"_index":83,"title":{},"description":{"43":{},"44":{},"45":{}}}],["contain",{"_index":33,"title":{},"description":{"15":{},"27":{}}}],["content",{"_index":39,"title":{"18":{},"23":{},"24":{},"25":{},"51":{}},"description":{}}],["creat",{"_index":27,"title":{"9":{},"16":{},"54":{}},"description":{}}],["csv",{"_index":51,"title":{"25":{}},"description":{}}],["data",{"_index":70,"title":{"42":{},"43":{}},"description":{"42":{},"47":{}}}],["delet",{"_index":30,"title":{"12":{},"19":{},"41":{},"46":{}},"description":{}}],["deprec",{"_index":74,"title":{},"description":{"42":{},"43":{},"44":{},"45":{}}}],["describ",{"_index":15,"title":{"3":{},"10":{},"17":{}},"description":{}}],["doc",{"_index":32,"title":{"15":{},"48":{},"49":{}},"description":{}}],["docs/{docid",{"_index":37,"title":{},"description":{"17":{},"18":{},"19":{}}}],["docs/{docid}/access",{"_index":44,"title":{},"description":{"21":{},"22":{}}}],["docs/{docid}/attach",{"_index":95,"title":{},"description":{"48":{},"49":{}}}],["docs/{docid}/attachments/{attachmentid",{"_index":97,"title":{},"description":{"50":{}}}],["docs/{docid}/attachments/{attachmentid}/download",{"_index":99,"title":{},"description":{"51":{}}}],["docs/{docid}/download",{"_index":47,"title":{},"description":{"23":{}}}],["docs/{docid}/download/csv",{"_index":52,"title":{},"description":{"25":{}}}],["docs/{docid}/download/table-schema",{"_index":58,"title":{},"description":{"26":{}}}],["docs/{docid}/download/xlsx",{"_index":49,"title":{},"description":{"24":{}}}],["docs/{docid}/mov",{"_index":43,"title":{},"description":{"20":{}}}],["docs/{docid}/sql",{"_index":116,"title":{},"description":{"59":{},"60":{}}}],["docs/{docid}/t",{"_index":66,"title":{},"description":{"33":{},"34":{},"35":{}}}],["docs/{docid}/tables/{tableid}/column",{"_index":68,"title":{},"description":{"37":{},"38":{},"39":{},"40":{}}}],["docs/{docid}/tables/{tableid}/columns/{colid",{"_index":69,"title":{},"description":{"41":{}}}],["docs/{docid}/tables/{tableid}/data",{"_index":89,"title":{},"description":{"43":{},"44":{},"45":{}}}],["docs/{docid}/tables/{tableid}/data/delet",{"_index":90,"title":{},"description":{"46":{}}}],["docs/{docid}/tables/{tableid}/record",{"_index":62,"title":{},"description":{"28":{},"29":{},"30":{},"31":{}}}],["docs/{docid}/webhook",{"_index":105,"title":{},"description":{"53":{},"54":{}}}],["docs/{docid}/webhooks/queu",{"_index":111,"title":{},"description":{"57":{}}}],["docs/{docid}/webhooks/{webhookid",{"_index":106,"title":{},"description":{"55":{},"56":{}}}],["document",{"_index":24,"title":{"8":{},"16":{},"17":{},"18":{},"19":{},"20":{},"21":{},"22":{},"23":{},"24":{},"33":{},"34":{},"35":{},"53":{},"54":{},"59":{},"60":{}},"description":{"7":{},"15":{},"32":{},"47":{},"52":{}}}],["document'",{"_index":107,"title":{"57":{}},"description":{}}],["download",{"_index":98,"title":{"51":{}},"description":{}}],["empti",{"_index":28,"title":{"9":{},"16":{},"57":{}},"description":{}}],["endpoint",{"_index":78,"title":{},"description":{"42":{},"43":{},"44":{},"45":{}}}],["enumer",{"_index":12,"title":{},"description":{"2":{}}}],["excel",{"_index":48,"title":{"24":{}},"description":{}}],["favor",{"_index":79,"title":{},"description":{"43":{},"44":{},"45":{}}}],["fetch",{"_index":61,"title":{"28":{},"43":{}},"description":{}}],["file",{"_index":46,"title":{"23":{},"24":{},"25":{}},"description":{"47":{}}}],["follow",{"_index":54,"title":{},"description":{"26":{}}}],["format",{"_index":76,"title":{},"description":{"42":{}}}],["frictionlessdata'",{"_index":55,"title":{},"description":{"26":{}}}],["grist",{"_index":35,"title":{},"description":{"15":{}}}],["group",{"_index":23,"title":{},"description":{"7":{}}}],["immedi",{"_index":80,"title":{},"description":{"43":{},"44":{},"45":{}}}],["includ",{"_index":92,"title":{},"description":{"47":{}}}],["list",{"_index":10,"title":{"2":{},"5":{},"8":{},"13":{},"21":{},"33":{},"37":{},"48":{}},"description":{}}],["metadata",{"_index":38,"title":{"18":{},"48":{},"50":{}},"description":{}}],["modifi",{"_index":17,"title":{"4":{},"11":{},"18":{},"30":{},"35":{},"39":{},"45":{},"55":{}},"description":{}}],["move",{"_index":40,"title":{"20":{}},"description":{}}],["new",{"_index":87,"title":{"54":{}},"description":{"43":{},"44":{},"45":{}}}],["now",{"_index":73,"title":{},"description":{"42":{}}}],["option",{"_index":117,"title":{"60":{}},"description":{}}],["org",{"_index":3,"title":{"1":{},"2":{},"3":{},"4":{},"5":{},"6":{},"8":{},"20":{}},"description":{"1":{},"2":{}}}],["organ",{"_index":22,"title":{},"description":{"7":{}}}],["orgs/{orgid",{"_index":16,"title":{},"description":{"3":{},"4":{}}}],["orgs/{orgid}/access",{"_index":19,"title":{},"description":{"5":{},"6":{}}}],["orgs/{orgid}/workspac",{"_index":26,"title":{},"description":{"8":{},"9":{}}}],["paramet",{"_index":118,"title":{"60":{}},"description":{}}],["payload",{"_index":110,"title":{"57":{}},"description":{}}],["person",{"_index":6,"title":{},"description":{"1":{},"2":{}}}],["plan",{"_index":81,"title":{},"description":{"43":{},"44":{},"45":{}}}],["point",{"_index":86,"title":{},"description":{"43":{},"44":{},"45":{}}}],["project",{"_index":88,"title":{},"description":{"43":{},"44":{},"45":{}}}],["queri",{"_index":114,"title":{"59":{},"60":{}},"description":{}}],["queue",{"_index":108,"title":{"57":{}},"description":{}}],["recommend",{"_index":77,"title":{},"description":{"42":{}}}],["record",{"_index":59,"title":{"27":{},"28":{},"29":{},"30":{},"31":{}},"description":{"27":{},"42":{},"43":{},"44":{},"45":{},"47":{}}}],["refer",{"_index":93,"title":{},"description":{"47":{}}}],["remov",{"_index":82,"title":{"56":{}},"description":{"43":{},"44":{},"45":{}}}],["request",{"_index":102,"title":{},"description":{"52":{}}}],["row",{"_index":60,"title":{"44":{},"45":{},"46":{}},"description":{"27":{}}}],["run",{"_index":113,"title":{"59":{},"60":{}},"description":{}}],["same",{"_index":42,"title":{"20":{}},"description":{}}],["schema",{"_index":53,"title":{"26":{}},"description":{"26":{}}}],["securitydefinit",{"_index":1,"title":{},"description":{"0":{}}}],["site",{"_index":5,"title":{},"description":{"1":{},"2":{},"7":{}}}],["space",{"_index":7,"title":{},"description":{"1":{}}}],["sql",{"_index":112,"title":{"58":{},"59":{},"60":{}},"description":{}}],["sqlite",{"_index":45,"title":{"23":{}},"description":{}}],["standard](https://specs.frictionlessdata.io/table-schema",{"_index":57,"title":{},"description":{"26":{}}}],["start",{"_index":85,"title":{},"description":{"43":{},"44":{},"45":{}}}],["structur",{"_index":65,"title":{},"description":{"32":{},"36":{}}}],["tabl",{"_index":50,"title":{"25":{},"26":{},"28":{},"29":{},"30":{},"31":{},"32":{},"33":{},"34":{},"35":{},"37":{},"38":{},"39":{},"40":{},"41":{},"43":{},"44":{},"45":{},"46":{}},"description":{"27":{},"32":{},"36":{},"42":{}}}],["table-schema",{"_index":56,"title":{},"description":{"26":{}}}],["team",{"_index":4,"title":{},"description":{"1":{},"2":{}}}],["trigger",{"_index":101,"title":{},"description":{"52":{}}}],["type",{"_index":94,"title":{},"description":{"47":{}}}],["undeliv",{"_index":109,"title":{"57":{}},"description":{}}],["updat",{"_index":64,"title":{"31":{},"40":{}},"description":{}}],["upload",{"_index":96,"title":{"49":{}},"description":{}}],["url",{"_index":103,"title":{},"description":{"52":{}}}],["us",{"_index":72,"title":{},"description":{"42":{},"47":{}}}],["user",{"_index":18,"title":{"5":{},"13":{},"21":{}},"description":{}}],["webhook",{"_index":100,"title":{"52":{},"53":{},"54":{},"55":{},"56":{}},"description":{"52":{}}}],["within",{"_index":25,"title":{"8":{}},"description":{}}],["work",{"_index":71,"title":{},"description":{"42":{}}}],["workspac",{"_index":21,"title":{"7":{},"8":{},"9":{},"10":{},"11":{},"12":{},"13":{},"14":{},"20":{}},"description":{"7":{},"15":{}}}],["workspaces/{workspaceid",{"_index":29,"title":{},"description":{"10":{},"11":{},"12":{}}}],["workspaces/{workspaceid}/access",{"_index":31,"title":{},"description":{"13":{},"14":{}}}],["workspaces/{workspaceid}/doc",{"_index":36,"title":{},"description":{"16":{}}}]],"pipeline":[]}},"options":{"theme":{"spacing":{"sectionVertical":2},"breakpoints":{"medium":"50rem","large":"50rem"},"sidebar":{"width":"0px"}},"hideDownloadButton":true,"pathInMiddlePanel":true,"scrollYOffset":48,"jsonSampleExpandLevel":"all"}};
+    const __redoc_state = {"menu":{"activeItemIdx":-1},"spec":{"data":{"info":{"description":"An API for manipulating Grist sites, workspaces, and documents.\n\n# Authentication\n<SecurityDefinitions />\n","version":"1.0.1","title":"Grist API"},"openapi":"3.0.0","security":[{"ApiKey":[]}],"servers":[{"url":"https://{subdomain}.getgrist.com/api","variables":{"subdomain":{"description":"The team name, or `docs` for personal areas","default":"docs"}}}],"paths":{"/orgs":{"get":{"operationId":"listOrgs","tags":["orgs"],"summary":"List the orgs you have access to","description":"This enumerates all the team sites or personal areas available.","responses":{"200":{"description":"An array of organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orgs"}}}}}}},"/orgs/{orgId}":{"get":{"operationId":"describeOrg","tags":["orgs"],"summary":"Describe an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"An organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}}}},"patch":{"operationId":"modifyOrg","tags":["orgs"],"summary":"Modify an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/orgs/{orgId}/access":{"get":{"operationId":"listOrgAccess","tags":["orgs"],"summary":"List users with access to org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"Users with access to org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgAccessRead"}}}}}},"patch":{"operationId":"modifyOrgAccess","tags":["orgs"],"summary":"Change who has access to org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/OrgAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/orgs/{orgId}/workspaces":{"get":{"operationId":"listWorkspaces","tags":["workspaces"],"summary":"List workspaces and documents within an org","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"responses":{"200":{"description":"An org's workspaces and documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceWithDocsAndDomain"}}}}}}},"post":{"operationId":"createWorkspace","tags":["workspaces"],"summary":"Create an empty workspace","parameters":[{"$ref":"#/components/parameters/orgIdPathParam"}],"requestBody":{"description":"settings for the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceParameters"}}},"required":true},"responses":{"200":{"description":"The workspace id","content":{"application/json":{"schema":{"type":"integer","description":"an identifier for the workspace","example":155}}}}}}},"/workspaces/{workspaceId}":{"get":{"operationId":"describeWorkspace","tags":["workspaces"],"summary":"Describe a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"A workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceWithDocsAndOrg"}}}}}},"patch":{"operationId":"modifyWorkspace","tags":["workspaces"],"summary":"Modify a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}},"delete":{"operationId":"deleteWorkspace","tags":["workspaces"],"summary":"Delete a workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/workspaces/{workspaceId}/docs":{"post":{"operationId":"createDoc","tags":["docs"],"summary":"Create an empty document","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"settings for the document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocParameters"}}},"required":true},"responses":{"200":{"description":"The document id","content":{"application/json":{"schema":{"type":"string","description":"a unique identifier for the document","example":"8b97c8db-b4df-4b34-b72c-17459e70140a"}}}}}}},"/workspaces/{workspaceId}/access":{"get":{"operationId":"listWorkspaceAccess","tags":["workspaces"],"summary":"List users with access to workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"responses":{"200":{"description":"Users with access to workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceAccessRead"}}}}}},"patch":{"operationId":"modifyWorkspaceAccess","tags":["workspaces"],"summary":"Change who has access to workspace","parameters":[{"$ref":"#/components/parameters/workspaceIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/WorkspaceAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}":{"get":{"operationId":"describeDoc","tags":["docs"],"summary":"Describe a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"A document's metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocWithWorkspace"}}}}}},"patch":{"operationId":"modifyDoc","tags":["docs"],"summary":"Modify document metadata (but not its contents)","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocParameters"}}},"required":true},"responses":{"200":{"description":"Success"}}},"delete":{"operationId":"deleteDoc","tags":["docs"],"summary":"Delete a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/move":{"patch":{"operationId":"moveDoc","tags":["docs"],"summary":"Move document to another workspace in the same org.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the target workspace","content":{"application/json":{"schema":{"type":"object","required":["workspace"],"properties":{"workspace":{"type":"integer","example":597}}}}}},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/access":{"get":{"operationId":"listDocAccess","tags":["docs"],"summary":"List users with access to document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Users with access to document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocAccessRead"}}}}}},"patch":{"operationId":"modifyDocAccess","tags":["docs"],"summary":"Change who has access to document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"type":"object","required":["delta"],"properties":{"delta":{"$ref":"#/components/schemas/DocAccessWrite"}}}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/download":{"get":{"operationId":"downloadDoc","tags":["docs"],"summary":"Content of document, as an Sqlite file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"nohistory","schema":{"type":"boolean","description":"Remove document history (can significantly reduce file size)"},"required":false},{"in":"query","name":"template","schema":{"type":"boolean","description":"Remove all data and history but keep the structure to use the document as a template"},"required":false}],"responses":{"200":{"description":"A document's content in Sqlite form","content":{"application/x-sqlite3":{"schema":{"type":"string","format":"binary"}}}}}}},"/docs/{docId}/download/xlsx":{"get":{"operationId":"downloadDocXlsx","tags":["docs"],"summary":"Content of document, as an Excel file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A document's content in Excel form","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}}}}},"/docs/{docId}/download/csv":{"get":{"operationId":"downloadDocCsv","tags":["docs"],"summary":"Content of table, as a CSV file","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"tableId","schema":{"type":"string","description":"Name of a table (normalized)."},"required":true},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A table's content in CSV form","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/docs/{docId}/download/table-schema":{"get":{"operationId":"downloadTableSchema","tags":["docs"],"summary":"The schema of a table","description":"The schema follows [frictionlessdata's table-schema standard](https://specs.frictionlessdata.io/table-schema/).","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"tableId","schema":{"type":"string","description":"Name of a table (normalized)."},"required":true},{"$ref":"#/components/parameters/headerQueryParam"}],"responses":{"200":{"description":"A table's table-schema in JSON format.","content":{"text/json":{"schema":{"$ref":"#/components/schemas/TableSchemaResult"}}}}}}},"/docs/{docId}/tables/{tableId}/data":{"get":{"operationId":"getTableData","tags":["data"],"summary":"Fetch data from a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"}],"responses":{"200":{"description":"Cells from the table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}}}}},"post":{"operationId":"addRows","tags":["data"],"summary":"Add rows to a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the data to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataWithoutId"}}},"required":true},"responses":{"200":{"description":"IDs of rows added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}},"patch":{"operationId":"modifyRows","tags":["data"],"summary":"Modify rows of a table","deprecated":true,"description":"Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects.","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the data to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Data"}}},"required":true},"responses":{"200":{"description":"IDs of rows modified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}}},"/docs/{docId}/tables/{tableId}/data/delete":{"post":{"operationId":"deleteRows","tags":["data"],"summary":"Delete rows of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the IDs of rows to remove","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}},"required":true},"responses":{"200":{"description":"Nothing returned"}}}},"/docs/{docId}/attachments":{"get":{"operationId":"listAttachments","tags":["attachments"],"summary":"List metadata of all attachments in a doc","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"}],"responses":{"200":{"description":"List of attachment metadata records. Note that the list may temporarily include records for attachments that are stored in the document but not referenced by any Attachments type cell.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentMetadataList"}}}}}},"post":{"operationId":"uploadAttachments","tags":["attachments"],"summary":"Upload attachments to a doc","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the files to add to the doc","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AttachmentUpload"}}},"required":true},"responses":{"200":{"description":"IDs of attachments added, one per file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIds"}}}}}}},"/docs/{docId}/attachments/{attachmentId}":{"get":{"operationId":"getAttachmentMetadata","tags":["attachments"],"summary":"Get the metadata for an attachment","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"attachmentId","schema":{"$ref":"#/components/schemas/AttachmentId"},"required":true}],"responses":{"200":{"description":"Attachment metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentMetadata"}}}}}}},"/docs/{docId}/attachments/{attachmentId}/download":{"get":{"operationId":"downloadAttachment","tags":["attachments"],"summary":"Download the contents of an attachment","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"attachmentId","schema":{"$ref":"#/components/schemas/AttachmentId"},"required":true}],"responses":{"200":{"description":"Attachment contents, with suitable Content-Type."}}}},"/docs/{docId}/tables/{tableId}/records":{"get":{"operationId":"listRecords","tags":["records"],"summary":"Fetch records from a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/filterQueryParam"},{"$ref":"#/components/parameters/sortQueryParam"},{"$ref":"#/components/parameters/limitQueryParam"},{"$ref":"#/components/parameters/sortHeaderParam"},{"$ref":"#/components/parameters/limitHeaderParam"},{"$ref":"#/components/parameters/hiddenQueryParam"}],"responses":{"200":{"description":"Records from the table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsList"}}}}}},"post":{"operationId":"addRecords","tags":["records"],"summary":"Add records to a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the records to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithoutId"}}},"required":true},"responses":{"200":{"description":"IDs of records added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithoutFields"}}}}}},"patch":{"operationId":"modifyRecords","tags":["records"],"summary":"Modify records of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"}],"requestBody":{"description":"the records to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsList"}}},"required":true},"responses":{"200":{"description":"Success"}}},"put":{"operationId":"replaceRecords","tags":["records"],"summary":"Add or update records of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/noparseQueryParam"},{"in":"query","name":"onmany","schema":{"type":"string","enum":["first","none","all"],"description":"Which records to update if multiple records are found to match `require`.\n  * `first` - the first matching record (default)\n  * `none` - do not update anything\n  * `all` - update all matches\n"}},{"in":"query","name":"noadd","schema":{"type":"boolean","description":"Set to true to prohibit adding records."}},{"in":"query","name":"noupdate","schema":{"type":"boolean","description":"Set to true to prohibit updating records."}},{"in":"query","name":"allow_empty_require","schema":{"type":"boolean","description":"Set to true to allow `require` in the body to be empty, which will match and update all records in the table."}}],"requestBody":{"description":"The records to add or update. Instead of an id, a `require` object is provided, with the same structure as `fields`. If no query parameter options are set, then the operation is as follows. First, we check if a record exists matching the values specified for columns in `require`. If so, we update it by setting the values specified for columns in `fields`. If not, we create a new record with a combination of the values in `require` and `fields`, with `fields` taking priority if the same column is specified in both. The query parameters allow for variations on this behavior.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsWithRequire"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables":{"get":{"operationId":"listTables","tags":["tables"],"summary":"List tables in a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"The tables in a document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesList"}}}}}},"post":{"operationId":"addTables","tags":["tables"],"summary":"Add tables to a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the tables to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTables"}}},"required":true},"responses":{"200":{"description":"The table created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesWithoutFields"}}}}}},"patch":{"operationId":"modifyTables","tags":["tables"],"summary":"Modify tables of a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"the tables to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TablesList"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables/{tableId}/columns":{"get":{"operationId":"listColumns","tags":["columns"],"summary":"List columns in a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/hiddenQueryParam"}],"responses":{"200":{"description":"The columns in a table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColumnsList"}}}}}},"post":{"operationId":"addColumns","tags":["columns"],"summary":"Add columns to a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the columns to add","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateColumns"}}},"required":true},"responses":{"200":{"description":"The columns created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColumnsWithoutFields"}}}}}},"patch":{"operationId":"modifyColumns","tags":["columns"],"summary":"Modify columns of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"}],"requestBody":{"description":"the columns to change, with ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateColumns"}}},"required":true},"responses":{"200":{"description":"Success"}}},"put":{"operationId":"replaceColumns","tags":["columns"],"summary":"Add or update columns of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"in":"query","name":"noadd","schema":{"type":"boolean","description":"Set to true to prohibit adding columns."}},{"in":"query","name":"noupdate","schema":{"type":"boolean","description":"Set to true to prohibit updating columns."}},{"in":"query","name":"replaceall","schema":{"type":"boolean","description":"Set to true to remove existing columns (except the hidden ones) that are not specified in the request body."}}],"requestBody":{"description":"The columns to add or update. We check whether the specified column ID exists: if so, the column is updated with the provided data, otherwise a new column is created.\nAlso note that some query parameters alter this behavior.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateColumns"}}},"required":true},"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/tables/{tableId}/columns/{colId}":{"delete":{"operationId":"deleteColumn","tags":["columns"],"summary":"Delete a column of a table","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"$ref":"#/components/parameters/tableIdPathParam"},{"$ref":"#/components/parameters/colIdPathParam"}],"responses":{"200":{"description":"Success"}}}},"/docs/{docId}/webhooks":{"get":{"tags":["webhooks"],"summary":"Webhooks associated with a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"A list of webhooks.","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"object","$ref":"#/components/schemas/Webhooks"}}}}}}}},"post":{"tags":["webhooks"],"summary":"Create new webhooks for a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"an array of webhook settings","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"$ref":"#/components/schemas/WebhookPartialFields"}}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/WebhookId"}}}}}}}}}},"/docs/{docId}/webhooks/{webhookId}":{"patch":{"tags":["webhooks"],"summary":"Modify a webhook","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"webhookId","schema":{"type":"string"},"required":true}],"requestBody":{"description":"the changes to make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPartialFields"}}}},"responses":{"200":{"description":"Success."}}},"delete":{"tags":["webhooks"],"summary":"Remove a webhook","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"path","name":"webhookId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","example":true}}}}}}}}},"/docs/{docId}/webhooks/queue":{"delete":{"tags":["webhooks"],"summary":"Empty a document's queue of undelivered payloads","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"responses":{"200":{"description":"Success."}}}},"/docs/{docId}/sql":{"get":{"tags":["sql"],"summary":"Run an SQL query against a document","parameters":[{"$ref":"#/components/parameters/docIdPathParam"},{"in":"query","name":"q","schema":{"type":"string","description":"The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string."}}],"responses":{"200":{"description":"The result set for the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResultSet"}}}}}},"post":{"tags":["sql"],"summary":"Run an SQL query against a document, with options or parameters","parameters":[{"$ref":"#/components/parameters/docIdPathParam"}],"requestBody":{"description":"Query options","content":{"application/json":{"schema":{"type":"object","required":["sql"],"properties":{"sql":{"type":"string","description":"The SQL query to run. Must be a single SELECT statement, with no trailing semicolon. WITH clauses are permitted. All Grist documents are currently SQLite databases, and the SQL query is interpreted and run by SQLite, with various defensive measures. Statements that would modify the database are not supported.","example":"select * from Pets where popularity >= ?"},"args":{"type":"array","items":{"oneOf":[{"type":"number"},{"type":"string"}]},"description":"Parameters for the query.","example":[50]},"timeout":{"type":"number","description":"Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced.","example":500}}}}}},"responses":{"200":{"description":"The result set for the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResultSet"}}}}}}}},"tags":[{"name":"orgs","description":"Team sites and personal spaces are called 'orgs' in the API."},{"name":"workspaces","description":"Sites can be organized into groups of documents called workspaces."},{"name":"docs","description":"Workspaces contain collections of Grist documents."},{"name":"records","description":"Tables contain collections of records (also called rows)."},{"name":"tables","description":"Documents are structured as a collection of tables."},{"name":"columns","description":"Tables are structured as a collection of columns."},{"name":"data","description":"Work with table data, using a (now deprecated) columnar format. We now recommend the `records` endpoints."},{"name":"attachments","description":"Documents may include attached files. Data records can refer to these using a column of type `Attachments`."},{"name":"webhooks","description":"Document changes can trigger requests to URLs called webhooks."}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Authorization: Bearer XXXXXXXXXXX","description":"Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key."}},"schemas":{"Org":{"type":"object","required":["id","name","domain","owner","createdAt","updatedAt","access"],"properties":{"id":{"type":"integer","format":"int64","example":42},"name":{"type":"string","example":"Grist Labs"},"domain":{"type":"string","nullable":true,"example":"gristlabs"},"owner":{"type":"object","$ref":"#/components/schemas/User","nullable":true},"access":{"type":"string","$ref":"#/components/schemas/Access"},"createdAt":{"type":"string","example":"2019-09-13T15:42:35.000Z"},"updatedAt":{"type":"string","example":"2019-09-13T15:42:35.000Z"}}},"Orgs":{"type":"array","items":{"$ref":"#/components/schemas/Org"}},"Webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"},"fields":{"$ref":"#/components/schemas/WebhookFields"},"usage":{"$ref":"#/components/schemas/WebhookUsage"}}},"WebhookFields":{"allOf":[{"$ref":"#/components/schemas/WebhookPartialFields"},{"$ref":"#/components/schemas/WebhookRequiredFields"}]},"WebhookRequiredFields":{"type":"object","required":["name","memo","url","enabled","unsubscribeKey","eventTypes","isReadyColumn","tableId"],"properties":{"unsubscribeKey":{"type":"string"}}},"WebhookPartialFields":{"type":"object","properties":{"name":{"type":"string","example":"new-project-email","nullable":true},"memo":{"type":"string","example":"Send an email when a project is added","nullable":true},"url":{"type":"string","format":"uri","example":"https://example.com/webhook/123"},"enabled":{"type":"boolean"},"eventTypes":{"type":"array","items":{"type":"string"},"example":["add","update"]},"isReadyColumn":{"type":"string","nullable":true,"example":null},"tableId":{"type":"string","example":"Projects"}}},"WebhookUsage":{"type":"object","nullable":true,"required":["numWaiting","status"],"properties":{"numWaiting":{"type":"integer"},"status":{"type":"string","example":"idle"},"updatedTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastSuccessTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastFailureTime":{"type":"number","nullable":true,"format":"UNIX epoch in milliseconds","example":1685637500424},"lastErrorMessage":{"type":"string","nullable":true,"example":null},"lastHttpStatus":{"type":"number","nullable":true,"example":200},"lastEventBatch":{"$ref":"#/components/schemas/WebhookBatchStatus"}}},"WebhookBatchStatus":{"type":"object","nullable":true,"required":["size","attempts","status"],"properties":{"size":{"type":"number","example":1},"attempts":{"type":"number","example":1},"errorMessage":{"type":"string","nullable":true,"example":null},"httpStatus":{"type":"number","example":200},"status":{"type":"string","example":"success"}}},"WebhookId":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Webhook identifier","example":"xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"}}},"WebhookRequiredProperties":{"type":"object","required":["size"],"properties":{"size":{"type":"number","example":1}}},"WebhookProperties":{"size":{"type":"number","example":1},"attempts":{"type":"number","example":1},"errorMessage":{"type":"string","nullable":true,"example":null},"httpStatus":{"type":"number","example":200},"status":{"type":"string","example":"success"}},"Workspace":{"type":"object","required":["id","name","access"],"properties":{"id":{"type":"integer","format":"int64","example":97},"name":{"type":"string","example":"Secret Plans"},"access":{"type":"string","$ref":"#/components/schemas/Access"}}},"Doc":{"type":"object","required":["id","name","isPinned","urlId","access"],"properties":{"id":{"type":"string","example":145},"name":{"type":"string","example":"Project Lollipop"},"access":{"type":"string","$ref":"#/components/schemas/Access"},"isPinned":{"type":"boolean","example":true},"urlId":{"type":"string","nullable":true,"example":null}}},"WorkspaceWithDocs":{"allOf":[{"$ref":"#/components/schemas/Workspace"},{"type":"object","required":["docs"],"properties":{"docs":{"type":"array","items":{"$ref":"#/components/schemas/Doc"}}}}]},"WorkspaceWithDocsAndDomain":{"allOf":[{"$ref":"#/components/schemas/WorkspaceWithDocs"},{"type":"object","properties":{"orgDomain":{"type":"string","example":"gristlabs"}}}]},"WorkspaceWithOrg":{"allOf":[{"$ref":"#/components/schemas/Workspace"},{"type":"object","required":["org"],"properties":{"org":{"$ref":"#/components/schemas/Org"}}}]},"WorkspaceWithDocsAndOrg":{"allOf":[{"$ref":"#/components/schemas/WorkspaceWithDocs"},{"$ref":"#/components/schemas/WorkspaceWithOrg"}]},"DocWithWorkspace":{"allOf":[{"$ref":"#/components/schemas/Doc"},{"type":"object","required":["workspace"],"properties":{"workspace":{"$ref":"#/components/schemas/WorkspaceWithOrg"}}}]},"User":{"type":"object","required":["id","name","picture"],"properties":{"id":{"type":"integer","format":"int64","example":101},"name":{"type":"string","example":"Helga Hufflepuff"},"picture":{"type":"string","nullable":true,"example":null}}},"Access":{"type":"string","enum":["owners","editors","viewers"]},"Data":{"type":"object","required":["id"],"properties":{"id":{"type":"array","items":{"type":"integer"}}},"additionalProperties":{"type":"array","items":{"type":"object"}},"example":{"id":[1,2],"pet":["cat","dog"],"popularity":[67,95]}},"DataWithoutId":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}},"example":{"pet":["cat","dog"],"popularity":[67,95]}},"RecordsList":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"number","example":1},"fields":{"type":"object","description":"A JSON object mapping column names to [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues)."}}}}},"example":{"records":[{"id":1,"fields":{"pet":"cat","popularity":67}},{"id":2,"fields":{"pet":"dog","popularity":95}}]}},"RecordsWithoutId":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"type":"object","description":"A JSON object mapping column names to [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues)."}}}}},"example":{"records":[{"fields":{"pet":"cat","popularity":67}},{"fields":{"pet":"dog","popularity":95}}]}},"RecordsWithoutFields":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"number","example":1}}}}},"example":{"records":[{"id":1},{"id":2}]}},"RecordsWithRequire":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["require"],"properties":{"require":{"type":"object","description":"keys are column identifiers, and values are [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues) we want to have in those columns (either by matching with an existing record, or creating a new record)\n"},"fields":{"type":"object","description":"keys are column identifiers, and values are [cell values](https://support.getgrist.com/code/interfaces/grist_plugin_api.rowrecord/#cellvalues) to place in those columns (either overwriting values in an existing record, or in a new record)\n"}}}}},"example":{"records":[{"require":{"pet":"cat"},"fields":{"popularity":67}},{"require":{"pet":"dog"},"fields":{"popularity":95}}]}},"TablesList":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"string","example":"Table1"},"fields":{"type":"object"}}}}},"example":{"tables":[{"id":"People","fields":{"tableRef":1,"onDemand":true}},{"id":"Places","fields":{"tableRef":2,"onDemand":false}}]}},"TablesWithoutFields":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"Table1"}}}}},"example":{"tables":[{"id":"People"},{"id":"Places"}]}},"CreateTables":{"type":"object","required":["tables"],"properties":{"tables":{"type":"array","items":{"type":"object","required":["columns"],"properties":{"id":{"type":"string","example":"Table1"},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ColumnName"},"fields":{"type":"object"}}}}}}}},"example":{"tables":[{"id":"People","columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤"}}]}]}},"ColumnsList":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ColumnName"},"fields":{"$ref":"#/components/schemas/GetFields"}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}}]}},"CreateColumns":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Column identifier"},"fields":{"$ref":"#/components/schemas/CreateFields"}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}},{"id":"Order","fields":{"type":"Ref:Orders","visibleCol":2}},{"id":"Formula","fields":{"type":"Int","formula":"$A + $B","isFormula":true}},{"id":"Status","fields":{"type":"Choice","widgetOptions":"{\"choices\":[\"New\",\"Old\"],\"choiceOptions\":{\"New\":{\"fillColor\":\"#FF0000\",\"textColor\":\"#FFFFFF\"}}}"}}]}},"UpdateColumns":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"string","description":"Column identifier"},"fields":{"allOf":[{"$ref":"#/components/schemas/CreateFields"},{"type":"object","properties":{"colId":{"type":"string","description":"Set it to the new column ID when you want to change it."}}}]}}}}},"example":{"columns":[{"id":"pet","fields":{"label":"Pet"}},{"id":"popularity","fields":{"label":"Popularity ❤","type":"Int"}}]}},"ColumnsWithoutFields":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"ColumnName"}}}}},"example":{"columns":[{"id":"pet"},{"id":"popularity"}]}},"Fields":{"type":"object","properties":{"type":{"type":"string","description":"Column type, by default Any. Ref, RefList and DateTime types requires a postfix, e.g. <code>DateTime:America/New_York</code>, <code>Ref:Users</code>","enum":["Any","Text","Numeric","Int","Bool","Date","DateTime:<timezone>","Choice","ChoiceList","Ref:<tableId>","RefList:<tableId>","Attachments"]},"label":{"type":"string","description":"Column label."},"formula":{"type":"string","description":"A python formula, e.g.: <code>$A + Table1.lookupOne(B=$B)</code>"},"isFormula":{"type":"boolean","description":"Use \"true\" to indicate that the column is a formula column. Use \"false\" for trigger formula column."},"widgetOptions":{"type":"string","description":"A JSON object with widget options, e.g.: <code>{\"choices\": [\"cat\", \"dog\"], \"alignment\": \"right\"}</code>"},"untieColIdFromLabel":{"type":"boolean","description":"Use \"true\" to indicate that the column label should not be used as the column identifier. Use \"false\" to use the label as the identifier."},"recalcWhen":{"type":"integer","description":"A number indicating when the column should be recalculated. <ol start='0'><li>On new records or when any field in recalcDeps changes, it's a 'data-cleaning'.</li><li>Never.</li><li>Calculate on new records and on manual updates to any data field.</li></ol>"},"visibleCol":{"type":"integer","description":"For Ref and RefList columns, the colRef of a column to display"}}},"CreateFields":{"allOf":[{"$ref":"#/components/schemas/Fields"},{"type":"object","properties":{"recalcDeps":{"type":"string","description":"An encoded array of column identifiers (colRefs) that this column depends on. If any of these columns change, the column will be recalculated. E.g.: <code>[2, 3]</code>"}}}]},"GetFields":{"allOf":[{"$ref":"#/components/schemas/Fields"},{"type":"object","properties":{"recalcDeps":{"type":"array","items":{"type":"integer"},"description":"An array of column identifiers (colRefs) that this column depends on, prefixed with \"L\" constant. If any of these columns change, the column will be recalculated. E.g.: <code>[\"L\", 2, 3]</code>"},"colRef":{"type":"integer","description":"Column reference, e.g.: <code>2</code>"}}}]},"RowIds":{"type":"array","example":[101,102,103],"items":{"type":"integer"}},"DocParameters":{"type":"object","properties":{"name":{"type":"string","example":"Competitive Analysis"},"isPinned":{"type":"boolean","example":false}}},"WorkspaceParameters":{"type":"object","properties":{"name":{"type":"string","example":"Retreat Docs"}}},"OrgParameters":{"type":"object","properties":{"name":{"type":"string","example":"ACME Unlimited"}}},"OrgAccessRead":{"type":"object","required":["users"],"properties":{"users":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Andrea"},"email":{"type":"string","example":"andrea@getgrist.com"},"access":{"$ref":"#/components/schemas/Access"}}}}}},"OrgAccessWrite":{"type":"object","required":["users"],"properties":{"users":{"type":"object","additionalProperties":{"type":"string","enum":["owners","editors","viewers","members",null]},"example":{"foo@getgrist.com":"owners","bar@getgrist.com":null}}}},"WorkspaceAccessRead":{"type":"object","required":["maxInheritedRole","users"],"properties":{"maxInheritedRole":{"$ref":"#/components/schemas/Access"},"users":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Andrea"},"email":{"type":"string","example":"andrea@getgrist.com"},"access":{"$ref":"#/components/schemas/Access"},"parentAccess":{"$ref":"#/components/schemas/Access"}}}}}},"WorkspaceAccessWrite":{"type":"object","properties":{"maxInheritedRole":{"$ref":"#/components/schemas/Access"},"users":{"type":"object","additionalProperties":{"type":"string","enum":["owners","editors","viewers","members",null]},"example":{"foo@getgrist.com":"owners","bar@getgrist.com":null}}}},"DocAccessWrite":{"$ref":"#/components/schemas/WorkspaceAccessWrite"},"DocAccessRead":{"$ref":"#/components/schemas/WorkspaceAccessRead"},"AttachmentUpload":{"type":"object","properties":{"upload":{"type":"array","items":{"type":"string","format":"binary"}}}},"AttachmentId":{"type":"number","description":"An integer ID"},"AttachmentMetadata":{"type":"object","properties":{"fileName":{"type":"string","example":"logo.png"},"fileSize":{"type":"number","example":12345},"timeUploaded":{"type":"string","example":"2020-02-13T12:17:19.000Z"}}},"AttachmentMetadataList":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","required":["id","fields"],"properties":{"id":{"type":"number","example":1},"fields":{"$ref":"#/components/schemas/AttachmentMetadata"}}}}}},"SqlResultSet":{"type":"object","required":["statement","records"],"properties":{"statement":{"type":"string","description":"A copy of the SQL statement.","example":"select * from Pets ..."},"records":{"type":"array","items":{"type":"object","required":["fields"],"properties":{"fields":{"type":"object"}}},"example":[{"fields":{"id":1,"pet":"cat","popularity":67}},{"fields":{"id":2,"pet":"dog","popularity":95}}]}}},"TableSchemaResult":{"type":"object","required":["name","title","schema"],"properties":{"name":{"type":"string","description":"The ID (technical name) of the table"},"title":{"type":"string","description":"The human readable name of the table"},"path":{"type":"string","description":"The URL to download the CSV","example":"https://getgrist.com/o/docs/api/docs/ID/download/csv?tableId=Table1&...."},"format":{"type":"string","enum":["csv"]},"mediatype":{"type":"string","enum":["text/csv"]},"encoding":{"type":"string","enum":["utf-8"]},"dialect":{"$ref":"#/components/schemas/csv-dialect"},"schema":{"$ref":"#/components/schemas/table-schema"}}},"csv-dialect":{"$schema":"http://json-schema.org/draft-04/schema#","title":"CSV Dialect","description":"The CSV dialect descriptor.","type":["string","object"],"required":["delimiter","doubleQuote"],"properties":{"csvddfVersion":{"title":"CSV Dialect schema version","description":"A number to indicate the schema version of CSV Dialect. Version 1.0 was named CSV Dialect Description Format and used different field names.","type":"number","default":1.2,"examples:":["{\n  \"csvddfVersion\": \"1.2\"\n}\n"]},"delimiter":{"title":"Delimiter","description":"A character sequence to use as the field separator.","type":"string","default":",","examples":["{\n  \"delimiter\": \",\"\n}\n","{\n  \"delimiter\": \";\"\n}\n"]},"doubleQuote":{"title":"Double Quote","description":"Specifies the handling of quotes inside fields.","context":"If Double Quote is set to true, two consecutive quotes must be interpreted as one.","type":"boolean","default":true,"examples":["{\n  \"doubleQuote\": true\n}\n"]},"lineTerminator":{"title":"Line Terminator","description":"Specifies the character sequence that must be used to terminate rows.","type":"string","default":"\r\n","examples":["{\n  \"lineTerminator\": \"\\r\\n\"\n}\n","{\n  \"lineTerminator\": \"\\n\"\n}\n"]},"nullSequence":{"title":"Null Sequence","description":"Specifies the null sequence, for example, `\\N`.","type":"string","examples":["{\n  \"nullSequence\": \"\\N\"\n}\n"]},"quoteChar":{"title":"Quote Character","description":"Specifies a one-character string to use as the quoting character.","type":"string","default":"\"","examples":["{\n  \"quoteChar\": \"'\"\n}\n"]},"escapeChar":{"title":"Escape Character","description":"Specifies a one-character string to use as the escape character.","type":"string","examples":["{\n  \"escapeChar\": \"\\\\\"\n}\n"]},"skipInitialSpace":{"title":"Skip Initial Space","description":"Specifies the interpretation of whitespace immediately following a delimiter. If false, whitespace immediately after a delimiter should be treated as part of the subsequent field.","type":"boolean","default":false,"examples":["{\n  \"skipInitialSpace\": true\n}\n"]},"header":{"title":"Header","description":"Specifies if the file includes a header row, always as the first row in the file.","type":"boolean","default":true,"examples":["{\n  \"header\": true\n}\n"]},"commentChar":{"title":"Comment Character","description":"Specifies that any row beginning with this one-character string, without preceeding whitespace, causes the entire line to be ignored.","type":"string","examples":["{\n  \"commentChar\": \"#\"\n}\n"]},"caseSensitiveHeader":{"title":"Case Sensitive Header","description":"Specifies if the case of headers is meaningful.","context":"Use of case in source CSV files is not always an intentional decision. For example, should \"CAT\" and \"Cat\" be considered to have the same meaning.","type":"boolean","default":false,"examples":["{\n  \"caseSensitiveHeader\": true\n}\n"]}},"examples":["{\n  \"dialect\": {\n    \"delimiter\": \";\"\n  }\n}\n","{\n  \"dialect\": {\n    \"delimiter\": \"\\t\",\n    \"quoteChar\": \"'\",\n    \"commentChar\": \"#\"\n  }\n}\n"]},"table-schema":{"$schema":"http://json-schema.org/draft-04/schema#","title":"Table Schema","description":"A Table Schema for this resource, compliant with the [Table Schema](./tableschema/) specification.","type":["string","object"],"required":["fields"],"properties":{"fields":{"type":"array","minItems":1,"items":{"title":"Table Schema Field","type":"object","oneOf":[{"type":"object","title":"String Field","description":"The field contains strings, that is, sequences of characters.","required":["name"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `string`.","enum":["string"]},"format":{"description":"The format keyword options for `string` are `default`, `email`, `uri`, `binary`, and `uuid`.","context":"The following `format` options are supported:\n  * **default**: any valid string.\n  * **email**: A valid email address.\n  * **uri**: A valid URI.\n  * **binary**: A base64 encoded string representing binary data.\n  * **uuid**: A string that is a uuid.","enum":["default","email","uri","binary","uuid"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `string` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"pattern":{"type":"string","description":"A regular expression pattern to test each value of the property against, where a truthy response indicates validity.","context":"Regular expressions `SHOULD` conform to the [XML Schema regular expression syntax](http://www.w3.org/TR/xmlschema-2/#regexs)."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"name\",\n  \"type\": \"string\"\n}\n","{\n  \"name\": \"name\",\n  \"type\": \"string\",\n  \"format\": \"email\"\n}\n","{\n  \"name\": \"name\",\n  \"type\": \"string\",\n  \"constraints\": {\n    \"minLength\": 3,\n    \"maxLength\": 35\n  }\n}\n"]},{"type":"object","title":"Number Field","description":"The field contains numbers of any kind including decimals.","context":"The lexical formatting follows that of decimal in [XMLSchema](https://www.w3.org/TR/xmlschema-2/#decimal): a non-empty finite-length sequence of decimal digits separated by a period as a decimal indicator. An optional leading sign is allowed. If the sign is omitted, '+' is assumed. Leading and trailing zeroes are optional. If the fractional part is zero, the period and following zero(es) can be omitted. For example: '-1.23', '12678967.543233', '+100000.00', '210'.\n\nThe following special string values are permitted (case does not need to be respected):\n  - NaN: not a number\n  - INF: positive infinity\n  - -INF: negative infinity\n\nA number `MAY` also have a trailing:\n  - exponent: this `MUST` consist of an E followed by an optional + or - sign followed by one or more decimal digits (0-9)\n  - percentage: the percentage sign: `%`. In conversion percentages should be divided by 100.\n\nIf both exponent and percentages are present the percentage `MUST` follow the exponent e.g. '53E10%' (equals 5.3).","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `number`.","enum":["number"]},"format":{"description":"There are no format keyword options for `number`: only `default` is allowed.","enum":["default"],"default":"default"},"bareNumber":{"type":"boolean","title":"bareNumber","description":"a boolean field with a default of `true`. If `true` the physical contents of this field must follow the formatting constraints already set out. If `false` the contents of this field may contain leading and/or trailing non-numeric characters (which implementors MUST therefore strip). The purpose of `bareNumber` is to allow publishers to publish numeric data that contains trailing characters such as percentages e.g. `95%` or leading characters such as currencies e.g. `€95` or `EUR 95`. Note that it is entirely up to implementors what, if anything, they do with stripped text.","default":true},"decimalChar":{"type":"string","description":"A string whose value is used to represent a decimal point within the number. The default value is `.`."},"groupChar":{"type":"string","description":"A string whose value is used to group digits within the number. The default value is `null`. A common value is `,` e.g. '100,000'."},"constraints":{"title":"Constraints","description":"The following constraints are supported for `number` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"number"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"number"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"number"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"field-name\",\n  \"type\": \"number\"\n}\n","{\n  \"name\": \"field-name\",\n  \"type\": \"number\",\n  \"constraints\": {\n    \"enum\": [ \"1.00\", \"1.50\", \"2.00\" ]\n  }\n}\n"]},{"type":"object","title":"Integer Field","description":"The field contains integers - that is whole numbers.","context":"Integer values are indicated in the standard way for any valid integer.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `integer`.","enum":["integer"]},"format":{"description":"There are no format keyword options for `integer`: only `default` is allowed.","enum":["default"],"default":"default"},"bareNumber":{"type":"boolean","title":"bareNumber","description":"a boolean field with a default of `true`. If `true` the physical contents of this field must follow the formatting constraints already set out. If `false` the contents of this field may contain leading and/or trailing non-numeric characters (which implementors MUST therefore strip). The purpose of `bareNumber` is to allow publishers to publish numeric data that contains trailing characters such as percentages e.g. `95%` or leading characters such as currencies e.g. `€95` or `EUR 95`. Note that it is entirely up to implementors what, if anything, they do with stripped text.","default":true},"constraints":{"title":"Constraints","description":"The following constraints are supported for `integer` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"integer"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"integer"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"age\",\n  \"type\": \"integer\",\n  \"constraints\": {\n    \"unique\": true,\n    \"minimum\": 100,\n    \"maximum\": 9999\n  }\n}\n"]},{"type":"object","title":"Date Field","description":"The field contains temporal date values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `date`.","enum":["date"]},"format":{"description":"The format keyword options for `date` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string of YYYY-MM-DD.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `date` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\"\n}\n","{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\",\n  \"constraints\": {\n    \"minimum\": \"01-01-1900\"\n  }\n}\n","{\n  \"name\": \"date_of_birth\",\n  \"type\": \"date\",\n  \"format\": \"MM-DD-YYYY\"\n}\n"]},{"type":"object","title":"Time Field","description":"The field contains temporal time values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `time`.","enum":["time"]},"format":{"description":"The format keyword options for `time` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string for time.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `time` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"appointment_start\",\n  \"type\": \"time\"\n}\n","{\n  \"name\": \"appointment_start\",\n  \"type\": \"time\",\n  \"format\": \"any\"\n}\n"]},{"type":"object","title":"Date Time Field","description":"The field contains temporal datetime values.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `datetime`.","enum":["datetime"]},"format":{"description":"The format keyword options for `datetime` are `default`, `any`, and `{PATTERN}`.","context":"The following `format` options are supported:\n  * **default**: An ISO8601 format string for datetime.\n  * **any**: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.\n  * **{PATTERN}**: The value can be parsed according to `{PATTERN}`, which `MUST` follow the date formatting syntax of C / Python [strftime](http://strftime.org/).","default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `datetime` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"timestamp\",\n  \"type\": \"datetime\"\n}\n","{\n  \"name\": \"timestamp\",\n  \"type\": \"datetime\",\n  \"format\": \"default\"\n}\n"]},{"type":"object","title":"Year Field","description":"A calendar year, being an integer with 4 digits. Equivalent to [gYear in XML Schema](https://www.w3.org/TR/xmlschema-2/#gYear)","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `year`.","enum":["year"]},"format":{"description":"There are no format keyword options for `year`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `year` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"integer"}}]},"minimum":{"oneOf":[{"type":"string"},{"type":"integer"}]},"maximum":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"year\",\n  \"type\": \"year\"\n}\n","{\n  \"name\": \"year\",\n  \"type\": \"year\",\n  \"constraints\": {\n    \"minimum\": 1970,\n    \"maximum\": 2003\n  }\n}\n"]},{"type":"object","title":"Year Month Field","description":"A calendar year month, being an integer with 1 or 2 digits. Equivalent to [gYearMonth in XML Schema](https://www.w3.org/TR/xmlschema-2/#gYearMonth)","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `yearmonth`.","enum":["yearmonth"]},"format":{"description":"There are no format keyword options for `yearmonth`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `yearmonth` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"month\",\n  \"type\": \"yearmonth\"\n}\n","{\n  \"name\": \"month\",\n  \"type\": \"yearmonth\",\n  \"constraints\": {\n    \"minimum\": 1,\n    \"maximum\": 6\n  }\n}\n"]},{"type":"object","title":"Boolean Field","description":"The field contains boolean (true/false) data.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `boolean`.","enum":["boolean"]},"format":{"description":"There are no format keyword options for `boolean`: only `default` is allowed.","enum":["default"],"default":"default"},"trueValues":{"type":"array","minItems":1,"items":{"type":"string"},"default":["true","True","TRUE","1"]},"falseValues":{"type":"array","minItems":1,"items":{"type":"string"},"default":["false","False","FALSE","0"]},"constraints":{"title":"Constraints","description":"The following constraints are supported for `boolean` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"boolean"}}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"registered\",\n  \"type\": \"boolean\"\n}\n"]},{"type":"object","title":"Object Field","description":"The field contains data which can be parsed as a valid JSON object.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `object`.","enum":["object"]},"format":{"description":"There are no format keyword options for `object`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints apply for `object` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"extra\"\n  \"type\": \"object\"\n}\n"]},{"type":"object","title":"GeoPoint Field","description":"The field contains data describing a geographic point.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `geopoint`.","enum":["geopoint"]},"format":{"description":"The format keyword options for `geopoint` are `default`,`array`, and `object`.","context":"The following `format` options are supported:\n  * **default**: A string of the pattern 'lon, lat', where `lon` is the longitude and `lat` is the latitude.\n  * **array**: An array of exactly two items, where each item is either a number, or a string parsable as a number, and the first item is `lon` and the second item is `lat`.\n  * **object**: A JSON object with exactly two keys, `lat` and `lon`","notes":["Implementations `MUST` strip all white space in the default format of `lon, lat`."],"enum":["default","array","object"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `geopoint` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"array"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"post_office\",\n  \"type\": \"geopoint\"\n}\n","{\n  \"name\": \"post_office\",\n  \"type\": \"geopoint\",\n  \"format\": \"array\"\n}\n"]},{"type":"object","title":"GeoJSON Field","description":"The field contains a JSON object according to GeoJSON or TopoJSON","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `geojson`.","enum":["geojson"]},"format":{"description":"The format keyword options for `geojson` are `default` and `topojson`.","context":"The following `format` options are supported:\n  * **default**: A geojson object as per the [GeoJSON spec](http://geojson.org/).\n  * **topojson**: A topojson object as per the [TopoJSON spec](https://github.com/topojson/topojson-specification/blob/master/README.md)","enum":["default","topojson"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `geojson` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"city_limits\",\n  \"type\": \"geojson\"\n}\n","{\n  \"name\": \"city_limits\",\n  \"type\": \"geojson\",\n  \"format\": \"topojson\"\n}\n"]},{"type":"object","title":"Array Field","description":"The field contains data which can be parsed as a valid JSON array.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `array`.","enum":["array"]},"format":{"description":"There are no format keyword options for `array`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints apply for `array` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"array"}}]},"minLength":{"type":"integer","description":"An integer that specifies the minimum length of a value."},"maxLength":{"type":"integer","description":"An integer that specifies the maximum length of a value."}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"options\"\n  \"type\": \"array\"\n}\n"]},{"type":"object","title":"Duration Field","description":"The field contains a duration of time.","context":"The lexical representation for duration is the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) extended format `PnYnMnDTnHnMnS`, where `nY` represents the number of years, `nM` the number of months, `nD` the number of days, 'T' is the date/time separator, `nH` the number of hours, `nM` the number of minutes and `nS` the number of seconds. The number of seconds can include decimal digits to arbitrary precision. Date and time elements including their designator may be omitted if their value is zero, and lower order elements may also be omitted for reduced precision. Here we follow the definition of [XML Schema duration datatype](http://www.w3.org/TR/xmlschema-2/#duration) directly and that definition is implicitly inlined here.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `duration`.","enum":["duration"]},"format":{"description":"There are no format keyword options for `duration`: only `default` is allowed.","enum":["default"],"default":"default"},"constraints":{"title":"Constraints","description":"The following constraints are supported for `duration` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"minimum":{"type":"string"},"maximum":{"type":"string"}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"period\"\n  \"type\": \"duration\"\n}\n"]},{"type":"object","title":"Any Field","description":"Any value is accepted, including values that are not captured by the type/format/constraint requirements of the specification.","required":["name","type"],"properties":{"name":{"title":"Name","description":"A name for this field.","type":"string"},"title":{"title":"Title","description":"A human-readable title.","type":"string","examples":["{\n  \"title\": \"My Package Title\"\n}\n"]},"description":{"title":"Description","description":"A text description. Markdown is encouraged.","type":"string","examples":["{\n  \"description\": \"# My Package description\\nAll about my package.\"\n}\n"]},"example":{"title":"Example","description":"An example value for the field.","type":"string","examples":["{\n  \"example\": \"Put here an example value for your field\"\n}\n"]},"type":{"description":"The type keyword, which `MUST` be a value of `any`.","enum":["any"]},"constraints":{"title":"Constraints","description":"The following constraints apply to `any` fields.","type":"object","properties":{"required":{"type":"boolean","description":"Indicates whether a property must have a value for each instance.","context":"An empty string is considered to be a missing value."},"unique":{"type":"boolean","description":"When `true`, each value for the property `MUST` be unique."},"enum":{"type":"array","minItems":1,"uniqueItems":true}}},"rdfType":{"type":"string","description":"The RDF type for this field."}},"examples":["{\n  \"name\": \"notes\",\n  \"type\": \"any\"\n"]}]},"description":"An `array` of Table Schema Field objects.","examples":["{\n  \"fields\": [\n    {\n      \"name\": \"my-field-name\"\n    }\n  ]\n}\n","{\n  \"fields\": [\n    {\n      \"name\": \"my-field-name\",\n      \"type\": \"number\"\n    },\n    {\n      \"name\": \"my-field-name-2\",\n      \"type\": \"string\",\n      \"format\": \"email\"\n    }\n  ]\n}\n"]},"primaryKey":{"oneOf":[{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string"}},{"type":"string"}],"description":"A primary key is a field name or an array of field names, whose values `MUST` uniquely identify each row in the table.","context":"Field name in the `primaryKey` `MUST` be unique, and `MUST` match a field name in the associated table. It is acceptable to have an array with a single value, indicating that the value of a single field is the primary key.","examples":["{\n  \"primaryKey\": [\n    \"name\"\n  ]\n}\n","{\n  \"primaryKey\": [\n    \"first_name\",\n    \"last_name\"\n  ]\n}\n"]},"foreignKeys":{"type":"array","minItems":1,"items":{"title":"Table Schema Foreign Key","description":"Table Schema Foreign Key","type":"object","required":["fields","reference"],"oneOf":[{"properties":{"fields":{"type":"array","items":{"type":"string","minItems":1,"uniqueItems":true,"description":"Fields that make up the primary key."}},"reference":{"type":"object","required":["resource","fields"],"properties":{"resource":{"type":"string","default":""},"fields":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true}}}}},{"properties":{"fields":{"type":"string","description":"Fields that make up the primary key."},"reference":{"type":"object","required":["resource","fields"],"properties":{"resource":{"type":"string","default":""},"fields":{"type":"string"}}}}}]},"examples":["{\n  \"foreignKeys\": [\n    {\n      \"fields\": \"state\",\n      \"reference\": {\n        \"resource\": \"the-resource\",\n        \"fields\": \"state_id\"\n      }\n    }\n  ]\n}\n","{\n  \"foreignKeys\": [\n    {\n      \"fields\": \"state\",\n      \"reference\": {\n        \"resource\": \"\",\n        \"fields\": \"id\"\n      }\n    }\n  ]\n}\n"]},"missingValues":{"type":"array","items":{"type":"string"},"default":[""],"description":"Values that when encountered in the source, should be considered as `null`, 'not present', or 'blank' values.","context":"Many datasets arrive with missing data values, either because a value was not collected or it never existed.\nMissing values may be indicated simply by the value being empty in other cases a special value may have been used e.g. `-`, `NaN`, `0`, `-9999` etc.\nThe `missingValues` property provides a way to indicate that these values should be interpreted as equivalent to null.\n\n`missingValues` are strings rather than being the data type of the particular field. This allows for comparison prior to casting and for fields to have missing value which are not of their type, for example a `number` field to have missing values indicated by `-`.\n\nThe default value of `missingValue` for a non-string type field is the empty string `''`. For string type fields there is no default for `missingValue` (for string fields the empty string `''` is a valid value and need not indicate null).","examples":["{\n  \"missingValues\": [\n    \"-\",\n    \"NaN\",\n    \"\"\n  ]\n}\n","{\n  \"missingValues\": []\n}\n"]}},"examples":["{\n  \"schema\": {\n    \"fields\": [\n      {\n        \"name\": \"first_name\",\n        \"type\": \"string\"\n        \"constraints\": {\n          \"required\": true\n        }\n      },\n      {\n        \"name\": \"age\",\n        \"type\": \"integer\"\n      },\n    ],\n    \"primaryKey\": [\n      \"name\"\n    ]\n  }\n}\n"]}},"parameters":{"filterQueryParam":{"in":"query","name":"filter","schema":{"type":"string"},"description":"This is a JSON object mapping column names to arrays of allowed values.  For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{\"pet\": [\"cat\", \"dog\"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them.  For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{\"pet\": [\"cat\", \"dog\"], \"size\": [\"tiny\", \"outrageously small\"]}`.","example":"{\"pet\": [\"cat\", \"dog\"]}","required":false},"sortQueryParam":{"in":"query","name":"sort","schema":{"type":"string"},"description":"Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyFirst,owner`). Available options are: `choiceOrder`, `naturalSort`, `emptyFirst`. Without the `sort` parameter, the order of results is unspecified.","example":"pet,-age","required":false},"limitQueryParam":{"in":"query","name":"limit","schema":{"type":"number"},"description":"Return at most this number of rows.  A value of 0 is equivalent to having no limit.","example":"5","required":false},"sortHeaderParam":{"in":"header","name":"X-Sort","schema":{"type":"string"},"description":"Same as `sort` query parameter.","example":"pet,-age","required":false},"limitHeaderParam":{"in":"header","name":"X-Limit","schema":{"type":"number"},"description":"Same as `limit` query parameter.","example":"5","required":false},"colIdPathParam":{"in":"path","name":"colId","schema":{"type":"string"},"description":"The column id (without the starting `$`) as shown in the column configuration below the label","required":true},"tableIdPathParam":{"in":"path","name":"tableId","schema":{"type":"string"},"description":"normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`","required":true},"docIdPathParam":{"in":"path","name":"docId","schema":{"type":"string"},"description":"A string id (UUID)","required":true},"orgIdPathParam":{"in":"path","name":"orgId","schema":{"oneOf":[{"type":"integer"},{"type":"string"}]},"description":"This can be an integer id, or a string subdomain (e.g. `gristlabs`), or `current` if the org is implied by the domain in the url","required":true},"workspaceIdPathParam":{"in":"path","name":"workspaceId","description":"An integer id","schema":{"type":"integer"},"required":true},"noparseQueryParam":{"in":"query","name":"noparse","schema":{"type":"boolean"},"description":"Set to true to prohibit parsing strings according to the column type."},"hiddenQueryParam":{"in":"query","name":"hidden","schema":{"type":"boolean"},"description":"Set to true to include the hidden columns (like \"manualSort\")"},"headerQueryParam":{"in":"query","name":"header","schema":{"type":"string","enum":["colId","label"]},"description":"Format for headers. Labels tend to be more human-friendly while colIds are more normalized.","required":false}}}}},"searchIndex":{"store":["section/Authentication","tag/orgs","tag/orgs/operation/listOrgs","tag/orgs/operation/describeOrg","tag/orgs/operation/modifyOrg","tag/orgs/operation/listOrgAccess","tag/orgs/operation/modifyOrgAccess","tag/workspaces","tag/workspaces/operation/listWorkspaces","tag/workspaces/operation/createWorkspace","tag/workspaces/operation/describeWorkspace","tag/workspaces/operation/modifyWorkspace","tag/workspaces/operation/deleteWorkspace","tag/workspaces/operation/listWorkspaceAccess","tag/workspaces/operation/modifyWorkspaceAccess","tag/docs","tag/docs/operation/createDoc","tag/docs/operation/describeDoc","tag/docs/operation/modifyDoc","tag/docs/operation/deleteDoc","tag/docs/operation/moveDoc","tag/docs/operation/listDocAccess","tag/docs/operation/modifyDocAccess","tag/docs/operation/downloadDoc","tag/docs/operation/downloadDocXlsx","tag/docs/operation/downloadDocCsv","tag/docs/operation/downloadTableSchema","tag/records","tag/records/operation/listRecords","tag/records/operation/addRecords","tag/records/operation/modifyRecords","tag/records/operation/replaceRecords","tag/tables","tag/tables/operation/listTables","tag/tables/operation/addTables","tag/tables/operation/modifyTables","tag/columns","tag/columns/operation/listColumns","tag/columns/operation/addColumns","tag/columns/operation/modifyColumns","tag/columns/operation/replaceColumns","tag/columns/operation/deleteColumn","tag/data","tag/data/operation/getTableData","tag/data/operation/addRows","tag/data/operation/modifyRows","tag/data/operation/deleteRows","tag/attachments","tag/attachments/operation/listAttachments","tag/attachments/operation/uploadAttachments","tag/attachments/operation/getAttachmentMetadata","tag/attachments/operation/downloadAttachment","tag/webhooks","tag/webhooks/paths/~1docs~1{docId}~1webhooks/get","tag/webhooks/paths/~1docs~1{docId}~1webhooks/post","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1{webhookId}/patch","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1{webhookId}/delete","tag/webhooks/paths/~1docs~1{docId}~1webhooks~1queue/delete","tag/sql","tag/sql/paths/~1docs~1{docId}~1sql/get","tag/sql/paths/~1docs~1{docId}~1sql/post"],"index":{"version":"2.3.9","fields":["title","description"],"fieldVectors":[["title/0",[0,5.068]],["description/0",[1,4.208,2,4.208]],["title/1",[3,2.418]],["description/1",[3,1.097,4,1.984,5,1.776,6,1.984,7,2.3,8,1.621,9,2.3]],["title/2",[3,1.739,10,1.946,11,2.068]],["description/2",[3,1.097,4,1.984,5,1.776,6,1.984,12,2.3,13,2.3,14,2.3]],["title/3",[3,2.023,15,3.275]],["description/3",[16,4.353]],["title/4",[3,2.023,17,2.264]],["description/4",[16,4.353]],["title/5",[3,1.525,10,1.706,11,1.814,18,2.468]],["description/5",[19,4.353]],["title/6",[3,1.739,11,2.068,20,2.569]],["description/6",[19,4.353]],["title/7",[21,2.294]],["description/7",[5,1.953,8,1.782,21,1.145,22,2.529,23,2.529,24,0.689]],["title/8",[3,1.358,10,1.519,21,1.288,24,0.775,25,2.845]],["description/8",[26,4.353]],["title/9",[21,1.65,27,2.815,28,2.815]],["description/9",[26,4.353]],["title/10",[15,3.275,21,1.919]],["description/10",[29,3.896]],["title/11",[17,2.264,21,1.919]],["description/11",[29,3.896]],["title/12",[21,1.919,30,2.988]],["description/12",[29,3.896]],["title/13",[10,1.706,11,1.814,18,2.468,21,1.447]],["description/13",[31,4.353]],["title/14",[11,2.068,20,2.569,21,1.65]],["description/14",[31,4.353]],["title/15",[32,3.914]],["description/15",[21,1.272,24,0.765,33,2.424,34,1.98,35,2.809]],["title/16",[24,0.993,27,2.815,28,2.815]],["description/16",[36,5.045]],["title/17",[15,3.275,24,1.155]],["description/17",[37,3.896]],["title/18",[17,1.706,24,0.87,38,2.468,39,2.08]],["description/18",[37,3.896]],["title/19",[24,1.155,30,2.988]],["description/19",[37,3.896]],["title/20",[3,1.223,21,1.161,24,0.698,40,2.564,41,2.564,42,2.564]],["description/20",[43,5.045]],["title/21",[10,1.706,11,1.814,18,2.468,24,0.87]],["description/21",[44,4.353]],["title/22",[11,2.068,20,2.569,24,0.993]],["description/22",[44,4.353]],["title/23",[24,0.87,39,2.08,45,3.196,46,2.252]],["description/23",[47,5.045]],["title/24",[24,0.87,39,2.08,46,2.252,48,3.196]],["description/24",[49,5.045]],["title/25",[39,2.08,46,2.252,50,0.833,51,3.196]],["description/25",[52,5.045]],["title/26",[50,1.105,53,3.658]],["description/26",[53,2.182,54,2.529,55,2.529,56,2.529,57,2.529,58,2.529]],["title/27",[59,2.294]],["description/27",[8,1.782,33,2.182,34,1.782,50,0.659,59,1.145,60,1.782]],["title/28",[50,0.95,59,1.65,61,3.144]],["description/28",[62,3.556]],["title/29",[50,0.95,59,1.65,63,2.209]],["description/29",[62,3.556]],["title/30",[17,1.946,50,0.95,59,1.65]],["description/30",[62,3.556]],["title/31",[50,0.833,59,1.447,63,1.937,64,2.757]],["description/31",[62,3.556]],["title/32",[50,1.321]],["description/32",[24,0.86,34,2.227,50,0.823,65,2.726]],["title/33",[10,1.946,24,0.993,50,0.95]],["description/33",[66,3.896]],["title/34",[24,0.993,50,0.95,63,2.209]],["description/34",[66,3.896]],["title/35",[17,1.946,24,0.993,50,0.95]],["description/35",[66,3.896]],["title/36",[67,2.706]],["description/36",[34,2.227,50,0.823,65,2.726,67,1.687]],["title/37",[10,1.946,50,0.95,67,1.946]],["description/37",[68,3.556]],["title/38",[50,0.95,63,2.209,67,1.946]],["description/38",[68,3.556]],["title/39",[17,1.946,50,0.95,67,1.946]],["description/39",[68,3.556]],["title/40",[50,0.833,63,1.937,64,2.757,67,1.706]],["description/40",[68,3.556]],["title/41",[30,2.569,50,0.95,67,1.946]],["description/41",[69,5.045]],["title/42",[70,3.572]],["description/42",[50,0.412,59,0.716,70,1.115,71,1.582,72,1.365,73,2.652,74,1.115,75,1.582,76,1.582,77,1.582,78,1.115]],["title/43",[50,0.95,61,3.144,70,2.569]],["description/43",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/44",[50,0.95,60,2.569,63,2.209]],["description/44",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/45",[17,1.946,50,0.95,60,2.569]],["description/45",[59,0.993,74,0.892,78,1.546,79,0.978,80,0.978,81,0.978,82,0.892,83,0.978,84,0.978,85,0.978,86,0.978,87,0.892,88,0.978,89,0.978]],["title/46",[30,2.569,50,0.95,60,2.569]],["description/46",[90,5.045]],["title/47",[91,3.071]],["description/47",[24,0.46,46,1.189,59,0.764,67,0.901,70,1.189,72,1.456,91,1.696,92,1.687,93,1.687,94,1.687]],["title/48",[10,1.706,32,2.468,38,2.468,91,1.937]],["description/48",[95,4.353]],["title/49",[32,2.815,91,2.209,96,3.645]],["description/49",[95,4.353]],["title/50",[38,3.275,91,2.569]],["description/50",[97,5.045]],["title/51",[39,2.372,91,2.209,98,3.645]],["description/51",[99,5.045]],["title/52",[100,3.071]],["description/52",[8,1.621,20,1.621,24,0.626,100,1.394,101,2.3,102,2.3,103,2.3]],["title/53",[24,0.993,100,2.209,104,3.645]],["description/53",[105,4.353]],["title/54",[24,0.87,27,2.468,87,2.252,100,1.937]],["description/54",[105,4.353]],["title/55",[17,2.264,100,2.569]],["description/55",[106,4.353]],["title/56",[82,2.988,100,2.569]],["description/56",[106,4.353]],["title/57",[28,2.198,107,2.845,108,2.845,109,2.845,110,2.845]],["description/57",[111,5.045]],["title/58",[112,3.914]],["description/58",[]],["title/59",[24,0.775,112,2.198,113,2.455,114,2.455,115,2.455]],["description/59",[116,4.353]],["title/60",[24,0.636,112,1.802,113,2.013,114,2.013,115,2.013,117,2.334,118,2.334]],["description/60",[116,4.353]]],"invertedIndex":[["",{"_index":2,"title":{},"description":{"0":{}}}],["access",{"_index":11,"title":{"2":{},"5":{},"6":{},"13":{},"14":{},"21":{},"22":{}},"description":{}}],["add",{"_index":63,"title":{"29":{},"31":{},"34":{},"38":{},"40":{},"44":{}},"description":{}}],["against",{"_index":115,"title":{"59":{},"60":{}},"description":{}}],["anoth",{"_index":41,"title":{"20":{}},"description":{}}],["api",{"_index":9,"title":{},"description":{"1":{}}}],["area",{"_index":13,"title":{},"description":{"2":{}}}],["associ",{"_index":104,"title":{"53":{}},"description":{}}],["attach",{"_index":91,"title":{"47":{},"48":{},"49":{},"50":{},"51":{}},"description":{"47":{}}}],["authent",{"_index":0,"title":{"0":{}},"description":{}}],["avail",{"_index":14,"title":{},"description":{"2":{}}}],["better",{"_index":84,"title":{},"description":{"43":{},"44":{},"45":{}}}],["call",{"_index":8,"title":{},"description":{"1":{},"7":{},"27":{},"52":{}}}],["chang",{"_index":20,"title":{"6":{},"14":{},"22":{}},"description":{"52":{}}}],["collect",{"_index":34,"title":{},"description":{"15":{},"27":{},"32":{},"36":{}}}],["column",{"_index":67,"title":{"36":{},"37":{},"38":{},"39":{},"40":{},"41":{}},"description":{"36":{},"47":{}}}],["columnar",{"_index":75,"title":{},"description":{"42":{}}}],["consid",{"_index":83,"title":{},"description":{"43":{},"44":{},"45":{}}}],["contain",{"_index":33,"title":{},"description":{"15":{},"27":{}}}],["content",{"_index":39,"title":{"18":{},"23":{},"24":{},"25":{},"51":{}},"description":{}}],["creat",{"_index":27,"title":{"9":{},"16":{},"54":{}},"description":{}}],["csv",{"_index":51,"title":{"25":{}},"description":{}}],["data",{"_index":70,"title":{"42":{},"43":{}},"description":{"42":{},"47":{}}}],["delet",{"_index":30,"title":{"12":{},"19":{},"41":{},"46":{}},"description":{}}],["deprec",{"_index":74,"title":{},"description":{"42":{},"43":{},"44":{},"45":{}}}],["describ",{"_index":15,"title":{"3":{},"10":{},"17":{}},"description":{}}],["doc",{"_index":32,"title":{"15":{},"48":{},"49":{}},"description":{}}],["docs/{docid",{"_index":37,"title":{},"description":{"17":{},"18":{},"19":{}}}],["docs/{docid}/access",{"_index":44,"title":{},"description":{"21":{},"22":{}}}],["docs/{docid}/attach",{"_index":95,"title":{},"description":{"48":{},"49":{}}}],["docs/{docid}/attachments/{attachmentid",{"_index":97,"title":{},"description":{"50":{}}}],["docs/{docid}/attachments/{attachmentid}/download",{"_index":99,"title":{},"description":{"51":{}}}],["docs/{docid}/download",{"_index":47,"title":{},"description":{"23":{}}}],["docs/{docid}/download/csv",{"_index":52,"title":{},"description":{"25":{}}}],["docs/{docid}/download/table-schema",{"_index":58,"title":{},"description":{"26":{}}}],["docs/{docid}/download/xlsx",{"_index":49,"title":{},"description":{"24":{}}}],["docs/{docid}/mov",{"_index":43,"title":{},"description":{"20":{}}}],["docs/{docid}/sql",{"_index":116,"title":{},"description":{"59":{},"60":{}}}],["docs/{docid}/t",{"_index":66,"title":{},"description":{"33":{},"34":{},"35":{}}}],["docs/{docid}/tables/{tableid}/column",{"_index":68,"title":{},"description":{"37":{},"38":{},"39":{},"40":{}}}],["docs/{docid}/tables/{tableid}/columns/{colid",{"_index":69,"title":{},"description":{"41":{}}}],["docs/{docid}/tables/{tableid}/data",{"_index":89,"title":{},"description":{"43":{},"44":{},"45":{}}}],["docs/{docid}/tables/{tableid}/data/delet",{"_index":90,"title":{},"description":{"46":{}}}],["docs/{docid}/tables/{tableid}/record",{"_index":62,"title":{},"description":{"28":{},"29":{},"30":{},"31":{}}}],["docs/{docid}/webhook",{"_index":105,"title":{},"description":{"53":{},"54":{}}}],["docs/{docid}/webhooks/queu",{"_index":111,"title":{},"description":{"57":{}}}],["docs/{docid}/webhooks/{webhookid",{"_index":106,"title":{},"description":{"55":{},"56":{}}}],["document",{"_index":24,"title":{"8":{},"16":{},"17":{},"18":{},"19":{},"20":{},"21":{},"22":{},"23":{},"24":{},"33":{},"34":{},"35":{},"53":{},"54":{},"59":{},"60":{}},"description":{"7":{},"15":{},"32":{},"47":{},"52":{}}}],["document'",{"_index":107,"title":{"57":{}},"description":{}}],["download",{"_index":98,"title":{"51":{}},"description":{}}],["empti",{"_index":28,"title":{"9":{},"16":{},"57":{}},"description":{}}],["endpoint",{"_index":78,"title":{},"description":{"42":{},"43":{},"44":{},"45":{}}}],["enumer",{"_index":12,"title":{},"description":{"2":{}}}],["excel",{"_index":48,"title":{"24":{}},"description":{}}],["favor",{"_index":79,"title":{},"description":{"43":{},"44":{},"45":{}}}],["fetch",{"_index":61,"title":{"28":{},"43":{}},"description":{}}],["file",{"_index":46,"title":{"23":{},"24":{},"25":{}},"description":{"47":{}}}],["follow",{"_index":54,"title":{},"description":{"26":{}}}],["format",{"_index":76,"title":{},"description":{"42":{}}}],["frictionlessdata'",{"_index":55,"title":{},"description":{"26":{}}}],["grist",{"_index":35,"title":{},"description":{"15":{}}}],["group",{"_index":23,"title":{},"description":{"7":{}}}],["immedi",{"_index":80,"title":{},"description":{"43":{},"44":{},"45":{}}}],["includ",{"_index":92,"title":{},"description":{"47":{}}}],["list",{"_index":10,"title":{"2":{},"5":{},"8":{},"13":{},"21":{},"33":{},"37":{},"48":{}},"description":{}}],["metadata",{"_index":38,"title":{"18":{},"48":{},"50":{}},"description":{}}],["modifi",{"_index":17,"title":{"4":{},"11":{},"18":{},"30":{},"35":{},"39":{},"45":{},"55":{}},"description":{}}],["move",{"_index":40,"title":{"20":{}},"description":{}}],["new",{"_index":87,"title":{"54":{}},"description":{"43":{},"44":{},"45":{}}}],["now",{"_index":73,"title":{},"description":{"42":{}}}],["option",{"_index":117,"title":{"60":{}},"description":{}}],["org",{"_index":3,"title":{"1":{},"2":{},"3":{},"4":{},"5":{},"6":{},"8":{},"20":{}},"description":{"1":{},"2":{}}}],["organ",{"_index":22,"title":{},"description":{"7":{}}}],["orgs/{orgid",{"_index":16,"title":{},"description":{"3":{},"4":{}}}],["orgs/{orgid}/access",{"_index":19,"title":{},"description":{"5":{},"6":{}}}],["orgs/{orgid}/workspac",{"_index":26,"title":{},"description":{"8":{},"9":{}}}],["paramet",{"_index":118,"title":{"60":{}},"description":{}}],["payload",{"_index":110,"title":{"57":{}},"description":{}}],["person",{"_index":6,"title":{},"description":{"1":{},"2":{}}}],["plan",{"_index":81,"title":{},"description":{"43":{},"44":{},"45":{}}}],["point",{"_index":86,"title":{},"description":{"43":{},"44":{},"45":{}}}],["project",{"_index":88,"title":{},"description":{"43":{},"44":{},"45":{}}}],["queri",{"_index":114,"title":{"59":{},"60":{}},"description":{}}],["queue",{"_index":108,"title":{"57":{}},"description":{}}],["recommend",{"_index":77,"title":{},"description":{"42":{}}}],["record",{"_index":59,"title":{"27":{},"28":{},"29":{},"30":{},"31":{}},"description":{"27":{},"42":{},"43":{},"44":{},"45":{},"47":{}}}],["refer",{"_index":93,"title":{},"description":{"47":{}}}],["remov",{"_index":82,"title":{"56":{}},"description":{"43":{},"44":{},"45":{}}}],["request",{"_index":102,"title":{},"description":{"52":{}}}],["row",{"_index":60,"title":{"44":{},"45":{},"46":{}},"description":{"27":{}}}],["run",{"_index":113,"title":{"59":{},"60":{}},"description":{}}],["same",{"_index":42,"title":{"20":{}},"description":{}}],["schema",{"_index":53,"title":{"26":{}},"description":{"26":{}}}],["securitydefinit",{"_index":1,"title":{},"description":{"0":{}}}],["site",{"_index":5,"title":{},"description":{"1":{},"2":{},"7":{}}}],["space",{"_index":7,"title":{},"description":{"1":{}}}],["sql",{"_index":112,"title":{"58":{},"59":{},"60":{}},"description":{}}],["sqlite",{"_index":45,"title":{"23":{}},"description":{}}],["standard](https://specs.frictionlessdata.io/table-schema",{"_index":57,"title":{},"description":{"26":{}}}],["start",{"_index":85,"title":{},"description":{"43":{},"44":{},"45":{}}}],["structur",{"_index":65,"title":{},"description":{"32":{},"36":{}}}],["tabl",{"_index":50,"title":{"25":{},"26":{},"28":{},"29":{},"30":{},"31":{},"32":{},"33":{},"34":{},"35":{},"37":{},"38":{},"39":{},"40":{},"41":{},"43":{},"44":{},"45":{},"46":{}},"description":{"27":{},"32":{},"36":{},"42":{}}}],["table-schema",{"_index":56,"title":{},"description":{"26":{}}}],["team",{"_index":4,"title":{},"description":{"1":{},"2":{}}}],["trigger",{"_index":101,"title":{},"description":{"52":{}}}],["type",{"_index":94,"title":{},"description":{"47":{}}}],["undeliv",{"_index":109,"title":{"57":{}},"description":{}}],["updat",{"_index":64,"title":{"31":{},"40":{}},"description":{}}],["upload",{"_index":96,"title":{"49":{}},"description":{}}],["url",{"_index":103,"title":{},"description":{"52":{}}}],["us",{"_index":72,"title":{},"description":{"42":{},"47":{}}}],["user",{"_index":18,"title":{"5":{},"13":{},"21":{}},"description":{}}],["webhook",{"_index":100,"title":{"52":{},"53":{},"54":{},"55":{},"56":{}},"description":{"52":{}}}],["within",{"_index":25,"title":{"8":{}},"description":{}}],["work",{"_index":71,"title":{},"description":{"42":{}}}],["workspac",{"_index":21,"title":{"7":{},"8":{},"9":{},"10":{},"11":{},"12":{},"13":{},"14":{},"20":{}},"description":{"7":{},"15":{}}}],["workspaces/{workspaceid",{"_index":29,"title":{},"description":{"10":{},"11":{},"12":{}}}],["workspaces/{workspaceid}/access",{"_index":31,"title":{},"description":{"13":{},"14":{}}}],["workspaces/{workspaceid}/doc",{"_index":36,"title":{},"description":{"16":{}}}]],"pipeline":[]}},"options":{"theme":{"spacing":{"sectionVertical":2},"breakpoints":{"medium":"50rem","large":"50rem"},"sidebar":{"width":"0px"}},"hideDownloadButton":true,"pathInMiddlePanel":true,"scrollYOffset":48,"jsonSampleExpandLevel":"all"}};
 
     var container = document.getElementById('redoc');
     Redoc.hydrate(__redoc_state, container);
diff --git a/help/en/docs/examples/2020-06-book-club.md b/help/en/docs/examples/2020-06-book-club.md
index 963e02cf2..e6d5d0a3a 100644
--- a/help/en/docs/examples/2020-06-book-club.md
+++ b/help/en/docs/examples/2020-06-book-club.md
@@ -19,7 +19,7 @@ on [isbnsearch.org](https://isbnsearch.org)
 by its title and author. To do this, add a new column, and then set it to be a
 [HyperLink column](../col-types.md#text-columns):
 
-![Make an ISBN finder](/examples/images/2020-06-book-club-find-isbn.png)
+![Make an ISBN finder](../examples/images/2020-06-book-club-find-isbn.png)
 
 What we're going to do is fill this column using a formula that takes the
 book title and the author's name, and uses them as a keyword to search on
@@ -35,17 +35,17 @@ URLs with spaces or apostrophes or other odd letters you might find in
 names need special encoding, so we've used the python `urllib` module to make sure
 everything gets encoded correctly.  Now we've got a handy `[isbn]` link beside each book:
 
-![ISBN link formula](/examples/images/2020-06-book-club-isbn-link.png)
+![ISBN link formula](../examples/images/2020-06-book-club-isbn-link.png)
 
 We can click the arrow by `[isbn]`, locate the book, and make note of its ISBN code
 in a new column:
 
-![Start](/examples/images/2020-06-book-club-isbn-search-result.png)
+![Start](../examples/images/2020-06-book-club-isbn-search-result.png)
 
 Then we can add it into our book list. Now that we have a helping hand for finding ISBNs,
 let's add a few more books too:
 
-![Start](/examples/images/2020-06-book-club-all-isbn.png)
+![Start](../examples/images/2020-06-book-club-all-isbn.png)
 
 ## Library and store lookups
 
@@ -68,12 +68,12 @@ keywords = ($Title or "") + " " + ($Author or "") + " " + ($ISBN or "")
 
 The new links look like this:
 
-![Start](/examples/images/2020-06-book-club-buy.png)
+![Start](../examples/images/2020-06-book-club-buy.png)
 
 Clicking on the `[buy]` link near a book now brings us to that book on
 [indiebound.org](https://indiebound.org).
 
-![Start](/examples/images/2020-06-book-club-indie.png)
+![Start](../examples/images/2020-06-book-club-indie.png)
 
 For your local library, the same idea is very likely to work.  For example, in
 northern New Jersey, in the US, here's what you want:
@@ -100,7 +100,7 @@ keywords = ($Title or "") + " " + ($Author.Name or "")
 
 Once we have all these links, it makes sense to add a [Card View](../linking-widgets.md#same-record-linking) so we can lay them out:
 
-![Start](/examples/images/2020-06-book-club-card.png)
+![Start](../examples/images/2020-06-book-club-card.png)
 
 ## Ready-made template
 
diff --git a/help/en/docs/examples/2020-06-credit-card.md b/help/en/docs/examples/2020-06-credit-card.md
index 72cc5e491..11701b7c7 100644
--- a/help/en/docs/examples/2020-06-credit-card.md
+++ b/help/en/docs/examples/2020-06-credit-card.md
@@ -12,13 +12,13 @@ Here is an example using data from American Express (redacted for privacy, of co
 This first page is a dashboard: it shows a few summary charts — your expenses by month, and two pie
 charts to let you quickly see which card member or which category has the most expenses.
 
-![Dashboard](/examples/images/2020-06-credit-card-dashboard.png)
+![Dashboard](../examples/images/2020-06-credit-card-dashboard.png)
 
 The next three pages show breakdowns by Category, Card Member, and by Month. In addition to the
 totals by Category, you can click on any Category to see all transactions in it, and then click on
 any transaction to see its complete details.
 
-![By Category](/examples/images/2020-06-credit-card-by-category.png)
+![By Category](../examples/images/2020-06-credit-card-by-category.png)
 
 Here is the
 [example with sample data](https://templates.getgrist.com/2i9WoHs2oRzK/Credit-Card-Activity-Template-AmEx/){:target="\_blank"}
diff --git a/help/en/docs/examples/2020-07-email-compose.md b/help/en/docs/examples/2020-07-email-compose.md
index abf101be9..ec3600954 100644
--- a/help/en/docs/examples/2020-07-email-compose.md
+++ b/help/en/docs/examples/2020-07-email-compose.md
@@ -16,13 +16,13 @@ this formula:
 `"Compose Email mailto:%s" % ($Email)`{: .formula}.
 Set its type to Text, and its cell format to Hyperlink:
 
-<span class="screenshot-large">*![HyperLink Format](/examples/images/2020-07-hyperlink-format.png)*</span>
+<span class="screenshot-large">*![HyperLink Format](../examples/images/2020-07-hyperlink-format.png)*</span>
 {: .screenshot-half }
 
 You'll get a link in each person's row, which you can click to start composing an email to that
 person:
 
-<span class="screenshot-large">*![Mailto Cells](/examples/images/2020-07-hyperlink-cells.png)*</span>
+<span class="screenshot-large">*![Mailto Cells](../examples/images/2020-07-hyperlink-cells.png)*</span>
 {: .screenshot-half }
 
 See an example of this in action here:
diff --git a/help/en/docs/examples/2020-08-invoices.md b/help/en/docs/examples/2020-08-invoices.md
index f5f094a2b..ea2fa21b2 100644
--- a/help/en/docs/examples/2020-08-invoices.md
+++ b/help/en/docs/examples/2020-08-invoices.md
@@ -4,7 +4,7 @@ If you are keeping records of who is charged what in Grist, it can be convenient
 to generate invoices right there and then beside those records.  This tutorial
 shows you how to set up a document like this:
 
-![Invoice](/examples/images/2020-08-invoices/final-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/final-invoice.png)
 
 
 You can find a finished template at <https://templates.getgrist.com/9NH6D58FmxwP/Invoicing>{:target="\_blank"}.
@@ -17,7 +17,7 @@ First of all, make a table to record invoices by
 [creating an empty document](../creating-doc.md) and renaming `Table1` to `Invoices`:
 
 
-![Invoice](/examples/images/2020-08-invoices/make-invoices-table.png)
+![Invoice](../examples/images/2020-08-invoices/make-invoices-table.png)
 
 Now, let's add a widget beside the table to view the finished invoices.
 There are all sorts of possible styles of invoice, so Grist lets web
@@ -32,14 +32,14 @@ Click on `Add New`, then `Add Widget to Page`.  Then:
   * For `Select By` choose `INVOICES` so that the Custom Widget will show data from whatever
     invoice is currently selected by the user.
 
-![Invoice](/examples/images/2020-08-invoices/add-custom-widget.png)
+![Invoice](../examples/images/2020-08-invoices/add-custom-widget.png)
 
 Great, now we have two widgets, a Table Widget that will have invoice data,
 and a Custom Widget that will view that data as a nicely formatted, printable invoice.
 The Custom Widget starts off blank; select `Widget options` to specify what we want in
 it:
 
-![Invoice](/examples/images/2020-08-invoices/widget-options.png)
+![Invoice](../examples/images/2020-08-invoices/widget-options.png)
 
 In the `CUSTOM` settings section where it says `Full URL of webpage to show`, put this
 link:
@@ -49,12 +49,12 @@ link:
 And set `Access` to `read table`.  This grants the Custom Widget access to read the
 Invoices table.
 
-![Invoice](/examples/images/2020-08-invoices/set-url.png)
+![Invoice](../examples/images/2020-08-invoices/set-url.png)
 
 Now place anything you like in a row of the Invoices table (I just added the number `1`).
 An incomplete invoice will immediately show up:
 
-![Invoice](/examples/images/2020-08-invoices/empty-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/empty-invoice.png)
 
 The incomplete invoice shows what column names to use to control what parts of the
 invoice.  An extra black box shows what columns the widget understands, what columns
@@ -71,25 +71,25 @@ where `$id` is an auto-incrementing numeric identifier assigned to each row.
 But you could set it manually or with a different formula.  As soon as it is
 set, the invoice updates:
 
-![Invoice](/examples/images/2020-08-invoices/add-number.png)
+![Invoice](../examples/images/2020-08-invoices/add-number.png)
 
 The next column the help box suggests is `Client`, so
 let's rename the `B` column to `Client`.  Later we will give client
 information in a structured way, but for now let's just put some text
 here (use <code class="keys">*Shift* + *Enter*</code> to insert line breaks):
 
-![Invoice](/examples/images/2020-08-invoices/add-client.png)
+![Invoice](../examples/images/2020-08-invoices/add-client.png)
 
 Great, now the Client box is filled out.  The next suggested column is `Items`,
 so let's rename the `C` column to `Items`.  Later we will give item
 information in a structured way, but for now let's just put some text here:
 
-![Invoice](/examples/images/2020-08-invoices/add-items.png)
+![Invoice](../examples/images/2020-08-invoices/add-items.png)
 
 And now the Description is set.  We're missing a total, so let's add a
 column called `Total` and set it to `100`:
 
-![Invoice](/examples/images/2020-08-invoices/add-total.png)
+![Invoice](../examples/images/2020-08-invoices/add-total.png)
 
 The invoice won't update immediately.  This is the first new column we've
 added - until now we've been renaming them.  When we created the Custom Widget,
@@ -97,20 +97,20 @@ it was given access to the columns that existed at the time of creation.
 To let the widget see the new column, open `Widget options` again and move
 `Total` from `Hidden Columns` to `Visible Columns`:
 
-![Invoice](/examples/images/2020-08-invoices/add-total-visible.png)
+![Invoice](../examples/images/2020-08-invoices/add-total-visible.png)
 
 Great, the invoice updated.  Now let's set who the invoice is from, by
 adding an `Invoicer` column (remember to make it visible to the widget
 via `Widget options`).
 
-![Invoice](/examples/images/2020-08-invoices/add-invoicer.png)
+![Invoice](../examples/images/2020-08-invoices/add-invoicer.png)
 
 As a last step to creating a usable invoice, let's make an `Issued`
 column and put today's date in it (remember to make it visible to the widget
 via `Widget options`).  As soon as the invoice has a date, the black help
 box will disappear:
 
-![Invoice](/examples/images/2020-08-invoices/add-issued.png)
+![Invoice](../examples/images/2020-08-invoices/add-issued.png)
 
 Okay!  If someone sent me that, I'd pay it.  You should nudge me by
 giving it a due date though.  Let's make a `Due` column and set it to
@@ -120,12 +120,12 @@ visible to the widget via `Widget options`.  Also, be sure to
 `Issued` to `Date` or you won't be able to do date math on it (it will
 just be a string).
 
-![Invoice](/examples/images/2020-08-invoices/add-due.png)
+![Invoice](../examples/images/2020-08-invoices/add-due.png)
 
 If there are special instructions to go with the invoice, we can add a `Note`
 column.  Remember to make it visible to the widget via `Widget options`.
 
-![Invoice](/examples/images/2020-08-invoices/add-note.png)
+![Invoice](../examples/images/2020-08-invoices/add-note.png)
 
 ## Entering client information
 
@@ -156,19 +156,19 @@ When the invoice widget sees a column named "References", it fills out the invoi
 "packaged" values in that column, rather than the individual invoice fields. The benefit will be
 seen in the next step, since these packaged values can include data from related records.
 
-![Invoice](/examples/images/2020-08-invoices/add-references.png)
+![Invoice](../examples/images/2020-08-invoices/add-references.png)
 
 Next let's place client information in a separate table.  Add a new table
 to the page for entering business information by clicking
 on `Add New`, `Add Widget to Page`, then `Select Widget > Table` and
 `Select Data > New Table`:
 
-![Invoice](/examples/images/2020-08-invoices/add-businesses.png)
+![Invoice](../examples/images/2020-08-invoices/add-businesses.png)
 
 Then rename the table to `Businesses`. Let's also empty the `Client` column
 so we can see help about what the widget expects there:
 
-![Invoice](/examples/images/2020-08-invoices/add-businesses-rename.png)
+![Invoice](../examples/images/2020-08-invoices/add-businesses-rename.png)
 
 The widget suggests `Name`, `Street1`, `Street2`, `City`, `State`
 and `Zip` columns.  So let's provide those columns in our `Businesses` table,
@@ -177,12 +177,12 @@ the `Client` column, and in `Column options` set the Column Type to
 `Reference`.  Refer to `Businesses` `Name` if Grist doesn't automatically
 guess that.
 
-![Invoice](/examples/images/2020-08-invoices/add-a-business.png)
+![Invoice](../examples/images/2020-08-invoices/add-a-business.png)
 
 Once you hit `Apply`, you will see a nicely formatted Client
 section.
 
-![Invoice](/examples/images/2020-08-invoices/link-client.png)
+![Invoice](../examples/images/2020-08-invoices/link-client.png)
 
 ## Entering invoicer information
 
@@ -207,7 +207,7 @@ your business, you could skip setting up a reference by entering a formula like
 
 Then set the Column Type for `Invoicer` to `Any` in the right-side panel.
 
-![Invoice](/examples/images/2020-08-invoices/link-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/link-invoice.png)
 
 Notice how emails, phone numbers, and links are specially formatted by the
 widget.
@@ -223,7 +223,7 @@ and give it those four columns.  We can set `Total` to be this simple formula:
 
 `$Price * $Quantity`{: .formula}
 
-![Invoice](/examples/images/2020-08-invoices/add-items-table.png)
+![Invoice](../examples/images/2020-08-invoices/add-items-table.png)
 
 Now we need to pull these items into the `Invoices` table so that
 the Custom Widget gets access to them. Set the `Items` column to
@@ -231,32 +231,32 @@ the formula `Items.lookupRecords()`{: .formula}, and then reset
 its column type to be `Any`. This formula needs a little more work,
 which we'll do soon, but let's just start with that.
 
-![Invoice](/examples/images/2020-08-invoices/add-items-lookup.png)
+![Invoice](../examples/images/2020-08-invoices/add-items-lookup.png)
 
 Great, our invoice is updating nicely!  Remove the `Total` column
 to get an automatically calculated one:
 
-![Invoice](/examples/images/2020-08-invoices/plausible-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/plausible-invoice.png)
 
 It is probably more comfortable to edit invoices
 as a Card Widget than a Table Widget, so let's change that
 using `Widget options`, `Table`, `Change Widget`, `Card`, `Save`.
 You can [customize the card layout](../widget-card.md#editing-card-layout) to your taste.
 
-![Invoice](/examples/images/2020-08-invoices/invoice-card.png)
+![Invoice](../examples/images/2020-08-invoices/invoice-card.png)
 
 To add a new invoice, click the little `+` above the invoices card,
 set an `Issued` date, and pick either the existing Client or add
 a new one.
 
-![Invoice](/examples/images/2020-08-invoices/invoice-new.png)
+![Invoice](../examples/images/2020-08-invoices/invoice-new.png)
 
 Once we have a second invoice, it becomes clear we skimped on the
 formula for collecting invoice items - all the invoices contain
 all the items.  No problem, we can get more specific by adding an `Invoice`
 column to `Items` and setting it up to refer to specific `Invoices`:
 
-![Invoice](/examples/images/2020-08-invoices/add-invoice-column.png)
+![Invoice](../examples/images/2020-08-invoices/add-invoice-column.png)
 
 Once that is done we can sprinkle on some Grist fairy dust, and
 go to `Widget options` for the `ITEMS` Table Widget, click
@@ -266,7 +266,7 @@ are shown.  Even better, when you add new items, the `invoice`
 column is automatically set to the invoice you are viewing.
 So you can just hide the `invoice` column and forget about it.
 
-![Invoice](/examples/images/2020-08-invoices/link-items-to-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/link-items-to-invoice.png)
 
 Now let the Custom Widget know what items to use by updating the
 `Items` formula to be more picky:
@@ -275,7 +275,7 @@ Now let the Custom Widget know what items to use by updating the
 Items.lookupRecords(Invoice=$id)
 ```
 
-![Invoice](/examples/images/2020-08-invoices/items-formula.png)
+![Invoice](../examples/images/2020-08-invoices/items-formula.png)
 
 With that, entering new invoices is a breeze!
 
@@ -298,6 +298,6 @@ don't need to be Grist experts).
 For interested developers, the GitHub code is here:
 <https://github.com/gristlabs/grist-widget/tree/master/invoices>.
 
-![Invoice](/examples/images/2020-08-invoices/final-invoice.png)
+![Invoice](../examples/images/2020-08-invoices/final-invoice.png)
 
 Enjoy, and good luck getting paid!
diff --git a/help/en/docs/examples/2020-09-payroll.md b/help/en/docs/examples/2020-09-payroll.md
index 33358c562..ff84809fc 100644
--- a/help/en/docs/examples/2020-09-payroll.md
+++ b/help/en/docs/examples/2020-09-payroll.md
@@ -6,7 +6,7 @@ and it probably asks you to enter hours for each employee once a month.
 This is where Grist can help you keep track of things conveniently, and to reduce mistakes,
 especially if you have part-time employees.
 
-![Payroll Summary](/examples/images/2020-09-payroll/pay-periods.png)
+![Payroll Summary](../examples/images/2020-09-payroll/pay-periods.png)
 
 ## The Payroll Template
 
@@ -27,7 +27,7 @@ The template addresses a few needs:
 
 Let’s start with the "People" tab in the example. It addresses our needs (1), (2), and (3).
 
-![People Page](/examples/images/2020-09-payroll/people-page.png)
+![People Page](../examples/images/2020-09-payroll/people-page.png)
 
 On top, we have a list of people, with contact info such as address and phone number. To add a new
 person, click into the last row of the `PEOPLE` table, and type in the data.
@@ -44,7 +44,7 @@ class="keys">*⌘* + **;** (semicolon)</code> on Mac or <code class="keys">*Ctrl
 Windows). Set the `Role` that it applies to, and the `Hourly Rate`. The `Comment` field is for
 your own notes.
 
-<span class="screenshot-large">*![Adding Rates](/examples/images/2020-09-payroll/add-rate.png)*</span>
+<span class="screenshot-large">*![Adding Rates](../examples/images/2020-09-payroll/add-rate.png)*</span>
 {: .screenshot-half }
 
 Don’t modify values for existing rates, or past payroll computations will be affected. When you
@@ -58,7 +58,7 @@ page first in the list of pages to have it open by default when you open the doc
 bottom (you can use these handy shortcuts: <code class="keys">*⌘* *↓*</code> on Mac, <code
 class="keys">*Ctrl* + *↓*</code> on Windows).
 
-![Payroll Page](/examples/images/2020-09-payroll/payroll-page.png)
+![Payroll Page](../examples/images/2020-09-payroll/payroll-page.png)
 
 To add a payroll entry, type in the date (or use the date picker), select the person using
 auto-complete, select their role, and type in their hours. The next few columns automatically look
@@ -76,7 +76,7 @@ to customize this further to your needs, I’ll explain it in detail below.
 Here the totals for each period are automatically tallied up to address our need (5) — to see an
 overview, to enter data into a payroll system, and to check that everything matches.
 
-![Payroll Summary](/examples/images/2020-09-payroll/pay-periods.png)
+![Payroll Summary](../examples/images/2020-09-payroll/pay-periods.png)
 
 The latest pay period (in our case, a month) is on top of the top-left table. You can select any
 pay period there to see a pie chart with an overview of pay broken down by role, and a table of
@@ -96,7 +96,7 @@ We now have a convenient and simple payroll tracker.
 I promised to show how rates are looked up. Open up the "Payroll" page, click on
 any cell in the `Per Hour` column, and hit <code class="keys">*Enter*</code>.
 
-<span class="screenshot-large">*![Rate Lookup Formula](/examples/images/2020-09-payroll/rate-lookup-formula.png)*</span>
+<span class="screenshot-large">*![Rate Lookup Formula](../examples/images/2020-09-payroll/rate-lookup-formula.png)*</span>
 {: .screenshot-half }
 
 The formula you see is an involved Python function, but it is intentionally broken up into bits,
@@ -144,12 +144,12 @@ To start using this example for your own payroll, start with the template:
 
 then click "Save Copy":
 
-<span class="screenshot-large">*![Save Copy](/examples/images/2020-09-payroll/save-copy.png)*</span>
+<span class="screenshot-large">*![Save Copy](../examples/images/2020-09-payroll/save-copy.png)*</span>
 {: .screenshot-half }
 
 Then mark the "As Template" checkbox.
 
-<span class="screenshot-large">*![Duplicate As Template](/examples/images/2020-09-payroll/duplicate-as-template.png)*</span>
+<span class="screenshot-large">*![Duplicate As Template](../examples/images/2020-09-payroll/duplicate-as-template.png)*</span>
 {: .screenshot-half }
 
 Your copy will then include all the structure, logic, and layouts of the Payroll document with
diff --git a/help/en/docs/examples/2020-10-print-labels.md b/help/en/docs/examples/2020-10-print-labels.md
index 220f17425..02aafcd7d 100644
--- a/help/en/docs/examples/2020-10-print-labels.md
+++ b/help/en/docs/examples/2020-10-print-labels.md
@@ -29,7 +29,7 @@ The template shows a few variations of what you can do.
 
 That's what you see in the first page:
 
-![Address Labels Page](/examples/images/2020-10-print-labels/address-labels-page.png)
+![Address Labels Page](../examples/images/2020-10-print-labels/address-labels-page.png)
 
 You can use the dropdown on top of the labels widget to select the size of the labels, depending
 on what actual label paper you are planning to print on.
@@ -42,7 +42,7 @@ together all the parts of an address. (We get into the
 To print the labels, select "Print widget" from the menu above the labels widget (see also
 [Printing Notes](#printing-notes) below):
 
-<span class="screenshot-large">*![Print Menu](/examples/images/2020-10-print-labels/print-menu.png)*</span>
+<span class="screenshot-large">*![Print Menu](../examples/images/2020-10-print-labels/print-menu.png)*</span>
 {: .screenshot-half }
 
 ### A sheet of labels for the same address
@@ -50,7 +50,7 @@ To print the labels, select "Print widget" from the menu above the labels widget
 If you need many identical labels, e.g. for a return address, add another column named
 `LabelCount`. This is illustrated in the page "Label Sheets".
 
-![Label Sheets Page](/examples/images/2020-10-print-labels/label-sheets-page.png)
+![Label Sheets Page](../examples/images/2020-10-print-labels/label-sheets-page.png)
 
 If you have multiple addresses in the table, and want to print just one, simply set the count to
 zero for the addresses you don't want to include.
@@ -63,7 +63,7 @@ are illustrated in the linked template:
 1. The "Address Labels" page includes a filter button for `State`, which allows simple filtering
    by state. You can click `+` button to easily create additional filters like this:
 
-    <span class="screenshot-large">*![Filter Button](/examples/images/2020-10-print-labels/filter-button.png)*</span>
+    <span class="screenshot-large">*![Filter Button](../examples/images/2020-10-print-labels/filter-button.png)*</span>
     {: .screenshot-half }
 
 2. To print out only a few labels out of a larger table, you can use the
@@ -72,7 +72,7 @@ are illustrated in the linked template:
    with the simple formula that includes only California addresses:
    `IF($State == "CA", 1, 0)`{: .formula}:
 
-    ![Filtered Page](/examples/images/2020-10-print-labels/filtered-page.png)
+    ![Filtered Page](../examples/images/2020-10-print-labels/filtered-page.png)
 
 3. The "Filtered Manually" page includes a `Select for Print` column. Click any toggle to include
    the corresponding row into the label sheet.
@@ -92,7 +92,7 @@ I'll assume that you already have a page that shows a table with addresses. Perh
 "People", "Clients", or "Employees". Open the menu next to the page name in the left
 panel, and click "Duplicate":
 
-<span class="screenshot-large">*![Duplicate Page](/examples/images/2020-10-print-labels/duplicate-page.png)*</span>
+<span class="screenshot-large">*![Duplicate Page](../examples/images/2020-10-print-labels/duplicate-page.png)*</span>
 {: .screenshot-half }
 
 This gives you a new page. We'll add the labels here, to avoid taking up screen space in the page
@@ -119,14 +119,14 @@ Note that this is Python syntax for formatting strings. Here is a brief guide to
 Click `Add New` button and select `Add Widget to Page`. In the dialog that appears select widget `Custom`
 and the table that contains the addresses:
 
-<span class="screenshot-large">*![Add Page](/examples/images/2020-10-print-labels/add-page.png)*</span>
+<span class="screenshot-large">*![Add Page](../examples/images/2020-10-print-labels/add-page.png)*</span>
 {: .screenshot-half }
 
 Click `Add to Page`.
 
 Open the menu above the widget and select "Widget Options":
 
-<span class="screenshot-large">*![Widget Options](/examples/images/2020-10-print-labels/widget-options.png)*</span>
+<span class="screenshot-large">*![Widget Options](../examples/images/2020-10-print-labels/widget-options.png)*</span>
 {: .screenshot-half }
 
 In the right-side panel that opens, in the "Custom" section, enter the URL of the widget that
@@ -139,7 +139,7 @@ Then change the "Access" dropdown from `none` to `read table`.
 You should now see your labels! If not, check that `LabelText` is listed below under "Visible
 Columns". (If it's under "Hidden Columns", click the "eye" icon to make it visible to the widget.)
 
-<span class="screenshot-large">*![Visible Columns](/examples/images/2020-10-print-labels/visible-columns.png)*</span>
+<span class="screenshot-large">*![Visible Columns](../examples/images/2020-10-print-labels/visible-columns.png)*</span>
 {: .screenshot-half }
 
 You can add another column named `LabelCount` for printing multiple labels or omitting some
@@ -172,5 +172,5 @@ This feature is built using [Custom Widgets](../widget-custom.md). It allows you
 developer, to customize it further using HTML, CSS, and Javascript. For interested developers, the
 code for this widget is available at <https://github.com/gristlabs/grist-widget/tree/master/printlabels>.
 
-<span class="screenshot-large">*![Enjoy Label](/examples/images/2020-10-print-labels/enjoy-label.png)*</span>
+<span class="screenshot-large">*![Enjoy Label](../examples/images/2020-10-print-labels/enjoy-label.png)*</span>
 {: .screenshot-half }
diff --git a/help/en/docs/examples/2020-11-treasure-hunt.md b/help/en/docs/examples/2020-11-treasure-hunt.md
index b4944b7e4..1a8074f27 100644
--- a/help/en/docs/examples/2020-11-treasure-hunt.md
+++ b/help/en/docs/examples/2020-11-treasure-hunt.md
@@ -12,7 +12,7 @@ Seekers can be paired up in teams as needed, depending on their age.
 The hunt really rewards preparation, and Grist can help with that.
 Here's an example hunt:
 
-![Treasure Hunt document](/examples/images/2020-11-treasure-hunt/hunt.png)
+![Treasure Hunt document](../examples/images/2020-11-treasure-hunt/hunt.png)
 
 You can play with the example yourself here:
 
@@ -41,7 +41,7 @@ the clues will survive long enough to be found!
 Enter everywhere you think of in the "Places" widget in the Treasure Hunt document.
 Don't worry about their order just yet.
 
-*![Places Widget](/examples/images/2020-11-treasure-hunt/places.png)*
+*![Places Widget](../examples/images/2020-11-treasure-hunt/places.png)*
 {: .screenshot-half }
 
 ## Clues
@@ -58,7 +58,7 @@ be a pleasure for people who know your space from the before-times
 but cannot be physically present to at least visualize it and propose devious
 hidey-holes to torture those who are.
 
-![Clues Widget](/examples/images/2020-11-treasure-hunt/clues.png)
+![Clues Widget](../examples/images/2020-11-treasure-hunt/clues.png)
 
 ## The Trail
 
@@ -72,7 +72,7 @@ definitely not rocket science but still surprisingly easy to lose
 track of (especially for younger trail creators).  It will also warn
 you if you've repeated the same location twice.
 
-*![Trail Widget](/examples/images/2020-11-treasure-hunt/trail.png)*
+*![Trail Widget](../examples/images/2020-11-treasure-hunt/trail.png)*
 {: .screenshot-half }
 
 ## Printing
@@ -83,7 +83,7 @@ them if delegating this task to enthusiastic helpers.  If the trail
 is outdoors, and it may rain, it is a good idea to wrap clues in
 aluminum foil or plastic.
 
-![Printing](/examples/images/2020-11-treasure-hunt/print.png)
+![Printing](../examples/images/2020-11-treasure-hunt/print.png)
 
 Ideas for places and clues are good to hang onto for future events,
 either as a Grist document or as a print-out.  Enjoy the hunt, and
diff --git a/help/en/docs/examples/2020-12-map.md b/help/en/docs/examples/2020-12-map.md
index 0240a10c0..d00c0ba93 100644
--- a/help/en/docs/examples/2020-12-map.md
+++ b/help/en/docs/examples/2020-12-map.md
@@ -4,16 +4,16 @@ It can be useful sometimes to visualize lists of locations on a geographic map.
 Grist can do that if a table has at least a `Name`, `Latitude`, and `Longitude` column.
 Suppose we have a list of some of the largest objects in America:
 
-![List of large objects](/examples/images/2020-12-map/large-objects.png)
+![List of large objects](../examples/images/2020-12-map/large-objects.png)
 
 The first step to making a map for these is to add a [Custom Widget](../widget-custom.md) to the page:
 
-![Add custom widget](/examples/images/2020-12-map/add-custom.png)
+![Add custom widget](../examples/images/2020-12-map/add-custom.png)
 
 Once we set the widget to be `https://gristlabs.github.io/grist-widget/map/`
 and give it `Read table` access, a map should appear:
 
-![Add map widget](/examples/images/2020-12-map/set-map.png)
+![Add map widget](../examples/images/2020-12-map/set-map.png)
 
 Clicking around in the list of objects brings up the corresponding
 "pop-up" on the map.
@@ -21,7 +21,7 @@ We can add other sections to taste, such as a detail "card" view
 of the attraction's details. This example is available at
 <https://public.getgrist.com/3boQPJrgFmFi/Large-in-America/m/fork>{:target="\_blank"}.
 
-![Large in America](/examples/images/2020-12-map/large-in-america.png)
+![Large in America](../examples/images/2020-12-map/large-in-america.png)
 
 This example has some hidden columns related to geocoding (the process
 of automatically calculating coordinates from addresses).  You can see
@@ -35,7 +35,7 @@ be left untouched; it is a space for the geocoder to store information.
 Finally, `Geocode` is a toggle that should be turned on to automatically
 generate latitude and longitudes.
 
-![Geocoding](/examples/images/2020-12-map/geocoding.png)
+![Geocoding](../examples/images/2020-12-map/geocoding.png)
 
 
 The geocoder will not touch any rows
diff --git a/help/en/docs/examples/2021-01-tasks.md b/help/en/docs/examples/2021-01-tasks.md
index a107b6d8c..8debb1872 100644
--- a/help/en/docs/examples/2021-01-tasks.md
+++ b/help/en/docs/examples/2021-01-tasks.md
@@ -11,7 +11,7 @@ We have a small team, and regular scheduled check-ins. The goals for the check-i
 all the work that was assigned, and to end up with a list of new assignments. After the check-in,
 everyone can see exactly what's expected of them for the next time.
 
-  [![Task View](/examples/images/2021-01-tasks/task-view.png)](https://public.getgrist.com/hik1whAV5snj/Task-Management/m/fork)
+  [![Task View](../examples/images/2021-01-tasks/task-view.png)](https://public.getgrist.com/hik1whAV5snj/Task-Management/m/fork)
 
 You can explore the example at <https://public.getgrist.com/hik1whAV5snj/Task-Management/m/fork>{:target="\_blank"}.
 
@@ -48,7 +48,7 @@ Then click the second date (previous check-in) to go over previously assigned wo
 we take turns going over the finished tasks. It's a chance to mark things as complete. If a task
 wasn't started, change the associated date to today's date -- this will move the task.
 
-  ![Change Task Date](/examples/images/2021-01-tasks/change-task-date.png)
+  ![Change Task Date](../examples/images/2021-01-tasks/change-task-date.png)
 
 There is a field to record optional notes about the outcome. If a task was only partly done, we
 make a note of what got finished, mark it as complete, and make a new task in today's check-in for
@@ -71,7 +71,7 @@ During check-in, we go over any new backlog items and assign priority for them:
 There is a separate `Backlog` page to view all the backlog tasks, ordered by priority from highest to
 lowest.
 
-  ![Backlog](/examples/images/2021-01-tasks/backlog.png)
+  ![Backlog](../examples/images/2021-01-tasks/backlog.png)
 
 When assigning tasks during check-in, visit this page to see if there is anything high-priority
 that should be assigned. If anyone has spare bandwidth, there are usually plenty of smaller
@@ -90,7 +90,7 @@ To start using it for your own tasks, open the Share menu (<span class="grist-ic
 style="--icon: var(--icon-Share)"></span>), and click "Duplicate Document...". Give
 it a name and click the "As Template" checkbox.
 
-  <span class="screenshot-large">*![Duplicate](/examples/images/2021-01-tasks/duplicate.png)*</span>
+  <span class="screenshot-large">*![Duplicate](../examples/images/2021-01-tasks/duplicate.png)*</span>
   {: .screenshot-half }
 
 Your copy will then include the structure and layouts with none of the sample data.
diff --git a/help/en/docs/examples/2021-03-leads.md b/help/en/docs/examples/2021-03-leads.md
index 20a630987..42b2e5e9e 100644
--- a/help/en/docs/examples/2021-03-leads.md
+++ b/help/en/docs/examples/2021-03-leads.md
@@ -4,7 +4,7 @@ Access rules let you control how a shared document is used, and maintain
 a separation of roles and responsibilities.  In this example, we suppose an entrepeneur
 is using Grist as an ad-hoc lead tracker for sales and potential advisors:
 
-[![Lead table](/examples/images/2021-03-leads/leads-table.png)](https://public.getgrist.com/3NsoHE2mWtEp/Lead-list/m/fork)
+[![Lead table](../examples/images/2021-03-leads/leads-table.png)](https://public.getgrist.com/3NsoHE2mWtEp/Lead-list/m/fork)
 
 Our entrepeneur wants to delegate sales leads to a small team of freelancers, and 
 keep potential advisors private.  They want to be able to assign someone to follow-up
@@ -12,7 +12,7 @@ a lead just by writing their initials in an "Assignment" column, and not
 allow anyone else to change that assignment.  Here are the rules they come up with,
 which you can see yourself [by visiting the example](https://public.getgrist.com/3NsoHE2mWtEp/Lead-list/m/fork/p/acl):
 
-[![Lead rules](/examples/images/2021-03-leads/leads-rules.png)](https://public.getgrist.com/3NsoHE2mWtEp/Lead-list/m/fork/p/acl)
+[![Lead rules](../examples/images/2021-03-leads/leads-rules.png)](https://public.getgrist.com/3NsoHE2mWtEp/Lead-list/m/fork/p/acl)
 
 There are three blocks of rules.  First, the rule for the Advisors table:
 
@@ -43,7 +43,7 @@ sure they [see what you expect](../access-rules.md#view-as-another-user).
 You'll want to turn off the "Special Rules" that allowed you to inspect the
 example and to make a complete copy of it:
 
-![Lead specials](/examples/images/2021-03-leads/leads-specials.png)
+![Lead specials](../examples/images/2021-03-leads/leads-specials.png)
 
 Remember to hit "Save" after you change rules, so they take effect.
 
@@ -54,24 +54,24 @@ are assigned to (or by the owner).  We can do that in several ways.  One
 convenient way is to add a table listing team members, including their
 email address:
 
-[![Lead team](/examples/images/2021-03-leads/leads-team.png)](https://public.getgrist.com/vuPduz2UdJDi/Lead-list-with-team/m/fork)
+[![Lead team](../examples/images/2021-03-leads/leads-team.png)](https://public.getgrist.com/vuPduz2UdJDi/Lead-list-with-team/m/fork)
 
 Once we have such a table, we can make the `Assignment` column refer to it.
 See <https://public.getgrist.com/vuPduz2UdJDi/Lead-list-with-team/m/fork> for
 the complete example (you'll need to make a copy to get full access,
 otherwise you'll see a filtered view).
 
-![Lead reference](/examples/images/2021-03-leads/leads-reference.png)
+![Lead reference](../examples/images/2021-03-leads/leads-reference.png)
 
 We can then use the team members in rules, via a
 [user attribute table](../access-rules.md#user-attribute-tables):
 
-![Lead attributes](/examples/images/2021-03-leads/leads-attributes.png)
+![Lead attributes](../examples/images/2021-03-leads/leads-attributes.png)
 
 Then every user the document is shared with (other than owners) will
 see a filtered view of just those leads assigned to them:
 
-![Lead filtered](/examples/images/2021-03-leads/leads-filtered.png)
+![Lead filtered](../examples/images/2021-03-leads/leads-filtered.png)
 
 Read our [introduction to access rules](../access-rules.md) to learn
 more about what you can do with access rules.
diff --git a/help/en/docs/examples/2023-07-proposals-contracts.md b/help/en/docs/examples/2023-07-proposals-contracts.md
index 209ca90e2..e1bfb2a26 100644
--- a/help/en/docs/examples/2023-07-proposals-contracts.md
+++ b/help/en/docs/examples/2023-07-proposals-contracts.md
@@ -3,7 +3,7 @@
 If you are keeping business details and contracts in Grist, it can be convenient
 to generate proposals and contracts right there, alongside those records. You can use the [Markdown Custom Widget](../widget-custom.md#markdown) to create a custom 'form' for Proposals, Contracts, or many other types of documents. This tutorial shows you how to set up a document like this:
 
-*![Proposal](/examples/images/2023-07-proposals-contracts/final-proposal.png)*
+*![Proposal](../examples/images/2023-07-proposals-contracts/final-proposal.png)*
 
 You can find a finished template here: [📝 Proposals & Contracts Template](https://public.getgrist.com/nyPmvvea8c54/-Proposals-Contracts/m/fork){:target="\_blank"}.
 
@@ -14,47 +14,47 @@ If you'd like to add a proposal to an existing document, understanding this tuto
 First of all, make a table to record project details by
 [creating an empty document](../creating-doc.md) and renaming `Table1` to `Projects`:
 
-*![Projects](/examples/images/2023-07-proposals-contracts/make-projects-table.png)*
+*![Projects](../examples/images/2023-07-proposals-contracts/make-projects-table.png)*
 
 We'll create our Proposal template alongside our `Projects` table. 
 
 We can insert column IDs as placeholders in our Proposal template that will then be replaced by the cell value for the selected project. For example, in the screenshot below, the value in the **Project Name** column will replace the variable `{Project_Name}` in the proposal template on the right. Seeing the available columns while creating our proposal will make it easier to populate those variables.
 
-*![Projects](/examples/images/2023-07-proposals-contracts/column-placeholders.png)*
+*![Projects](../examples/images/2023-07-proposals-contracts/column-placeholders.png)*
 
 ## Creating templates
 
 Let's add a new table, `Templates`, to the page to store our template data. Add two columns: **Name** and **Template Formatting**. 
 
-*![Templates](/examples/images/2023-07-proposals-contracts/templates-table.png)*
+*![Templates](../examples/images/2023-07-proposals-contracts/templates-table.png)*
 
 Now, let's add a custom widget beside the table to view our **Template Formatting**. Click the green 'Add New' button then 'Add widget to page'. Under 'Select Widget', select 'Custom' and under 'Select Data', select `Templates`. Under 'Select By', select `Templates` again.
 
-*![Add Custom Widget](/examples/images/2023-07-proposals-contracts/add-custom-widget.png)*
+*![Add Custom Widget](../examples/images/2023-07-proposals-contracts/add-custom-widget.png)*
 
 Configure the custom widget by selecting 'Markdown' from the 'Custom' dropdown. Since we will be editing the template directly in the custom widget, you must allow 'Full document access' under Access Level so the widget can update the `Templates` table. 
 
 Under 'Content', select the column **Template Formatting**. This is the column that will be updated when we make edits within the custom widget.
 
-*![Markdown Widget](/examples/images/2023-07-proposals-contracts/markdown-configuration.png)*
+*![Markdown Widget](../examples/images/2023-07-proposals-contracts/markdown-configuration.png)*
 {: .screenshot-half }
 
 Create a Template in the `Templates` table by entering a value in the **Name** column. Then, start editing the template formatting within the custom widget. 
 
-*![Proposal Template](/examples/images/2023-07-proposals-contracts/create-proposal-template-1.png)*
+*![Proposal Template](../examples/images/2023-07-proposals-contracts/create-proposal-template-1.png)*
 
 The widget uses Markdown formatting to format the text. For help on Markdown, click the `?` at the top of the widget to view the [Markdown Guide](https://www.markdownguide.org/basic-syntax/).
 
-*![markdown-help](/examples/images/2023-07-proposals-contracts/markdown-help.png)*
+*![markdown-help](../examples/images/2023-07-proposals-contracts/markdown-help.png)*
 {: .screenshot-half }
 
 When you click the 'save' icon, formatting from the widget will populate the **Template Formatting** column.
 
-![Proposal Template](/examples/images/2023-07-proposals-contracts/create-proposal-template.png)
+![Proposal Template](../examples/images/2023-07-proposals-contracts/create-proposal-template.png)
 
 We will exclusively use the custom widget to edit the template formatting so this column can be hidden from the table view. To hide the column, right-click on the column header then 'Hide column'.
 
-![Hide Column](/examples/images/2023-07-proposals-contracts/hide-formatting-column.png)
+![Hide Column](../examples/images/2023-07-proposals-contracts/hide-formatting-column.png)
 
 In your template, you'll have details and text that remain the same across all projects such as formatting, section headers and your own company's information. That is the information you'll type directly into the template. You'll also have information that changes, such as **Project Name** or **Customer Name**. We can use variables containing column IDs as placeholders for that dynamic data. 
 
@@ -62,15 +62,15 @@ In your template, you'll have details and text that remain the same across all p
 
 Add the columns **Project Name**, **Customer Name** and **Customer Address** to the `Projects` table.
 
-![Projects Table](/examples/images/2023-07-proposals-contracts/project-customer-columns.png)
+![Projects Table](../examples/images/2023-07-proposals-contracts/project-customer-columns.png)
 
 We can use the column IDs for each of these columns as placeholders in our template with the format `{COLUMN_ID}`. A column's ID can be found under the 'Table' tab of the Creator Panel, directly under the Column Label.
 
-![Variables](/examples/images/2023-07-proposals-contracts/project-name-variable.png)
+![Variables](../examples/images/2023-07-proposals-contracts/project-name-variable.png)
 
 Finish building out your template to fit your needs. Be sure to add a column to your `Projects` table for all variable information.
 
-![Proposal](/examples/images/2023-07-proposals-contracts/proposal-template.png)
+![Proposal](../examples/images/2023-07-proposals-contracts/proposal-template.png)
 
 Finally, we need to add a formula column that will create our unique proposals. This formula column will combine the template formatting we just created with our project-specifc data. Add a new column to the `Projects` table with the following formula:
 ```
@@ -86,7 +86,7 @@ template = Templates.lookupOne(Name="Proposal").Template_Formatting
 template.format_map(Find_Data())
 ```
 
-![Proposal Formula](/examples/images/2023-07-proposals-contracts/proposal-formula.png)
+![Proposal Formula](../examples/images/2023-07-proposals-contracts/proposal-formula.png)
 
 ## Setting up a proposal dashboard
 
@@ -94,43 +94,43 @@ Next, we'll want to populate our proposal template with actual project data! Sta
 
 Under 'Select Widget', select 'Table' and under 'Select Data', select `Projects`.
 
-![Add Project Table](/examples/images/2023-07-proposals-contracts/add-projects-table.png)
+![Add Project Table](../examples/images/2023-07-proposals-contracts/add-projects-table.png)
 
 You'll notice that having this information in a table view is a bit busy. A [Card widget](../widget-card.md) will help simplify our view.
 
 Add a new widget to the page by clicking the green 'Add New' button then 'Add widget to page'. Under 'Select Widget', select 'Card' and under 'Select Data', select `Projects`. Under 'Select By', select `Projects` and add to page.
 
-![Add Project Card](/examples/images/2023-07-proposals-contracts/add-projects-card.png)
+![Add Project Card](../examples/images/2023-07-proposals-contracts/add-projects-card.png)
 
 Your dashboard should look similar to the screenshot below.
 
-![project-dashboard-start](/examples/images/2023-07-proposals-contracts/project-dashboard-start.png)
+![project-dashboard-start](../examples/images/2023-07-proposals-contracts/project-dashboard-start.png)
 
 Now that we have all of our Project details in a Card view, we can hide them from our table view. Under the 'Table' tab of the Creator Panel, select all columns except **Project Name** and **Customer Name** then click the green 'Hide Columns' button.
 
-*![Hide Columns](/examples/images/2023-07-proposals-contracts/hide-project-columns.png)*
+*![Hide Columns](../examples/images/2023-07-proposals-contracts/hide-project-columns.png)*
 {: .screenshot-half }
 
 Keeping most project details in the Card widget, rather than the Table widget, simplifies our dashboard. You can easily see all projects in the Table widget, and when you want to see details for a specific project, select the project and the Card widget will update to show you project details.
 
-![project-table-card](/examples/images/2023-07-proposals-contracts/project-table-card.png)
+![project-table-card](../examples/images/2023-07-proposals-contracts/project-table-card.png)
 
 Finally, we'll want to add a view of our project-specific proposal. Add a new custom widget to the page by clicking the green 'Add New' button then 'Add widget to page'. Under 'Select Widget', select 'Custom' and under 'Select Data', select `Projects`. Under 'Select By', select `Projects` and add to page.
 
-*![Add custom Widget](/examples/images/2023-07-proposals-contracts/add-custom-project-widget.png)*
+*![Add custom Widget](../examples/images/2023-07-proposals-contracts/add-custom-project-widget.png)*
 
 Configure the custom widget by selecting 'Markdown' from the 'Custom' dropdown. You must allow 'Full document access'. 
 
 Under 'Content', select the column **Proposal**. This is the formula column that combines our template formatting with our project-specific data.
 
-*![Configure Custom Widget](/examples/images/2023-07-proposals-contracts/proposal-custom-widget-configuration.png)*
+*![Configure Custom Widget](../examples/images/2023-07-proposals-contracts/proposal-custom-widget-configuration.png)*
 {: .screenshot-half }
 
 [Customize your layout](../custom-layouts.md) by rearranging and resizing widgets.
 
 Add project details for a new project and see how your proposal updates to display the newly added data.
 
-*![Populated Proposal](/examples/images/2023-07-proposals-contracts/populated-proposal.png)*
+*![Populated Proposal](../examples/images/2023-07-proposals-contracts/populated-proposal.png)*
 
 ## Entering customer information
 
@@ -142,13 +142,13 @@ Now, let's make two useful changes to the Project set-up:
 
 First, create a new table called `Customers` for customer-specific information like **Name** and **Address**.
 
-*![Customers Table](/examples/images/2023-07-proposals-contracts/customers-table.png)*
+*![Customers Table](../examples/images/2023-07-proposals-contracts/customers-table.png)*
 
 Some of this data is included in our Projects data set. To avoid duplicating data, we need to update our **Customer Name** and **Customer Address** columns to pull from our `Customers` table. 
 
 On our *Proposals Dashboard* page, select the **Customer Name** field then update the column type to *Reference*. Confirm that 'Data from Table' is set to `Customers` and 'Show Column' is **Name**. 
 
-*![customer-name-reference](/examples/images/2023-07-proposals-contracts/customer-name-reference.png)*
+*![customer-name-reference](../examples/images/2023-07-proposals-contracts/customer-name-reference.png)*
 
 Next, we need to update the **Customer Address** field to pull the address for the customer listed in the **Customer Name** column. 
 
@@ -160,7 +160,7 @@ This formula uses our reference column, **Customer**, along with [dot notation](
 
 When you take a look at a proposal for an existing project, you'll notice that the **Customer Name** no longer populates. This is because of the way reference columns store data. Although under 'Show Column', we chose to see the value from the **Name** column of the referenced table, reference columns actually store a record's ID. That is what we are seeing now in the proposal. 
 
-*![proposal-reference](/examples/images/2023-07-proposals-contracts/proposal-reference.png)*
+*![proposal-reference](../examples/images/2023-07-proposals-contracts/proposal-reference.png)*
 
 We can modify our formula in the **Proposal** column to look for data in other tables.
 
@@ -199,11 +199,11 @@ In the last portion of the formula, we can specify variables that pull from othe
 
 Once your proposal is ready to go, you can print it or save it as a PDF. Click the three-dot icon at the upper-right of the widget then select 'Print widget'.
 
-*![print-proposal](/examples/images/2023-07-proposals-contracts/print-proposal.png)*
+*![print-proposal](../examples/images/2023-07-proposals-contracts/print-proposal.png)*
 
 From here, you can either select a printer or choose 'Save as PDF' from the 'Destination' dropdown.
 
-*![print-or-pdf](/examples/images/2023-07-proposals-contracts/print-or-pdf.png)*
+*![print-or-pdf](../examples/images/2023-07-proposals-contracts/print-or-pdf.png)*
 
 ## Setting up multiple forms
 
@@ -211,17 +211,17 @@ You can add more form templates by following the same steps that we have just co
 
 Add a new template to the `Templates` table then build out the template using variables containing column IDs for any data that is project-specific. If you have some sections that are the same as another form, copy it over to save yourself the trouble of retyping!
 
-*![contract-template](/examples/images/2023-07-proposals-contracts/contract-template.png)*
+*![contract-template](../examples/images/2023-07-proposals-contracts/contract-template.png)*
 
 Create a dashboard where you can select a project and enter details for this form then preview the form in a custom widget. 
 
-*![contract-dashboard](/examples/images/2023-07-proposals-contracts/contract-dashboard.png)*
+*![contract-dashboard](../examples/images/2023-07-proposals-contracts/contract-dashboard.png)*
 
 Don't forget, you'll need to add a formula column that combines the new form template with details for the selected project!
 
-*![contract-formula](/examples/images/2023-07-proposals-contracts/contract-formula.png)*
+*![contract-formula](../examples/images/2023-07-proposals-contracts/contract-formula.png)*
 
 This formula column is what you'll select under the 'Content' dropdown while configuring the [Markdown Custom Widget](../widget-custom.md#markdown).
 
-*![contract-widget-configuration](/examples/images/2023-07-proposals-contracts/contract-widget-configuration.png)*
+*![contract-widget-configuration](../examples/images/2023-07-proposals-contracts/contract-widget-configuration.png)*
 
diff --git a/help/en/docs/investment-research.md b/help/en/docs/investment-research.md
index 2f7f726a4..cf82f5810 100644
--- a/help/en/docs/investment-research.md
+++ b/help/en/docs/investment-research.md
@@ -11,8 +11,8 @@ investments in them up to 2013. Let’s take a look at the
 sample document and then we’ll talk about how to build it so that you can apply these tools to
 your own data.
 
-[^doc_desc]: Download [crunchbase_companies_ny.csv](/unlocalized-assets/investment-research/crunchbase-companies-ny.csv)
-and [crunchbase_investments_ny.csv](/unlocalized-assets/investment-research/crunchbase-investments-ny.csv). The sample data includes only the “companies” and “investments” data, and includes only
+[^doc_desc]: Download [crunchbase_companies_ny.csv](./unlocalized-assets/investment-research/crunchbase-companies-ny.csv)
+and [crunchbase_investments_ny.csv](./unlocalized-assets/investment-research/crunchbase-investments-ny.csv). The sample data includes only the “companies” and “investments” data, and includes only
 New York companies to keep it smaller and faster. The dataset comes
 from [Kaggle](https://www.kaggle.com/mauriciocap/crunchbase2013).
 
@@ -68,9 +68,9 @@ the first step.
 
 Let’s import the raw data. We’ll import two CSV files, where each will become its own table. To
 follow along, save the files from
-[crunchbase_companies_ny.csv](/unlocalized-assets/investment-research/crunchbase-companies-ny.csv)
+[crunchbase_companies_ny.csv](./unlocalized-assets/investment-research/crunchbase-companies-ny.csv)
 and
-[crunchbase_investments_ny.csv](/unlocalized-assets/investment-research/crunchbase-investments-ny.csv)
+[crunchbase_investments_ny.csv](./unlocalized-assets/investment-research/crunchbase-investments-ny.csv)
 to
 your computer first. Then, create a Grist document by importing the first file from the home page.
 
diff --git a/help/en/docs/lightweight-crm.md b/help/en/docs/lightweight-crm.md
index 5c6b75a4f..cd9c82f6b 100644
--- a/help/en/docs/lightweight-crm.md
+++ b/help/en/docs/lightweight-crm.md
@@ -139,7 +139,7 @@ The rest of this tutorial will show you how to create such a document on your ow
 exercise that will teach you some of the key features of Grist.
 
 To start, we'll import a file with sample contacts from the Grist home page. First, save this file
-to your desktop: [lightweight-crm-contacts.csv](/unlocalized-assets/lightweight-crm-contacts.csv). Then click the "Add
+to your desktop: [lightweight-crm-contacts.csv](./unlocalized-assets/lightweight-crm-contacts.csv). Then click the "Add
 New" button on the top left of your Grist home page, click "Import document", and select the file
 on your desktop.
 
diff --git a/help/en/docs/newsletters/2020-08.md b/help/en/docs/newsletters/2020-08.md
index dd83bae7b..34bcdbc11 100644
--- a/help/en/docs/newsletters/2020-08.md
+++ b/help/en/docs/newsletters/2020-08.md
@@ -136,7 +136,7 @@ Here is an example of what you can do with Grist:
   This is also an example of the kind of new visualization that can be built with
   [Custom Widgets](../widget-custom.md).
 
-![invoice example](/examples/images/2020-08-invoices/final-invoice.png)
+![invoice example](../examples/images/2020-08-invoices/final-invoice.png)
 
 
 ## Learning Grist
diff --git a/help/en/docs/newsletters/2020-09.md b/help/en/docs/newsletters/2020-09.md
index e979ae271..15ae4af19 100644
--- a/help/en/docs/newsletters/2020-09.md
+++ b/help/en/docs/newsletters/2020-09.md
@@ -139,7 +139,7 @@ Here is an example of what you can do with Grist:
   hours, rates, and roles, and to reduce mistakes with up-to-date payroll summaries and
   detailed histories of rates and hours.
 
-![payroll example](/examples/images/2020-09-payroll/pay-periods.png)
+![payroll example](../examples/images/2020-09-payroll/pay-periods.png)
 
 
 ## Learning Grist
diff --git a/help/en/docs/newsletters/2020-10.md b/help/en/docs/newsletters/2020-10.md
index 7fdcf42b1..ad26e99c8 100644
--- a/help/en/docs/newsletters/2020-10.md
+++ b/help/en/docs/newsletters/2020-10.md
@@ -132,7 +132,7 @@ trust in quality of code and in long-term availability of Grist. Read more at
 label sizes and makes it easy to create printable labels and have them available at
 the click of a button. It's yet another example of the extensibility of Grist.
 
-![Address Labels Page](/examples/images/2020-10-print-labels/address-labels-page.png)
+![Address Labels Page](../examples/images/2020-10-print-labels/address-labels-page.png)
 
 
 ## Learning Grist
diff --git a/help/en/docs/newsletters/2020-11.md b/help/en/docs/newsletters/2020-11.md
index 711e4e445..32a1dafa8 100644
--- a/help/en/docs/newsletters/2020-11.md
+++ b/help/en/docs/newsletters/2020-11.md
@@ -152,7 +152,7 @@ using Grist for fun! Check out this template that helps you plan a treasure hunt
 track. Conspire with relatives or friends online to create a trail of clues, then watch and
 laugh as the rest of your household flails their way through it.
 
-[![Treasure Hunt document](/examples/images/2020-11-treasure-hunt/hunt.png)](../examples/2020-11-treasure-hunt.md)
+[![Treasure Hunt document](../examples/images/2020-11-treasure-hunt/hunt.png)](../examples/2020-11-treasure-hunt.md)
 
 
 ## Learning Grist
diff --git a/help/en/docs/newsletters/2021-03.md b/help/en/docs/newsletters/2021-03.md
index 72101ac6e..e6b92dfa5 100644
--- a/help/en/docs/newsletters/2021-03.md
+++ b/help/en/docs/newsletters/2021-03.md
@@ -125,7 +125,7 @@ In our [Lead List](../examples/2021-03-leads.md) example, we suppose an entrepen
 is using Grist as an ad-hoc lead tracker for sales and potential advisors, and
 show how they can use access rules to shape collaboration.
 
-![Lead table](/examples/images/2021-03-leads/leads-table.png)
+![Lead table](../examples/images/2021-03-leads/leads-table.png)
 
 ## Quick Tips
 
diff --git a/help/en/docs/newsletters/2023-10.md b/help/en/docs/newsletters/2023-10.md
index f79b1029c..882d0e569 100644
--- a/help/en/docs/newsletters/2023-10.md
+++ b/help/en/docs/newsletters/2023-10.md
@@ -162,7 +162,7 @@ To learn more and try it out yourself, check out our [beta docs](https://github.
 
 ![JupyterLite notebook widget](../images/newsletters/2023-10/jupyter.gif)
 
-This experimental widget lets you run custom Python code in [JupyterLite](https://jupyterlite.readthedocs.io/){:target="\_blank"}, a version of [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/index.html){:target="\_blank"} running entirely in the browser. It can use the [custom widget plugin API](code/modules/grist_plugin_api/){:target="\_blank"} and access or modify any data in the document (subject to Access Rules), unlocking nearly unlimited possibilities for advanced users.
+This experimental widget lets you run custom Python code in [JupyterLite](https://jupyterlite.readthedocs.io/){:target="\_blank"}, a version of [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/index.html){:target="\_blank"} running entirely in the browser. It can use the [custom widget plugin API](../code/modules/grist_plugin_api.md){:target="\_blank"} and access or modify any data in the document (subject to Access Rules), unlocking nearly unlimited possibilities for advanced users.
 
 For more information on how to get it up and running, check out our [beta docs](https://github.com/gristlabs/jupyterlite-widget/blob/main/USAGE.md){:target="\_blank"}.
 
diff --git a/help/en/docs/self-managed.md b/help/en/docs/self-managed.md
index 55ac41496..d2cf352f8 100644
--- a/help/en/docs/self-managed.md
+++ b/help/en/docs/self-managed.md
@@ -404,7 +404,7 @@ Here are the meanings of the keys in this file:
     suppressed via the unsubscribe link in emails.
 
 For reference, there are example SendGrid templates in
-[example-sendgrid-templates.zip](/install/example-sendgrid-templates.zip)
+[example-sendgrid-templates.zip](./install/example-sendgrid-templates.zip)
 based on an export of the SendGrid templates for our SaaS.
 
 ### How do I add more python packages? {: .tag-core .tag-ee }
diff --git a/help/en/docs/widget-custom.md b/help/en/docs/widget-custom.md
index 5b6824b08..512f76378 100644
--- a/help/en/docs/widget-custom.md
+++ b/help/en/docs/widget-custom.md
@@ -388,7 +388,7 @@ to show your own custom configuration screen.
 
 Custom widgets can also be used as a source of linking (see [Linking widgets](linking-widgets.md)).
 All you need to do is inform Grist that your widget supports linking by passing an additional
-option to the `ready` call (see [Widget API](/code/modules/grist_plugin_api/#ready)):
+option to the `ready` call (see [Widget API](./code/modules/grist_plugin_api.md#ready)):
 
 ```javascript
 grist.ready({
@@ -580,7 +580,7 @@ For a video walkthrough, be sure to watch our [Custom Widgets Webinar](https://w
 
 ### JupyterLite Notebook
 
-This widget lets you run custom Python code in [JupyterLite](https://jupyterlite.readthedocs.io/), a version of [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/index.html) running entirely in the browser. You can use the full [custom widget plugin API](/code/modules/grist_plugin_api/) and access or modify any data in the document (subject to Access Rules), unlocking nearly unlimited possibilities for advanced users.
+This widget lets you run custom Python code in [JupyterLite](https://jupyterlite.readthedocs.io/), a version of [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/index.html) running entirely in the browser. You can use the full [custom widget plugin API](./code/modules/grist_plugin_api.md) and access or modify any data in the document (subject to Access Rules), unlocking nearly unlimited possibilities for advanced users.
 
 You’ll be presented with a notebook where you can enter and run Python code, e.g:
 
@@ -590,7 +590,7 @@ After typing code in a cell, click the play button or press Shift+Enter to run t
 
 Unlike formulas, code isn’t saved automatically. You must press the usual ‘Save’ button above the widget (outside the notebook) to persist the code within your Grist document. On the other hand, changes to settings within the notebook (e.g. keyboard shortcuts) are saved in your browser’s local storage, so they’re not shared with other users of the document.
 
-A special object called `grist` is automatically available to use in Python code, which mirrors many common methods of the usual [JS plugin API](/code/modules/grist_plugin_api/). Note that many of these methods are asynchronous, so you should use `await` before calling them.
+A special object called `grist` is automatically available to use in Python code, which mirrors many common methods of the usual [JS plugin API](./code/modules/grist_plugin_api.md). Note that many of these methods are asynchronous, so you should use `await` before calling them.
 
 - `async fetch_selected_table()`: returns the data of the table backing the notebook widget.
 - `async fetch_selected_record(row_id=None)`: returns a record of the table backing the notebook widget. If `row_id` is specified, returns the record at that row. Otherwise, returns the record at the current cursor position in a widget linked to the notebook widget.
@@ -603,7 +603,7 @@ A special object called `grist` is automatically available to use in Python code
     - The values for reference columns are row IDs of the referenced table, whereas `fetch_selected_table` returns the values displayed based on the 'SHOW COLUMN' configuration.
 - `on_record(callback)`: registers a callback function to run when the cursor moves in a widget linked to the notebook widget, i.e. the widget chosen from the "SELECT BY" dropdown in the Data section of the widget configuration. The callback function will be passed the record at the current cursor position. You can also use this as a decorator, i.e. `@grist.on_record`.
 - `on_records(callback)`: similar to `on_record`, but runs when the source data of the widget changes. The callback function will be passed the same data as returned by `fetch_selected_table`.
-- `get_table(table_id)`: returns a `TableOperations` class similar to the interface in the usual [JS plugin API](/code/interfaces/TableOperations.TableOperations/) for performing CRUD-style operations on a table. See the plugin API documentation for details on the parameters. The class has the following methods:
+- `get_table(table_id)`: returns a `TableOperations` class similar to the interface in the usual [JS plugin API](./code/interfaces/TableOperations.TableOperations.md) for performing CRUD-style operations on a table. See the plugin API documentation for details on the parameters. The class has the following methods:
     - `async create(records, parse_strings=True)`
     - `async update(records, parse_strings=True)`
     - `async upsert(records, parse_strings=True, add=True, update=True, on_many="first", allow_empty_require=False)`

From 50c038adedf3d28b96b0ecee8d60eac03e026cec Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 09:03:59 +0100
Subject: [PATCH 04/30] Clean up docs.py

---
 docs.py | 81 ---------------------------------------------------------
 1 file changed, 81 deletions(-)

diff --git a/docs.py b/docs.py
index 443c777f3..0b187fb83 100644
--- a/docs.py
+++ b/docs.py
@@ -42,13 +42,6 @@
 build_site_path = Path("site_build").absolute()
 
 
-@lru_cache
-def is_mkdocs_insiders() -> bool:
-    return False
-    # version = metadata.version("mkdocs-material")
-    # return "insiders" in version
-
-
 def get_base_config_path() -> Dict[str, Any]:
     return mkdocs.utils.yaml_load(base_config_path.read_text(encoding="utf-8"))
 
@@ -71,14 +64,6 @@ def complete_existing_lang(incomplete: str):
             yield lang_path.name
 
 
-@app.callback()
-def callback() -> None:
-    if is_mkdocs_insiders():
-        os.environ["INSIDERS_FILE"] = "../en/mkdocs.insiders.yml"
-    # For MacOS with insiders and Cairo
-    os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
-
-
 @app.command()
 def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     """
@@ -113,8 +98,6 @@ def build_lang(
     """
     insiders_env_file = os.environ.get("INSIDERS_FILE")
     print(f"Insiders file {insiders_env_file}")
-    if is_mkdocs_insiders():
-        print("Using insiders")
     lang_path: Path = docs_path / lang
     if not lang_path.is_dir():
         typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
@@ -139,70 +122,6 @@ def build_lang(
     os.chdir(current_dir)
     typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
 
-
-index_sponsors_template = """
-{% if sponsors %}
-{% for sponsor in sponsors.gold -%}
-<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
-{% endfor -%}
-{%- for sponsor in sponsors.silver -%}
-<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}"></a>
-{% endfor %}
-{% endif %}
-"""
-
-
-def generate_readme_content() -> str:
-    en_index = en_docs_path / docs_folder_name / "index.md"
-    content = en_index.read_text("utf-8")
-    match_pre = re.search(r"</style>\n\n", content)
-    match_start = re.search(r"<!-- sponsors -->", content)
-    match_end = re.search(r"<!-- /sponsors -->", content)
-    sponsors_data_path = en_docs_path / "data" / "sponsors.yml"
-    sponsors = mkdocs.utils.yaml_load(sponsors_data_path.read_text(encoding="utf-8"))
-    if not (match_start and match_end):
-        raise RuntimeError("Couldn't auto-generate sponsors section")
-    if not match_pre:
-        raise RuntimeError("Couldn't find pre section (<style>) in index.md")
-    frontmatter_end = match_pre.end()
-    pre_end = match_start.end()
-    post_start = match_end.start()
-    template = Template(index_sponsors_template)
-    message = template.render(sponsors=sponsors)
-    pre_content = content[frontmatter_end:pre_end]
-    post_content = content[post_start:]
-    new_content = pre_content + message + post_content
-    return new_content
-
-
-@app.command()
-def generate_readme() -> None:
-    """
-    Generate README.md content from main index.md
-    """
-    typer.echo("Generating README")
-    readme_path = Path("README.md")
-    new_content = generate_readme_content()
-    readme_path.write_text(new_content, encoding="utf-8")
-
-
-@app.command()
-def verify_readme() -> None:
-    """
-    Verify README.md content from main index.md
-    """
-    typer.echo("Verifying README")
-    readme_path = Path("README.md")
-    generated_content = generate_readme_content()
-    readme_content = readme_path.read_text("utf-8")
-    if generated_content != readme_content:
-        typer.secho(
-            "README.md outdated from the latest index.md", color=typer.colors.RED
-        )
-        raise typer.Abort()
-    typer.echo("Valid README ✅")
-
-
 @app.command()
 def build_all() -> None:
     """

From e984bddbc6a184a528d4dd0b939f753c1224514f Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 09:10:44 +0100
Subject: [PATCH 05/30] Use docs.py in build-doc.sh and credit FastAPI for
 docs.py

---
 README.md    | 2 ++
 build-doc.sh | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0ca69a970..592f2fd93 100644
--- a/README.md
+++ b/README.md
@@ -101,3 +101,5 @@ You need to first run `yarn install` in your Grist checkout directory.
 
 This work is licensed under a
 [Creative Commons Attribution-ShareAlike 4.0 International License](LICENSE.txt).
+
+The script [docs.py](./docs.py) is MIT licensed, credits to Sebastián Ramírez and the FastAPI project contributors.
diff --git a/build-doc.sh b/build-doc.sh
index 3565466eb..3d83d13d2 100755
--- a/build-doc.sh
+++ b/build-doc.sh
@@ -8,4 +8,4 @@ if [ -e env ]; then
   source ./env/bin/activate
 fi
 
-mkdocs build
+python3 ./docs.py build-all

From 763e3ec7239f9ccc4e8a3a1d05c6444470ef61b5 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 09:52:25 +0100
Subject: [PATCH 06/30] Make `./docs.py new-lang` work

---
 docs.py | 38 ++++++++++++++++++++++++--------------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/docs.py b/docs.py
index 0b187fb83..9e3356b8d 100644
--- a/docs.py
+++ b/docs.py
@@ -15,6 +15,7 @@
 from multiprocessing import Pool
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
+from textwrap import dedent
 
 import mkdocs.commands.build
 import mkdocs.commands.serve
@@ -30,10 +31,6 @@
 
 mkdocs_name = "mkdocs.yml"
 
-missing_translation_snippet = """
-{!../../../docs/missing-translation.md!}
-"""
-
 docs_folder_name = "help"
 docs_path = Path("help")
 en_docs_path = Path("help/en")
@@ -42,6 +39,25 @@
 build_site_path = Path("site_build").absolute()
 
 
+def language_docs_dir(langue_base: Path):
+    return langue_base / "docs"
+
+
+def get_missing_translation_snippet() -> str:
+    missing_translation_file_path = (Path(__file__).parent / "help/missing-translation.md")
+    return missing_translation_file_path.read_text(encoding="utf-8")
+
+
+def get_mkdocs_yaml_for_lang(lang: str) -> str:
+    return dedent(f"""
+    INHERIT: ../../mkdocs.yml
+    docs_dir: './docs'
+    theme:
+      custom_dir: ../../overrides
+      language: {lang}
+    """).lstrip()
+
+
 def get_base_config_path() -> Dict[str, Any]:
     return mkdocs.utils.yaml_load(base_config_path.read_text(encoding="utf-8"))
 
@@ -75,13 +91,13 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
         raise typer.Abort()
     new_path.mkdir()
     new_config_path: Path = Path(new_path) / mkdocs_name
-    new_config_path.write_text("INHERIT: ../en/mkdocs.yml\n", encoding="utf-8")
-    new_config_docs_path: Path = new_path / folder_name
+    new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
+    new_config_docs_path: Path = language_docs_dir(new_path)
     new_config_docs_path.mkdir()
-    en_index_path: Path = en_docs_path / folder_name / "index.md"
+    en_index_path: Path = language_docs_dir(en_docs_path) / "index.md"
     new_index_path: Path = new_config_docs_path / "index.md"
     en_index_content = en_index_path.read_text(encoding="utf-8")
-    new_index_content = f"{missing_translation_snippet}\n\n{en_index_content}"
+    new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"
     new_index_path.write_text(new_index_content, encoding="utf-8")
     typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN)
     update_languages()
@@ -249,12 +265,6 @@ def verify_config() -> None:
     typer.echo("Valid mkdocs.yml ✅")
 
 
-@app.command()
-def verify_docs():
-    verify_readme()
-    verify_config()
-
-
 @app.command()
 def langs_json():
     langs = []

From 611cb9271efa8fb63fba080e34003cfe51b2d437 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 15:21:22 +0100
Subject: [PATCH 07/30] Make docs.py executable

---
 docs.py | 2 ++
 1 file changed, 2 insertions(+)
 mode change 100644 => 100755 docs.py

diff --git a/docs.py b/docs.py
old mode 100644
new mode 100755
index 9e3356b8d..8a4cee69f
--- a/docs.py
+++ b/docs.py
@@ -1,3 +1,5 @@
+#!./env/bin/python
+
 # Python script adapted from the fastapi project to manage translations
 # License: MIT
 # Source: https://github.com/tiangolo/fastapi/blob/master/scripts/docs.py

From ad3210fcaf3b431c4beff108fd582707cd51d413 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 15:21:40 +0100
Subject: [PATCH 08/30] Change port 8008 to 8000

---
 docs.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs.py b/docs.py
index 8a4cee69f..4b764d07e 100755
--- a/docs.py
+++ b/docs.py
@@ -180,9 +180,9 @@ def serve() -> None:
     typer.echo("This is here only to preview a site with translations already built.")
     typer.echo("Make sure you run the build-all command first.")
     os.chdir("site")
-    server_address = ("", 8008)
+    server_address = ("", 8000)
     server = HTTPServer(server_address, SimpleHTTPRequestHandler)
-    typer.echo("Serving at: http://127.0.0.1:8008")
+    typer.echo("Serving at: http://127.0.0.1:8000")
     server.serve_forever()
 
 
@@ -207,7 +207,7 @@ def live(
         lang = "en"
     lang_path: Path = docs_path / lang
     os.chdir(lang_path)
-    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8008")
+    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8000")
 
 
 def get_updated_config_content() -> Dict[str, Any]:

From f9ea42946204632e01dc2595052062fb6df40672 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 15:22:40 +0100
Subject: [PATCH 09/30] Adapt README to suggest using docs.py

---
 README.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 592f2fd93..bcb567221 100644
--- a/README.md
+++ b/README.md
@@ -18,15 +18,14 @@ Conversation tab.
 ``` sh
 python3 -m venv env
 ./env/bin/pip install -r requirements.txt
-./env/bin/mkdocs serve
+./docs.py live en # or whatever code for language you want to see
 ```
 
 Then visit <http://localhost:8000/> to preview documentation. All the articles,
-as well as static files, are under `/help/en/docs` subdirectory. While `mkdocs serve`
-is running, you may make changes there, and the open page will refresh to show
-the changes.
+as well as static files, are under `/help/en/docs` subdirectory. While `./docs.py live`
+is running, you may make changes there, and the open page will refresh to show the changes.
 
-While `mkdocs serve` is running, you can run `./check_links.sh` to check
+While `./docs.py live` is running, you can run `./check_links.sh` to check
 for broken links in the site.  It will print out a lot of chatter, then
 if there are broken links, conclude with a section like this:
 

From e328566e4b298e0ce99304942566e82cc990e87f Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 16:08:02 +0100
Subject: [PATCH 10/30] Small changes to docs.py

---
 docs.py | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/docs.py b/docs.py
index 4b764d07e..eef5e6577 100755
--- a/docs.py
+++ b/docs.py
@@ -3,7 +3,7 @@
 # Python script adapted from the fastapi project to manage translations
 # License: MIT
 # Source: https://github.com/tiangolo/fastapi/blob/master/scripts/docs.py
-# Original Author: Sebastián Ramírez
+# Original Author: Sebastián Ramírez and contributors
 
 import json
 import logging
@@ -41,8 +41,8 @@
 build_site_path = Path("site_build").absolute()
 
 
-def language_docs_dir(langue_base: Path):
-    return langue_base / "docs"
+def language_docs_dir(lang: str) -> Path:
+    return docs_path / lang / "docs"
 
 
 def get_missing_translation_snippet() -> str:
@@ -82,6 +82,18 @@ def complete_existing_lang(incomplete: str):
             yield lang_path.name
 
 
+# FIXME: remove this?
+# def fallback_to_en(lang: str, file: str) -> str:
+#     en_file = language_docs_dir('en') / file
+#     local_file = language_docs_dir(lang) / file
+#     local_file.parent.mkdir(parents=True, exist_ok=True)
+#     if not en_file.exists() or local_file.exists():
+#         return
+#     en_file_content = en_file.read_text(encoding="utf-8")
+#     local_file_content = f"{get_missing_translation_snippet()}\n\n{en_file_content}"
+#     local_file.write_text(local_file_content, encoding="utf-8")
+
+
 @app.command()
 def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     """
@@ -94,9 +106,9 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     new_path.mkdir()
     new_config_path: Path = Path(new_path) / mkdocs_name
     new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
-    new_config_docs_path: Path = language_docs_dir(new_path)
+    new_config_docs_path: Path = language_docs_dir(lang)
     new_config_docs_path.mkdir()
-    en_index_path: Path = language_docs_dir(en_docs_path) / "index.md"
+    en_index_path: Path = language_docs_dir('en') / "index.md"
     new_index_path: Path = new_config_docs_path / "index.md"
     en_index_content = en_index_path.read_text(encoding="utf-8")
     new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"

From 09ee7c3352c81eb1e5b106983ed7eaaaa2f72636 Mon Sep 17 00:00:00 2001
From: Florent FAYOLLE <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 16:09:48 +0100
Subject: [PATCH 11/30] Add mkdocs hooks (taken from FastAPI)

---
 mkdocs-utils/hooks.py | 140 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 mkdocs-utils/hooks.py

diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
new file mode 100644
index 000000000..8335a13f6
--- /dev/null
+++ b/mkdocs-utils/hooks.py
@@ -0,0 +1,140 @@
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, List, Union
+
+import material
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.nav import Link, Navigation, Section
+from mkdocs.structure.pages import Page
+
+non_traslated_sections = [
+    "reference/",
+    "release-notes.md",
+]
+
+
+@lru_cache
+def get_missing_translation_content(docs_dir: str) -> str:
+    docs_dir_path = Path(docs_dir)
+    missing_translation_path = docs_dir_path.parent.parent / "missing-translation.md"
+    return missing_translation_path.read_text(encoding="utf-8")
+
+
+@lru_cache
+def get_mkdocs_material_langs() -> List[str]:
+    material_path = Path(material.__file__).parent
+    material_langs_path = material_path / "templates" / "partials" / "languages"
+    langs = [file.stem for file in material_langs_path.glob("*.html")]
+    return langs
+
+
+class EnFile(File):
+    pass
+
+
+def on_config(config: MkDocsConfig, **kwargs: Any) -> MkDocsConfig:
+    available_langs = get_mkdocs_material_langs()
+    dir_path = Path(config.docs_dir)
+    lang = dir_path.parent.name
+    if lang in available_langs:
+        config.theme["language"] = lang
+    if not (config.site_url or "").endswith(f"{lang}/") and not lang == "en":
+        config.site_url = f"{config.site_url}{lang}/"
+    return config
+
+
+def resolve_file(*, item: str, files: Files, config: MkDocsConfig) -> None:
+    item_path = Path(config.docs_dir) / item
+    if not item_path.is_file():
+        en_src_dir = (Path(config.docs_dir) / "../../en/docs").resolve()
+        potential_path = en_src_dir / item
+        if potential_path.is_file():
+            files.append(
+                EnFile(
+                    path=item,
+                    src_dir=str(en_src_dir),
+                    dest_dir=config.site_dir,
+                    use_directory_urls=config.use_directory_urls,
+                )
+            )
+
+
+def resolve_files(*, items: List[Any], files: Files, config: MkDocsConfig) -> None:
+    for item in items:
+        if isinstance(item, str):
+            resolve_file(item=item, files=files, config=config)
+        elif isinstance(item, dict):
+            assert len(item) == 1
+            values = list(item.values())
+            if not values:
+                continue
+            if isinstance(values[0], str):
+                resolve_file(item=values[0], files=files, config=config)
+            elif isinstance(values[0], list):
+                resolve_files(items=values[0], files=files, config=config)
+            else:
+                raise ValueError(f"Unexpected value: {values}")
+
+
+def on_files(files: Files, *, config: MkDocsConfig) -> Files:
+    resolve_files(items=config.nav or [], files=files, config=config)
+    if "logo" in config.theme:
+        resolve_file(item=config.theme["logo"], files=files, config=config)
+    if "favicon" in config.theme:
+        resolve_file(item=config.theme["favicon"], files=files, config=config)
+    resolve_files(items=config.extra_css, files=files, config=config)
+    resolve_files(items=config.extra_javascript, files=files, config=config)
+    return files
+
+
+def generate_renamed_section_items(
+    items: List[Union[Page, Section, Link]], *, config: MkDocsConfig
+) -> List[Union[Page, Section, Link]]:
+    new_items: List[Union[Page, Section, Link]] = []
+    for item in items:
+        if isinstance(item, Section):
+            new_title = item.title
+            new_children = generate_renamed_section_items(item.children, config=config)
+            first_child = new_children[0]
+            if isinstance(first_child, Page):
+                if first_child.file.src_path.endswith("index.md"):
+                    # Read the source so that the title is parsed and available
+                    first_child.read_source(config=config)
+                    new_title = first_child.title or new_title
+            # Creating a new section makes it render it collapsed by default
+            # no idea why, so, let's just modify the existing one
+            # new_section = Section(title=new_title, children=new_children)
+            item.title = new_title
+            item.children = new_children
+            new_items.append(item)
+        else:
+            new_items.append(item)
+    return new_items
+
+
+def on_nav(
+    nav: Navigation, *, config: MkDocsConfig, files: Files, **kwargs: Any
+) -> Navigation:
+    new_items = generate_renamed_section_items(nav.items, config=config)
+    return Navigation(items=new_items, pages=nav.pages)
+
+
+def on_pre_page(page: Page, *, config: MkDocsConfig, files: Files) -> Page:
+    return page
+
+
+def on_page_markdown(
+    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+) -> str:
+    if isinstance(page.file, EnFile):
+        for excluded_section in non_traslated_sections:
+            if page.file.src_path.startswith(excluded_section):
+                return markdown
+        missing_translation_content = get_missing_translation_content(config.docs_dir)
+        header = ""
+        body = markdown
+        if markdown.startswith("#"):
+            header, _, body = markdown.partition("\n\n")
+        return f"{header}\n\n{missing_translation_content}\n\n{body}"
+    return markdown

From 917638520b0eb62a81eb83a50ad66f2d6cae50e6 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 21:53:07 +0100
Subject: [PATCH 12/30] Also copy images

---
 mkdocs-utils/hooks.py | 59 ++++++++++++++++++++++++-------------------
 mkdocs.yml            |  2 ++
 requirements.txt      |  4 +--
 3 files changed, 37 insertions(+), 28 deletions(-)

diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 8335a13f6..17f4ac027 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -1,18 +1,21 @@
+# Mkdocs hooks adapted from the fastapi project
+# License: MIT
+# Source: https://github.com/tiangolo/fastapi/blob/master/scripts/mkdocs_hooks.py
+# Original Author: Sebastián Ramírez and contributors
+
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, List, Union
 
-import material
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.structure.files import File, Files
 from mkdocs.structure.nav import Link, Navigation, Section
 from mkdocs.structure.pages import Page
+from mkdocs.utils.yaml import yaml_load
 
-non_traslated_sections = [
-    "reference/",
-    "release-notes.md",
-]
+import glob
 
+non_translated_sections = [] # Add the sections that are not translated here
 
 @lru_cache
 def get_missing_translation_content(docs_dir: str) -> str:
@@ -21,29 +24,18 @@ def get_missing_translation_content(docs_dir: str) -> str:
     return missing_translation_path.read_text(encoding="utf-8")
 
 
-@lru_cache
-def get_mkdocs_material_langs() -> List[str]:
-    material_path = Path(material.__file__).parent
-    material_langs_path = material_path / "templates" / "partials" / "languages"
-    langs = [file.stem for file in material_langs_path.glob("*.html")]
-    return langs
+# @lru_cache
+# def get_mkdocs_material_langs() -> List[str]:
+#     material_path = Path(material.__file__).parent
+#     material_langs_path = material_path / "templates" / "partials" / "languages"
+#     langs = [file.stem for file in material_langs_path.glob("*.html")]
+#     return langs
 
 
 class EnFile(File):
     pass
 
 
-def on_config(config: MkDocsConfig, **kwargs: Any) -> MkDocsConfig:
-    available_langs = get_mkdocs_material_langs()
-    dir_path = Path(config.docs_dir)
-    lang = dir_path.parent.name
-    if lang in available_langs:
-        config.theme["language"] = lang
-    if not (config.site_url or "").endswith(f"{lang}/") and not lang == "en":
-        config.site_url = f"{config.site_url}{lang}/"
-    return config
-
-
 def resolve_file(*, item: str, files: Files, config: MkDocsConfig) -> None:
     item_path = Path(config.docs_dir) / item
     if not item_path.is_file():
@@ -76,11 +68,26 @@ def resolve_files(*, items: List[Any], files: Files, config: MkDocsConfig) -> No
             else:
                 raise ValueError(f"Unexpected value: {values}")
 
+def get_images_relative_paths(docs_dir: str) -> List[str]:
+    en_docs_path = (Path(docs_dir) / "../../en/docs").resolve()
+    images = glob.glob(f"{en_docs_path}/images/**/*", recursive=True)
+    return list(map(lambda i: str(Path(i).relative_to(en_docs_path)), images))
 
 def on_files(files: Files, *, config: MkDocsConfig) -> Files:
-    resolve_files(items=config.nav or [], files=files, config=config)
-    if "logo" in config.theme:
-        resolve_file(item=config.theme["logo"], files=files, config=config)
+
+    # We circumvent the fact that the config.nav object is not available anymore
+    # due to the removal made by mkdocs-awesome-pages-plugin.
+    #
+    # So we read the config file again to get the nav object.
+    with open(config.config_file_path, 'rb') as f:
+        untouched_config = yaml_load(f)
+        resolve_files(items=untouched_config['nav'] or [], files=files, config=config)
+
+    images = get_images_relative_paths(config.docs_dir)
+
+    resolve_files(items=images, files=files, config=config)
+    if "logo" in config.extra:
+        resolve_file(item=config.extra["logo"], files=files, config=config)
     if "favicon" in config.theme:
         resolve_file(item=config.theme["favicon"], files=files, config=config)
     resolve_files(items=config.extra_css, files=files, config=config)
@@ -128,7 +135,7 @@ def on_page_markdown(
     markdown: str, *, page: Page, config: MkDocsConfig, files: Files
 ) -> str:
     if isinstance(page.file, EnFile):
-        for excluded_section in non_traslated_sections:
+        for excluded_section in non_translated_sections:
             if page.file.src_path.startswith(excluded_section):
                 return markdown
         missing_translation_content = get_missing_translation_content(config.docs_dir)
diff --git a/mkdocs.yml b/mkdocs.yml
index faf28384d..b4b267d82 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -196,3 +196,5 @@ markdown_extensions:
   smarty: {}
   extra: {}
   meta: {}
+hooks:
+- ../../mkdocs-utils/hooks.py
diff --git a/requirements.txt b/requirements.txt
index 5311b906e..0b03740e1 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -8,12 +8,12 @@ lunr==0.5.8
 Markdown==3.2.2
 MarkupSafe==2.0.1
 mkdocs==1.5.3
-mkdocs-awesome-pages-plugin==2.7.0
+mkdocs-awesome-pages-plugin==2.9.2
 mkdocs-htmlproofer-plugin==0.8.0
 mkdocs-meta-descriptions-plugin==2.0.0
 mkdocs-windmill==1.0.4
 nltk==3.5
-PyYAML==5.3.1
+PyYAML>=5.3.1,<7.0.0
 regex==2020.7.14
 requests==2.26.0
 six==1.15.0

From 39d5a0dcf74fbf7fc4987d31c76c442c1b361208 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 21:53:29 +0100
Subject: [PATCH 13/30] Add missing-translation.md

---
 help/missing-translation.md | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 help/missing-translation.md

diff --git a/help/missing-translation.md b/help/missing-translation.md
new file mode 100644
index 000000000..674db4480
--- /dev/null
+++ b/help/missing-translation.md
@@ -0,0 +1,4 @@
+!!! warning
+    The current page still doesn't have a translation for this language.
+
+    But you can help translating it: [Contributing](https://hosted.weblate.org/engage/grist-help/){.internal-link target=_blank}.

From 27280ef7c6518ad1eb50ddb6d7e4c0071b59cc62 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 22:04:23 +0100
Subject: [PATCH 14/30] Fix hscout

---
 hscout/mkdocs.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/hscout/mkdocs.yml b/hscout/mkdocs.yml
index 747e41532..951cea506 100644
--- a/hscout/mkdocs.yml
+++ b/hscout/mkdocs.yml
@@ -3,3 +3,5 @@ INHERIT: ../mkdocs.yml
 markdown_extensions:
   toc:
     permalink: False
+hooks:
+- ../mkdocs-utils/hooks.py

From b34451a908245800abb60d64f1d8dd1f6f71e07a Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Thu, 22 Feb 2024 22:05:20 +0100
Subject: [PATCH 15/30] Cleanup docs.py

---
 docs.py               | 14 --------------
 mkdocs-utils/hooks.py |  8 --------
 2 files changed, 22 deletions(-)

diff --git a/docs.py b/docs.py
index eef5e6577..215ebdbd2 100755
--- a/docs.py
+++ b/docs.py
@@ -82,18 +82,6 @@ def complete_existing_lang(incomplete: str):
             yield lang_path.name
 
 
-# FIXME: remove this?
-# def fallback_to_en(lang: str, file: str) -> str:
-#     en_file = language_docs_dir('en') / file
-#     local_file = language_docs_dir(lang) / file
-#     local_file.parent.mkdir(parents=True, exist_ok=True)
-#     if not en_file.exists() or local_file.exists():
-#         return
-#     en_file_content = en_file.read_text(encoding="utf-8")
-#     local_file_content = f"{get_missing_translation_snippet()}\n\n{en_file_content}"
-#     local_file.write_text(local_file_content, encoding="utf-8")
-
-
 @app.command()
 def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     """
@@ -126,8 +114,6 @@ def build_lang(
     """
     Build the docs for a language.
     """
-    insiders_env_file = os.environ.get("INSIDERS_FILE")
-    print(f"Insiders file {insiders_env_file}")
     lang_path: Path = docs_path / lang
     if not lang_path.is_dir():
         typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 17f4ac027..f130f350a 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -24,14 +24,6 @@ def get_missing_translation_content(docs_dir: str) -> str:
     return missing_translation_path.read_text(encoding="utf-8")
 
 
-# @lru_cache
-# def get_mkdocs_material_langs() -> List[str]:
-#     material_path = Path(material.__file__).parent
-#     material_langs_path = material_path / "templates" / "partials" / "languages"
-#     langs = [file.stem for file in material_langs_path.glob("*.html")]
-#     return langs
-
-
 class EnFile(File):
     pass
 

From 9c16ec1e10418d333c8c8739f51d01449e3d6b65 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 11:00:46 +0100
Subject: [PATCH 16/30] Move extra.alternate in a separate mkdocs.yaml file to
 keep comments

---
 docs.py                    |  25 +--
 mkdocs-alternate-langs.yml |   5 +
 mkdocs.yml                 | 363 +++++++++++++++++++------------------
 3 files changed, 205 insertions(+), 188 deletions(-)
 create mode 100644 mkdocs-alternate-langs.yml

diff --git a/docs.py b/docs.py
index 215ebdbd2..a21d306aa 100755
--- a/docs.py
+++ b/docs.py
@@ -31,12 +31,12 @@
 
 app = typer.Typer()
 
-mkdocs_name = "mkdocs.yml"
+alternate_langs_config_name = "mkdocs-alternate-langs.yml"
 
 docs_folder_name = "help"
 docs_path = Path("help")
 en_docs_path = Path("help/en")
-base_config_path: Path = Path(mkdocs_name)
+alternate_langs_config_path: Path = Path(alternate_langs_config_name)
 site_path = Path("site").absolute()
 build_site_path = Path("site_build").absolute()
 
@@ -60,8 +60,8 @@ def get_mkdocs_yaml_for_lang(lang: str) -> str:
     """).lstrip()
 
 
-def get_base_config_path() -> Dict[str, Any]:
-    return mkdocs.utils.yaml_load(base_config_path.read_text(encoding="utf-8"))
+def get_alternate_langs_config() -> Dict[str, Any]:
+    return mkdocs.utils.yaml_load(alternate_langs_config_path.read_text(encoding="utf-8"))
 
 
 def get_lang_paths() -> List[Path]:
@@ -92,7 +92,7 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
         typer.echo(f"The language was already created: {lang}")
         raise typer.Abort()
     new_path.mkdir()
-    new_config_path: Path = Path(new_path) / mkdocs_name
+    new_config_path: Path = Path(new_path) / alternate_langs_config_name
     new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
     new_config_docs_path: Path = language_docs_dir(lang)
     new_config_docs_path.mkdir()
@@ -209,7 +209,7 @@ def live(
 
 
 def get_updated_config_content() -> Dict[str, Any]:
-    config = get_base_config_path()
+    config = get_alternate_langs_config()
     languages = [{"en": "/"}]
     new_alternate: List[Dict[str, str]] = []
     # Language names sourced from https://quickref.me/iso-639-1
@@ -240,7 +240,8 @@ def get_updated_config_content() -> Dict[str, Any]:
 
 def update_config() -> None:
     config = get_updated_config_content()
-    base_config_path.write_text(
+    alternate_langs_config_path.write_text(
+        "# WARNING: this file is auto-generated by ./docs.py\n" +
         yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
         encoding="utf-8",
     )
@@ -251,18 +252,20 @@ def verify_config() -> None:
     """
     Verify main mkdocs.yml content to make sure it uses the latest language names.
     """
-    typer.echo("Verifying mkdocs.yml")
-    config = get_base_config_path()
+    typer.echo("Verifying mkdocs-alternate-lang.yml")
+    config = get_alternate_langs_config()
+    print(config)
     updated_config = get_updated_config_content()
+    print(updated_config)
     if config != updated_config:
         typer.secho(
-            f"{docs_folder_name}/en/mkdocs.yml outdated from {docs_folder_name}/language_names.yml, "
+            f"./mkdocs-alternate-lang.yml outdated from {docs_folder_name}/language_names.yml, "
             "update language_names.yml and run "
             "python ./docs.py update-languages",
             color=typer.colors.RED,
         )
         raise typer.Abort()
-    typer.echo("Valid mkdocs.yml ✅")
+    typer.echo("Valid mkdocs-alternate-lang.yml ✅")
 
 
 @app.command()
diff --git a/mkdocs-alternate-langs.yml b/mkdocs-alternate-langs.yml
new file mode 100644
index 000000000..9015636c9
--- /dev/null
+++ b/mkdocs-alternate-langs.yml
@@ -0,0 +1,5 @@
+# WARNING: this file is auto-generated by ./docs.py
+extra:
+  alternate:
+  - link: /
+    name: en - English
diff --git a/mkdocs.yml b/mkdocs.yml
index b4b267d82..01015e973 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,200 +1,209 @@
+INHERIT: ./mkdocs-alternate-langs.yml
 site_name: Grist Help Center
 site_dir: site
-site_description: Tutorials and resources for Grist, to help you organize your data, your way.
-site_url: https://support.getgrist.com
-repo_name: GitHub
-repo_url: https://github.com/gristlabs/grist-help
-use_directory_urls: true
-docs_dir: ./help/en/docs
+site_description: "Tutorials and resources for Grist, to help you organize your data, your way."
+site_url: "https://support.getgrist.com"
+repo_name: "GitHub"
+repo_url: "https://github.com/gristlabs/grist-help"
+
+# use directory urls (for prettiness) unless running htmlproofing
+# (which is confused by them).
+use_directory_urls: !ENV [HTMLPROOFER_OVERRIDE_USE_DIRECTORY_URLS, true]
+
+docs_dir: './help/en/docs' # Add localization folder here for now, we'll handle i18n later
+# windmill is a theme maintained by Grist Labs in https://github.com/gristlabs/mkdocs-windmill
 theme:
   name: windmill
   custom_dir: overrides
 nav:
-- Welcome to Grist: index.md
-- FAQ: FAQ.md
-- How-To Tutorials:
-  - Create your own CRM: lightweight-crm.md
-  - Analyze and visualize: investment-research.md
-  - Manage business data: afterschool-program.md
-- Managing documents:
-  - Creating a document: creating-doc.md
-  - Sharing a document: sharing.md
-  - Copying documents: copying-docs.md
-  - Importing more data: imports.md
-  - Exports & backups: exports.md
-  - Automatic backups: automatic-backups.md
-  - Document history: document-history.md
-  - Workspaces: workspaces.md
-- Pages and Tables:
-  - Entering data: enter-data.md
-  - Pages & widgets: page-widgets.md
-  - Raw data page: raw-data.md
-  - Search, sort & filter: search-sort-filter.md
-  - Table widget: widget-table.md
-  - Card & Card List: widget-card.md
-  - Form: widget-form.md
-  - Chart: widget-chart.md
-  - Calendar: widget-calendar.md
-  - Custom: widget-custom.md
-  - Linking widgets: linking-widgets.md
-  - Custom layouts: custom-layouts.md
-  - Record Cards: record-cards.md
-  - Summary tables: summary-tables.md
-  - On-Demand tables: on-demand-tables.md
-- Columns and data types:
-  - Columns & types: col-types.md
-  - Reference columns: col-refs.md
-  - Conditional Formatting: conditional-formatting.md
-  - Timestamp columns: timestamps.md
-  - Authorship columns: authorship.md
-  - Transformations: col-transform.md
-- Using formulas:
-  - Intro to formulas: formulas.md
-  - References and Lookups: references-lookups.md
-  - Working with dates: dates.md
-  - Python versions: python.md
-  - Function reference: functions.md
-  - Formula Cheat Sheet: formula-cheat-sheet.md
-- AI Assistant:
-  - AI Assistant: ai-assistant.md
-- Team Sites:
-  - Creating team sites: teams.md
-  - Sharing team sites: team-sharing.md
-- Access rules:
-  - Intro to access rules: access-rules.md
-- Integrations:
-  - REST API usage: rest-api.md
-  - REST API reference: api.md
-  - Integrator Services: integrators.md
-  - Embedding: embedding.md
-  - Plugin API:
-    - Intro to Plugin API: code/README.md
-    - grist-plugin-api: code/modules/grist_plugin_api.md
-    - '... | flat | **/code/interfaces/**'
-    - '... | flat | **/code/modules/**'
-- Self-Managed:
-  - Self-managed Grist: self-managed.md
-  - SAML: install/saml.md
-  - OIDC: install/oidc.md
-  - Forwarded headers: install/forwarded-headers.md
-  - Cloud storage: install/cloud-storage.md
-  - GristConnect: install/grist-connect.md
-  - AWS Marketplace: install/aws-marketplace.md
-  - Telemetry:
-    - Overview of Telemetry: telemetry.md
-    - Limited Telemetry: telemetry-limited.md
-    - Full Telemetry: telemetry-full.md
-- News & updates:
-  - Newsletters: newsletters.md
-  - 2024/01: newsletters/2024-01.md
-  - 2023/12: newsletters/2023-12.md
-  - 2023/11: newsletters/2023-11.md
-  - 2023/10: newsletters/2023-10.md
-  - 2023/09: newsletters/2023-09.md
-  - 2023/08: newsletters/2023-08.md
-  - 2023/07: newsletters/2023-07.md
-  - 2023/06: newsletters/2023-06.md
-  - 2023/05: newsletters/2023-05.md
-  - 2023/04: newsletters/2023-04.md
-  - 2023/03: newsletters/2023-03.md
-  - 2023/02: newsletters/2023-02.md
-  - 2023/01: newsletters/2023-01.md
-  - 2022/12: newsletters/2022-12.md
-  - 2022/11: newsletters/2022-11.md
-  - 2022/10: newsletters/2022-10.md
-  - 2022/09: newsletters/2022-09.md
-  - 2022/08: newsletters/2022-08.md
-  - 2022/07: newsletters/2022-07.md
-  - 2022/06: newsletters/2022-06.md
-  - 2022/05: newsletters/2022-05.md
-  - 2022/04: newsletters/2022-04.md
-  - 2022/03: newsletters/2022-03.md
-  - 2022/02: newsletters/2022-02.md
-  - 2022/01: newsletters/2022-01.md
-  - 2021/12: newsletters/2021-12.md
-  - 2021/11: newsletters/2021-11.md
-  - 2021/10: newsletters/2021-10.md
-  - 2021/09: newsletters/2021-09.md
-  - 2021/08: newsletters/2021-08.md
-  - 2021/07: newsletters/2021-07.md
-  - 2021/06: newsletters/2021-06.md
-  - 2021/05: newsletters/2021-05.md
-  - 2021/04: newsletters/2021-04.md
-  - 2021/03: newsletters/2021-03.md
-  - 2021/02: newsletters/2021-02.md
-  - 2021/01: newsletters/2021-01.md
-  - 2020/12: newsletters/2020-12.md
-  - 2020/11: newsletters/2020-11.md
-  - 2020/10: newsletters/2020-10.md
-  - 2020/09: newsletters/2020-09.md
-  - 2020/08: newsletters/2020-08.md
-  - 2020/07: newsletters/2020-07.md
-  - 2020/06: newsletters/2020-06.md
-  - 2020/05: newsletters/2020-05.md
-- More examples:
-  - More examples: examples.md
-  - Credit card expenses: examples/2020-06-credit-card.md
-  - Book club links: examples/2020-06-book-club.md
-  - Prefill emails: examples/2020-07-email-compose.md
-  - Prepare Invoices: examples/2020-08-invoices.md
-  - Track Payroll: examples/2020-09-payroll.md
-  - Print mailing labels: examples/2020-10-print-labels.md
-  - Treasure Hunt: examples/2020-11-treasure-hunt.md
-  - Map: examples/2020-12-map.md
-  - Task Management: examples/2021-01-tasks.md
-  - Lead List: examples/2021-03-leads.md
-  - Link Keys Guide: examples/2021-04-link-keys.md
-  - Reference Columns Guide: examples/2021-05-reference-columns.md
-  - Summary Tables Guide: examples/2021-06-timesheets.md
-  - Time and User Stamps: examples/2021-07-auto-stamps.md
-  - Restrict Duplicate Records: examples/2023-01-acl-memo.md
-  - Proposals & Contracts: examples/2023-07-proposals-contracts.md
-- Reference:
-  - Shortcuts: keyboard-shortcuts.md
-  - Function reference: functions.md
-  - Limits: limits.md
-  - Data Security: data-security.md
-  - Browser Support: browser-support.md
-  - Glossary: glossary.md
+  - Welcome to Grist: index.md
+  - FAQ: FAQ.md
+  - How-To Tutorials:
+    - Create your own CRM: lightweight-crm.md
+    - Analyze and visualize: investment-research.md
+    - Manage business data: afterschool-program.md
+  - Managing documents:
+    - Creating a document: creating-doc.md
+    - Sharing a document: sharing.md
+    - Copying documents: copying-docs.md
+    - Importing more data: imports.md
+    - Exports & backups: exports.md
+    - Automatic backups: automatic-backups.md
+    - Document history: document-history.md
+    - Workspaces: workspaces.md
+  - Pages and Tables:
+    - Entering data: enter-data.md
+    - Pages & widgets: page-widgets.md
+    - Raw data page: raw-data.md
+    - Search, sort & filter: search-sort-filter.md
+    - Table widget: widget-table.md
+    - Card & Card List: widget-card.md
+    - Form: widget-form.md
+    - Chart: widget-chart.md
+    - Calendar: widget-calendar.md
+    - Custom: widget-custom.md
+    - Linking widgets: linking-widgets.md
+    - Custom layouts: custom-layouts.md
+    - Record Cards: record-cards.md
+    - Summary tables: summary-tables.md
+    - On-Demand tables: on-demand-tables.md
+  - Columns and data types:
+    - Columns & types: col-types.md
+    - Reference columns: col-refs.md
+    - Conditional Formatting: conditional-formatting.md
+    - Timestamp columns: timestamps.md
+    - Authorship columns: authorship.md
+    - Transformations: col-transform.md
+  - Using formulas:
+    - Intro to formulas: formulas.md
+    - References and Lookups: references-lookups.md
+    - Working with dates: dates.md
+    - Python versions: python.md
+    - Function reference: functions.md
+    - Formula Cheat Sheet: formula-cheat-sheet.md
+  - AI Assistant:
+    - AI Assistant: ai-assistant.md
+  - Team Sites:
+    - Creating team sites: teams.md
+    - Sharing team sites: team-sharing.md
+  - Access rules:
+    - Intro to access rules: access-rules.md
+  - Integrations:
+    - REST API usage: rest-api.md
+    - REST API reference: api.md
+    - Integrator Services: integrators.md
+    - Embedding: embedding.md
+    - Plugin API:
+      - Intro to Plugin API: code/README.md
+      - grist-plugin-api: code/modules/grist_plugin_api.md
+      - ... | flat | **/code/interfaces/**
+      - ... | flat | **/code/modules/**
+  - Self-Managed:
+    - Self-managed Grist: self-managed.md
+    - SAML: install/saml.md
+    - OIDC: install/oidc.md
+    - Forwarded headers: install/forwarded-headers.md
+    - Cloud storage: install/cloud-storage.md
+    - GristConnect: install/grist-connect.md
+    - AWS Marketplace: install/aws-marketplace.md
+    - Telemetry:
+      - Overview of Telemetry: telemetry.md
+      - Limited Telemetry: telemetry-limited.md
+      - Full Telemetry: telemetry-full.md
+  - News & updates:
+    - Newsletters: newsletters.md
+    - 2024/01: newsletters/2024-01.md
+    - 2023/12: newsletters/2023-12.md
+    - 2023/11: newsletters/2023-11.md
+    - 2023/10: newsletters/2023-10.md
+    - 2023/09: newsletters/2023-09.md
+    - 2023/08: newsletters/2023-08.md
+    - 2023/07: newsletters/2023-07.md
+    - 2023/06: newsletters/2023-06.md
+    - 2023/05: newsletters/2023-05.md
+    - 2023/04: newsletters/2023-04.md
+    - 2023/03: newsletters/2023-03.md
+    - 2023/02: newsletters/2023-02.md
+    - 2023/01: newsletters/2023-01.md
+    - 2022/12: newsletters/2022-12.md
+    - 2022/11: newsletters/2022-11.md
+    - 2022/10: newsletters/2022-10.md
+    - 2022/09: newsletters/2022-09.md
+    - 2022/08: newsletters/2022-08.md
+    - 2022/07: newsletters/2022-07.md
+    - 2022/06: newsletters/2022-06.md
+    - 2022/05: newsletters/2022-05.md
+    - 2022/04: newsletters/2022-04.md
+    - 2022/03: newsletters/2022-03.md
+    - 2022/02: newsletters/2022-02.md
+    - 2022/01: newsletters/2022-01.md
+    - 2021/12: newsletters/2021-12.md
+    - 2021/11: newsletters/2021-11.md
+    - 2021/10: newsletters/2021-10.md
+    - 2021/09: newsletters/2021-09.md
+    - 2021/08: newsletters/2021-08.md
+    - 2021/07: newsletters/2021-07.md
+    - 2021/06: newsletters/2021-06.md
+    - 2021/05: newsletters/2021-05.md
+    - 2021/04: newsletters/2021-04.md
+    - 2021/03: newsletters/2021-03.md
+    - 2021/02: newsletters/2021-02.md
+    - 2021/01: newsletters/2021-01.md
+    - 2020/12: newsletters/2020-12.md
+    - 2020/11: newsletters/2020-11.md
+    - 2020/10: newsletters/2020-10.md
+    - 2020/09: newsletters/2020-09.md
+    - 2020/08: newsletters/2020-08.md
+    - 2020/07: newsletters/2020-07.md
+    - 2020/06: newsletters/2020-06.md
+    - 2020/05: newsletters/2020-05.md
+  - More examples:
+      - More examples: examples.md
+      - Credit card expenses: examples/2020-06-credit-card.md
+      - Book club links: examples/2020-06-book-club.md
+      - Prefill emails: examples/2020-07-email-compose.md
+      - Prepare Invoices: examples/2020-08-invoices.md
+      - Track Payroll: examples/2020-09-payroll.md
+      - Print mailing labels: examples/2020-10-print-labels.md
+      - Treasure Hunt: examples/2020-11-treasure-hunt.md
+      - Map: examples/2020-12-map.md
+      - Task Management: examples/2021-01-tasks.md
+      - Lead List: examples/2021-03-leads.md
+      - Link Keys Guide: examples/2021-04-link-keys.md
+      - Reference Columns Guide: examples/2021-05-reference-columns.md
+      - Summary Tables Guide: examples/2021-06-timesheets.md
+      - Time and User Stamps: examples/2021-07-auto-stamps.md
+      - Restrict Duplicate Records: examples/2023-01-acl-memo.md
+      - Proposals & Contracts: examples/2023-07-proposals-contracts.md
+  - Reference:
+    - Shortcuts: keyboard-shortcuts.md
+    # The function reference (functions.md) is listed above; here is an intentionally non-standard
+    # link, so that only the above page item gets highlighted when the function reference is open.
+    - Function reference: /functions/
+    - Limits: limits.md
+    - Data Security: data-security.md
+    - Browser Support: browser-support.md
+    - Glossary: glossary.md
+
 extra:
-  logo: images/logo.png
+  logo: 'images/logo.png'
   palette:
-    primary: blue grey
-    accent: orange
+    primary: 'blue grey'
+    accent: 'orange'
   font:
-    text: Roboto
-    code: Roboto Mono
-  homepage: /help
-  version: 1.0.2-dev
+    text: 'Roboto'
+    code: 'Roboto Mono'
+  homepage: '/help'
+  version: '1.0.2-dev'
   article_nav_bottom: false
   history_buttons: false
   home_links:
-  - href: https://community.getgrist.com
-    text: Community
-  - href: https://www.getgrist.com
-    text: Back to Grist
-    hide_on_small_screen: true
-  google_tag_manager: GTM-5FDHKQ9
-  alternate:
-  - link: /
-    name: en - English
+    - href: https://community.getgrist.com
+      text: 'Community'
+    - href: https://www.getgrist.com
+      text: 'Back to Grist'
+      hide_on_small_screen: true
+  google_tag_manager: 'GTM-5FDHKQ9'
 extra_css:
-- css/grist.css
+  - css/grist.css
 extra_javascript:
-- js/grist.js
+  - js/grist.js
+
 plugins:
-- search
-- awesome-pages
-- htmlproofer:
-    enabled: false
-    validate_external_urls: false
-- meta-descriptions
+  - search
+  - awesome-pages
+  - htmlproofer:
+      enabled: !ENV [HTMLPROOFER_ENABLED, false]
+      validate_external_urls: false
+  - meta-descriptions
+
 markdown_extensions:
   toc:
-    permalink: '#'
+      permalink: '#'
   admonition: {}
   smarty: {}
   extra: {}
   meta: {}
+
 hooks:
 - ../../mkdocs-utils/hooks.py

From cd5d6a02996b3800fa50c345700b9669387a8f5f Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 17:36:09 +0100
Subject: [PATCH 17/30] Document a bit more in README.md

---
 README.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index bcb567221..b551e953b 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,8 @@ Conversation tab.
 
 ``` sh
 python3 -m venv env
-./env/bin/pip install -r requirements.txt
+source ./env/bin/activate # for most shells, or source ./env/bin/activate.fish or source ./env/bin/activate.csh depending on your shell
+pip install -r requirements.txt
 ./docs.py live en # or whatever code for language you want to see
 ```
 
@@ -44,6 +45,14 @@ Total wall clock time: 1.3s
 Downloaded: 36 files, 2.0M in 0.009s (226 MB/s)
 ```
 
+In order to build the website with all the languages, run:
+```sh
+source ./env/bin/activate
+./docs.py serve
+```
+
+Also see `./docs.py --help` for the full list of commands and options available.
+
 ## Publishing for preview
 
 This is now automatically done by Netlify. Whenever you create a pull request, Netlify will build

From 4b4fe9e8f4703e6cba707473b471d6572358d743 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 17:38:26 +0100
Subject: [PATCH 18/30] Reset language_names to its original content

---
 help/language_names.yml | 181 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)

diff --git a/help/language_names.yml b/help/language_names.yml
index b461eae69..c5a15ddd9 100644
--- a/help/language_names.yml
+++ b/help/language_names.yml
@@ -1,2 +1,183 @@
+aa: Afaraf
+ab: аҧсуа бызшәа
+ae: avesta
+af: Afrikaans
+ak: Akan
+am: አማርኛ
+an: aragonés
+ar: اللغة العربية
+as: অসমীয়া
+av: авар мацӀ
+ay: aymar aru
+az: azərbaycan dili
+ba: башҡорт теле
+be: беларуская мова
+bg: български език
+bh: भोजपुरी
+bi: Bislama
+bm: bamanankan
+bn: বাংলা
+bo: བོད་ཡིག
+br: brezhoneg
+bs: bosanski jezik
+ca: Català
+ce: нохчийн мотт
+ch: Chamoru
+co: corsu
+cr: ᓀᐦᐃᔭᐍᐏᐣ
+cs: čeština
+cu: ѩзыкъ словѣньскъ
+cv: чӑваш чӗлхи
+cy: Cymraeg
+da: dansk
+de: Deutsch
+dv: Dhivehi
+dz: རྫོང་ཁ
+ee: Eʋegbe
+el: Ελληνικά
 en: English
+eo: Esperanto
+es: español
+et: eesti
+eu: euskara
+fa: فارسی
+ff: Fulfulde
+fi: suomi
+fj: Vakaviti
+fo: føroyskt
 fr: français
+fy: Frysk
+ga: Gaeilge
+gd: Gàidhlig
+gl: galego
+gu: ગુજરાતી
+gv: Gaelg
+ha: هَوُسَ
+he: עברית
+hi: हिन्दी
+ho: Hiri Motu
+hr: Hrvatski
+ht: Kreyòl ayisyen
+hu: magyar
+hy: Հայերեն
+hz: Otjiherero
+ia: Interlingua
+id: Bahasa Indonesia
+ie: Interlingue
+ig: Asụsụ Igbo
+ii: ꆈꌠ꒿ Nuosuhxop
+ik: Iñupiaq
+io: Ido
+is: Íslenska
+it: italiano
+iu: ᐃᓄᒃᑎᑐᑦ
+ja: 日本語
+jv: basa Jawa
+ka: ქართული
+kg: Kikongo
+ki: Gĩkũyũ
+kj: Kuanyama
+kk: қазақ тілі
+kl: kalaallisut
+km: ខេមរភាសា
+kn: ಕನ್ನಡ
+ko: 한국어
+kr: Kanuri
+ks: कश्मीरी
+ku: Kurdî
+kv: коми кыв
+kw: Kernewek
+ky: Кыргызча
+la: latine
+lb: Lëtzebuergesch
+lg: Luganda
+li: Limburgs
+ln: Lingála
+lo: ພາສາ
+lt: lietuvių kalba
+lu: Tshiluba
+lv: latviešu valoda
+mg: fiteny malagasy
+mh: Kajin M̧ajeļ
+mi: te reo Māori
+mk: македонски јазик
+ml: മലയാളം
+mn: Монгол хэл
+mr: मराठी
+ms: Bahasa Malaysia
+mt: Malti
+my: ဗမာစာ
+na: Ekakairũ Naoero
+nb: Norsk bokmål
+nd: isiNdebele
+ne: नेपाली
+ng: Owambo
+nl: Nederlands
+nn: Norsk nynorsk
+'no': Norsk
+nr: isiNdebele
+nv: Diné bizaad
+ny: chiCheŵa
+oc: occitan
+oj: ᐊᓂᔑᓈᐯᒧᐎᓐ
+om: Afaan Oromoo
+or: ଓଡ଼ିଆ
+os: ирон æвзаг
+pa: ਪੰਜਾਬੀ
+pi: पाऴि
+pl: Polski
+ps: پښتو
+pt: português
+qu: Runa Simi
+rm: rumantsch grischun
+rn: Ikirundi
+ro: Română
+ru: русский язык
+rw: Ikinyarwanda
+sa: संस्कृतम्
+sc: sardu
+sd: सिन्धी
+se: Davvisámegiella
+sg: yângâ tî sängö
+si: සිංහල
+sk: slovenčina
+sl: slovenščina
+sn: chiShona
+so: Soomaaliga
+sq: shqip
+sr: српски језик
+ss: SiSwati
+st: Sesotho
+su: Basa Sunda
+sv: svenska
+sw: Kiswahili
+ta: தமிழ்
+te: తెలుగు
+tg: тоҷикӣ
+th: ไทย
+ti: ትግርኛ
+tk: Türkmen
+tl: Wikang Tagalog
+tn: Setswana
+to: faka Tonga
+tr: Türkçe
+ts: Xitsonga
+tt: татар теле
+tw: Twi
+ty: Reo Tahiti
+ug: ئۇيغۇرچە‎
+uk: українська мова
+ur: اردو
+uz: Ўзбек
+ve: Tshivenḓa
+vi: Tiếng Việt
+vo: Volapük
+wa: walon
+wo: Wollof
+xh: isiXhosa
+yi: ייִדיש
+yo: Yorùbá
+za: Saɯ cueŋƅ
+zh: 简体中文
+zh-hant: 繁體中文
+zu: isiZulu

From dfd12af31844aebb3c09892efbcf2e16ef88a89f Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 18:09:35 +0100
Subject: [PATCH 19/30] Linting

---
 docs.py               | 348 +++++++++++++++++++++---------------------
 mkdocs-utils/hooks.py | 179 +++++++++++-----------
 2 files changed, 259 insertions(+), 268 deletions(-)

diff --git a/docs.py b/docs.py
index a21d306aa..2b81ab6d4 100755
--- a/docs.py
+++ b/docs.py
@@ -8,12 +8,9 @@
 import json
 import logging
 import os
-import re
 import shutil
 import subprocess
-from functools import lru_cache
 from http.server import HTTPServer, SimpleHTTPRequestHandler
-from importlib import metadata
 from multiprocessing import Pool
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
@@ -25,7 +22,6 @@
 import mkdocs.utils
 import typer
 import yaml
-from jinja2 import Template
 
 logging.basicConfig(level=logging.INFO)
 
@@ -42,240 +38,240 @@
 
 
 def language_docs_dir(lang: str) -> Path:
-    return docs_path / lang / "docs"
+  return docs_path / lang / "docs"
 
 
 def get_missing_translation_snippet() -> str:
-    missing_translation_file_path = (Path(__file__).parent / "help/missing-translation.md")
-    return missing_translation_file_path.read_text(encoding="utf-8")
+  missing_translation_file_path = (Path(__file__).parent / "help/missing-translation.md")
+  return missing_translation_file_path.read_text(encoding="utf-8")
 
 
 def get_mkdocs_yaml_for_lang(lang: str) -> str:
-    return dedent(f"""
-    INHERIT: ../../mkdocs.yml
-    docs_dir: './docs'
-    theme:
-      custom_dir: ../../overrides
-      language: {lang}
-    """).lstrip()
+  return dedent(f"""
+  INHERIT: ../../mkdocs.yml
+  docs_dir: './docs'
+  theme:
+   custom_dir: ../../overrides
+   language: {lang}
+  """).lstrip()
 
 
 def get_alternate_langs_config() -> Dict[str, Any]:
-    return mkdocs.utils.yaml_load(alternate_langs_config_path.read_text(encoding="utf-8"))
+  return mkdocs.utils.yaml_load(alternate_langs_config_path.read_text(encoding="utf-8"))
 
 
 def get_lang_paths() -> List[Path]:
-    return sorted(docs_path.iterdir())
+  return sorted(docs_path.iterdir())
 
 
 def lang_callback(lang: Optional[str]) -> Union[str, None]:
-    if lang is None:
-        return None
-    lang = lang.lower()
-    return lang
+  if lang is None:
+    return None
+  lang = lang.lower()
+  return lang
 
 
 def complete_existing_lang(incomplete: str):
-    lang_path: Path
-    for lang_path in get_lang_paths():
-        if lang_path.is_dir() and lang_path.name.startswith(incomplete):
-            yield lang_path.name
+  lang_path: Path
+  for lang_path in get_lang_paths():
+    if lang_path.is_dir() and lang_path.name.startswith(incomplete):
+      yield lang_path.name
 
 
 @app.command()
 def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
-    """
-    Generate a new docs translation directory for the language LANG.
-    """
-    new_path: Path = docs_path / lang
-    if new_path.exists():
-        typer.echo(f"The language was already created: {lang}")
-        raise typer.Abort()
-    new_path.mkdir()
-    new_config_path: Path = Path(new_path) / alternate_langs_config_name
-    new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
-    new_config_docs_path: Path = language_docs_dir(lang)
-    new_config_docs_path.mkdir()
-    en_index_path: Path = language_docs_dir('en') / "index.md"
-    new_index_path: Path = new_config_docs_path / "index.md"
-    en_index_content = en_index_path.read_text(encoding="utf-8")
-    new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"
-    new_index_path.write_text(new_index_content, encoding="utf-8")
-    typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN)
-    update_languages()
+  """
+  Generate a new docs translation directory for the language LANG.
+  """
+  new_path: Path = docs_path / lang
+  if new_path.exists():
+    typer.echo(f"The language was already created: {lang}")
+    raise typer.Abort()
+  new_path.mkdir()
+  new_config_path: Path = Path(new_path) / alternate_langs_config_name
+  new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
+  new_config_docs_path: Path = language_docs_dir(lang)
+  new_config_docs_path.mkdir()
+  en_index_path: Path = language_docs_dir('en') / "index.md"
+  new_index_path: Path = new_config_docs_path / "index.md"
+  en_index_content = en_index_path.read_text(encoding="utf-8")
+  new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"
+  new_index_path.write_text(new_index_content, encoding="utf-8")
+  typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN)
+  update_languages()
 
 
 @app.command()
 def build_lang(
-    lang: str = typer.Argument(
-        ..., callback=lang_callback, autocompletion=complete_existing_lang
-    ),
+  lang: str = typer.Argument(
+    ..., callback=lang_callback, autocompletion=complete_existing_lang
+  ),
 ) -> None:
-    """
-    Build the docs for a language.
-    """
-    lang_path: Path = docs_path / lang
-    if not lang_path.is_dir():
-        typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
-        raise typer.Abort()
-    typer.echo(f"Building docs for: {lang}")
-    build_site_dist_path = build_site_path / lang
-    if lang == "en":
-        dist_path = site_path
-        # Don't remove en dist_path as it might already contain other languages.
-        # When running build_all(), that function already removes site_path.
-        # All this is only relevant locally, on GitHub Actions all this is done through
-        # artifacts and multiple workflows, so it doesn't matter if directories are
-        # removed or not.
-    else:
-        dist_path = site_path / lang
-        shutil.rmtree(dist_path, ignore_errors=True)
-    current_dir = os.getcwd()
-    os.chdir(lang_path)
-    shutil.rmtree(build_site_dist_path, ignore_errors=True)
-    subprocess.run(["mkdocs", "build", "--site-dir", build_site_dist_path], check=True)
-    shutil.copytree(build_site_dist_path, dist_path, dirs_exist_ok=True)
-    os.chdir(current_dir)
-    typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
+  """
+  Build the docs for a language.
+  """
+  lang_path: Path = docs_path / lang
+  if not lang_path.is_dir():
+    typer.echo(f"The language translation doesn't seem to exist yet: {lang}")
+    raise typer.Abort()
+  typer.echo(f"Building docs for: {lang}")
+  build_site_dist_path = build_site_path / lang
+  if lang == "en":
+    dist_path = site_path
+    # Don't remove en dist_path as it might already contain other languages.
+    # When running build_all(), that function already removes site_path.
+    # All this is only relevant locally, on GitHub Actions all this is done through
+    # artifacts and multiple workflows, so it doesn't matter if directories are
+    # removed or not.
+  else:
+    dist_path = site_path / lang
+    shutil.rmtree(dist_path, ignore_errors=True)
+  current_dir = os.getcwd()
+  os.chdir(lang_path)
+  shutil.rmtree(build_site_dist_path, ignore_errors=True)
+  subprocess.run(["mkdocs", "build", "--site-dir", build_site_dist_path], check=True)
+  shutil.copytree(build_site_dist_path, dist_path, dirs_exist_ok=True)
+  os.chdir(current_dir)
+  typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
 
 @app.command()
 def build_all() -> None:
-    """
-    Build mkdocs site for en, and then build each language inside, end result is located
-    at directory ./site/ with each language inside.
-    """
-    update_languages()
-    shutil.rmtree(site_path, ignore_errors=True)
-    langs = [lang.name for lang in get_lang_paths() if lang.is_dir()]
-    cpu_count = os.cpu_count() or 1
-    process_pool_size = cpu_count * 4
-    typer.echo(f"Using process pool size: {process_pool_size}")
-    with Pool(process_pool_size) as p:
-        p.map(build_lang, langs)
+  """
+  Build mkdocs site for en, and then build each language inside, end result is located
+  at directory ./site/ with each language inside.
+  """
+  update_languages()
+  shutil.rmtree(site_path, ignore_errors=True)
+  langs = [lang.name for lang in get_lang_paths() if lang.is_dir()]
+  cpu_count = os.cpu_count() or 1
+  process_pool_size = cpu_count * 4
+  typer.echo(f"Using process pool size: {process_pool_size}")
+  with Pool(process_pool_size) as p:
+    p.map(build_lang, langs)
 
 
 @app.command()
 def update_languages() -> None:
-    """
-    Update the mkdocs.yml file Languages section including all the available languages.
-    """
-    update_config()
+  """
+  Update the mkdocs.yml file Languages section including all the available languages.
+  """
+  update_config()
 
 
 @app.command()
 def serve() -> None:
-    """
-    A quick server to preview a built site with translations.
+  """
+  A quick server to preview a built site with translations.
 
-    For development, prefer the command live (or just mkdocs serve).
+  For development, prefer the command live (or just mkdocs serve).
 
-    This is here only to preview a site with translations already built.
+  This is here only to preview a site with translations already built.
 
-    Make sure you run the build-all command first.
-    """
-    typer.echo("Warning: this is a very simple server.")
-    typer.echo("For development, use the command live instead.")
-    typer.echo("This is here only to preview a site with translations already built.")
-    typer.echo("Make sure you run the build-all command first.")
-    os.chdir("site")
-    server_address = ("", 8000)
-    server = HTTPServer(server_address, SimpleHTTPRequestHandler)
-    typer.echo("Serving at: http://127.0.0.1:8000")
-    server.serve_forever()
+  Make sure you run the build-all command first.
+  """
+  typer.echo("Warning: this is a very simple server.")
+  typer.echo("For development, use the command live instead.")
+  typer.echo("This is here only to preview a site with translations already built.")
+  typer.echo("Make sure you run the build-all command first.")
+  os.chdir("site")
+  server_address = ("", 8000)
+  server = HTTPServer(server_address, SimpleHTTPRequestHandler)
+  typer.echo("Serving at: http://127.0.0.1:8000")
+  server.serve_forever()
 
 
 @app.command()
 def live(
-    lang: str = typer.Argument(
-        None, callback=lang_callback, autocompletion=complete_existing_lang
-    ),
+  lang: str = typer.Argument(
+    None, callback=lang_callback, autocompletion=complete_existing_lang
+  ),
 ) -> None:
-    """
-    Serve with livereload a docs site for a specific language.
+  """
+  Serve with livereload a docs site for a specific language.
 
-    This only shows the actual translated files, not the placeholders created with
-    build-all.
+  This only shows the actual translated files, not the placeholders created with
+  build-all.
 
-    Takes an optional LANG argument with the name of the language to serve, by default
-    en.
-    """
-    # Enable line numbers during local development to make it easier to highlight
-    os.environ["LINENUMS"] = "true"
-    if lang is None:
-        lang = "en"
-    lang_path: Path = docs_path / lang
-    os.chdir(lang_path)
-    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8000")
+  Takes an optional LANG argument with the name of the language to serve, by default
+  en.
+  """
+  # Enable line numbers during local development to make it easier to highlight
+  os.environ["LINENUMS"] = "true"
+  if lang is None:
+    lang = "en"
+  lang_path: Path = docs_path / lang
+  os.chdir(lang_path)
+  mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8000")
 
 
 def get_updated_config_content() -> Dict[str, Any]:
-    config = get_alternate_langs_config()
-    languages = [{"en": "/"}]
-    new_alternate: List[Dict[str, str]] = []
-    # Language names sourced from https://quickref.me/iso-639-1
-    # Contributors may wish to update or change these, e.g. to fix capitalization.
-    language_names_path = Path(__file__).parent / docs_folder_name / "language_names.yml"
-    local_language_names: Dict[str, str] = mkdocs.utils.yaml_load(
-        language_names_path.read_text(encoding="utf-8")
-    )
-    for lang_path in get_lang_paths():
-        if lang_path.name == "en" or not lang_path.is_dir():
-            continue
-        code = lang_path.name
-        languages.append({code: f"/{code}/"})
-    for lang_dict in languages:
-        code = list(lang_dict.keys())[0]
-        url = lang_dict[code]
-        if code not in local_language_names:
-            print(
-                f"Missing language name for: {code}, "
-                f"update it in {docs_folder_name}/language_names.yml"
-            )
-            raise typer.Abort()
-        use_name = f"{code} - {local_language_names[code]}"
-        new_alternate.append({"link": url, "name": use_name})
-    config["extra"]["alternate"] = new_alternate
-    return config
+  config = get_alternate_langs_config()
+  languages = [{"en": "/"}]
+  new_alternate: List[Dict[str, str]] = []
+  # Language names sourced from https://quickref.me/iso-639-1
+  # Contributors may wish to update or change these, e.g. to fix capitalization.
+  language_names_path = Path(__file__).parent / docs_folder_name / "language_names.yml"
+  local_language_names: Dict[str, str] = mkdocs.utils.yaml_load(
+    language_names_path.read_text(encoding="utf-8")
+  )
+  for lang_path in get_lang_paths():
+    if lang_path.name == "en" or not lang_path.is_dir():
+      continue
+    code = lang_path.name
+    languages.append({code: f"/{code}/"})
+  for lang_dict in languages:
+    code = list(lang_dict.keys())[0]
+    url = lang_dict[code]
+    if code not in local_language_names:
+      print(
+        f"Missing language name for: {code}, "
+        f"update it in {docs_folder_name}/language_names.yml"
+      )
+      raise typer.Abort()
+    use_name = f"{code} - {local_language_names[code]}"
+    new_alternate.append({"link": url, "name": use_name})
+  config["extra"]["alternate"] = new_alternate
+  return config
 
 
 def update_config() -> None:
-    config = get_updated_config_content()
-    alternate_langs_config_path.write_text(
-        "# WARNING: this file is auto-generated by ./docs.py\n" +
-        yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
-        encoding="utf-8",
-    )
+  config = get_updated_config_content()
+  alternate_langs_config_path.write_text(
+    "# WARNING: this file is auto-generated by ./docs.py\n" +
+    yaml.dump(config, sort_keys=False, width=200, allow_unicode=True),
+    encoding="utf-8",
+  )
 
 
 @app.command()
 def verify_config() -> None:
-    """
-    Verify main mkdocs.yml content to make sure it uses the latest language names.
-    """
-    typer.echo("Verifying mkdocs-alternate-lang.yml")
-    config = get_alternate_langs_config()
-    print(config)
-    updated_config = get_updated_config_content()
-    print(updated_config)
-    if config != updated_config:
-        typer.secho(
-            f"./mkdocs-alternate-lang.yml outdated from {docs_folder_name}/language_names.yml, "
-            "update language_names.yml and run "
-            "python ./docs.py update-languages",
-            color=typer.colors.RED,
-        )
-        raise typer.Abort()
-    typer.echo("Valid mkdocs-alternate-lang.yml ✅")
+  """
+  Verify main mkdocs.yml content to make sure it uses the latest language names.
+  """
+  typer.echo("Verifying mkdocs-alternate-lang.yml")
+  config = get_alternate_langs_config()
+  print(config)
+  updated_config = get_updated_config_content()
+  print(updated_config)
+  if config != updated_config:
+    typer.secho(
+      f"./mkdocs-alternate-lang.yml outdated from {docs_folder_name}/language_names.yml, "
+      "update language_names.yml and run "
+      "python ./docs.py update-languages",
+      color=typer.colors.RED,
+    )
+    raise typer.Abort()
+  typer.echo("Valid mkdocs-alternate-lang.yml ✅")
 
 
 @app.command()
 def langs_json():
-    langs = []
-    for lang_path in get_lang_paths():
-        if lang_path.is_dir():
-            langs.append(lang_path.name)
-    print(json.dumps(langs))
+  langs = []
+  for lang_path in get_lang_paths():
+    if lang_path.is_dir():
+      langs.append(lang_path.name)
+  print(json.dumps(langs))
 
 
 if __name__ == "__main__":
-    app()
+  app()
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index f130f350a..ba2eb372f 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -3,6 +3,7 @@
 # Source: https://github.com/tiangolo/fastapi/blob/master/scripts/mkdocs_hooks.py
 # Original Author: Sebastián Ramírez and contributors
 
+import glob
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, List, Union
@@ -13,127 +14,121 @@
 from mkdocs.structure.pages import Page
 from mkdocs.utils.yaml import yaml_load
 
-import glob
-
 non_translated_sections = [] # Add the sections that are not translated here
 
 @lru_cache
 def get_missing_translation_content(docs_dir: str) -> str:
-    docs_dir_path = Path(docs_dir)
-    missing_translation_path = docs_dir_path.parent.parent / "missing-translation.md"
-    return missing_translation_path.read_text(encoding="utf-8")
+  docs_dir_path = Path(docs_dir)
+  missing_translation_path = docs_dir_path.parent.parent / "missing-translation.md"
+  return missing_translation_path.read_text(encoding="utf-8")
 
 
 class EnFile(File):
-    pass
+  pass
 
 
 def resolve_file(*, item: str, files: Files, config: MkDocsConfig) -> None:
-    item_path = Path(config.docs_dir) / item
-    if not item_path.is_file():
-        en_src_dir = (Path(config.docs_dir) / "../../en/docs").resolve()
-        potential_path = en_src_dir / item
-        if potential_path.is_file():
-            files.append(
-                EnFile(
-                    path=item,
-                    src_dir=str(en_src_dir),
-                    dest_dir=config.site_dir,
-                    use_directory_urls=config.use_directory_urls,
-                )
-            )
+  item_path = Path(config.docs_dir) / item
+  if not item_path.is_file():
+    en_src_dir = (Path(config.docs_dir) / "../../en/docs").resolve()
+    potential_path = en_src_dir / item
+    if potential_path.is_file():
+      files.append(
+        EnFile(
+          path=item,
+          src_dir=str(en_src_dir),
+          dest_dir=config.site_dir,
+          use_directory_urls=config.use_directory_urls,
+        )
+      )
 
 
 def resolve_files(*, items: List[Any], files: Files, config: MkDocsConfig) -> None:
-    for item in items:
-        if isinstance(item, str):
-            resolve_file(item=item, files=files, config=config)
-        elif isinstance(item, dict):
-            assert len(item) == 1
-            values = list(item.values())
-            if not values:
-                continue
-            if isinstance(values[0], str):
-                resolve_file(item=values[0], files=files, config=config)
-            elif isinstance(values[0], list):
-                resolve_files(items=values[0], files=files, config=config)
-            else:
-                raise ValueError(f"Unexpected value: {values}")
+  for item in items:
+    if isinstance(item, str):
+      resolve_file(item=item, files=files, config=config)
+    elif isinstance(item, dict):
+      assert len(item) == 1
+      values = list(item.values())
+      if not values:
+        continue
+      if isinstance(values[0], str):
+        resolve_file(item=values[0], files=files, config=config)
+      elif isinstance(values[0], list):
+        resolve_files(items=values[0], files=files, config=config)
+      else:
+        raise ValueError(f"Unexpected value: {values}")
 
 def get_images_relative_paths(docs_dir: str) -> List[str]:
-    en_docs_path = (Path(docs_dir) / "../../en/docs").resolve()
-    images = glob.glob(f"{en_docs_path}/images/**/*", recursive=True)
-    return list(map(lambda i: str(Path(i).relative_to(en_docs_path)), images))
+  en_docs_path = (Path(docs_dir) / "../../en/docs").resolve()
+  images = glob.glob(f"{en_docs_path}/images/**/*", recursive=True)
+  return list(map(lambda i: str(Path(i).relative_to(en_docs_path)), images))
 
 def on_files(files: Files, *, config: MkDocsConfig) -> Files:
 
-    # We circumvent the fact that the config.nav object is not available anymore
-    # due to the removal made by mkdocs-awesome-pages-plugin.
-    #
-    # So we read the config file again to get the nav object.
-    with open(config.config_file_path, 'rb') as f:
-        untouched_config = yaml_load(f)
-        resolve_files(items=untouched_config['nav'] or [], files=files, config=config)
+  # We circumvent the fact that the config.nav object is not available anymore
+  # due to the removal made by mkdocs-awesome-pages-plugin.
+  #
+  # So we read the config file again to get the nav object.
+  with open(config.config_file_path, 'rb') as f:
+    untouched_config = yaml_load(f)
+    resolve_files(items=untouched_config['nav'] or [], files=files, config=config)
 
-    images = get_images_relative_paths(config.docs_dir)
+  images = get_images_relative_paths(config.docs_dir)
 
-    resolve_files(items=images, files=files, config=config)
-    if "logo" in config.extra:
-        resolve_file(item=config.extra["logo"], files=files, config=config)
-    if "favicon" in config.theme:
-        resolve_file(item=config.theme["favicon"], files=files, config=config)
-    resolve_files(items=config.extra_css, files=files, config=config)
-    resolve_files(items=config.extra_javascript, files=files, config=config)
-    return files
+  resolve_files(items=images, files=files, config=config)
+  if "logo" in config.extra:
+    resolve_file(item=config.extra["logo"], files=files, config=config)
+  if "favicon" in config.theme:
+    resolve_file(item=config.theme["favicon"], files=files, config=config)
+  resolve_files(items=config.extra_css, files=files, config=config)
+  resolve_files(items=config.extra_javascript, files=files, config=config)
+  return files
 
 
 def generate_renamed_section_items(
-    items: List[Union[Page, Section, Link]], *, config: MkDocsConfig
+  items: List[Union[Page, Section, Link]], *, config: MkDocsConfig
 ) -> List[Union[Page, Section, Link]]:
-    new_items: List[Union[Page, Section, Link]] = []
-    for item in items:
-        if isinstance(item, Section):
-            new_title = item.title
-            new_children = generate_renamed_section_items(item.children, config=config)
-            first_child = new_children[0]
-            if isinstance(first_child, Page):
-                if first_child.file.src_path.endswith("index.md"):
-                    # Read the source so that the title is parsed and available
-                    first_child.read_source(config=config)
-                    new_title = first_child.title or new_title
-            # Creating a new section makes it render it collapsed by default
-            # no idea why, so, let's just modify the existing one
-            # new_section = Section(title=new_title, children=new_children)
-            item.title = new_title
-            item.children = new_children
-            new_items.append(item)
-        else:
-            new_items.append(item)
-    return new_items
+  new_items: List[Union[Page, Section, Link]] = []
+  for item in items:
+    if isinstance(item, Section):
+      new_title = item.title
+      new_children = generate_renamed_section_items(item.children, config=config)
+      first_child = new_children[0]
+      if isinstance(first_child, Page):
+        if first_child.file.src_path.endswith("index.md"):
+          # Read the source so that the title is parsed and available
+          first_child.read_source(config=config)
+          new_title = first_child.title or new_title
+      # Creating a new section makes it render it collapsed by default
+      # no idea why, so, let's just modify the existing one
+      # new_section = Section(title=new_title, children=new_children)
+      item.title = new_title
+      item.children = new_children
+      new_items.append(item)
+    else:
+      new_items.append(item)
+  return new_items
 
 
 def on_nav(
-    nav: Navigation, *, config: MkDocsConfig, files: Files, **kwargs: Any
+  nav: Navigation, *, config: MkDocsConfig, _: Files
 ) -> Navigation:
-    new_items = generate_renamed_section_items(nav.items, config=config)
-    return Navigation(items=new_items, pages=nav.pages)
-
-
-def on_pre_page(page: Page, *, config: MkDocsConfig, files: Files) -> Page:
-    return page
+  new_items = generate_renamed_section_items(nav.items, config=config)
+  return Navigation(items=new_items, pages=nav.pages)
 
 
 def on_page_markdown(
-    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+  markdown: str, *, page: Page, config: MkDocsConfig
 ) -> str:
-    if isinstance(page.file, EnFile):
-        for excluded_section in non_translated_sections:
-            if page.file.src_path.startswith(excluded_section):
-                return markdown
-        missing_translation_content = get_missing_translation_content(config.docs_dir)
-        header = ""
-        body = markdown
-        if markdown.startswith("#"):
-            header, _, body = markdown.partition("\n\n")
-        return f"{header}\n\n{missing_translation_content}\n\n{body}"
-    return markdown
+  if isinstance(page.file, EnFile):
+    for excluded_section in non_translated_sections:
+      if page.file.src_path.startswith(excluded_section):
+        return markdown
+    missing_translation_content = get_missing_translation_content(config.docs_dir)
+    header = ""
+    body = markdown
+    if markdown.startswith("#"):
+      header, _, body = markdown.partition("\n\n")
+    return f"{header}\n\n{missing_translation_content}\n\n{body}"
+  return markdown

From e8a57339b321441900a3cd069c939628beace133 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 18:19:29 +0100
Subject: [PATCH 20/30] Fix issues with scripts

---
 docs.py               | 7 ++++---
 mkdocs-utils/hooks.py | 4 ++--
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs.py b/docs.py
index 2b81ab6d4..cd6ad8160 100755
--- a/docs.py
+++ b/docs.py
@@ -27,12 +27,12 @@
 
 app = typer.Typer()
 
-alternate_langs_config_name = "mkdocs-alternate-langs.yml"
+mkdocs_config_name = "mkdocs.yml"
 
 docs_folder_name = "help"
 docs_path = Path("help")
 en_docs_path = Path("help/en")
-alternate_langs_config_path: Path = Path(alternate_langs_config_name)
+alternate_langs_config_path: Path = Path("mkdocs-alternate-langs.yml")
 site_path = Path("site").absolute()
 build_site_path = Path("site_build").absolute()
 
@@ -88,7 +88,7 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
     typer.echo(f"The language was already created: {lang}")
     raise typer.Abort()
   new_path.mkdir()
-  new_config_path: Path = Path(new_path) / alternate_langs_config_name
+  new_config_path: Path = Path(new_path) / mkdocs_config_name
   new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
   new_config_docs_path: Path = language_docs_dir(lang)
   new_config_docs_path.mkdir()
@@ -134,6 +134,7 @@ def build_lang(
   os.chdir(current_dir)
   typer.secho(f"Successfully built docs for: {lang}", color=typer.colors.GREEN)
 
+
 @app.command()
 def build_all() -> None:
   """
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index ba2eb372f..3da330663 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -112,14 +112,14 @@ def generate_renamed_section_items(
 
 
 def on_nav(
-  nav: Navigation, *, config: MkDocsConfig, _: Files
+  nav: Navigation, *, config: MkDocsConfig, **_: Any
 ) -> Navigation:
   new_items = generate_renamed_section_items(nav.items, config=config)
   return Navigation(items=new_items, pages=nav.pages)
 
 
 def on_page_markdown(
-  markdown: str, *, page: Page, config: MkDocsConfig
+  markdown: str, *, page: Page, config: MkDocsConfig, **_: Any
 ) -> str:
   if isinstance(page.file, EnFile):
     for excluded_section in non_translated_sections:

From fd47f5f86b5950d3804f5dc46e780c6b38bbc4f1 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Fri, 23 Feb 2024 18:44:26 +0100
Subject: [PATCH 21/30] Add empty "images/" folder when adding a language

---
 docs.py               | 7 +++++++
 mkdocs-utils/hooks.py | 1 +
 2 files changed, 8 insertions(+)

diff --git a/docs.py b/docs.py
index cd6ad8160..c0fd6864a 100755
--- a/docs.py
+++ b/docs.py
@@ -92,11 +92,18 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
   new_config_path.write_text(get_mkdocs_yaml_for_lang(lang), encoding="utf-8")
   new_config_docs_path: Path = language_docs_dir(lang)
   new_config_docs_path.mkdir()
+
   en_index_path: Path = language_docs_dir('en') / "index.md"
   new_index_path: Path = new_config_docs_path / "index.md"
   en_index_content = en_index_path.read_text(encoding="utf-8")
   new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"
   new_index_path.write_text(new_index_content, encoding="utf-8")
+
+  # Create the images directory
+  images_dir = new_config_docs_path / "images"
+  images_dir.mkdir()
+  (images_dir / ".gitkeep").touch()
+
   typer.secho(f"Successfully initialized: {new_path}", color=typer.colors.GREEN)
   update_languages()
 
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 3da330663..2588907a6 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -16,6 +16,7 @@
 
 non_translated_sections = [] # Add the sections that are not translated here
 
+
 @lru_cache
 def get_missing_translation_content(docs_dir: str) -> str:
   docs_dir_path = Path(docs_dir)

From 598a7da2d41677b832cdcd42dee5710364c647e7 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Mon, 26 Feb 2024 13:23:03 +0100
Subject: [PATCH 22/30] Remove on_nav hook (used in FastAPI to translate
 sections)

We'll find a way to translate sections later
---
 mkdocs-utils/hooks.py | 32 --------------------------------
 1 file changed, 32 deletions(-)

diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 2588907a6..5b6157c0f 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -87,38 +87,6 @@ def on_files(files: Files, *, config: MkDocsConfig) -> Files:
   return files
 
 
-def generate_renamed_section_items(
-  items: List[Union[Page, Section, Link]], *, config: MkDocsConfig
-) -> List[Union[Page, Section, Link]]:
-  new_items: List[Union[Page, Section, Link]] = []
-  for item in items:
-    if isinstance(item, Section):
-      new_title = item.title
-      new_children = generate_renamed_section_items(item.children, config=config)
-      first_child = new_children[0]
-      if isinstance(first_child, Page):
-        if first_child.file.src_path.endswith("index.md"):
-          # Read the source so that the title is parsed and available
-          first_child.read_source(config=config)
-          new_title = first_child.title or new_title
-      # Creating a new section makes it render it collapsed by default
-      # no idea why, so, let's just modify the existing one
-      # new_section = Section(title=new_title, children=new_children)
-      item.title = new_title
-      item.children = new_children
-      new_items.append(item)
-    else:
-      new_items.append(item)
-  return new_items
-
-
-def on_nav(
-  nav: Navigation, *, config: MkDocsConfig, **_: Any
-) -> Navigation:
-  new_items = generate_renamed_section_items(nav.items, config=config)
-  return Navigation(items=new_items, pages=nav.pages)
-
-
 def on_page_markdown(
   markdown: str, *, page: Page, config: MkDocsConfig, **_: Any
 ) -> str:

From 026f9d940c4c8dee48e19093ff873e3d6d227fc1 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Tue, 27 Feb 2024 11:34:59 +0100
Subject: [PATCH 23/30] Add language selectbox to switch languages

---
 docs.py                    |  2 +-
 mkdocs-alternate-langs.yml |  1 +
 overrides/base.html        |  2 +-
 overrides/js/base.js       | 14 +++++++++++++-
 overrides/topbar.html      |  5 +++++
 5 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs.py b/docs.py
index c0fd6864a..cf31f76f5 100755
--- a/docs.py
+++ b/docs.py
@@ -237,7 +237,7 @@ def get_updated_config_content() -> Dict[str, Any]:
       )
       raise typer.Abort()
     use_name = f"{code} - {local_language_names[code]}"
-    new_alternate.append({"link": url, "name": use_name})
+    new_alternate.append({"link": url, "name": use_name, "code": code})
   config["extra"]["alternate"] = new_alternate
   return config
 
diff --git a/mkdocs-alternate-langs.yml b/mkdocs-alternate-langs.yml
index 9015636c9..9d45d41ce 100644
--- a/mkdocs-alternate-langs.yml
+++ b/mkdocs-alternate-langs.yml
@@ -3,3 +3,4 @@ extra:
   alternate:
   - link: /
     name: en - English
+    code: en
diff --git a/overrides/base.html b/overrides/base.html
index d56e2a213..095adde09 100644
--- a/overrides/base.html
+++ b/overrides/base.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="{{config.theme.language}}">
 <head>
   {% set is_top = (page and page.is_homepage) and not force_plain_page %}
   {% set base_url = base_url or "." %}
diff --git a/overrides/js/base.js b/overrides/js/base.js
index f80fd1d98..045bbfada 100644
--- a/overrides/js/base.js
+++ b/overrides/js/base.js
@@ -129,6 +129,13 @@ function initMainWindow() {
 
   // Initialize search functionality.
   initSearch();
+
+  $('#wm-language-select').on('change', function() {
+    var currentLang = document.documentElement.lang || 'en';
+
+    var matchLangInPath = new RegExp('^/' + (currentLang === 'en' ? '' : currentLang + '/'));
+    location.pathname = location.pathname.replace(matchLangInPath, $(this).val());
+  });
 }
 
 // Other initialization of iframe contents.
@@ -158,7 +165,12 @@ function initSearch() {
   var searchResults = $('#mkdocs-search-results');
 
   // Fetch the prebuilt index data, and add to the index.
-  $.getJSON(getUrl('/search/search_index.json'))
+  var lang = document.documentElement.lang || 'en';
+  var searchPath = '/search/search_index.json';
+  if (lang !== 'en') {
+    searchPath = '/' + lang + searchPath;
+  }
+  $.getJSON(getUrl(searchPath))
   .done(function(data) {
     data.docs.forEach(function(doc) {
       searchIndex.addDoc(doc);
diff --git a/overrides/topbar.html b/overrides/topbar.html
index 8110ac911..72a458419 100644
--- a/overrides/topbar.html
+++ b/overrides/topbar.html
@@ -24,6 +24,11 @@
     <div class="wm-top-tool wm-vcenter pull-right wm-small-left wm-top-toc-button">
       <button id="wm-toc-button" type="button" class="btn btn-sm btn-default wm-vcentered"><i class="fa fa-th-list" aria-hidden="true"></i></button>
     </div>
+    <select id="wm-language-select" class="wm-top-tool wm-vcenter pull-right wm-small-left" name="lang">
+      {% for lang in config.extra.alternate %}
+      <option value="{{ lang.link }}" {% if lang.code == config.theme.language %}selected{% endif %}>{{ lang.name }}</option>
+      {% endfor %}
+    </select>
 
     {# Optional forward-back buttons #}
     {% if config.extra.history_buttons %}

From ae7072308612084b51a3b31920e7811b922c86f1 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Tue, 27 Feb 2024 11:41:26 +0100
Subject: [PATCH 24/30] Add explanation in README.md that a command initiates a
 virtual env

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index b551e953b..f554b405f 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ Conversation tab.
 ## Setting up local environment
 
 ``` sh
+# initiate a python virtual environment
 python3 -m venv env
 source ./env/bin/activate # for most shells, or source ./env/bin/activate.fish or source ./env/bin/activate.csh depending on your shell
 pip install -r requirements.txt

From 06b04dc5914496cab19b36403530d8bc2496441b Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Tue, 27 Feb 2024 12:13:15 +0100
Subject: [PATCH 25/30] Disable language selector when running live()

---
 docs.py               | 3 +--
 mkdocs-utils/hooks.py | 5 +++++
 overrides/js/base.js  | 9 +++++++++
 overrides/topbar.html | 6 +++++-
 4 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs.py b/docs.py
index cf31f76f5..7037d4f4e 100755
--- a/docs.py
+++ b/docs.py
@@ -209,6 +209,7 @@ def live(
     lang = "en"
   lang_path: Path = docs_path / lang
   os.chdir(lang_path)
+  os.environ["DISABLE_LANGUAGE_SELECTOR"] = "true"
   mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8000")
 
 
@@ -258,9 +259,7 @@ def verify_config() -> None:
   """
   typer.echo("Verifying mkdocs-alternate-lang.yml")
   config = get_alternate_langs_config()
-  print(config)
   updated_config = get_updated_config_content()
-  print(updated_config)
   if config != updated_config:
     typer.secho(
       f"./mkdocs-alternate-lang.yml outdated from {docs_folder_name}/language_names.yml, "
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 5b6157c0f..3bacc70f7 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -5,6 +5,7 @@
 
 import glob
 from functools import lru_cache
+import os
 from pathlib import Path
 from typing import Any, List, Union
 
@@ -86,6 +87,10 @@ def on_files(files: Files, *, config: MkDocsConfig) -> Files:
   resolve_files(items=config.extra_javascript, files=files, config=config)
   return files
 
+def on_config(config: MkDocsConfig) -> MkDocsConfig:
+  if os.environ.get("DISABLE_LANGUAGE_SELECTOR") == 'true':
+    config.theme["disable_language_selector"] = True
+  return config
 
 def on_page_markdown(
   markdown: str, *, page: Page, config: MkDocsConfig, **_: Any
diff --git a/overrides/js/base.js b/overrides/js/base.js
index 045bbfada..08914ad1e 100644
--- a/overrides/js/base.js
+++ b/overrides/js/base.js
@@ -131,6 +131,15 @@ function initMainWindow() {
   initSearch();
 
   $('#wm-language-select').on('change', function() {
+    // Hint the user if they're using in live mode (which doesn't support language switching).
+    // This should not happen in production, so an alert is fine.
+    if (this.dataset.unavailable) {
+      alert(
+        'The website is run using "./docs.py live [lang]", which is meant for a single language.\n\n'
+        + 'Please run it using "./docs.py build-all" and then "./docs.py serve" to test the language selector.'
+      );
+      return false;
+    }
     var currentLang = document.documentElement.lang || 'en';
 
     var matchLangInPath = new RegExp('^/' + (currentLang === 'en' ? '' : currentLang + '/'));
diff --git a/overrides/topbar.html b/overrides/topbar.html
index 72a458419..d09ad7744 100644
--- a/overrides/topbar.html
+++ b/overrides/topbar.html
@@ -24,7 +24,11 @@
     <div class="wm-top-tool wm-vcenter pull-right wm-small-left wm-top-toc-button">
       <button id="wm-toc-button" type="button" class="btn btn-sm btn-default wm-vcentered"><i class="fa fa-th-list" aria-hidden="true"></i></button>
     </div>
-    <select id="wm-language-select" class="wm-top-tool wm-vcenter pull-right wm-small-left" name="lang">
+    <select id="wm-language-select" class="wm-top-tool wm-vcenter pull-right wm-small-left" name="lang"
+      {% if config.theme.disable_language_selector %}
+        data-unavailable="true"
+      {% endif %}
+      >
       {% for lang in config.extra.alternate %}
       <option value="{{ lang.link }}" {% if lang.code == config.theme.language %}selected{% endif %}>{{ lang.name }}</option>
       {% endfor %}

From c05fb6db1b21cb38a82e996cf377222de10326b8 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Tue, 27 Feb 2024 13:21:16 +0100
Subject: [PATCH 26/30] language selector: eval DISABLE_LANGUAGE_SELECTOR
 directly in mkdocs.yml

---
 mkdocs-utils/hooks.py | 5 -----
 mkdocs.yml            | 2 ++
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 3bacc70f7..8df3219fd 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -87,11 +87,6 @@ def on_files(files: Files, *, config: MkDocsConfig) -> Files:
   resolve_files(items=config.extra_javascript, files=files, config=config)
   return files
 
-def on_config(config: MkDocsConfig) -> MkDocsConfig:
-  if os.environ.get("DISABLE_LANGUAGE_SELECTOR") == 'true':
-    config.theme["disable_language_selector"] = True
-  return config
-
 def on_page_markdown(
   markdown: str, *, page: Page, config: MkDocsConfig, **_: Any
 ) -> str:
diff --git a/mkdocs.yml b/mkdocs.yml
index 01015e973..c6fc183aa 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,6 +15,8 @@ docs_dir: './help/en/docs' # Add localization folder here for now, we'll handle
 theme:
   name: windmill
   custom_dir: overrides
+  # Disable the language selector when running in live (so for a specific language)
+  disable_language_selector: !ENV [DISABLE_LANGUAGE_SELECTOR, false]
 nav:
   - Welcome to Grist: index.md
   - FAQ: FAQ.md

From f98b7068e700085aafff798f35820f3f4c6bf14e Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Wed, 28 Feb 2024 15:30:40 +0100
Subject: [PATCH 27/30] Make MISSING-TRANSLATION translatable

---
 docs.py                             | 12 +++++++++---
 help/en/docs/MISSING-TRANSLATION.md |  3 +++
 help/missing-translation.md         |  4 ----
 mkdocs-utils/hooks.py               |  7 ++++---
 4 files changed, 16 insertions(+), 10 deletions(-)
 create mode 100644 help/en/docs/MISSING-TRANSLATION.md
 delete mode 100644 help/missing-translation.md

diff --git a/docs.py b/docs.py
index 7037d4f4e..cdbd14f3c 100755
--- a/docs.py
+++ b/docs.py
@@ -14,7 +14,7 @@
 from multiprocessing import Pool
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
-from textwrap import dedent
+from textwrap import dedent, indent
 
 import mkdocs.commands.build
 import mkdocs.commands.serve
@@ -42,8 +42,9 @@ def language_docs_dir(lang: str) -> Path:
 
 
 def get_missing_translation_snippet() -> str:
-  missing_translation_file_path = (Path(__file__).parent / "help/missing-translation.md")
-  return missing_translation_file_path.read_text(encoding="utf-8")
+  missing_translation_file_path = (Path(__file__).parent / "help/en/docs/MISSING-TRANSLATION.md")
+  missing_translation_content = missing_translation_file_path.read_text(encoding="utf-8")
+  return "!!!warning\n\n" + indent(missing_translation_content, "    ")
 
 
 def get_mkdocs_yaml_for_lang(lang: str) -> str:
@@ -99,6 +100,11 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
   new_index_content = f"{get_missing_translation_snippet()}\n\n{en_index_content}"
   new_index_path.write_text(new_index_content, encoding="utf-8")
 
+  # Copy the MISSING-TRANSLATION.md file, which can be localized later
+  en_missing_translation_path: Path = language_docs_dir('en') / "MISSING-TRANSLATION.md"
+  new_missing_translation_path: Path = new_config_docs_path / "MISSING-TRANSLATION.md"
+  new_missing_translation_path.write_bytes(en_missing_translation_path.read_bytes())
+
   # Create the images directory
   images_dir = new_config_docs_path / "images"
   images_dir.mkdir()
diff --git a/help/en/docs/MISSING-TRANSLATION.md b/help/en/docs/MISSING-TRANSLATION.md
new file mode 100644
index 000000000..c69a3b193
--- /dev/null
+++ b/help/en/docs/MISSING-TRANSLATION.md
@@ -0,0 +1,3 @@
+The current page still doesn't have a translation for this language.
+
+But you can help translating it: [Contributing](https://hosted.weblate.org/engage/grist-help/){.internal-link target=_blank}.
diff --git a/help/missing-translation.md b/help/missing-translation.md
deleted file mode 100644
index 674db4480..000000000
--- a/help/missing-translation.md
+++ /dev/null
@@ -1,4 +0,0 @@
-!!! warning
-    The current page still doesn't have a translation for this language.
-
-    But you can help translating it: [Contributing](https://hosted.weblate.org/engage/grist-help/){.internal-link target=_blank}.
diff --git a/mkdocs-utils/hooks.py b/mkdocs-utils/hooks.py
index 8df3219fd..689fc22eb 100644
--- a/mkdocs-utils/hooks.py
+++ b/mkdocs-utils/hooks.py
@@ -7,6 +7,7 @@
 from functools import lru_cache
 import os
 from pathlib import Path
+from textwrap import indent
 from typing import Any, List, Union
 
 from mkdocs.config.defaults import MkDocsConfig
@@ -20,9 +21,9 @@
 
 @lru_cache
 def get_missing_translation_content(docs_dir: str) -> str:
-  docs_dir_path = Path(docs_dir)
-  missing_translation_path = docs_dir_path.parent.parent / "missing-translation.md"
-  return missing_translation_path.read_text(encoding="utf-8")
+  missing_translation_file_path = Path(docs_dir) / "MISSING-TRANSLATION.md"
+  missing_translation_content = missing_translation_file_path.read_text(encoding="utf-8")
+  return "!!!warning\n\n" + indent(missing_translation_content, "    ")
 
 
 class EnFile(File):

From 00341d1d04a2976f3bcffebe761670ad1e6db7f9 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Wed, 28 Feb 2024 15:30:58 +0100
Subject: [PATCH 28/30] Fix language selector backgroud color

---
 overrides/css/base.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/overrides/css/base.css b/overrides/css/base.css
index 5b8ef3dee..fae79e2a0 100644
--- a/overrides/css/base.css
+++ b/overrides/css/base.css
@@ -106,6 +106,14 @@ html {
   margin-left: 0.5rem;
 }
 
+#wm-language-select {
+  border: none;
+}
+
+#wm-language-select, #wm-language-select option {
+  background-color: var(--color-dark);
+}
+
 /***********************************************************************
  Table of contents (side pane)
  ***********************************************************************/

From 10aa15b1be729677ee18e6e90b8e17d3cf5aacff Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Wed, 28 Feb 2024 16:19:14 +0100
Subject: [PATCH 29/30] Specify in README that `./docs.py serve` requires
 `build-all` first

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f554b405f..18848ee9c 100644
--- a/README.md
+++ b/README.md
@@ -46,9 +46,11 @@ Total wall clock time: 1.3s
 Downloaded: 36 files, 2.0M in 0.009s (226 MB/s)
 ```
 
-In order to build the website with all the languages, run:
+In order to build the website with all the languages, run both `build-all`
+(so it builds the website) and then `serve` for preview:
 ```sh
 source ./env/bin/activate
+./docs.py build-all
 ./docs.py serve
 ```
 

From 4d7814ac689e188e43ce2095eb1c015ec2e6b395 Mon Sep 17 00:00:00 2001
From: fflorent <florent.fayolle@beta.gouv.fr>
Date: Wed, 28 Feb 2024 16:44:48 +0100
Subject: [PATCH 30/30] Hide the language selector for now

---
 overrides/css/base.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/overrides/css/base.css b/overrides/css/base.css
index fae79e2a0..e732baca7 100644
--- a/overrides/css/base.css
+++ b/overrides/css/base.css
@@ -108,6 +108,7 @@ html {
 
 #wm-language-select {
   border: none;
+  display: none; /* Hide it for now :) */
 }
 
 #wm-language-select, #wm-language-select option {