ssqch 0.12.0 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bundled/completions/bash +66 -8
- package/bundled/completions/elvish +23 -4
- package/bundled/completions/fish +36 -25
- package/bundled/completions/powershell +25 -4
- package/bundled/completions/zsh +44 -10
- package/bundled/docs/agents.md +2 -2
- package/bundled/docs/build-summary.md +1 -1
- package/bundled/docs/comparing-builds.md +2 -2
- package/bundled/docs/configuring.md +3 -6
- package/bundled/docs/deploying.md +1 -1
- package/bundled/docs/field-guide.md +4 -4
- package/bundled/docs/github-pages.md +1 -0
- package/bundled/docs/index.md +1 -1
- package/bundled/docs/install.md +1 -1
- package/bundled/docs/known-gaps.md +1 -1
- package/bundled/docs/markdown.md +8 -12
- package/bundled/docs/nav.yml +5 -1
- package/bundled/docs/netlify.md +4 -2
- package/bundled/docs/patrol.md +48 -0
- package/bundled/docs/plugins.md +6 -6
- package/bundled/docs/robots.md +85 -0
- package/bundled/docs/seo.md +2 -38
- package/bundled/docs/serving-markdown.md +142 -0
- package/bundled/docs/template-languages.md +1 -1
- package/bundled/docs/templates.md +1 -1
- package/bundled/docs/trailheads/from-hugo.md +5 -3
- package/bundled/docs/trailheads/from-jekyll.md +54 -13
- package/bundled/docs/trailheads/from-mkdocs.md +15 -12
- package/bundled/docs/trailheads/from-vitepress.md +13 -11
- package/bundled/docs/trailheads.md +3 -3
- package/bundled/docs/where-values-come-from.md +5 -5
- package/bundled/docs/writing-plugins.md +69 -0
- package/bundled/ssqch.d.ts +118 -44
- package/bundled/starter/engines/index.edge +1 -0
- package/bundled/starter/engines/index.ejs +1 -0
- package/bundled/starter/engines/index.hbs +1 -0
- package/bundled/starter/engines/index.liquid +1 -0
- package/bundled/starter/engines/layout.edge +7 -0
- package/bundled/starter/engines/layout.ejs +4 -0
- package/bundled/starter/engines/layout.hbs +4 -0
- package/bundled/starter/engines/layout.liquid +4 -0
- package/bundled/starter/src/_data/site.json +1 -0
- package/bundled/starter/src/_includes/layout.jinja +4 -0
- package/bundled/starter/src/index.jinja +1 -0
- package/bundled/starter/ssqch.config.js +14 -1
- package/bundled/starter-docs/engines/edge/base.edge +7 -0
- package/bundled/starter-docs/engines/edge/doc.edge +4 -0
- package/bundled/starter-docs/engines/ejs/base.ejs +4 -0
- package/bundled/starter-docs/engines/ejs/doc.ejs +4 -0
- package/bundled/starter-docs/engines/hbs/base.hbs +4 -0
- package/bundled/starter-docs/engines/hbs/doc.hbs +3 -0
- package/bundled/starter-docs/engines/liquid/base.liquid +4 -0
- package/bundled/starter-docs/engines/liquid/doc.liquid +4 -0
- package/bundled/starter-docs/src/_data/site.json +1 -0
- package/bundled/starter-docs/src/_includes/base.jinja +4 -0
- package/bundled/starter-docs/src/_includes/doc.jinja +4 -0
- package/bundled/starter-docs/src/assets/docs.css +4 -0
- package/bundled/starter-docs/src/assets/docs.js +17 -0
- package/bundled/starter-docs/ssqch.config.js +14 -1
- package/lib/assets.js +9 -9
- package/lib/chunk-25WERNDD.js +112 -0
- package/lib/{chunk-4ZMNLWE4.js → chunk-2BJFGKOE.js} +2 -2
- package/lib/{chunk-M2BBE2C3.js → chunk-3ZTRIO6O.js} +18 -17
- package/lib/{chunk-57HLSKZS.js → chunk-4AZFCSGJ.js} +2 -2
- package/lib/{chunk-ULQHJ4TS.js → chunk-55WXDGO4.js} +3 -3
- package/lib/{chunk-JX43SJHU.js → chunk-6FY77I4M.js} +24 -22
- package/lib/{chunk-RY3KLUQ3.js → chunk-6OUCRDYI.js} +267 -202
- package/lib/{chunk-EVFNYUTR.js → chunk-6U5VIQVY.js} +5 -5
- package/lib/{chunk-N3IZ44XY.js → chunk-7U5GWTEH.js} +88 -54
- package/lib/{chunk-VTYQ3JKL.js → chunk-AIJNG6MJ.js} +2 -2
- package/lib/{chunk-IIBZPHAW.js → chunk-C2Q7JKFI.js} +8 -8
- package/lib/{chunk-6CSH757V.js → chunk-DFJFHULZ.js} +33 -8
- package/lib/{chunk-XVV7JJK7.js → chunk-ENWDM2RW.js} +40 -39
- package/lib/{chunk-JUALMFW3.js → chunk-ER72RPD6.js} +1 -1
- package/lib/{chunk-RFREB3SI.js → chunk-F3JPNFCZ.js} +7 -7
- package/lib/{chunk-LLOA3QXV.js → chunk-FENJHLNM.js} +3 -2
- package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
- package/lib/{chunk-IZCF4UH3.js → chunk-FQZDUDFK.js} +1 -1
- package/lib/chunk-GM5SHCTU.js +272 -0
- package/lib/{chunk-GVHQ37JE.js → chunk-GSNRAGKQ.js} +10 -5
- package/lib/{chunk-L2IY4P6O.js → chunk-GU7BBYWB.js} +3 -3
- package/lib/{chunk-RGYJQYW3.js → chunk-HDKU6LRI.js} +32 -5
- package/lib/{chunk-IQUGLVZY.js → chunk-K5WZ2VYK.js} +4 -4
- package/lib/{chunk-JVT5ZRRH.js → chunk-OOKBXQAY.js} +5 -5
- package/lib/{chunk-MOLTDO5A.js → chunk-SNQOHNXE.js} +1 -1
- package/lib/{chunk-Z3XH4KWX.js → chunk-SPIFZBIW.js} +1 -1
- package/lib/{chunk-FNNXRVSU.js → chunk-T5IUI7W7.js} +10 -10
- package/lib/{chunk-5HEZ3WUQ.js → chunk-TGSVSG2G.js} +2 -2
- package/lib/{chunk-3GROJ3TY.js → chunk-U2KEMVXO.js} +24 -17
- package/lib/{chunk-4B3N44SN.js → chunk-UHRBPZ4A.js} +3 -3
- package/lib/{chunk-GWWA5Y3X.js → chunk-ULCT3PAV.js} +1 -1
- package/lib/{chunk-7RGEWDLF.js → chunk-UZNUS7RP.js} +10 -8
- package/lib/{chunk-DZ5F5XSI.js → chunk-V3G2QGL3.js} +10 -105
- package/lib/{chunk-DOHOKUGB.js → chunk-VILOEVK7.js} +50 -26
- package/lib/{chunk-DXMDXHV7.js → chunk-WGAIE3DD.js} +15 -14
- package/lib/{chunk-G3RFQDKO.js → chunk-WUCRAV36.js} +8 -6
- package/lib/{chunk-52ROOMBZ.js → chunk-XYAWJTHM.js} +9 -9
- package/lib/{chunk-L3K7MMFC.js → chunk-YA23NDMW.js} +2 -2
- package/lib/{chunk-R7PBREXL.js → chunk-YNJNMQWU.js} +8 -5
- package/lib/{chunk-AK7ZKSZP.js → chunk-ZMG25MXF.js} +17 -16
- package/lib/cli.js +56 -34
- package/lib/elements.js +9 -9
- package/lib/from-hugo.js +36 -0
- package/lib/from-jekyll.js +41 -0
- package/lib/from-mkdocs.js +49 -0
- package/lib/from-vitepress.js +49 -0
- package/lib/image.js +10 -10
- package/lib/links.js +9 -9
- package/lib/llms.js +619 -54
- package/lib/minify.js +10 -10
- package/lib/redirects.js +9 -9
- package/lib/robots.js +87 -0
- package/lib/rss.js +22 -12
- package/lib/sass.js +10 -10
- package/lib/sitemap.js +22 -33
- package/lib/ssqch.js +5 -5
- package/lib/vue.js +14 -13
- package/package.json +21 -1
- package/types/from-hugo.d.ts +5 -0
- package/types/from-jekyll.d.ts +11 -0
- package/types/from-mkdocs.d.ts +11 -0
- package/types/from-vitepress.d.ts +5 -0
- package/types/index.d.ts +45 -29
- package/types/llms.d.ts +18 -8
- package/types/robots.d.ts +13 -0
- package/types/sass.d.ts +1 -1
- package/types/sitemap.d.ts +3 -5
- package/wasm/markdown.wasm +0 -0
- /package/lib/{chunk-JX43SJHU.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
- /package/lib/{chunk-R7PBREXL.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Serving Markdown to agents"
|
|
3
|
+
description: "A coding agent asks for a page with Accept: text/markdown. ssqch serve answers with the page's Markdown copy; on a host, a few lines of the host's own code do the same."
|
|
4
|
+
---
|
|
5
|
+
Claude Code, Cursor and OpenCode ask for a page with `Accept: text/markdown`, and a page's Markdown copy (written by `llmsPlugin()`) is what they'd rather read: the text without the navigation, scripts and styles. A browser never asks for it, and neither does a crawler, so the same address can answer both.
|
|
6
|
+
|
|
7
|
+
## While you work
|
|
8
|
+
|
|
9
|
+
`ssqch serve` and `ssqch serve --built` answer a request for a page with its copy when the request asks for `text/markdown` by name, at a q-value at least as high as HTML's: `Accept: text/markdown, text/html;q=0.9` gets the copy, a browser's `text/html,...,*/*;q=0.8` gets the page, and `*/*` alone (curl's) gets the page too. The copy is the page's file with `.md` for `.html` (`guide/intro/index.html` has `guide/intro/index.md`), sent as `text/markdown; charset=utf-8`; a page that has a copy is sent with `Vary: Accept` either way, and one without is the page whatever the request asks. A copy at its own address (`/guide/intro/index.md`) is Markdown too.
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
curl -H "Accept: text/markdown" http://localhost:8080/guide/intro/
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## On a host
|
|
16
|
+
|
|
17
|
+
A static host sends the HTML file for a page's address whatever the request asks for, so answering with the copy takes a few lines of the host's own code. Each version below does the same thing: it checks the `Accept` header as `ssqch serve` does, finds the copy beside the page, sends it as Markdown with `Vary: Accept` and a `Link` header naming the page as the canonical address, and leaves every other request alone. They differ in where the code lives and what it costs.
|
|
18
|
+
|
|
19
|
+
Every version uses these two functions; paste them above it:
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
/** Whether `accept` asks for text/markdown by name, at least as much as for HTML (by q-values). */
|
|
23
|
+
function prefersMarkdown(accept) {
|
|
24
|
+
const q = new Map();
|
|
25
|
+
for (const part of accept.split(",")) {
|
|
26
|
+
const [type, ...params] = part.split(";").map((p) => p.trim().toLowerCase());
|
|
27
|
+
const given = params.find((p) => p.startsWith("q="));
|
|
28
|
+
if (type) q.set(type, given === undefined ? 1 : Number(given.slice(2)) || 0);
|
|
29
|
+
}
|
|
30
|
+
const markdown = q.get("text/markdown") ?? 0;
|
|
31
|
+
return markdown > 0 && markdown >= (q.get("text/html") ?? q.get("text/*") ?? q.get("*/*") ?? 0);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** A page's Markdown copy, as llmsPlugin() writes it: `/guide/intro/` (or `/guide/intro`) is `/guide/intro/index.md`, `/about.html` is `/about.md`; a file of another kind has none. */
|
|
35
|
+
function copyOf(pathname) {
|
|
36
|
+
if (pathname.endsWith("/")) return `${pathname}index.md`;
|
|
37
|
+
if (/\.html?$/.test(pathname)) return pathname.replace(/\.html?$/, ".md");
|
|
38
|
+
return /\.[a-z0-9]+$/i.test(pathname) ? undefined : `${pathname}/index.md`;
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Cloudflare
|
|
43
|
+
|
|
44
|
+
Workers with static assets (what Cloudflare suggests for a new site): a Worker that runs before the files for the pages with a copy. This is sitesquatch.dev's own `worker.js`, which serves this page. In `wrangler.jsonc`:
|
|
45
|
+
|
|
46
|
+
```jsonc
|
|
47
|
+
{
|
|
48
|
+
"main": "worker.js",
|
|
49
|
+
"assets": {
|
|
50
|
+
"directory": "./dist",
|
|
51
|
+
"binding": "ASSETS",
|
|
52
|
+
// The pages with a copy; everything else is a file, served without the Worker.
|
|
53
|
+
"run_worker_first": ["/", "/docs", "/docs/*"],
|
|
54
|
+
"not_found_handling": "404-page"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
And `worker.js`:
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
export default {
|
|
63
|
+
async fetch(request, env) {
|
|
64
|
+
const url = new URL(request.url);
|
|
65
|
+
const copy = copyOf(url.pathname);
|
|
66
|
+
if (copy && prefersMarkdown(request.headers.get("Accept") ?? "")) {
|
|
67
|
+
const found = await env.ASSETS.fetch(new URL(copy, url));
|
|
68
|
+
if (found.ok) {
|
|
69
|
+
const out = new Response(found.body, found);
|
|
70
|
+
out.headers.set("Content-Type", "text/markdown; charset=utf-8");
|
|
71
|
+
out.headers.set("Link", `<${url.origin}${url.pathname}>; rel="canonical"`);
|
|
72
|
+
out.headers.append("Vary", "Accept");
|
|
73
|
+
return out;
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
const response = await env.ASSETS.fetch(request);
|
|
77
|
+
if (!copy) return response;
|
|
78
|
+
const out = new Response(response.body, response);
|
|
79
|
+
out.headers.append("Vary", "Accept");
|
|
80
|
+
return out;
|
|
81
|
+
},
|
|
82
|
+
};
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
It costs a Worker request for each page view in `run_worker_first` (the free plan has 100,000 a day); files outside it don't run the Worker. `_headers` rules don't apply to what a Worker answers, so the headers are set here.
|
|
86
|
+
|
|
87
|
+
### Netlify
|
|
88
|
+
|
|
89
|
+
An edge function, which Netlify runs only for a request whose `Accept` mentions `text/markdown` (the `header` setting), so a browser's request never reaches it. `netlify/edge-functions/markdown.js`:
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
export default async (request) => {
|
|
93
|
+
if (!prefersMarkdown(request.headers.get("accept") ?? "")) return;
|
|
94
|
+
const url = new URL(request.url);
|
|
95
|
+
const copy = copyOf(url.pathname);
|
|
96
|
+
if (!copy) return;
|
|
97
|
+
const found = await fetch(new URL(copy, url));
|
|
98
|
+
if (!found.ok) return;
|
|
99
|
+
return new Response(found.body, { headers: { "Content-Type": "text/markdown; charset=utf-8", "Vary": "Accept", "Link": `<${url.origin}${url.pathname}>; rel="canonical"` } });
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
export const config = { path: "/*", excludedPath: ["/*.md"], header: { accept: "text/markdown" } };
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Returning nothing hands the request on to the page as usual. `_redirects` can't do this: its conditions are country, language, role and cookie, not `Accept`. Edge functions are billed by invocation; with the `header` setting, only agents' requests count. Not run on Netlify yet: the ReverentGeek blog will be the first site to.
|
|
106
|
+
|
|
107
|
+
### Vercel
|
|
108
|
+
|
|
109
|
+
Routing Middleware, which works for a site without a framework: `middleware.js` at the project's root (with `"type": "module"` in `package.json`) and `npm install @vercel/functions`:
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
import { next } from "@vercel/functions";
|
|
113
|
+
|
|
114
|
+
export default async function middleware(request) {
|
|
115
|
+
const url = new URL(request.url);
|
|
116
|
+
const copy = copyOf(url.pathname);
|
|
117
|
+
if (!copy || !prefersMarkdown(request.headers.get("accept") ?? "")) return next();
|
|
118
|
+
const found = await fetch(new URL(copy, url));
|
|
119
|
+
if (!found.ok) return next();
|
|
120
|
+
return new Response(found.body, { headers: { "Content-Type": "text/markdown; charset=utf-8", "Vary": "Accept", "Link": `<${url.origin}${url.pathname}>; rel="canonical"` } });
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Without a `matcher`, it runs for every request, files included, and each counts as a middleware invocation. A `rewrites` entry in `vercel.json` with a `has` condition on the `accept` header is the other way people try; Vercel's docs don't say it wins over a page's own file, so the middleware is the one to rely on. Not run on Vercel yet.
|
|
125
|
+
|
|
126
|
+
### GitHub Pages
|
|
127
|
+
|
|
128
|
+
GitHub Pages has no code that runs per request and no headers file, so a page's address is always its HTML. An agent finds the copy through the page's `<link rel="alternate" type="text/markdown">` and `llms.txt` instead ([Posted signs](robots.md#the-links-in-the-layout)), which is enough for one that reads them.
|
|
129
|
+
|
|
130
|
+
## The copies' own headers
|
|
131
|
+
|
|
132
|
+
A copy at its own address is a second version of the page, which a search engine shouldn't list beside it. On Netlify and Cloudflare, a `_headers` file in the output says so (a template with `permalink: /_headers`, or a file in `passthrough`):
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
/*.md
|
|
136
|
+
X-Robots-Tag: noindex
|
|
137
|
+
Content-Type: text/markdown; charset=utf-8
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Cloudflare allows 100 rules in `_headers`; Netlify's apply only to the files it serves, not to an edge function's answers (which set their own, above).
|
|
141
|
+
|
|
142
|
+
`ssqch patrol` checks the copies themselves; whether a host answers `Accept: text/markdown` needs the live site, which it doesn't check yet.
|
|
@@ -19,7 +19,7 @@ title: Squatch Snacks
|
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
- **Data:** front matter, the cascade, `page`, `collections` and `content` in layouts, the same as in the other engines. Undefined values, and properties of undefined values, print nothing (`strict: true` makes printing one an error).
|
|
22
|
-
- **Escaping:** output is HTML-escaped, as in Nunjucks and Jinja; use `| safe` to opt out. A layout's `content` is already marked safe, so `{{ content }}` works, and so is what a config filter returns with `safe(html)`. `jinja: { autoescape: false }` prints `.jinja` values as they are, as MkDocs' Jinja does (`
|
|
22
|
+
- **Escaping:** output is HTML-escaped, as in Nunjucks and Jinja; use `| safe` to opt out. A layout's `content` is already marked safe, so `{{ content }}` works, and so is what a config filter returns with `safe(html)`. `jinja: { autoescape: false }` prints `.jinja` values as they are, as MkDocs' Jinja does (`fromMkdocs({ templates: true })` does that too); `| e` still escapes.
|
|
23
23
|
- **Filters and functions:** Jinja's built-in filters, plus Nunjucks' own (`dump`, `truncate`, `forceescape`, `nl2br`, `urlize`, `wordcount`, `center`, `random`), and `pluralize`, `filesizeformat`, `striptags`, `cycler()` and `joiner()`. Your config `filters` work both ways: `{{ title | shout }}` and `{{ shout(title) }}`. On a page whose data has a field with a function's name, the call finds the field first, so use the filter form there. An async function is awaited.
|
|
24
24
|
- **JavaScript properties and methods:** Nunjucks templates use JavaScript's, and they work in `.njk` and `.jinja` files alike. `.length` counts a list's items or a string's characters (`{{ collections.posts.length }}`, the same as `| length`); `loop.length` and an object's own `length` key keep their meaning, and on any other object `.length` is undefined, as in JavaScript. Strings and lists also have `startsWith()`, `endsWith()`, `includes()`, `indexOf()`, `toLowerCase()`, `toUpperCase()` and `trim()`, beside Python's (`startswith()`, `lower()`).
|
|
25
25
|
- **Dates:** `{{ page.date | dateformat }}` prints `Mar 14 2026`. `dateformat`, `timeformat` and `datetimeformat` take `"short"`, `"medium"`, `"long"`, `"full"`, `"iso"`, `"unix"`, or a `strftime` pattern (`dateformat("%B %-d, %Y")`), in UTC. Dates also have Python's `strftime()` and `isoformat()` and JavaScript's `toISOString()` and friends, and `now()` is the build's time.
|
|
@@ -4,7 +4,7 @@ description: "The lay of the land."
|
|
|
4
4
|
---
|
|
5
5
|
The lay of the land:
|
|
6
6
|
|
|
7
|
-
- **The data cascade:** a page's data comes from several places, and each one replaces what the ones before it set: global data, the front matter of its layouts, directory data, the page's data file, its front matter, then `computed`. [Where a value comes from](where-values-come-from.md) has the exact order, and `ssqch
|
|
7
|
+
- **The data cascade:** a page's data comes from several places, and each one replaces what the ones before it set: global data, the front matter of its layouts, directory data, the page's data file, its front matter, then `computed`. [Where a value comes from](where-values-come-from.md) has the exact order, and `ssqch trace` shows it for any page.
|
|
8
8
|
- **Collections:** tags become collections, sorted by date, plus your custom ones. `excludeFromCollections: true` keeps a page out.
|
|
9
9
|
- **Pagination:** one template makes a page for each item, or each group of items, in a list. In its front matter, `pagination: { data: "collections.posts", size: 10, alias: "posts" }` and a `permalink` with the page number (`/blog/{% if pagination.pageNumber > 0 %}{{ pagination.pageNumber + 1 }}/{% endif %}`). `data` names the list: global data (`snacks`), a collection (`collections.posts`, a custom collection included, even one that returns plain objects, so one template can write a page per route of a route table), or `collections` itself, the collections' names, for a page per tag (`filter: [all]` leaves `all` out). `size: 1` gives a page per item, and `alias` names the item (`alias: post`, then `{{ post.data.title }}`). Each page gets `pagination.items` (its items), `pageNumber` (from 0), `pages` (every page's items), `hrefs` (every page's URL), `href.previous`, `href.next`, `href.first` and `href.last`. More options: `reverse`, `filter` (values to leave out) and `addAllPagesToCollections` (every page in the template's collections, not just the first). A `computed` value in a data file beside the template sees the alias, so each page's data can come from its item.
|
|
10
10
|
- **Permalinks:** dynamic permalinks, `permalink: false` and `dynamicPermalink`. A permalink (or `computed` value) with `{{ }}` renders in the page's own template language, so a Liquid page can write `permalink: "/{{ title | slugify }}/"`; Markdown and HTML pages use their `markdownEngine` or `htmlEngine` (Edge when that's `false`).
|
|
@@ -14,13 +14,15 @@ export default defineConfig({
|
|
|
14
14
|
dirs: { input: "content", output: "public", includes: "../_includes", data: "../data" },
|
|
15
15
|
// Hugo doesn't run template code in content, and its shortcodes on a line of their own are containers.
|
|
16
16
|
markdownEngine: false,
|
|
17
|
-
markdown: {
|
|
17
|
+
markdown: { highlight: { classes: "pygments" } },
|
|
18
18
|
passthrough: [{ static: "." }],
|
|
19
19
|
data: { site: { title: "Trail Notes", url: "https://example.com", params: {} } },
|
|
20
|
-
plugins: [sitemapPlugin({ url: "https://example.com" }), linksPlugin({ fail: false })],
|
|
20
|
+
plugins: [fromHugo(), sitemapPlugin({ url: "https://example.com" }), linksPlugin({ fail: false })],
|
|
21
21
|
});
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
+
`fromHugo()` from `ssqch/from-hugo` reads Hugo's shortcodes as containers, below: a default (`shortcodes: "hugo"`) your own `markdown` can change.
|
|
25
|
+
|
|
24
26
|
## The config
|
|
25
27
|
|
|
26
28
|
| Hugo (`hugo.toml`) | SiteSquatch (`ssqch.config.js`) |
|
|
@@ -45,7 +47,7 @@ export default defineConfig({
|
|
|
45
47
|
## Content
|
|
46
48
|
|
|
47
49
|
- **Template code in your Markdown:** Hugo's docs and many tutorials have `{{ .Title }}` in code samples. ssqch runs Markdown through a template engine first unless `markdownEngine: false`, so set that before the first build.
|
|
48
|
-
- **Shortcodes:** with `
|
|
50
|
+
- **Shortcodes:** with `fromHugo()`, a shortcode on a line of its own is a container ([Markdown](../markdown.md), "Containers"): `{{< note type="tip" >}}` to `{{< /note >}}` (or `{{% %}}`) renders `_includes/containers/note.*`, with `container.args` (what the call wrote), `container.props` (its `key="value"` parameters) `container.content` (the inside, rendered as Markdown) and `container.source` (the inside as written, for a `{{< >}}` shortcode, whose inside Hugo doesn't read as Markdown). One without a closing tag (`{{< youtube abc >}}`) has no content. Port each shortcode's Go template into its container template. A shortcode inside a line of text (`{{< new-in 0.148 />}}`, `[About]({{< ref "about" >}})`) renders through the same container template in its place, with `container.inline` true, so a template that's called both ways can check it: `{% if container.inline %}<span>...</span>{% else %}<div>...</div>{% endif %}`.
|
|
49
51
|
- **URLs:** Hugo lowercases paths and reads `slug` and `url`. In ssqch, `permalink` in front matter or directory data sets a page's URL; `computed` can make one from the path for every page.
|
|
50
52
|
- **Sections:** an `_index.md` is a section's list page. In ssqch it's a page like any other: give it a layout in its folder's directory data, and list its folder's pages with a collection: a tag, or one in the config (`collections: { functions: (api) => api.byGlob("content/functions/**") }`).
|
|
51
53
|
- **Page bundles:** a folder with `index.md` and its images is a bundle in both; set `bundles: true`.
|
|
@@ -9,7 +9,7 @@ opensource.guide (382 pages in 29 languages, on GitHub Pages' gem) was moved thi
|
|
|
9
9
|
|
|
10
10
|
## Scouting
|
|
11
11
|
|
|
12
|
-
`ssqch scout` (see [Scouting a site](../trailheads.md#scouting-a-site)) lists what this guide describes for your site, with file and line, and drafts the mechanical part. It reads the files a fresh checkout has: ones git doesn't track (notes, a scratch folder) are left out of `passthrough`, and listed. Its draft is a first `ssqch.config.js` from `_config.yml`: Liquid for Markdown and HTML pages, `layouts_dir`,
|
|
12
|
+
`ssqch scout` (see [Scouting a site](../trailheads.md#scouting-a-site)) lists what this guide describes for your site, with file and line, and drafts the mechanical part. It reads the files a fresh checkout has: ones git doesn't track (notes, a scratch folder) are left out of `passthrough`, and listed. Its draft is a first `ssqch.config.js` from `_config.yml`: Liquid for Markdown and HTML pages, `layouts_dir`, kramdown's Markdown options, `exclude` as `ignore`, the files Jekyll copies as they are (those without front matter) as `passthrough`, `site` read from `_config.yml`, the `defaults` for every page as data, and the plugins it knows (jekyll-sitemap, jekyll-redirect-from, jekyll-feed; Sass when there's a `_sass` folder or a stylesheet with front matter). It drafts directory data for `_posts` (the `posts` tag and the `permalink` style) and for each collection (its tag, its `defaults`, and its `permalink`, or none when `output` isn't true), and for the other folders `defaults` names. It turns on `fromJekyll()`, so layouts, includes and pages keep Jekyll's `page` and `site` as they're written (`page.title`, `site.posts`, `site.data.locales`, `post.title`). For what the plugins wrote beside the pages it drafts `_includes/seo.liquid` (jekyll-seo-tag's tags), `redirects.liquid` (jekyll-redirect-from's `/redirects.json`), `robots.liquid` (jekyll-sitemap's `/robots.txt`, when the site has none) and a redirect hook with the new URL whole; for a GitHub Pages site, `site.url` from `CNAME` (as jekyll-github-metadata gave it) and Rouge's markup on code. Its edits are only what's mechanical: `{% seo %}` includes `_includes/seo.liquid`, a `.rss` or `.xml` layout becomes `.liquid`, and a file with front matter in another extension gets `render` and a permalink. It lists the rest with file and line: where Jekyll's `excerpt` and `sort` mean something else, Jekyll's own `page` keys (`page.next`), plugins' tags, kramdown's attribute lists (`{: .class}`), each `_plugins/*.rb` and what it registers, and what each plugin is in ssqch. It changes nothing on its own: `--write-draft` writes the draft and `--patch move.patch` the edits, to read and `git apply`. opensource.guide went from a fresh checkout to a full build with no hand edits this way, and 306 of its 404 pages matched Jekyll's.
|
|
13
13
|
|
|
14
14
|
```sh
|
|
15
15
|
ssqch scout # what moving the site takes
|
|
@@ -25,10 +25,11 @@ Build the Jekyll site from a fresh checkout twice and compare the two: a page th
|
|
|
25
25
|
|
|
26
26
|
## The config
|
|
27
27
|
|
|
28
|
-
Start with `templateFormats: ["liquid", "md", "html"]`, `markdownEngine: "liquid"` and `htmlEngine: "liquid"`, so Markdown and HTML pages run through Liquid first, as in Jekyll, `dirs: { layouts: "_layouts" }
|
|
28
|
+
Start with `templateFormats: ["liquid", "md", "html"]`, `markdownEngine: "liquid"` and `htmlEngine: "liquid"`, so Markdown and HTML pages run through Liquid first, as in Jekyll, and `dirs: { layouts: "_layouts" }`. Jekyll drops the blank lines after a template's closing `---`, and ssqch keeps them: in HTML they're whitespace that browsers and `ssqch diff` don't see, but a feed has to start with `<?xml` and a text file's first line is its first line, so take the blank line out of those templates (`ssqch scout --patch` does).
|
|
29
29
|
|
|
30
30
|
```js
|
|
31
31
|
import { defineConfig, readData } from "ssqch";
|
|
32
|
+
import { fromJekyll } from "ssqch/from-jekyll";
|
|
32
33
|
import { sitemapPlugin } from "ssqch/sitemap";
|
|
33
34
|
import { redirectsPlugin } from "ssqch/redirects";
|
|
34
35
|
|
|
@@ -39,15 +40,15 @@ export default defineConfig({
|
|
|
39
40
|
markdownEngine: "liquid",
|
|
40
41
|
htmlEngine: "liquid",
|
|
41
42
|
dirs: { layouts: "_layouts" },
|
|
42
|
-
trimAfterFrontMatter: true,
|
|
43
|
-
// kramdown's habits: markdown="1", its heading ids, smart quotes, no bare-URL links.
|
|
44
|
-
markdown: { htmlMarkdown: "kramdown", headingIds: "kramdown", smartPunctuation: true, autolinks: false, encodeUrls: false },
|
|
45
43
|
ignore: ["Gemfile", "Gemfile.lock", "README.md", "script/**"],
|
|
46
44
|
data: { site },
|
|
47
|
-
|
|
45
|
+
// Jekyll's `page` and `site` in templates, and kramdown's Markdown.
|
|
46
|
+
plugins: [fromJekyll(), sitemapPlugin({ url: site.url }), redirectsPlugin()],
|
|
48
47
|
});
|
|
49
48
|
```
|
|
50
49
|
|
|
50
|
+
`fromJekyll()` from `ssqch/from-jekyll` is what a Jekyll site's templates and Markdown expect, as one plugin. `templates` (on by default) gives templates Jekyll's `page` and `site` (below). `kramdown` (on by default) is kramdown's habits, each a default your own `markdown` can change: Markdown inside `markdown="1"` HTML (`htmlMarkdown: "kramdown"`), kramdown's heading ids (`headingIds: "kramdown"`), smart quotes (`smartPunctuation: true`), and no links from bare URLs (`autolinks: false`). `fromJekyll({ templates: false })` leaves templates as ssqch's.
|
|
51
|
+
|
|
51
52
|
| Jekyll (`_config.yml`) | ssqch (`ssqch.config.js`) |
|
|
52
53
|
| --- | --- |
|
|
53
54
|
| `title`, `description`, `url`, any key | `readData("_config.yml")` as `data: { site }`, so `site.title` still works |
|
|
@@ -61,12 +62,12 @@ export default defineConfig({
|
|
|
61
62
|
|
|
62
63
|
## Templates
|
|
63
64
|
|
|
64
|
-
- **`page`, `site` and front matter:** `
|
|
65
|
-
- **`site.posts` and collections:** with `
|
|
65
|
+
- **`page`, `site` and front matter:** `fromJekyll()` (in scout's draft) gives templates Jekyll's `page` and `site`: `page.title` and the rest of the front matter, `site.posts` (newest first), `site.<collection>`, `site.data`, `site.categories` and `site.tags`, with items in Jekyll's shape (`post.title`, `post.content`, `post.excerpt`), so layouts and includes run as they're written. Without it, front matter is at the top level (`{{ title }}`), `page` has the file's facts (`page.url`, `page.inputPath`, `page.date`, `page.headings`), and items keep front matter under `data`; the build warns once for each `page.<key>` that's front matter.
|
|
66
|
+
- **`site.posts` and collections:** with `fromJekyll()`, `site.posts` and `site.articles` are there as in Jekyll. ssqch's own names for them are `collections.posts` and `collections.articles` (a folder's directory data tags its pages `articles`), whose items keep front matter under `data` (`post.data.title`, `| where: "data.lang", "fr"`), with `post.templateContent` and `post.page.excerpt`.
|
|
66
67
|
- **Excerpts:** Jekyll's `excerpt` is the source up to `excerpt_separator` (the first blank line by default), rendered; ssqch's `page.excerpt` is the rendered page up to a `<!-- more -->` comment, or else its first paragraph. They're the same for a post that starts with a paragraph; for one that starts with a heading, a list or a quote, put `<!-- more -->` where Jekyll's separator was. `excerpt_separator: <!--more-->` in `_config.yml` is the same as ssqch's.
|
|
67
68
|
- **A language menu and hreflang links** (each page's translations, looked up in a loop over every page): ssqch has no built-in i18n yet. The Liquid loop works as it is, but it runs on every page; a filter that groups the pages once is faster, `translations: (pages, url) => ...` in the config's `filters` (`ssqch docs "Multilingual sites"`).
|
|
68
69
|
- **Jekyll's tags:** `{% highlight ruby %}...{% endhighlight %}` writes Jekyll's `<figure class="highlight">` with ssqch's highlighter, and `{% link _posts/2016-07-26-pine.md %}` and `{% post_url 2016-07-26-pine %}` are that page's URL (a path no page has is an error that names it). A site's own `highlight` function keeps that tag.
|
|
69
|
-
- **`site.data`:** `_data` is global data (`site.data.locales` is `locales` in ssqch); with `
|
|
70
|
+
- **`site.data`:** `_data` is global data (`site.data.locales` is `locales` in ssqch); with `fromJekyll()`, `site.data.locales` works too.
|
|
70
71
|
- **Includes:** `{% include nav.html section="home" %}` works, with `include.section`, and so does `{% include_relative parts/intro.md %}`. A file read by `include_relative` is a page of its own too, if it's Markdown: give its folder `permalink: false` in directory data.
|
|
71
72
|
- **Plugin tags** (`{% seo %}`, `{% feed_meta %}`): an include, or a function in `filters` that returns the HTML: the config's functions are Liquid tags (`{% seo title=false %}` calls `seo({ title: false })`). A function sees only what it's given, so pass it the page and the front matter it reads (`{% seo page, title, description %}`). `ssqch docs "From jekyll-seo-tag"` has an include that writes jekyll-seo-tag's tags.
|
|
72
73
|
- **Filters:** `relative_url`, `markdownify` and `jsonify` work, and `where` is fast. Math, `split` and blocks that only `assign` behave as in Ruby's Liquid (`"r>" | times: 1` is 0, which jekyll-toc depends on). `xml_escape` (`'` as `'`), `normalize_whitespace`, `where_exp`, `group_by` and `sort` of a hash (into `[key, value]` pairs, by key) write what Jekyll's do. With a property, Jekyll's `sort` puts pages missing it first and ssqch's (Liquid's) last, so `sort` then handle the missing ones, or pass a list from the config. A whole float prints as `5` (Ruby writes `5.0`). `truncate` and `truncatewords` are Ruby's Liquid 4's. Front matter dates in Jekyll's form (`2009-12-25 10:41:06 +0000`) are read, and a key written twice is the last one, with a warning.
|
|
@@ -78,13 +79,53 @@ export default defineConfig({
|
|
|
78
79
|
| Jekyll | ssqch |
|
|
79
80
|
| --- | --- |
|
|
80
81
|
| jekyll-redirect-from | `redirect_from` works (ssqch calls it `aliases`, and templates read it as `aliases`: `p.data.aliases`), with `redirectsPlugin()`; `_includes/hooks/redirect.*` for its page's markup (`ssqch scout` drafts jekyll-redirect-from's). Its `redirects.json` is a template of your own over `collections.all`. |
|
|
81
|
-
| jekyll-sitemap | `sitemapPlugin({ url: site.url })
|
|
82
|
+
| jekyll-sitemap | `sitemapPlugin({ url: site.url })`. It needs the site's address: Jekyll's `url` (`url: https://example.com` in `_config.yml`, which `site.url` reads). jekyll-sitemap wrote paths from the root without one, which search engines can't read; ssqch's build stops and asks for it, and `ssqch scout` leaves the plugin commented out in its draft until `url` is there |
|
|
82
83
|
| jekyll-feed | `rssPlugin()` and a feed template |
|
|
83
|
-
| jekyll-seo-tag |
|
|
84
|
+
| jekyll-seo-tag | An include that writes its tags ([below](#from-jekyll-seo-tag), and `ssqch scout` drafts it), or a `seo` function (a tag) |
|
|
84
85
|
| jekyll-toc | `toc(page.headings, ...)`, above |
|
|
85
86
|
| jekyll-github-metadata | Data in the config (`site.github.repository_nwo`) |
|
|
86
87
|
| github-pages' default theme (jekyll-theme-primer) | Nothing: it writes `/assets/css/style.css`. Check whether a page links to it. |
|
|
87
88
|
|
|
89
|
+
## From jekyll-seo-tag
|
|
90
|
+
|
|
91
|
+
Jekyll's `{% seo %}` becomes an include, `{% include seo.liquid %}` in the layout. This one writes what jekyll-seo-tag 2.8 writes, in its order and its bytes, for a site whose `_config.yml` is read as `site` (`data: { site: readData("_config.yml") }`) and whose pages have `title`, `description` and `image` in front matter. As jekyll-seo-tag does, the title and description go through `markdownify` for their quotes and dashes; the canonical link and `og:url` need `site.url`; a dated page (front matter `date`, or a post's or collection's `tags`) is an `article` with its `published_time` and a `BlogPosting`; the home page (`/` or `/about/`) is a `WebSite` with a `name`; `site.twitter.username`, `site.facebook.publisher` and `site.logo` add their tags; and the generator is ssqch's (`ssqch scout`'s draft for a Jekyll site writes Jekyll's version there instead, from `Gemfile.lock`, so the first build matches). Add the tags for options this leaves out (authors, `fb:app_id`, webmaster verifications):
|
|
92
|
+
|
|
93
|
+
```liquid
|
|
94
|
+
{%- comment -%} _includes/seo.liquid {%- endcomment -%}
|
|
95
|
+
{%- assign site_title = site.title | default: site.name | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
96
|
+
{%- assign page_title = title | markdownify | strip_html | normalize_whitespace | escape_once | default: site_title -%}
|
|
97
|
+
{%- assign about = description | default: site.description | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
98
|
+
{%- if page_title != site_title -%}{%- assign full_title = page_title | append: " | " | append: site_title -%}{%- elsif site.description -%}{%- assign full_title = site_title | append: " | " | append: about -%}{%- else -%}{%- assign full_title = site_title -%}{%- endif -%}
|
|
99
|
+
{%- assign canonical = site.url | append: page.url -%}
|
|
100
|
+
{%- if image -%}{%- assign image_url = site.url | append: image -%}{%- endif -%}
|
|
101
|
+
{%- if date or tags -%}{%- assign published = page.date | date_to_xmlschema -%}{%- endif -%}
|
|
102
|
+
{%- if page.url == "/" or page.url == "/about/" -%}{%- assign ld_type = "WebSite" -%}{%- elsif published -%}{%- assign ld_type = "BlogPosting" -%}{%- else -%}{%- assign ld_type = "WebPage" -%}{%- endif -%}
|
|
103
|
+
<!-- Begin Jekyll SEO tag v2.8.0 -->
|
|
104
|
+
<title>{{ full_title }}</title>
|
|
105
|
+
<meta name="generator" content="{{ ssqch.generator }}" />
|
|
106
|
+
<meta property="og:title" content="{{ page_title }}" />
|
|
107
|
+
<meta property="og:locale" content="{{ lang | default: site.lang | default: "en_US" | replace: "-", "_" }}" />
|
|
108
|
+
{% if about %}<meta name="description" content="{{ about }}" />
|
|
109
|
+
<meta property="og:description" content="{{ about }}" />
|
|
110
|
+
{% endif %}{% if site.url %}<link rel="canonical" href="{{ canonical }}" />
|
|
111
|
+
<meta property="og:url" content="{{ canonical }}" />
|
|
112
|
+
{% endif %}<meta property="og:site_name" content="{{ site_title }}" />
|
|
113
|
+
{% if image_url %}<meta property="og:image" content="{{ image_url }}" />
|
|
114
|
+
{% endif %}{% if published %}<meta property="og:type" content="article" />
|
|
115
|
+
<meta property="article:published_time" content="{{ published }}" />
|
|
116
|
+
{% else %}<meta property="og:type" content="website" />
|
|
117
|
+
{% endif %}<meta name="twitter:card" content="{% if image_url %}summary_large_image{% else %}summary{% endif %}" />
|
|
118
|
+
{% if image_url %}<meta property="twitter:image" content="{{ image_url }}" />
|
|
119
|
+
{% endif %}<meta property="twitter:title" content="{{ page_title }}" />
|
|
120
|
+
{% if site.twitter.username %}<meta name="twitter:site" content="@{{ site.twitter.username | remove: "@" }}" />
|
|
121
|
+
{% endif %}{% if site.facebook.publisher %}<meta property="article:publisher" content="{{ site.facebook.publisher }}" />
|
|
122
|
+
{% endif %}<script type="application/ld+json">
|
|
123
|
+
{"@context":"https://schema.org","@type":{{ ld_type | jsonify }}{% if published %},"dateModified":{{ published | jsonify }},"datePublished":{{ published | jsonify }}{% endif %}{% if about %},"description":{{ about | jsonify }}{% endif %},"headline":{{ page_title | jsonify }}{% if image_url %},"image":{{ image_url | jsonify }}{% endif %}{% if ld_type == "BlogPosting" %},"mainEntityOfPage":{"@type":"WebPage","@id":{{ canonical | jsonify }}}{% endif %}{% if ld_type == "WebSite" %},"name":{{ site_title | jsonify }}{% endif %}{% if site.logo %},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":{{ site.url | append: site.logo | jsonify }}}}{% endif %},"url":{{ canonical | jsonify }}}</script>
|
|
124
|
+
<!-- End Jekyll SEO tag -->
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
A function can write all of it instead, when the template passes it what it needs: functions are Liquid tags too, so `{% seo page, title, description %}` calls `seo(page, title, description)` (a function doesn't see the page unless it's given). opensource.guide's port did that, writing jekyll-seo-tag's bytes, JSON-LD included, in 100 lines.
|
|
128
|
+
|
|
88
129
|
## Porting a site's own plugins
|
|
89
130
|
|
|
90
131
|
A Jekyll site's own Ruby plugins (`_plugins/*.rb`) can't run in ssqch, but each kind has an ssqch feature that does its job. `ssqch scout` lists each file with what it registers; port each to that feature, in a module of the site's own that the config imports (`lib/jekyll.js`), and build and compare with `ssqch diff` after each. www.ruby-lang.org's 8 plugins (705 lines of Ruby) became 572 lines of JavaScript.
|
|
@@ -103,13 +144,13 @@ What a plugin printed with Ruby's own methods (`strftime`, `Time#to_s`, `Hash` o
|
|
|
103
144
|
|
|
104
145
|
## Markdown
|
|
105
146
|
|
|
106
|
-
ssqch's Markdown is CommonMark; Jekyll's is kramdown. `
|
|
147
|
+
ssqch's Markdown is CommonMark; Jekyll's is kramdown. `fromJekyll()` turns on what comes closest. What differs:
|
|
107
148
|
|
|
108
149
|
- **`markdown="1"`** on an HTML element (kramdown reads its content as Markdown): `htmlMarkdown: "kramdown"` reads it the same way, and keeps kramdown's HTML rules (a block element is raw to its end tag, blank lines and all). Without it, ssqch writes the element as it is and Markdown inside stays text. A container (`::: name`) is ssqch's own way to wrap Markdown in HTML.
|
|
109
150
|
- **Heading ids:** `headingIds: "kramdown"` gives kramdown's: its GFM ids for the page's headings (accents and other letters kept, emoji dropped), and its ASCII ids for headings inside `markdown="1"` HTML (`section`, `section-1`). Repeats are counted within each, where kramdown counts them across the page.
|
|
110
151
|
- **Bold next to punctuation** (`**完成。**下一步`) closes in kramdown but not in CommonMark.
|
|
111
152
|
- **Code:** GitHub Pages adds Rouge's `class="language-plaintext highlighter-rouge"` to code; ssqch doesn't (`markdown: { highlight: true }` highlights, with its own classes). To keep those classes on code spans, write them in a `code` render hook: `_includes/hooks/code.liquid` with `<code class="language-plaintext highlighter-rouge">{{ code.code | escape }}</code>` ([Code spans](../markdown.md)).
|
|
112
|
-
- **Link URLs:** ssqch percent-encodes non-ASCII characters in them (`#كتابة` as `#%D9%83...`) and kramdown keeps them
|
|
153
|
+
- **Link URLs:** ssqch percent-encodes non-ASCII characters in them (`#كتابة` as `#%D9%83...`) and kramdown keeps them. Browsers go to the same place, and `ssqch diff` reads them as the same. Smart quotes next to non-Latin letters can come out differently; readers see the same page.
|
|
113
154
|
|
|
114
155
|
## Checking the move
|
|
115
156
|
|
|
@@ -16,16 +16,19 @@ export default defineConfig({
|
|
|
16
16
|
dirs: { input: "docs", output: "site", includes: "../_includes", data: "../_data" },
|
|
17
17
|
base: "/mkdocs-material/", // site_url's path
|
|
18
18
|
markdownEngine: false, // MkDocs doesn't run template code in pages
|
|
19
|
-
markdown: {
|
|
19
|
+
markdown: { highlight: { classes: "pygments" } },
|
|
20
20
|
passthrough: [{ "docs/**/*.png": "." }, { "docs/CNAME": "CNAME" }], // MkDocs copies the docs folder's other files
|
|
21
21
|
// MkDocs warns about a broken link unless strict: true, and so does the draft.
|
|
22
|
-
|
|
22
|
+
// MkDocs' Markdown: Python-Markdown's reading, admonitions, tabs, toc's ids, `.md` links.
|
|
23
|
+
plugins: [fromMkdocs(), sitemapPlugin({ url: "https://squidfunk.github.io/mkdocs-material" }), redirectsPlugin({ redirects: { "/old/": "/new/" } }), linksPlugin({ fail: false })],
|
|
23
24
|
});
|
|
24
25
|
```
|
|
25
26
|
|
|
27
|
+
`fromMkdocs()` from `ssqch/from-mkdocs` is MkDocs' Markdown as one plugin, each part a default your own `markdown` can change: `dialect: "python-markdown"` (a raw HTML block runs to its closing tag, lists nest at four spaces), `admonitions` and `tabs` as Material writes them, toc's heading ids (`headingIds: "python-markdown"`) and `.md` links from the page (`sourceLinks: "relative"`). `fromMkdocs({ templates: true, config: "mkdocs.yml" })` adds the theme's context, below.
|
|
28
|
+
|
|
26
29
|
## The theme
|
|
27
30
|
|
|
28
|
-
`
|
|
31
|
+
`fromMkdocs({ templates: true })` gives templates what MkDocs gives a theme's, so the theme's Jinja templates, Material for MkDocs' included, run as they're written: `config` (`mkdocs.yml`, with the theme's `mkdocs_theme.yml` under its `theme`), `nav` (MkDocs' Sections, Pages and Links, with `active` on the page being rendered), `page` (MkDocs' page, with `content`, `toc`, `meta`, `previous_page` and `next_page`), `base_url`, and the `url` and `script_tag` filters, which make URLs relative to the page. Each Markdown page renders with the theme's `main.html` (or its front matter's `template`), the theme's `404.html` makes `/404.html`, and Jinja doesn't escape, as MkDocs' doesn't. `ssqch docs fromMkdocs` has the details.
|
|
29
32
|
|
|
30
33
|
A theme from pip is Python's, so copy its templates into an ssqch theme: the templates in `_includes`, the files to copy (`assets/`) beside it. For Material:
|
|
31
34
|
|
|
@@ -38,9 +41,9 @@ mkdir -p theme/_includes && cp -R "$M"/. theme/_includes/ && mv theme/_includes/
|
|
|
38
41
|
export default defineConfig({
|
|
39
42
|
dirs: { input: "docs", output: "site", includes: "overrides" }, // theme.custom_dir, from docs_dir
|
|
40
43
|
theme: "theme",
|
|
41
|
-
mkdocsTemplates: true,
|
|
42
44
|
markdownEngine: false,
|
|
43
|
-
markdown: {
|
|
45
|
+
markdown: { highlight: { classes: "pygments" } },
|
|
46
|
+
plugins: [fromMkdocs({ templates: true })],
|
|
44
47
|
});
|
|
45
48
|
```
|
|
46
49
|
|
|
@@ -52,7 +55,7 @@ On the httpx docs (Material, 24 pages), this config, with no template changed an
|
|
|
52
55
|
| --- | --- |
|
|
53
56
|
| `docs_dir`, `site_dir` | `dirs: { input, output }` |
|
|
54
57
|
| `nav:` | `_data/nav.yml`, in the shape the nav helpers read: `- { title: Install, url: /install/ }`, with sections holding `children` (or `items`, `pages`). `navTree(nav, page.url)` marks the current page and its sections, `navPager` gives previous and next, `navBreadcrumbs` the trail. |
|
|
55
|
-
| `theme: material` and its options | The theme's own templates with `
|
|
58
|
+
| `theme: material` and its options | The theme's own templates with `fromMkdocs({ templates: true })` ([The theme](#the-theme), below), or templates of your own (start from `docs-sidebar`) |
|
|
56
59
|
| `theme.custom_dir` / `overrides/` (Jinja) | The includes folder (`dirs.includes`, which the draft sets to it): read before a theme's, so a template there replaces the theme's of the same name; `{% extends %}`, blocks and macros work |
|
|
57
60
|
| `extra:` | `_data/site.yml` |
|
|
58
61
|
| `use_directory_urls: true` | The default: `install.md` is `/install/` |
|
|
@@ -62,22 +65,22 @@ On the httpx docs (Material, 24 pages), this config, with no template changed an
|
|
|
62
65
|
| `mkdocs-macros` (Jinja in Markdown) | Built in: Markdown runs through Jinja first (`markdownEngine: "jinja"`, the default) |
|
|
63
66
|
| `extra_css` with Sass | `sassPlugin()` from `ssqch/sass` |
|
|
64
67
|
| `strict: true` | `linksPlugin()` fails the build on a broken link (`linksPlugin({ fail: false })` warns, as MkDocs does without `strict`), and `strict: true` for undefined template values |
|
|
65
|
-
| `404.html`, `sitemap.xml.gz` (written by MkDocs) | With `
|
|
68
|
+
| `404.html`, `sitemap.xml.gz` (written by MkDocs) | With `fromMkdocs({ templates: true })`, the theme's `404.html` makes `/404.html`; otherwise a page with `permalink: /404.html`. `sitemapPlugin()` writes `sitemap.xml`, and the gzipped copy is an `afterBuild` step (`node:zlib`) |
|
|
66
69
|
|
|
67
70
|
## Markdown extensions
|
|
68
71
|
|
|
69
72
|
| Python-Markdown / PyMdown | SiteSquatch |
|
|
70
73
|
| --- | --- |
|
|
71
|
-
| `admonition`: `!!! note "Title"` and an indented body | `
|
|
72
|
-
| `pymdownx.details`: `??? note` | `
|
|
73
|
-
| `pymdownx.tabbed`: `=== "Tab"` | `
|
|
74
|
+
| `admonition`: `!!! note "Title"` and an indented body | `fromMkdocs()` reads them as they are, and writes Python-Markdown's markup (`<div class="admonition note">`), which Material's CSS styles. Or, in ssqch's own syntax, a container: `::: note Title` ... `:::`. GitHub's `> [!NOTE]` works too. |
|
|
75
|
+
| `pymdownx.details`: `??? note` | `fromMkdocs()` too: `<details class="note">`, open with `???+`. Or a container whose template writes `<details>` (see `docs-sidebar`'s `details` container) |
|
|
76
|
+
| `pymdownx.tabbed`: `=== "Tab"` | `fromMkdocs()` reads them as they are, in the alternate style's markup. Or `:::: tabs` holding `::: tab Name` containers (see `versioned-docs`) |
|
|
74
77
|
| `pymdownx.superfences` custom fences (`mermaid`) | A `fence-mermaid` hook |
|
|
75
78
|
| `pymdownx.highlight`, `codehilite`, `hl_lines="2 3"` | `markdown: { highlight: { classes: "pygments" } }`, with Pygments' class names for the theme's CSS, and `{2,3}` in the fence's info string. The tokens are cut by ssqch's grammars, not Pygments', and the wrapper (`<div class="highlight"><pre><span></span><code>`) is a fence hook's (`_includes/hooks/fence.jinja`, which the draft writes), so the theme's styles fit, but not byte for byte |
|
|
76
79
|
| `mkautodoc`, `mkdocstrings` (`::: package.module`) | Not in ssqch yet: Python writes the API pages. Their `:::` lines would read as ssqch's containers, so set `markdown: { containers: false }` (the draft does), and render the pages with the extension in Python |
|
|
77
80
|
| `pymdownx.snippets`: `--8<-- "file.py"` | `{% include "samples/file.py" %}` inside the fence |
|
|
78
|
-
| `toc` with `permalink: true` | `
|
|
81
|
+
| `toc` with `permalink: true` | `fromMkdocs()` gives toc's default ids (`headingIds: "python-markdown"`) (a repeated heading gets `_1`, as toc writes it); a heading hook adds the permalink. `toc(page.headings)` builds the table of contents. |
|
|
79
82
|
| `attr_list`: `## Title { #id }` | `## Title {#id}` |
|
|
80
|
-
| Links to other pages' `.md` files | `
|
|
83
|
+
| Links to other pages' `.md` files | `fromMkdocs()` (`sourceLinks: "relative"`): each goes to that page's URL, written from the page as MkDocs writes it, and images and other files are read from the Markdown file's folder too |
|
|
81
84
|
| `footnotes`, `tables` | Built in |
|
|
82
85
|
| `def_list` | `markdown: { definitionLists: true }` |
|
|
83
86
|
| `md_in_html` (`markdown="1"`) | The `markdown` filter, or a container |
|
|
@@ -13,6 +13,7 @@ VitePress builds each Markdown page into a Vue component and ships a client app
|
|
|
13
13
|
// ssqch.config.js, as scout drafts it for vuejs.org
|
|
14
14
|
import { sitemapPlugin } from "ssqch/sitemap";
|
|
15
15
|
import { vuePlugin } from "ssqch/vue";
|
|
16
|
+
import { fromVitepress } from "ssqch/from-vitepress";
|
|
16
17
|
|
|
17
18
|
export default {
|
|
18
19
|
dirs: { input: "src", output: "dist" },
|
|
@@ -21,10 +22,11 @@ export default {
|
|
|
21
22
|
urls: "html",
|
|
22
23
|
ignore: ["api/api.data.ts", "error-reference/errors.data.ts", "examples/examples.data.ts", "tutorial/tutorial.data.ts", "tutorial/**/description.md", ".vitepress/**", "public/**"],
|
|
23
24
|
passthrough: { "src/public/**": "." },
|
|
24
|
-
markdown: {
|
|
25
|
+
markdown: { highlight: true },
|
|
25
26
|
plugins: [
|
|
27
|
+
fromVitepress(),
|
|
26
28
|
vuePlugin({ components: { VueSchoolLink: ".vitepress/theme/components/VueSchoolLink.vue", ScrimbaLink: ".vitepress/theme/components/ScrimbaLink.vue" }, hydrate: "visible" }),
|
|
27
|
-
sitemapPlugin({ url: "https://vuejs.org"
|
|
29
|
+
sitemapPlugin({ url: "https://vuejs.org" }),
|
|
28
30
|
],
|
|
29
31
|
};
|
|
30
32
|
```
|
|
@@ -34,29 +36,29 @@ export default {
|
|
|
34
36
|
- **`ignore`:** VitePress's data loaders are `*.data.ts`, and `api/api.data.ts` is the name ssqch gives a folder's data. Listed by their paths, they aren't read as data, and the `.data.js` files the move adds (a dynamic route's pagination) still are; `vuePlugin()` runs the loaders for the components and pages that import their `data`.
|
|
35
37
|
- **`vuePlugin()`:** the Vue components the pages use, rendered with your Vite and Vue (`npm install -D vite @vitejs/plugin-vue vue`, which a VitePress site has already), with the ones the theme registers for every page in `components`, and `hydrate: "visible"` when one has state.
|
|
36
38
|
- **`passthrough: { "src/public/**": "." }`:** `public/`'s files at the site's root. `{ "src/public": "." }` would copy the folder by its name.
|
|
37
|
-
- **`
|
|
39
|
+
- **`fromVitepress()`** from `ssqch/from-vitepress`: VitePress's Markdown (below), as one plugin. It turns on VitePress's heading ids and email autolinks unless your `markdown` sets them, and a template of yours with a hook's or container's name replaces its markup.
|
|
38
40
|
|
|
39
41
|
## What maps
|
|
40
42
|
|
|
41
43
|
| VitePress | SiteSquatch |
|
|
42
44
|
| --- | --- |
|
|
43
45
|
| Pages, front matter, `{#id}` on headings | The same |
|
|
44
|
-
| `::: tip`, `info`, `warning`, `danger`, `details`, `raw`, `code-group` | `
|
|
45
|
-
| A closing `:::` indented under a list (Prettier writes them) |
|
|
46
|
-
| Heading anchors, `tabindex`, VitePress's ids |
|
|
47
|
-
| Links to `.md` files, external links in a new tab |
|
|
48
|
-
| Code blocks, `[title]`, `vue-html`, `-vue` fences |
|
|
46
|
+
| `::: tip`, `info`, `warning`, `danger`, `details`, `raw`, `code-group` | `fromVitepress()` writes VitePress's markup, default titles and all. A template in `_includes/containers/tip.*` replaces one. |
|
|
47
|
+
| A closing `:::` indented under a list (Prettier writes them) | The same: it closes its container |
|
|
48
|
+
| Heading anchors, `tabindex`, VitePress's ids | `fromVitepress()`'s heading, with `headingIds: "vitepress"` (`What's Vue?` is `what-s-vue`) |
|
|
49
|
+
| Links to `.md` files, external links in a new tab | `fromVitepress()`'s links: `.html` with `urls: "html"`, `./` in front of a relative one, `target="_blank" rel="noreferrer"` on an external one |
|
|
50
|
+
| Code blocks, `[title]`, `vue-html`, `-vue` fences | `fromVitepress()`'s wrapper, copy button and label; `highlight: true` for colors, with ssqch's classes rather than Shiki's |
|
|
49
51
|
| `[[toc]]` | The same, in any case |
|
|
50
|
-
| `<script setup>`, `<style>`, `<ClientOnly>` in a page | Left out by
|
|
52
|
+
| `<script setup>`, `<style>`, `<ClientOnly>` in a page | Left out by `fromVitepress()`, as VitePress writes none of it |
|
|
51
53
|
| A component in a page (`<VueSchoolLink href="..." />`) | A template in `_includes/components/VueSchoolLink.*`, with `component.props` and `component.content` ([components](../templates.md)) |
|
|
52
|
-
| A `.vue` component a page imports, or the theme registers | `vuePlugin()` from `ssqch/vue` renders it with your Vite and Vue at build time
|
|
54
|
+
| A `.vue` component a page imports, or the theme registers | `vuePlugin()` from `ssqch/vue` renders it with your Vite and Vue at build time; with `fromVitepress()`, VitePress's loaders and `useData()` work in it too; `hydrate: "visible"` runs it in the browser as an island (the vuejs.org demos work this way). Scout drafts it, with the theme's `app.component()`s. |
|
|
53
55
|
| A component with state, without Vue | Its HTML from a template, and what it does from a custom element in `ssqch/elements` |
|
|
54
56
|
| `themeConfig.nav` and `sidebar` | Data: move them to `_data/themeConfig.js` and import that file in `.vitepress/config.ts`, so both read one list. `navTree` marks the page you're on; a sidebar keyed by path is the longest key the page's URL starts with. In Jinja, read `link.get("items")`: `link.items` is the dict's method where there's no key. |
|
|
55
57
|
| The default theme's `Layout`, a theme's slots | A layout in `_includes/`. The theme's markup is in your build's HTML; `toc()`, `navTree` and `navPager` make the outline, the sidebar and the pager. |
|
|
56
58
|
| `page: true`, `layout: home` | `page` is ssqch's own (it's warned about): give those pages a layout of their own (`layout: home.jinja`) |
|
|
57
59
|
| `[param].md` with `[param].paths.ts` | `pagination` over the same list, `size: 1`, a `permalink` with the item's value, and `addAllPagesToCollections: true`, in `[param].data.js` beside the page |
|
|
58
60
|
| `head` in the config | The layout's `<head>` |
|
|
59
|
-
| `sitemap: { hostname }` | `sitemapPlugin({ url
|
|
61
|
+
| `sitemap: { hostname }` | `sitemapPlugin({ url })`, with the same URLs. The file is ssqch's own (a tag a line, pages by URL, with `<lastmod>`; `lastmod: false` leaves it out), so `ssqch diff` lists `sitemap.xml` as changed, and that's expected: no reader of a sitemap needs VitePress's bytes |
|
|
60
62
|
| `markdown.config(md)` plugins | A render hook, a container, or `markdown.preprocess` |
|
|
61
63
|
| `vitepress-plugin-llms` | `llmsPlugin()` from `ssqch/llms`: `llms.txt`, a Markdown copy of each page and `llms-full.txt` |
|
|
62
64
|
|
|
@@ -13,9 +13,9 @@ Everything migrates eventually. The trailheads map another generator's config, f
|
|
|
13
13
|
- **A summary first:** how many things there are to do, across how many pages, and how many of them ssqch does as it is, an option does (the draft turns it on), are not in ssqch yet, or are the site's own code to port. It's the first answer to "how big is this move?".
|
|
14
14
|
- **To do:** what the site uses that needs doing in ssqch, each with its file and line, ssqch's way to do it, or "not in ssqch yet", the most files first. A thing used many times is one line, with a count and the first place it's used. Each line is marked `[option]` (an option does it, in the draft), `[not yet]` or `[port]` (the site's own code: templates, plugins, hooks); a line without a mark is something ssqch does.
|
|
15
15
|
- **Draft:** the new files a move starts with: a first `ssqch.config.js` from the old config, directory data for posts and collections, includes and render hooks for the old generator's plugins. `--write-draft` writes the ones that aren't there, and never overwrites a file.
|
|
16
|
-
- **Edits:** the changes to the site's own files that are mechanical and clearly right (a data file's name, an image attribute, `{% seo %}` to an include, a `package.json` script). `--patch move.patch` writes them as a patch to read and apply with `git apply move.patch`; scout never applies it. It doesn't rewrite templates: where a template would need a rewrite, ssqch has the compatibility instead (`
|
|
16
|
+
- **Edits:** the changes to the site's own files that are mechanical and clearly right (a data file's name, an image attribute, `{% seo %}` to an include, a `package.json` script). `--patch move.patch` writes them as a patch to read and apply with `git apply move.patch`; scout never applies it. It doesn't rewrite templates: where a template would need a rewrite, ssqch has the compatibility instead (`fromJekyll()` and the other trailheads' modules, Eleventy's front matter keys as aliases), or the list says so.
|
|
17
17
|
|
|
18
|
-
It changes nothing unless it's asked, so it's safe to run again during a move: the draft files you've written show as there already, applied edits are gone from the list, an `[option]` the site's `ssqch.config.js` sets already is done (scout loads the config and checks each value the option names: `3 done already: ssqch.config.js has
|
|
18
|
+
It changes nothing unless it's asked, so it's safe to run again during a move: the draft files you've written show as there already, applied edits are gone from the list, an `[option]` the site's `ssqch.config.js` sets already is done (scout loads the config and checks each value the option names: `3 done already: ssqch.config.js has fromMkdocs, ...`), and so is an Eleventy to-do the config does under the same name: a filter, shortcode or tag in `filters`, a collection in `collections`, a transform in `transforms`, a plugin's work by ssqch's plugin (`rssPlugin()` for the RSS plugin and its filters, `minifyPlugin()` for an `htmlmin` transform), a library by `engines: { md }` or the `markdown` options, or the old package itself, imported in `ssqch.config.js` for an identical first build. The config's own imports of Eleventy's packages aren't to-dos, and only data in the input folder is Eleventy's data (a JSON file elsewhere, such as a saved scout report, is left alone). What's left is what still needs doing. An option that's a plugin call or a list stays on the list for you to check, and a config that doesn't load says why and counts nothing as done. `--compare` also builds the site with ssqch and compares the output with the reference build (`ssqch baseline`'s `ref-common`, or `ref-1`; `--reference <dir>` names another), and adds the result to the report: how many files differ, and the biggest groups of differences, the most files first, with the first file and the change. It builds with the clock `ssqch baseline` pins (`TZ=UTC`, and `SOURCE_DATE_EPOCH` at the HEAD commit's time, or 2026-01-01 outside git; one you set wins), so a sitemap's dates aren't a difference of their own. The comparison is the normalized one `ssqch diff` makes; `ssqch diff --exact` checks byte for byte. Fix the top group, and run `ssqch scout --compare` again: it's the move's loop in one command.
|
|
19
19
|
|
|
20
20
|
`--format json` prints the same report for agents and scripts: `generator`, `detectedBy`, `underWay` (an `ssqch.config.js` is there), `configError` (why it couldn't be read, or `null`), `summary` (`pages`, how many to-dos are `ssqch`, `option`, `notYet` and `site`, and how many are `done`), `build` (`command`, `output`, `baseline`, `needs`), `todo` (`at`, `what`, a stable `code` such as `hugo-shortcode` or `mkdocs-admonitions`, `status`: `ssqch`, `option`, `not-yet` or `site`, `count` and `files` when it's counted, `option` for the config that does it, and `docs` for an `ssqch docs` query), `done` (the to-dos the config does already: `at`, `what`, `code`, `option`), `draft` (`path`, `from`, `there`), `edits` (`path`, `to` for a rename, `changes`), `wroteDraft`, `patch`, `trailhead`, and with `--compare`, `compare` (`reference`, `output`, `built`, `errors`, `same`, `summary`, `groups` with `files`, `kind`, `first`, `removed` and `added`, `files` with the paths `changed`, `added` and `removed`, the first 20 of each, and `problem` when there was nothing to compare).
|
|
21
21
|
|
|
@@ -26,7 +26,7 @@ git apply move.patch # after reading it
|
|
|
26
26
|
ssqch scout # later: what's left
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
What it reads in depth: Eleventy (the config and the modules it loads, filters and shortcodes, plugins, data files, `package.json`), Jekyll (`_config.yml`, the Gemfile's plugins, collections, `_plugins/*.rb`, templates that read Jekyll's `page` and `site`), Zola (`config.toml`, sections, Tera templates and shortcodes), Hugo (shortcodes and their calls, sections and `cascade`, render hooks, Go templates and Hugo Pipes; the draft turns on `
|
|
29
|
+
What it reads in depth: Eleventy (the config and the modules it loads, filters and shortcodes, plugins, data files, `package.json`), Jekyll (`_config.yml`, the Gemfile's plugins, collections, `_plugins/*.rb`, templates that read Jekyll's `page` and `site`), Zola (`config.toml`, sections, Tera templates and shortcodes), Hugo (shortcodes and their calls, sections and `cascade`, render hooks, Go templates and Hugo Pipes; the draft turns on `fromHugo()` and has a container template to port for each of the site's shortcodes) and MkDocs (`mkdocs.yml`'s nav, theme, plugins and Markdown extensions, and the MkDocs syntax the pages use: admonitions, tabs, `.md` links, icons; the draft turns on the options that read them as they are, and writes the nav as `_data/nav.yml`) and VitePress (`.vitepress/config.ts`'s `srcDir`, `srcExclude`, `cleanUrls`, sitemap, `head` and markdown-it plugins, and what the pages use: Vue's `<script setup>`, containers and Prettier's indented `:::`, every component by name with its `.vue` file and whether it has state, the front matter the theme reads, data loaders and dynamic routes; the draft turns on `fromVitepress()`, `urls`, `ignore` for the loaders and the sitemap, and a component counts as done once it has a template). For Docusaurus (MDX and its imports, `<Tabs>`, admonitions, the sidebar, versions, plugins), Astro (`.astro` and framework components, content collections, integrations) and Hexo (tag plugins, the theme, scaffolds, plugins) it lists what the pages use, without a draft yet. If it finds no generator's files, or two generators', it says so and asks for `--from`.
|
|
30
30
|
|
|
31
31
|
|
|
32
32
|
## Words you bring with you
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
2
|
+
title: "Following the tracks: where a value comes from"
|
|
3
3
|
description: "A page's data is a cascade."
|
|
4
4
|
---
|
|
5
5
|
A page's data is a cascade. From the lowest level to the highest:
|
|
@@ -13,10 +13,10 @@ A page's data is a cascade. From the lowest level to the highest:
|
|
|
13
13
|
|
|
14
14
|
A higher level replaces what a lower one set. Objects merge key by key and lists are joined (a post's `tags` add to its folder's), unless `deepMerge` is off. `page` and `ssqch` are built in.
|
|
15
15
|
|
|
16
|
-
When a value isn't what you expected, `ssqch
|
|
16
|
+
When a value isn't what you expected, `ssqch trace` follows its tracks back to the level that set it. Give it a page's URL or its template's path:
|
|
17
17
|
|
|
18
18
|
```sh
|
|
19
|
-
ssqch
|
|
19
|
+
ssqch trace /guides/pine/
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
```text
|
|
@@ -39,7 +39,7 @@ ssqch inspect /guides/pine/
|
|
|
39
39
|
`--field` shows one value in full, with every level that set it:
|
|
40
40
|
|
|
41
41
|
```sh
|
|
42
|
-
ssqch
|
|
42
|
+
ssqch trace src/guides/2024-03-02-pine.md --field level
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
```text
|
|
@@ -52,6 +52,6 @@ Set by (the last one wins):
|
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
- **Inside a value:** a dotted path reaches into objects (`--field site.author.name`, `--field hero.alt`).
|
|
55
|
-
- **Pages made by pagination:** a template that makes many pages needs the URL of one of them. `ssqch
|
|
55
|
+
- **Pages made by pagination:** a template that makes many pages needs the URL of one of them. `ssqch trace src/tags.jinja` lists them.
|
|
56
56
|
- **Scripts and agents:** `--format json` prints the report as JSON (`schemaVersion: 1`), with `value`, `from` and `setBy` for each field.
|
|
57
57
|
- **No page is built:** it reads the site as a build does, up to the point of rendering. `beforeBuild` hooks run, since data can depend on them (a command that writes a data file, a plugin that sets itself up there), but no page is rendered or written, and `afterBuild` doesn't run. Standard output is only the report; anything a hook or `console.log` prints goes to standard error.
|