{"docs": [{"location": "/reference/directory-structure/", "title": "Directory structure", "text": "Directory structure Grow sites are encapsulated into directories that follow a specific structure. These directories are called \"pods\". Grow uses the configuration files and the structure of files in each pod to declaratively build your site. Pods contain source files, but for deployment, Grow builds only what's needed to serve your site. Sources and other \"internal\" files are never built to the output directory. Example structure Items marked with * are inbuilt, and their names cannot change. Other items aren't required by Grow, but are often found by convention. \u251c\u2500\u2500 /build # Default location for builds. \u251c\u2500\u2500 /content* # All your content. | \u251c\u2500\u2500 /pages # A content collection. | \u251c\u2500\u2500 /_blueprint.yaml* # A blueprint. | \u251c\u2500\u2500 /about.md # A content document. | \u251c\u2500\u2500 /contact.md | \u2514\u2500\u2500 /index.md | \u2514\u2500\u2500 /posts | \u251c\u2500\u2500 /_blueprint.yaml* | \u251c\u2500\u2500 /my-first-post.md | \u2514\u2500\u2500 /hello-grow.md \u251c\u2500\u2500 /dist # Compiled files like minified js and css. | \u251c\u2500\u2500 /css # Used for static serving of minified files. | \u2514\u2500\u2500 /composite | \u251c\u2500\u2500 global.min.css | \u2514\u2500\u2500 main.min.css | \u2514\u2500\u2500 /js | \u2514\u2500\u2500 /composite | \u251c\u2500\u2500 global.min.js | \u2514\u2500\u2500 main.min.js \u251c\u2500\u2500 /source # Frontend source files. | \u251c\u2500\u2500 /js | \u2514\u2500\u2500 /composite | \u251c\u2500\u2500 /global.js | \u2514\u2500\u2500 /main.js | \u251c\u2500\u2500 /sass | \u2514\u2500\u2500 /composite | \u251c\u2500\u2500 /global.sass | \u2514\u2500\u2500 /main.sass | \u2514\u2500\u2500 /static # Static files. | \u2514\u2500\u2500 /images | \u2514\u2500\u2500 /favicon.png \u251c\u2500\u2500 /translations* # All your translation data. | \u251c\u2500\u2500 /messages.pot # Message catalog template. | \u2514\u2500\u2500 /de | \u2514\u2500\u2500 /messages.po # A message catalog. | \u2514\u2500\u2500 /fr | \u2514\u2500\u2500 /messages.po | \u2514\u2500\u2500 /it | \u2514\u2500\u2500 /messages.po \u251c\u2500\u2500 /views* # Jinja templates. \u251c\u2500\u2500 /partials* # Partial templates. | \u2514\u2500\u2500 /hero | \u251c\u2500\u2500 /hero.html | \u251c\u2500\u2500 /hero.js | \u2514\u2500\u2500 /hero.sass | \u2514\u2500\u2500 /base.html # Base template for rendering partials. | \u2514\u2500\u2500 /pages.html | \u2514\u2500\u2500 /posts.html \u251c\u2500\u2500 /package.json # JS dependencies. \u2514\u2500\u2500 /podspec.yaml* # Pod specification."}, {"location": "/reference/podspec/", "title": "Podspec", "text": "Podspec (podspec.yaml) Every Grow pod has a root podspec.yaml file that declares site-wide settings: locales, static asset directories, Markdown extensions, sitemaps, preprocessors, and deployments. Complete example # podspec.yaml grow_version: \">=2.0.0\" title@: My Site description@: A fast, localized static site. home: /content/pages/index.md root: \"/\" meta: site_author: Example Team static_dirs: - static_dir: /static/ serve_at: /static/ fingerprinted: true localization: default_locale: en locales: - en - fr - de aliases: en_uk: en_GB require_translations: false require_translations@env.prod: true markdown: extensions: - kind: markdown.extensions.codehilite theme: github-dark sitemap: enabled: true path: /sitemap.xml deployments: prod: destination: local out_dir: ./build/ env: name: prod host: example.com port: 443 scheme: https Core fields Field Description grow_version Optional semver constraint checked by Grow (e.g. \">=2.0.0\"). title / description Site-wide title and description, exposed as podspec.title / podspec.description. home Pod path to the homepage document (accessible as podspec.home). root URL root prefix for all routes (defaults to \"/\"). meta Arbitrary site-wide key/value metadata exposed as podspec.meta. static_dirs Maps directories in your pod to serving URL prefixes. static_dirs: # Serve /static/ files at /static/ with content-hash fingerprints. - static_dir: /static/ serve_at: /static/ fingerprinted: true # Serve /public/ files at the site root (e.g. robots.txt, favicon.ico). - static_dir: /public/ serve_at: / Fingerprinting When fingerprinted: true is enabled, /static/css/main.css is served as /static/css/main-.css for immutable browser caching. Reference fingerprinted files in templates with {{ g.static('/static/css/main.css').url.path }}. Path filtering (filter) By default, Grow ignores dotfiles (files starting with .). Override this globally or per static_dirs entry using regex patterns: filter: ignore_paths: - \\.DS_Store$ include_paths: - \\.well-known/ localization Configures site-wide locales, aliases, translation enforcement, and locale groups. localization: default_locale: en locales: - en - fr - de aliases: en_uk: en_GB import_as: en_uk: - en_GB require_translations: false require_translations@env.prod: true groups: europe: - de - fr default_locale: Fallback locale when none is specified on a document or collection. locales: List of locale identifiers generated for the site. aliases: Maps URL/server locale slugs to Grow locale identifiers. import_as: Maps external translation-provider locale codes to internal Grow locales during grow translations import. require_translations: Fails builds if untranslated strings remain (can be scoped per environment with @env.). groups: Named locale groups usable in YAML front matter (e.g. headline@locale.europe: ...). markdown Configures Python-Markdown extensions and syntax highlighting themes (via Pygments): markdown: extensions: - kind: markdown.extensions.codehilite theme: github-dark classes: false - kind: toc permalink: false Set classes: true to emit CSS classes instead of inline Pygments styles. sitemap Automatically generates a sitemap.xml covering your site's localized routes: sitemap: enabled: true path: /{root}/sitemap.xml collections: - pages locales: - en - fr preprocessors and extensions Configure preprocessors and Python extensions loaded by your pod: preprocessors: - kind: google_sheets name: strings autorun: false id: path: /content/data/strings.yaml extensions: jinja2: - ext.my_filters.MyFiltersExtension deployments Defines named targets for grow deploy and per-environment {{ env }} values. See Deployment for full details. deployments: prod: destination: local out_dir: ./build/ env: name: prod host: example.com port: 443 scheme: https footnotes Customizes footnote symbols and numeric-footnote locale rules used by doc.footnotes: footnotes: numeric_locales_pattern: (US|CA)$ use_numeric_symbols: false symbols: - \"*\" - \"\u2020\" - \"\u2021\" - \"\u00a7\""}, {"location": "/reference/templates/", "title": "Templates", "text": "Templates Grow renders pages using Jinja2 templates stored in your pod's /views/ directory. Grow injects document context variables, a g helper namespace, and built-in localization and formatting filters into every template. Template globals These variables are available in every template without a prefix. Avoid shadowing them with {% set %}. Variable Type Description doc Document The current document being rendered. See Documents. env Env Active build/deployment environment (name, host, port, scheme, fingerprint). podspec PodSpec Parsed contents of podspec.yaml. _(text) Function Alias for gettext() \u2014 marks a string for extraction and translates it for doc.locale. gettext(text, **vars) Function Translates a string using the active locale's .po catalog. ngettext(singular, plural, n, **vars) Function Translates a pluralized string based on n. doc

{{ doc.title }}

{{ doc.category }}

{{ doc.html | safe }}
{# Access custom YAML front matter and collection blueprint fields #}

{{ doc.author }}

{{ doc.collection.section_title }}

env {# Target behavior by environment name (e.g. dev, staging, prod) #} {% if env.name == 'prod' %} {% endif %} podspec {{ doc.title }} \u2014 {{ podspec.title }} _(), gettext(), and ngettext() {# Simple translated string #}

{{ _('Welcome') }}

{# Named placeholders #}

{{ _('Hello, %(name)s', name=doc.author) }}

{# Singular / plural forms #}

{{ ngettext('%(num)d article', '%(num)d articles', posts | length, num=posts | length) }}

Helper functions (g.*) All Grow template helpers live under the g namespace so they never collide with your front matter variables. Function Returns Description g.doc(path, locale=None) Document Fetches a single document by pod path. g.docs(collection, ...) list[Document] Queries documents in a collection with optional sorting/filtering. g.categories(collection, ...) list[(str, list[Document])] Groups documents in a collection by $category. g.collection(path) Collection Returns a single collection object. g.collections(paths=None) list[Collection] Lists all (or specified) collections in the pod. g.static(path, locale=None) StaticFile Resolves a static asset with fingerprinting and build-time existence checks. g.statics(dir_path, locale=None) list[StaticFile] Lists all static files inside a directory. g.url(path, locale=None) Url Returns the resolved Url object for a document pod path. g.yaml(path) dict | list Loads a YAML file (with translation tagging and ?key.subkey lookup). g.json(path) dict | list Loads a JSON file by pod path. g.csv(path, locale=None) list[dict] Parses a CSV file into a list of row dicts. g.date(value, from=...) datetime Parses a date string using Python strptime directives. g.locale(code) Locale Returns a Babel Locale object for a locale code. g.locales(codes) list[Locale] Returns a list of Babel Locale objects. g.doc and g.docs {# Fetch a specific document (optionally in another locale) #} {% set home = g.doc('/content/pages/index.md') %} {% set home_fr = g.doc('/content/pages/index.md', locale='fr') %} {# List documents in a collection sorted by multiple fields #}
    {% for post in g.docs('blog', order_by=('dates.published', 'title'), reverse=True) %}
  • {{ post.title }}
  • {% endfor %}
g.categories Groups documents in a collection by their $category front matter field: {% for category, items in g.categories('docs') %}

{{ category }}

{% endfor %} g.collection and g.collections {% set pages = g.collection('pages') %} {% for col in g.collections(['docs', 'blog']) %}

{{ col.title }}

{% endfor %} g.static and g.statics Always reference static assets with g.static() rather than hardcoding URLs. Grow rewrites fingerprinted filenames automatically and fails the build if a referenced asset is missing. Requires a matching entry in static_dirs in podspec.yaml. \"\" {# List every image in a static directory #} {% for asset in g.statics('/static/gallery/') %} \"\" {% endfor %} g.url Returns the Url object for a document without loading its body: About g.yaml, g.json, and g.csv Load structured data files directly inside templates: {% set nav = g.yaml('/content/data/nav.yaml') %} {% set config = g.json('/content/data/config.json') %} {% set team = g.csv('/content/data/team.csv') %}
    {% for member in team %}
  • {{ member.name }} \u2014 {{ member.role }}
  • {% endfor %}
g.date Parses a string into a Python datetime using Python strptime directives: {% set release = g.date('2026-11-21', from='%Y-%m-%d') %} g.locale and g.locales Convert locale codes into Babel Locale objects: {% set current = g.locale('fr_CA') %} {{ current.display_name }} {% for loc in g.locales(['en', 'fr', 'ja']) %} {{ loc.get_display_name(loc) }} {% endfor %} Built-in filters Grow includes 17 built-in Jinja2 filters for formatting, localization, URLs, and template rendering. Filter Example Description currency {{ 123.45 | currency('USD') }} Localized currency formatting via Babel. date {{ dt | date(format='medium') }} Localized date formatting via Babel. datetime {{ dt | datetime(format='short') }} Localized datetime formatting via Babel. time {{ dt | time(format='short') }} Localized time formatting via Babel. decimal {{ 1234.56 | decimal }} Localized decimal formatting via Babel. number {{ 12345 | number }} Localized integer/number formatting via Babel. percent {{ 0.25 | percent }} Localized percentage formatting via Babel. deeptrans {{ data | deeptrans }} Recursively translates all strings in a dict or list via gettext. expand_partial {{ 'hero' | expand_partial }} Resolves a partial name to its template path (e.g. /partials/hero/hero.html). hash {{ value | hash('sha256') }} Hashes a string (sha / sha1, md5, sha256, sha512). jsonify {{ obj | jsonify }} Serializes a Python object to JSON. markdown {{ text | markdown | safe }} Renders a Markdown string to HTML. relative {{ target.url.path | relative }} Converts an absolute path to a path relative to the current doc.url.path. re_replace {{ text | re_replace('\\s+', '-') }} Replaces regex matches in a string. render {{ doc.html | render | safe }} Evaluates Jinja2 syntax inside a string using the current template context. shuffle {{ items | shuffle }} Returns a randomly shuffled copy of a list. slug {{ 'Hello World!' | slug }} Converts text to a URL-friendly slug (hello-world). Formatting & localization examples {{ 1234.50 | currency('EUR', locale='de_DE') }} {{ doc.date | date(format='long', locale='ja_JP') }} {{ 0.875 | percent }} Markdown, rendering, and data examples {# Render a Markdown field from YAML front matter #} {{ doc.summary | markdown | safe }} {# Evaluate Jinja expressions inside document HTML #} {{ doc.html | render | safe }} {# Embed structured data safely for client-side scripts #} {# Compute a relative link from the current page #} About"}, {"location": "/reference/collections/", "title": "Collections", "text": "Collections All content in Grow is stored as flat files in your pod's /content/ directory. Content is grouped into collections, and each collection contains a single blueprint and many documents. Blueprints describe the structure of all documents in the collection. Grow makes it easy to separate content from presentation, but ultimately leaves the choice up to you. Content documents can be associated with URLs and with views (so they represent pages in your site), or not. Content documents without URLs are simply used internally, and can be referenced by other content documents. Blueprints Every content collection must have a blueprint. Blueprints define how content is structured, displayed, and served. Blueprints are stored as YAML files in your pod's content directory. For example, a blueprint for a collection \"people\" would be /content/people/_blueprint.yaml path: /people/{slug}/ # The URL path format for content. view: /views/people.html # The template to use. localization: # Overrides localization from podspec.yaml. path: /{locale}/people/{slug}/ locales: - de - fr - it path Specifies the URL path format for all content in this collection. Documents inherit the path specified in the blueprint. If path is omitted, content in this collection will not be generated into pages, unless a document specifies its own $path. If path is specified, view is a required field. See a list of path formatters. $path: /{root}/{base}/ view Specifies which template should be used to render content in this collection. If view is specified, path is a required field. # Documents in this collection will use the following template. $view: /views/pages.html localization Localization configuration for content in this collection. path Specifies a URL path format for localized content. By specifying both path and localization:path, you can use different formats for the URL paths for \"root\" and localized content. $localization: path: /{locale}/people/{slug}/ locales Specifies a list of locales that documents in this collection are available in. Each document's path will be expanded using locales to derive the URLs that the document is available at. $localization: locales: - de - fr - it categories The categories key contains a list of categories that documents inside the collection can fall into. A collection's categories can be used in conjunction with the g.categories template function to iterate over the documents in the collection, grouped by category."}, {"location": "/reference/documents/", "title": "Documents", "text": "Documents All content in Grow lives in documents inside /content//. Every file in a collection directory (other than _blueprint.yaml) is treated as a document. Documents with a resolved $path and $view (either set directly or inherited from _blueprint.yaml) are rendered as pages. Documents without a $path act as reusable data or partial documents. Supported file formats Extension Format Front matter doc.html / doc.body .md, .markdown, .mdown, .mkd Markdown Optional (--- delimited) Rendered HTML / raw Markdown .yaml, .yml YAML Whole file is front matter None .html, .htm HTML Optional (--- delimited) Raw HTML source Markdown document \u200b--- $title: Hello, Grow $category: Guides author: Ada Lovelace \u200b--- # Welcome Write standard **Markdown** in the body and access metadata via `{{ doc.author }}`. YAML document # /content/pages/home.yaml $title: Home $view: /views/home.html $path: / hero: heading@: Build fast static sites cta_url: !g.url /content/pages/about.md HTML document \u200b--- $title: Custom landing page $view: /views/base.html items: - One - Two \u200b---
    {% for item in doc.items %}
  • {{ item }}
  • {% endfor %}
In your base view, evaluate Jinja inside an HTML document's body using {{ doc.html | render | safe }}. YAML constructors Use custom YAML tags in front matter or data files to reference other pod files, URLs, static assets, and translatable strings: Constructor Example Description !_ !_ Hello world Marks an inline string value for translation. !g.doc !g.doc /content/pages/about.md Loads another Document object. !g.url !g.url /content/pages/about.md Resolves to a document's Url object. !g.static !g.static /static/images/logo.svg Resolves to a StaticFile object. !g.yaml !g.yaml /content/data/nav.yaml Loads a YAML file (supports ?key.subkey). !g.json !g.json /content/data/config.json Loads a JSON file (supports ?key.subkey). !g.csv !g.csv /content/data/team.csv Loads a CSV file as a list of dicts. !g.string !g.string products.categories.art References a key in /content/strings/.yaml. Deep key lookups Append ?key.sub_key to !g.yaml or !g.json to extract a nested value: nav_items: !g.yaml /content/data/site.yaml?navigation.primary api_url: !g.json /content/data/config.json?endpoints.public String references (!g.string) Store shared strings in /content/strings/.yaml and reference them as ..: # /content/strings/products.yaml categories: art@: Art tech@: Technology # /content/pages/art.yaml category_label: !g.string products.categories.art Document API (properties & methods) Every document exposes built-in properties and helper methods inside templates. Properties Property Type Description doc.title str Canonical title from $title. doc.url Url Resolved URL (url.path, url.host, url.scheme, url.port). doc.html str | None Rendered HTML (for .md) or raw HTML (for .html). Pipe to | safe. doc.body str | None Unprocessed body text after front matter. doc.fields dict All parsed front matter fields. doc.pod_path str Full path in the pod (e.g. /content/pages/about.md). doc.base str Filename without extension (e.g. about). doc.slug str Slug from $slug or slugified $title. doc.collection Collection Parent Collection object. doc.collection_base str Subdirectory relative to the collection (e.g. / or /sub/). doc.collection_path str File path relative to the collection (e.g. /sub/about.md). doc.category str | None Category from $category. doc.date datetime | None Date from $date. doc.order int | float | None Sort order from $order. doc.hidden bool Whether $hidden: true is set. doc.parent Document | None Parent document from $parent. doc.view str | None Template pod path from $view or blueprint. doc.path_format str | None URL path format; falsy if the document does not generate a route. doc.exists bool Whether the underlying file exists in the pod. doc.locale Locale Current Babel Locale (e.g. doc.locale.is_rtl, doc.locale.get_display_name('en')). doc.locales list[Locale] All locales this document is available in. doc.default_locale Locale Document's default fallback locale. doc.hreflang str BCP-47 language tag suitable for . doc.footnotes Footnotes Footnote manager for registering and rendering page footnotes. doc.sitemap dict Sitemap metadata from $sitemap. Methods doc.titles(name=None) Returns a context-specific title from $titles, falling back to $title: $title: Getting Started with Grow $titles: nav: Get started breadcrumb: Start {{ doc.titles('nav') }} {# Get started #} {{ doc.titles('breadcrumb') }} {# Start #} {{ doc.titles('unknown') }} {# Getting Started with Grow #} {{ doc.title }} {# Getting Started with Grow #} doc.dates(name=None) Returns a named date from $dates: $dates: created: 2026-01-15 published: 2026-11-21 {{ doc.dates('published') | date(format='long') }} doc.localize(locale) Returns the same document localized to a different locale (useful for language switchers and hreflang tags): {% for loc in doc.locales %} {% set alt = doc.localize(loc) %} {% endfor %} doc.prev(docs=None) and doc.next(docs=None) Returns the previous or next document in the collection's default order (or within an explicit list of documents), or None at the ends: {% set prev_doc = doc.prev() %} {% set next_doc = doc.next() %} {% if prev_doc %} {{ prev_doc.title }} {% endif %} {% if next_doc %} {{ next_doc.title }} {% endif %} Checking whether a document builds a URL Before linking to arbitrary documents in a collection, check item.path_format to skip non-routed partial/data documents: {% for item in g.docs('pages') if item.path_format %} {{ item.title }} {% endfor %} Working with doc.locale {# Language name in its own language and in English #} {{ doc.locale.get_display_name(doc.locale) }} {{ doc.locale.get_display_name('en') }} Working with doc.footnotes {# Register a footnote inline #} {% set symbol = doc.footnotes.add('See the podspec reference for details.') %} Important note{{ symbol }} {# Render collected footnotes at the bottom of the page #} {% for symbol, text in doc.footnotes %}

{{ symbol }} {{ _(text) }}

{% endfor %} Built-in front matter fields ($*) Fields prefixed with $ control Grow's built-in behavior. Omit the $ when reading them in templates (for example, $title is read as doc.title). Field Example Description $title $title: About us Canonical document title. $titles $titles: { nav: About } Named alternate titles accessed via doc.titles('nav'). $path $path: /about/ Overrides the collection blueprint's serving URL path (use ~ to disable routing). $view $view: /views/page.html Overrides the Jinja2 template used to render the document. $category $category: Guides Groups documents for g.categories(). $order $order: 2.5 Numeric sort order (supports negative and decimal values). $date $date: 2026-11-21 Primary document date. $dates $dates: { updated: 2026-11-21 } Named dates accessed via doc.dates('updated'). $slug $slug: custom-slug Overrides the auto-generated slug. $hidden $hidden: true Omits the document from g.docs() results while still rendering its route. $parent $parent: /content/pages/index.md Declares a parent document for hierarchical navigation. $localization $localization: { locales: [en, fr] } Overrides collection-level localization paths or locales for this document. $sitemap $sitemap: { enabled: false } Controls inclusion in generated sitemap.xml."}, {"location": "/reference/urls/", "title": "Routes and URLs", "text": "Routes and URLs Grow provides a flexible way to configure the URL serving paths for your site's routes. By leveraging the URL path configuration features, you can easily create clean, maintainable, and flexible URLs for all routes in your site. Philosophy Serving paths and filesystem paths do not need to match one-to-one. This is an explicit capability that exists to remove the need to name internal files a specific way. Because internal file paths do not need to match serving paths, you can change the URL of content at any time without renaming files or performing find and replace operations throughout your site. Configuring URLs There are three places URLs are specified. Your site's routing map is generated by analyzing and combining the rules set in all three locations. podspec.yaml blueprints content documents Content document path formatters Use these formatters to configure serving paths for documents either in a content document or its blueprint. Setting path in both a collection's blueprint and in a content document is optional. You should only define a path in a content document if you need to override a content document's path from the one specified in its blueprint. Remember: don't repeat yourself. If you can specify a path format in a collection's blueprint that generates the right path for all of its documents, then there is no need to also specify $path for each document. Only specify $path in a document for paths you need to override. Path formatter Description {base} The document's basename. Ex: my-page.yaml -> my-page {collection.root} The document's collection's root. {collection.basename} The document's collection's base name. Ex: /content/pages/my-page.yaml -> /pages {collection.sub_path} The document's collection sub directory path. Ex: /content/pages/sub/my-page.yaml -> /sub/ {env.fingerprint} A fingerprint assigned to the build environment. By default this is a timestamp. You can optionally override it by specifying env: fingerprint: in a deployment configuration. {date} The document's date. {locale} The document's locale (or its alias, if one exists). {root} The pod's root as defined in podspec.yaml. {slug} A url slug of the document's title. Examples # In a collection's _blueprint.yaml $path: /pages/{slug}/ $path: /pages/{base}/ $path: /{root}/pages/{base}/ $localization: path: /{locale}/pages/{slug}/ # In document.yaml (only specify document-level paths if you need to override the format set in the blueprint) $path: /pages/home/ $localization: path: /{locale}/pages/home/ Static file path formatters Use these formatters to configure serving paths for static files in podspec.yaml. Path formatter Description {env.fingerprint} A fingerprint assigned to the build environment. By default this is a timestamp. You can optionally override it by specifying env: fingerprint: in a deployment configuration. {fingerprint} A fingerprint uniquely identifying a static file. The fingerprint is a hash of the corresponding static file's contents. Can be used for cache-busting on a per-file basis. {locale} The static file's locale (or its alias, if one exists). {root} The pod's root as defined in podspec.yaml. Examples # In podspec.yaml static_dirs: - static_dir: /source/images/ serve_at: /static/images/ localization: static_dir: /source/{locale}/images/ serve_at: /{locale}/static/images/ Specifying a site root You can specify the site root in podspec.yaml and then reference the root in path formats elsewhere. This provides flexibility should you need to change the site root later, and allows you to avoid repeating the site root throughout multiple configurations. # In podspec.yaml root: /my-site/ # In a collection's _blueprint.yaml path: /{root}/pages/{base}/ Specifying the homepage Most sites have homepages. You can specify your site's homepage in podspec.yaml, which improves automation by providing you with a clickable link to your homepage when the development server starts up. Notifications may also contain links to your homepage, so it's always a good idea to set this. Note that the value of the homepage should point to a content document, not a URL path. Your homepage's URL will be derived from the content document's URL. # In podspec.yaml home: /content/pages/home.yaml URLs in templates Because you are provided with the freedom to change a serving path at any time, whenever you need to reference a URL in a template (such as in a element for a stylesheet or for a link), you should always programmatically generate those URLs using a built-in template function. In general, you should never refer to a linkable resource by its URL: you should refer to it by its internal pod path and leverage either g.doc or g.static to programmatically generate its URL. This technique provides you with flexibility to change URLs later without finding and replacing URLs in your site's code. Plus, it helps avoid broken links. URL object Documents and static files both have url properties that return their corresponding Url object. # The serving path for a content document. {{g.doc('/content/pages/home.yaml').url.path}} # The serving path for a static file. {{g.static('/source/images/image.png').url.path}} {{doc.url}} # The full URL to the document (based on the environment). {{doc.url.path}} # The serving path to the document. {{doc.url.host}} {{doc.url.scheme}} {{doc.url.port}} Relative URLs All URLs generated from a Url object are absolute. However, if you'd like to generate relative URLs, you can use the relative template filter. The final URL generated is relative to the current document context. {{g.doc('/content/pages/home.yaml').url|relative}} Checking routes Use the grow inspect routes command to quickly audit all of the routes that your site generates. You can use this command to avoid building the site and inspecting the generated fileset or saving and refreshing to check paths in the browser. Grow validates your URL path configuration and raises errors upon misconfiguration. For example, Grow will raise an error if you generate the same serving path for two different resources \u2013 no two resources may share the same serving path. Sitemap Grow can autogenerate a sitemap.xml file for your site, upon build. You can enable sitemap generation in podspec.yaml and, optionally, customize which pages and locales are included in the sitemap. # podspec.yaml sitemap: enabled: yes path: \"/{root}/sitemap.xml\" # Optional. collections: # Optional. - pages locales: # Optional. - en - fr"}, {"location": "/reference/content-localization/", "title": "Content localization", "text": "Content localization In addition to controlling site-wide localization in podspec.yaml, you can create and manage fully localized content at the collection-level or the document-level. Front matter localization You can localize front matter data on a per-locale basis. If you've localized some fields, but not all fields that are specified in the blueprint or default locale, the localized fields will fall back to default locale's fields, cascading from a localized version down to the default version. title@: Title title@fr: Title in FR body@: Body body@fr: Body for FR caption@: Caption # Default {{doc.title}} -> Title {{doc.body}} -> Body {{doc.caption}} -> Caption # FR {{doc.title}} -> Title in FR {{doc.body}} -> Body for FR {{doc.caption}} -> Caption File based localization Similar to the idea of using the @locale localization in the front matter, file names can also be used to manage the localization. The file naming should follow the CLDR codes for locales (case sensitive to support all file systems). For example, files should be named page@en_GB.yaml instead of page@en_gb.yaml. # Content /content/pages/presentation.yaml title@: Title body@: Body caption@: Caption # Content /content/pages/presentation@fr.yaml title: Title in FR body: Body for FR # Default {{doc.title}} -> Title {{doc.body}} -> Body {{doc.caption}} -> Caption # FR {{doc.title}} -> Title in FR {{doc.body}} -> Body for FR {{doc.caption}} -> Caption Locale class Grow's Locale objects subclass the Babel project's Locale class, providing access to some useful data. Grow validates locales and only accepts locales from the Common Locale Data Repository (CLDR), which uses ICU. A full list of compatible locales can be found here. # Page /de/hello/ {{doc.locale.get_language_name('en')}} # German. {{doc.locale.get_language_name('de')}} # Deutsch."}, {"location": "/reference/environments/", "title": "Build environments", "text": "Build environments Environment information is defined in the podspec. Most grow commands default to use the development environment. Some grow commands allow for specifying an environment to use by using the --deployment flag. This allows you to do things like test builds with the environment settings from production. Front matter tagging You can tag front matter data based on the environment information. title@: Title title@env.prod: Title in production title@env.staging: Title in staging # Default {{doc.title}} -> Title # Prod Environment {{doc.title}} -> Title in production # Staging Environment {{doc.title}} -> Title in staging This can also be helpful for preventing specific pages from being deployed to specific deployments. $path: /styleguide/ $path@env.prod: \"\""}, {"location": "/reference/markdown-extensions/", "title": "Markdown reference", "text": "Markdown reference Grow uses the Python-Markdown package for its Markdown implementation. You can see John Gruber's Syntax Documentation to learn about Markdown's default syntax rules. These built-in extensions are enabled by default. Tables Generates tables. View documentation. | Header 1 | Header 2 |-|-| | Row 1 | Content | Row 2 | Content Table of Contents Generates a table of contents based on the headings in a document. View documentation. [\u200bTOC] Configuration Configuration options available to the toc extension can be configured in the podspec. # podspec.yaml markdown: extensions: - kind: toc title: baselevel: 1 anchorlink: False permalink: False separator: \"-\" Include Includes content from another document. # Remove the extra space after `)`. [include('/content/shared/stuff.md') ] URL Url to a document or static file in the pod. # Remove the extra space after `)`. [url('/content/pages/archive.md') ] Sourcecode Implements pygments syntax highlighting for code snippets. [\u200bsourcecode:html] Hello World!

Source code highlighting. [\u200b/sourcecode] You can also highlight specific lines: [\u200bsourcecode:html, hl_lines=\"1 3\"] Hello World!

Source code highlighting. [\u200b/sourcecode] Which appears as: Hello World!

Source code highlighting. Configuration # podspec.yaml markdown: extensions: - kind: sourcecode classes: False # Uses classes instead of inline styles. class_name: code # Class to use on the wrapper div. highlighter: pygments # pygments/plain theme: default # Pygments theme name. If you choose to use classes instead of inline styles you can use pygments to generate the stylesheet for a theme. To generate the styles for the friendly theme with a code class wrapper. pygmentize -S friendly -f html -a .code > styles.css Code Block An alternative to the [sourcecode] block is to use GitHub-flavor backticks via python markdown's code fence extension. `\u200b``js console.log('Hello World'); `\u200b`` You can also highlight specific lines: `\u200b``js hl_lines=\"1\" console.log('Hello World'); `\u200b`` Which would show up as: console.log('Hello World'); Configuration # podspec.yaml markdown: extensions: - kind: markdown.extensions.codehilite classes: False # Uses classes instead of inline styles. class_name: code # Class to use on the wrapper div. highlighter: pygments # pygments/plain theme: default # Pygments theme name. If you choose to use classes instead of inline styles you can use pygments to generate the stylesheet for a theme. To generate the styles for the friendly theme with a code class wrapper. pygmentize -S friendly -f html -a .code > styles.css"}, {"location": "/reference/translations/", "title": "Translations", "text": "Translations Translatable items Items that are \"translatable\" are ones which contain text which can be extracted by Grow into message catalogs for translation. Message catalogs can be used to generate translated content. Grow takes a what you tag is what you translate approach: only things that you deem translatable will be extracted for translation, and then subsequently translated upon request. Views UI strings (and other text) in views are translatable. UI strings must be tagged with a template function that indicates the text is translatable. This template function, gettext, has been aliased to {{_(text)}}. {{_('Hello World!')}}

{{_('Page Title')}}

    {% for callout in g.doc.callouts %}
  • {{_(callout.title)}} \u2013 {{_(callout.description)}} {% endfor %}

{{_('Posted: %(date)s', date='12/25/86')}} Since Grow translations are opt-in instead of opt-out, it's possible to show translated text from a content document right next to untranslated text. {{doc.title()}} {{_(doc.title())}} Text replacement When doing translations there are two ways to text replacement: {{_('Test out %(name)s in %(text)s', name='Julie', text='indecipherable')}} {{_('Test out {name} in {text}', name='Julie', text='indecipherable')}} Named placeholders should be used as other languages may not use the words in the same order. Content documents Field names postfixed with an @ symbol are translatable. Note that you should omit the @ when referring to the field in a template. The @ is simply used to tag the field for translation in the YAML front matter. # /content/pages/page.yaml (content document) $title@: Hello World! sections: - title@: Section A # Extracted for translation. content@: A's content. - title@: Section B # Extracted for translation. content@: B's content. - title: Section C # Not extracted for translation. content: C's content. items@: # Tagged list of strings. - Item 1. - Item 2. # /views/pages.html (sample usage in a view) {% for section in doc.sections %}

  • {{_(doc.title)}}
  • {{doc.content}} {% endfor %} CSV files Messages can be extracted from CSV files by appending @ to a header cell's value. header1,header2@,header3 Not extracted,Extracted,Not Extracted Translator comments You can provide clarifying details about strings to translators by using translator comments. Upon extraction, translator comments appear alongside their corresponding messages in message catalogs. Translators may then reference the comment in order to produce a more accurate translation. Translator comments are particularly useful to convey restrictions about a string (such as its length) or to clarify context when a string may be ambiguous. # Translator comments in YAML. prop@: Text to translate prop@#: Comment for translator. # Translator comments in templates. {#: Comment for translator. #}

    {{_('Text to translate')}}

    Extracting translations To extract translations into a message catalog, tag all translatable items as explained above, and then use the grow translations extract command. Messages will be extracted to a file /translations/messages.pot. The message catalog (messages.pot) contains all of your pod's extracted messages. This file can then be used to create translation catalogs manually using a PO file editor, or integrated with a translation management service. grow translations extract Extracted translations can also be audited to find content that is untagged for translation. grow translations extract --audit Compiling translations Grow automatically recompiles translations when the development server starts, builds a pod, and during deployment. Translations must be recompiled before they're visible on your site. Importing translations Grow can import translation PO files from external sources. Currently Grow expects a zip file containing one directory named after its locale. Within each directory should be a messages.po file. Alternatively, you can specify a directory instead of a zip file. # Structure of source zip file. /foo.zip /de /messages.po /it/ /messages.po grow translations import --source= Untranslated content To help find content that is in use, but not yet translated you can generate a summary of the missing translations. # Builds pod and shows untranslated strings. grow build --locate-untranslated You can also update the configuration in your podspec to prevent specific deployments when there are untranslated content."}, {"location": "/reference/preprocessors/", "title": "Preprocessors", "text": "Preprocessors Preprocessors do things like optimization and code generation against your pod's source files. Grow runs preprocessors every time affected source files change, allowing you to \"save and refresh\" to preview your changes. Preprocessors are also run at build time. Grow includes the below preprocessors as built-ins with the SDK, and you'll always be free to bring your own external processing tools (such as Gulp). Global settings By default, preprocessors run when the development server is started and when your site is built. You can control preprocessor execution by using the autorun parameter and optionally by using the name parameter. preprocessors: - name: my_preprocessor kind: autorun: false tags: - red - blue A preprocessor with the above configuration will only be run when using grow preprocess -A or when using grow preprocess -p my_preprocessor. This can be handy to control how often a data-importing preprocessor (such as Google Sheets or Google Docs importers) run. You may not want to run those preprocessors each time your site is built. Kinds Google Docs The Google Docs preprocessor downloads a Google Doc and saves it to a data file within your pod. It can optionally convert the Google Doc to Markdown, ready for use with the markdown filter in templates. Specifying an .md file extension for the path parameter will convert the output to Markdown. After enabling this preprocessor, when you run the grow build command, you will be prompted (once on the command line) to authorize Grow to read your Google Drive files. preprocessors: - kind: google_docs path: /data/filename.{html|md} # Where to save downloaded file. id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI # File ID. convert: true # Whether to convert the file to Markdown. Google Sheets The Google Sheets preprocessor downloads data from a Google Sheet and saves it to a data file within your pod. The data can then be consumed by the g.csv tag, for example, in templates. After enabling this preprocessor, when you run the grow build command, you will be prompted (once on the command line) to authorize Grow to read your Google Drive files. Grow will export data from Google Sheets as either JSON or CSV, depending on the extension used in the path field. preprocessors: - kind: google_sheets path: /content/data/filename.{csv|json|yaml} # Where to save the downloaded file. id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI # Spreadsheet ID. gid: 0 # Worksheet ID (optional). output_style: {compressed|pretty} # Whether to compress or pretty print JSON-formatted docs (default: compressed). By default, Grow treats Google Sheets data as a list. Optionally, the data can be treated as a map and reformatted appropriately. This can be useful for binding a Google Sheet to a content document. Field names beginning with # are ignored when downloaded. The preserve option can be set to builtins to preserve any existing builtin fields in the document (fields whose names begin with $). preprocessors: - kind: google_sheets path: /content/pages/file.yaml id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI format: map preserve: builtins Optionally, data can be saved to a specific key within a YAML document, rather than overwriting an entire document. In the following example, a Google Sheet is downloaded and the faq key within /content/pages/page.yaml is updated with a list of data. preprocessors: - kind: google_sheets path: /content/pages/page.yaml:faq id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI Spreadsheets can also be imported as a collection into Grow. Each sheet will be imported as a separate yaml file that maps the first column to the second column. preprocessors: - kind: google_sheets collection: /content/strings/ id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI An alternative to the map format is the string format which will is the same as the map except it appends a @ to the key name to mark the string for translation. preprocessors: - kind: google_sheets collection: /content/strings/ id: 1ZhJshmT2pZq_IALA6leXJ0oRuKVO12N9BbjAarAT8kI format: string Gulp The Gulp preprocessor simplifies using Gulp in conjunction with Grow. Instead of running Gulp and Grow separately, Grow can manage Gulp as a subprocess and run different Gulp tasks at build and run time. Typically, you would pair grow run with a Gulp task that watches for changes and rebuilds static assets; and you would pair grow build with a Gulp task that builds static assets for release. You can use the build_task and run_task options to control the Gulp task that is run for these two Grow commands. preprocessors: - kind: gulp build_task: \"build\" # Task to run at build time (optional). run_task: \"\" # Task to run when the development server runs (optional)."}, {"location": "/reference/preferences/", "title": "Command preferences", "text": "Command preferences RC file Grow uses a ~/.growrc.yaml file to keep track of global Grow preferences. This file tracks: Auto-update preferences. Timestamp of the last update check. Custom grow command flag defaults. Additionally, Grow will look for a .growrc.yaml file in the directory that the grow command is run. This allows for setting custom Grow preferences for individual projects. Custom Grow command flag defaults For certain command line flags you can provide custom defaults for Grow by adding them to the .growrc.yaml file. Build grow: build: deployment: null preprocess: true clear-cache: false locate-untranslated: false re-route: false Deploy grow: deploy: preprocess: true confirm: true test: true force-untranslated: false Extract grow: extract: include-obsolete: null localized: null include-header: null fuzzy-matching: null Filter grow: filter: include-obsolete: false localized: false include-header: false out-dir: null force: false Import Translations grow: translations: import: include-obsolete: true Preprocess grow: preprocess: deployment: null Run grow: run: deployment: null host: localhost port: 8080 https: false debug: false browser: false update-check: true preprocess: true ui: true re-route: false Stage grow: stage: preprocess: true force-untranslated: false Stats grow: stats: full: true Upload Translations grow: translations: upload: download: true extract: true force: false Shared Command Flag Defaults Some of the flags are common between different Grow commands. These can be done as custom defaults in each command or in the shared settings: grow: shared: deployment: null force-untranslated: false include-header: false include-obsolete: false localized: false out-dir: null preprocess: true re-route: false"}, {"location": "/reference/partials/", "title": "Partials", "text": "Partials Partial templates are a powerful concept that permit site architects to divide a design up into sections, and then freely rearrange and reuse those designs throughout the site. Most pages that can be divided up into discrete sections (such as a header, content area \u2013 or collection of various content areas in order, and a footer) should be implemented using partials. Setting up the partial system Setup the partial system by adding a partial loop to your page template. {# /views/base.html #} {% if doc.partials %} {% for field in doc.partials %} {% if not field.partial %} {% continue %} {% endif %} {# Render the partial with the values in {{partial}}. #} {% set partial_filename = field.partial|expand_partial %} {% with partial = field %} {% include partial_filename with context %} {% endwith %} {% endfor %} {% else %} {{doc.html|safe}} {% endif %} Create partials in the /partials directory. {# /partials/hero/hero.html #}

    {{_(partial.title)}}

    {# /partials/about-me/about-me.html #}

    {{_(partial.title)}}

    {{_(partial.description)}}

    {# /partials/footer/footer.html #}
    Add structured partials to your page front matter # /content/pages/about.yaml $view: /views/base.html $path: /about/ partials: - partial: hero title@: My hero image: !gstatic /static/images/about_me.jpg - partial: about-me title@: About me description@: I am a Grow user! - partial: footer copyright@: Example Corp Now your \u201cabout\u201d page will render a hero, about-me and footer partial. Easily reuse partials across your site pages. Naming partials Name partials after their layout or component role (such as hero, feature-grid, or cta-banner) rather than a specific page. Keeping partials self-contained and lowercase hyphen-delimited makes them easy to reuse across pages \u2014 and you can selectively render different partials per locale. The following example renders a different partial for en_US vs en_CA: # /content/pages/about.yaml $view: /views/base.html $path: /about/ partials: - partial: hero title@: My hero image: !g.static /static/images/about_me.jpg - partial@en_US: about-me title@: About me description@: I am a Grow user! - partial@en_CA: trip title@: My trip to Canada - partial: footer copyright@: 2017 Mysite.com Keep it DRY Do not repeat yourself and duplicate similar partials. Instead try to create multiple variations within same partial by passing configuration flags or by passing css classes. # /content/pages/about.yaml partials: - partial: hero title@: My hero class@ja_JP: carousel--large carousel_disabled@en_CA: true"}, {"location": "/", "title": "Introduction", "text": "A declarative, file-based static site generator Grow is a simple, declarative static site generator written in Python. Author your content in YAML, JSON, and Markdown, bind it to Jinja2 templates, and compile to fast, self-contained static HTML with built-in localization. Grow keeps content strictly separate from presentation and makes zero assumptions about your frontend CSS or JavaScript stack. Quick start Install Grow with uv (Python 3.10 \u2013 3.12): uv tool install grow Clone the monorepo and preview the zero-Node starter pod locally: git clone https://github.com/grow/grow.git cd grow grow run examples/starter Build the static site to build/: grow build examples/starter Key features Declarative content & routing: Define collections, URL patterns, and metadata in YAML \u2014 update URLs without breaking internal links. Jinja2 templates & partials: Compose reusable HTML templates and modular page partials with full template-level link validation. Built-in internationalization (i18n): Mark translatable strings in YAML and templates, manage standard .po message catalogs, and localize URLs and content per locale. Environment-aware builds: Target development, staging, and production configurations from a single podspec.yaml. Zero frontend lock-in: Bring plain CSS/JS or any external bundler you prefer. Static output everywhere: Deploy build/ to GitHub Pages, Cloudflare Pages, Netlify, Cloud Storage, S3, or any static host. Next steps Install Grow \u2014 uv, pip, and Docker setup. Workflow: Developing & building \u2014 Local server, Dev Console (/_grow), and production builds. Starter project on GitHub \u2014 Minimal localized pod with zero Node dependencies. Walk through the codelab"}, {"location": "/install/", "title": "Install", "text": "Install Grow Grow requires Python 3.10 \u2013 3.12. Install with uv (Recommended) uv installs Grow in an isolated environment and makes the grow command available globally: uv tool install grow Install with pip You can also install Grow into any virtual environment using pip: pip install grow Verify the installation: grow --version Quick Start Clone the Grow monorepo and run the built-in zero-Node starter project: git clone https://github.com/grow/grow.git cd grow uv sync uv run grow run examples/starter Docker Prebuilt Docker images with Grow, Python, Node.js, Yarn, and the Google Cloud CLI are available on Docker Hub and GitHub Container Registry: docker run --rm -it -v \"$PWD\":/site -w /site grow/base grow build Migrating from the legacy installer (install.grow.io) The legacy standalone binary installer (curl https://install.grow.io | bash / install.py) has been deprecated and retired. If you have local setups or CI scripts using it, replace that step with one of the methods above (uv tool install grow, pip install grow, or the grow/base Docker image)."}, {"location": "/workflow/building/", "title": "Developing & building", "text": "Developing & building Grow provides a built-in local development server for instant previews and a static builder that compiles your pod into plain HTML, CSS, JS, and assets. Local development server Start the development server from your pod directory (or pass the path to a pod): grow run Grow serves your site locally at http://localhost:8080/ and includes a built-in Dev Console at http://localhost:8080/_grow/ where you can inspect routes, patterns, localized URLs, and pod metadata. Edits to content (content/), templates (views/), static files, or podspec.yaml are picked up automatically on refresh. # Run on a specific port or pod directory grow run --port=8081 ./my-site Building static output Use grow build to render every route in your pod to static files. By default, files are written to ./build/ inside the pod directory. # Build the current pod to ./build/ grow build # Build to a custom output directory grow build --out_dir=./dist # Build and report any untranslated strings grow build --locate-untranslated When --locate-untranslated is passed, Grow exports missing strings to .po files in .grow/untranslated/ so they can be sent for translation. Preprocessors To run configured preprocessors without running a full build: grow preprocess Inspecting a pod Grow includes inspection commands for debugging routes and localization coverage: # Print every resolved URL route in the pod grow inspect routes # Find strings missing translation tagging in templates and front matter grow inspect untranslated"}, {"location": "/workflow/deployment/", "title": "Deployment", "text": "Deployment Grow compiles your pod into a directory of static files that can be hosted anywhere \u2014 GitHub Pages, Cloudflare Pages, Netlify, Google Cloud Storage, Amazon S3, or any standard web server. Deploying with grow build (Recommended) For most projects, the simplest deployment workflow is to run grow build in CI (for example, GitHub Actions) and publish the resulting build/ directory to your static host. See Continuous integration for a complete GitHub Actions + GitHub Pages workflow. Built-in grow deploy destinations If you want Grow to manage incremental diffs and upload files directly, define named destinations under deployments: in podspec.yaml and run grow deploy : # podspec.yaml deployments: local: destination: local out_dir: ./dist/ pages: destination: git repo: https://github.com/owner/project.git branch: gh-pages grow deploy pages Launch lifecycle Every grow deploy follows the same predictable lifecycle: Preprocess & build: Configured preprocessors run and all routes are rendered. Diff against deployment index: Grow compares the newly built files against the destination's deployment index and shows a diff of additions, edits, and deletions for confirmation (pass --noconfirm in CI). Apply changes: Only modified files are written and removed routes are deleted cleanly, then the deployment index is updated. Local destination Writes the built site (with diff tracking) to a local directory on disk: destination: local out_dir: /path/to/output/ Git destination Clones a Git repository, checks out the target branch, applies the build diff, commits, and pushes. Useful for branch-based hosting such as gh-pages: destination: git repo: https://github.com/owner/project.git branch: gh-pages root_dir: \"\" # Optional subdirectory within the repository. Deployment environments Each deployment can define an env block exposed to templates as {{env}}, allowing you to adjust canonical URLs, analytics, or robots behavior per target: deployments: prod: destination: local out_dir: ./build/ env: name: prod host: example.com port: 443 scheme: https"}, {"location": "/workflow/continuous/", "title": "Continuous integration", "text": "You can easily test, build, and deploy your website using a continuous integration (CI) system. CI systems automate repetitive build steps and keep your published site in sync with Git. The combination of GitHub, GitHub Actions, Grow, and a static host such as GitHub Pages, Google Cloud Storage, or Amazon S3 lets your team collaborate on Git and deploy automatically on every merge. In fact, this is exactly how this documentation is deployed. For security, store deployment credentials as encrypted repository secrets in your CI provider rather than committing them to your repository. Using GitHub Actions and GitHub Pages Create .github/workflows/deploy.yml in your repository to build your Grow pod with uv and publish the output to GitHub Pages on every push to main: name: Deploy site on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v5 with: python-version: \"3.10\" - name: Build site run: uvx grow build . - uses: actions/upload-pages-artifact@v3 with: path: build deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v4 Deploying to Cloud Storage or S3 To deploy to a destination configured in podspec.yaml (such as Google Cloud Storage or Amazon S3), configure the required provider credentials as GitHub Actions secrets and run: - name: Deploy site run: uvx grow deploy --noconfirm prod Docker image Grow also publishes a prebuilt Docker image on Docker Hub (grow/base) and GitHub Container Registry (ghcr.io/grow/grow) with Grow, Python, Node.js, and gcloud preinstalled."}, {"location": "/extensions/install/", "title": "Install extensions", "text": "Installing extensions Grow has a powerful and simple extension system that enables you to extend the functionality of Grow with extensions. Installing extensions Grow supports an extensions.txt file as part of the pod. When the file is present the grow install command will handle the installation of the extensions. # extensions.txt git+https://github.com/grow/grow-ext-google-cloud-images The extensions.txt follows the same format as a normal pip requirements.txt style. This means you can install pip packages or directly from version control. See the documentation for each extension for instructions on how to properly configure the extension and what settings to add to the podspec.yaml file. Finding extensions Extensions can be found by searching for grow-ext- in pypi or github. Custom extensions When possible, extensions should be created as separate repositories and use the extensions.txt file to reference the extension. This helps the extensions be reusable across projects. Repositories for grow extensions should be named using the grow-ext- format. For example: grow-ext-google-cloud-images. In some cases it makes more sense to write the extension inside the same repository as it is very specific to the site. The same principles apply just put the extension files into a subdirectory inside the extensions/ directory. Extensions are standard Python modules, so your site's extensions folder must be set up appropriately, with __init__.py files: \u251c\u2500\u2500 /extensions # All your extensions | \u251c\u2500\u2500 /__init__.py # Empty file, required by Python | \u2514\u2500\u2500 /extension_name # Subfolder for custom extension | \u251c\u2500\u2500 /__init__.py # Empty file, required by Python | \u251c\u2500\u2500 /extension_name.py # Extension code"}, {"location": "/extensions/create/", "title": "Create extensions", "text": "Create extensions Grow has a powerful extension system that enables you to extend the functionality of Grow with extensions. Example extension As an example of a simple Grow extension see the html min extension. Anatomy of an extension Grow extensions work by creating hooks to bind to events that happen within Grow. For example, a hook to change the contents of a page after it has already been rendered. Each extension can bind to any number of hooks. Extensions are provided with a configuration optionally defined in the podspec.yaml that can be used to control the extension's functionality: # podspec.yaml ext: - extensions.html_min.HtmlMinExtension: options: remove_comments: true reduce_boolean_attributes: false For complex extensions specific hooks can be enabled or disabled piecemeal: # podspec.yaml ext: - extensions.complex.ComplexExtension: enabled: - post_render disabled: - dev_file_change Extension hooks Base hooks are defined by Grow and can be extended in the extension. When hooks are triggered in Grow (ex: after the content is rendered) it calls the trigger method on the hook. Hook triggers follow some basic conventions: The first argument is the previous_result from any hooks already triggered. Arguments change depending on the hook and are documented below. Each trigger method should have *_args, **_kwargs as the last two arguments. For hooks that are expecting a specific result a result object will be provided in the previous_result argument and should just be updated as needed. If there is a specific return type it will be documented with the hook. Even if your extension doesn't change the previous_result, the previous_result should be returned to continue the chain of extensions. By using the *_args, **_kwargs on all trigger methods it allows Grow to add additional arguments to the hook without breaking existing extensions. from grow.extensions import hooks class MyPostRenderHook(hooks.PostRenderHook): \"\"\"Handle the post-render hook.\"\"\" def trigger(self, previous_result, doc, raw_content, *_args, **_kwargs): \"\"\"Execute post-render modification.\"\"\" content = previous_result if previous_result else raw_content # Do something to modify the contents. return content Extensions A simple extension only needs to extend the BaseExtension and define the available_hooks property. from grow import extensions class MyExtension(extensions.BaseExtension): \"\"\"Example Extension.\"\"\" @property def available_hooks(self): \"\"\"Returns the available hook classes.\"\"\" return [MyPostRenderHook] For special cases when you need to have additional arguments to the hook class you can create hook getters in the extension to control how the hook is created. from grow import extensions class MyExtension(extensions.BaseExtension): \"\"\"Example Extension.\"\"\" @property def available_hooks(self): \"\"\"Returns the available hook classes.\"\"\" return [MyPostRenderHook] def post_render_hook(self): \"\"\"Returns the hook object.\"\"\" return MyPostRenderHook(self, other_arg=True) Grow Hooks The following hooks are currently available for extensions. hooks.DevFileChangeHook When a file is changed when running the development server this hook is triggered. def trigger(self, previous_result, pod_path, *_args, **_kwargs): return previous_result pod_path \u2013 path of the file that changed in the pod. See the core routes extension for an example of the dev file change. hooks.DevHandlerHook When running the local development server the dev handler hook allows for adding custom handlers for the development server. def trigger(self, previous_result, routes, *_args, **_kwargs): return previous_result routes \u2013 The routes object for adding the handler. See the core routes extension for an example of the dev handler. hooks.PostRenderHook def trigger(self, previous_result, doc, raw_content, *_args, **_kwargs): return previous_result doc \u2013 The document being rendered. This can be a normal document or a static document. raw_content \u2013 The raw rendered content. See the html min extension for an example of the dev handler. hooks.PreprocessHook def trigger(self, previous_result, config, names, tags, run_all, rate_limit, *_args, **_kwargs): return previous_result config \u2013 Configuration for the preprocessor from the podspec. names \u2013 Names of the preprocessors being run. tags \u2013 Tags of the preprocessors being run. run_all - If all preprocessors are being run. rate_limit - Time in seconds when rate limiting should be used between bulk processing. hooks.PreRenderHook def trigger(self, previous_result, doc, original_body, *_args, **_kwargs): return previous_result doc \u2013 The document being rendered. This can be a normal document or a static document. original_body \u2013 The original content before being rendered."}]}