[Target_example]
Available since Exponential 6.0.15 (in development, not in a release yet).
Summary
The group [Target_example] of settings/staticcache.ini.
File
settings/staticcache.ini; override it in settings/override/staticcache.ini.append.php, in a siteaccess or in an extension.
Settings
| Setting | Default | Description |
|---|---|---|
| Name | Example target | A target, as a template: copy the block as [Target_<id>] in settings/override/staticcache.ini.append.php and add <id> to TargetList[]. This block is not built (TargetList[] does not name it). Settings left out of a target take the values shown here. The name shown in lists and the administration. |
| SiteAccess | (empty) | The front siteaccess to publish. Administration and editing siteaccesses (those that require a login or use an administration design) are refused. |
| SiteAccessList[] | (empty array) | Several front siteaccesses in one copy, instead of SiteAccess: sites that share one host by their URI prefix (site.ini [SiteAccessSettings] MatchOrder with uri, or host_uri with a URI), such as site, bold and bold_ger. Each one but the default is written to the folder of its prefix (/bold_ger/...); the links between them stay in the copy, and links to a siteaccess not listed are links outside the copy (OutsideLinks). When it names any, SiteAccess is not read. |
| DefaultSiteAccess | (empty) | The siteaccess of SiteAccessList[] served at the root of the copy. Empty: every siteaccess is in its folder, and the root is a page that links to each. A target of one siteaccess always has it at the root. |
| Kind | github-pages | Where the build goes: github-pages (GitHub Pages) or git (any git host). |
| Remote | (empty) | The git address the build is pushed to (no password or token in it). |
| Branch | gh-pages | The branch the build is pushed to: gh-pages, or main with Folder=docs. |
| Folder | (empty) | The folder of the branch the site is in: empty for the root, or docs. |
| Delivery | branch | How GitHub Pages receives the build: branch (pushed to Branch) or actions (a GitHub Actions workflow publishes it). |
| Links | relative | How links are written: relative (../about-us/, works below any path) or base-path (/my-site/about-us/, below BasePath). |
| BasePath | (empty) | The path the site is served below: /<repository>/ for a GitHub project site, empty or / for a custom domain or a user site. 404.html links below it whatever Links says, and exp:static:serve serves the build below it. |
| PublicURL | (empty) | The public address of the site (https://owner.github.io/my-site/), for the sitemap, robots.txt and the canonical and social card links. Empty: they are written like any other link and no sitemap is written. |
| CustomDomain | (empty) | A custom domain (www.example.com): written to CNAME; with it the site is served at the root of the domain. |
| Credential | none | The credential the push uses: token:<secret name> (or token:env:<VARIABLE>) for an https Remote, sshkey:<secret name> for an SSH Remote (exp:static:keys <target> --generate makes the key: sshkey:staticpublish.<target>.deploy_key), app:<installation> (a GitHub App, with the GitHub integration), or none (the host's own SSH agent or credential helper). Only a name; the value stays in Setup > Secrets and reaches git only through its environment. |
| CrawlURL | (empty) | Fetch the pages from this address instead of the siteaccess's SiteURL (an internal address of the same site, http://127.0.0.1:8080). |
| LiveURL | (empty) | Where links to what the build does not hold go (the search, the login, a form, another siteaccess): the live site, https://www.example.com. Empty: https:// and the host of the siteaccess's SiteURL. |
| OutsideLinks | keep | Links to pages of the site's own host (or LiveURL) that the build does not hold (a module view such as /user/login or /shop/basket, a page with a query string, a page left out, another siteaccess): keep (they go to the live site, or stay as they are without one) or unlink (the link stays an <a> with its classes but without an address, marked aria-disabled and greyed out by the build's exp-static.css, so the theme's look holds). Images, style sheets, forms (see Forms) and links to other hosts are never taken out. |
| AdminLinks | keep | Links into an administration siteaccess (/admin/..., on the site's own host or LiveURL): keep (as OutsideLinks=keep) or unlink. The administration siteaccesses are the ones the target's checks already know: a login is required, an administration design, or a name such as admin or editor. |
| MaxPages | 10000 | The most pages one build crawls (1 to 20000). |
| MaxDepth | (empty) | How many links away from the front page the crawl goes (0 to 30). Empty: [CacheSettings] MaxCacheDepth. |
| Assets | referenced-and-storage | The files copied: referenced (what the pages and style sheets name) or referenced-and-storage (also every image of var/<site>/storage that belongs to published content the anonymous user may see). |
| Extras[] | nojekyll; 404; robots; sitemap; manifest | The files written besides the pages: nojekyll (.nojekyll, so GitHub Pages publishes the files as they are), 404 (404.html from the site's own 404 page), robots (robots.txt), sitemap (sitemap.xml, needs PublicURL), manifest (.static-publish/manifest.json; always written), redirects (a small page for every old address and custom alias of a page, and for URL wildcards without *), readme (README.md), license (LICENSE, from License below), workflow (the GitHub Actions workflow). CNAME is written whenever CustomDomain is set. |
| PostProcess[] | strip | What is done to every page: strip (always) removes debug output, form tokens, session ids and Content Security Policy nonces. Optional: minify (less white space, no comments), precompress (.gz, and .br with PHP's brotli extension, next to every text file), fingerprint (style sheets and scripts named by the hash of their content, site.3f2a9c1b.css). |
| Search | disabled | A search page for the static copy (search.html, an index per language and a small script; the site's search forms go there): enabled or disabled. |
| Forms | hide | What happens to information collectors (forms): hide (the fallback text, FormFallbackText), or endpoint (they post to the form endpoint of the live site; needs PublicURL or CustomDomain). Comment, basket and login forms are never sent from a static copy. |
| ExcludePaths[] | (empty array) | Pages left out, by their path in the site (/members, /shop/*); * matches any part. Links to them go to the live site. |
| ExcludeSections[] | (empty array) | Pages left out by the section of their content (section ids). |
| Triggers[] | manual; cli | What may start a build: manual, publish (the cronjob part staticpublish publishes the changed pages after a content publish), schedule (the same cronjob part publishes in full at the times of Schedule), cli. |
| Schedule | (empty) | When a scheduled build runs (a cron expression, the server's time zone: 0 3 * * *, or @daily), for Triggers[]=schedule. |
| Notify[] | failure | When to send a notice by e-mail ([StaticPublishSettings] NotifyEmail): failure, success. |
| Webhook | (empty) | An https address that is sent a notice of every publish and rollback (POST, JSON, schema exp-static-webhook/1). |
| License | (empty) | The license of the content for Extras[]=license: an SPDX id (CC-BY-4.0) or the text itself. |
See also
Generated example: staticcache.ini [Target_example]
Added to the reference for Exponential 6.0.15: the 4.x reference had no page for this group. The descriptions are the comment lines of settings/staticcache.ini.
Contributors
- Graham Brookins Updated
Comments
Add a comment