ssqch 0.11.0 → 0.13.0
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 +67 -9
- package/bundled/completions/elvish +24 -4
- package/bundled/completions/fish +37 -25
- package/bundled/completions/powershell +26 -4
- package/bundled/completions/zsh +45 -10
- package/bundled/docs/agents.md +2 -2
- package/bundled/docs/build-summary.md +1 -1
- package/bundled/docs/comparing-builds.md +7 -4
- package/bundled/docs/configuring.md +7 -12
- package/bundled/docs/deploying.md +1 -1
- package/bundled/docs/field-guide.md +4 -4
- package/bundled/docs/github-pages.md +2 -1
- 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 +11 -13
- package/bundled/docs/nav.yml +6 -1
- package/bundled/docs/netlify.md +4 -2
- package/bundled/docs/patrol.md +48 -0
- package/bundled/docs/plugins.md +6 -4
- package/bundled/docs/robots.md +72 -0
- package/bundled/docs/seo.md +2 -38
- package/bundled/docs/serving-markdown.md +142 -0
- package/bundled/docs/template-languages.md +2 -1
- package/bundled/docs/templates.md +2 -1
- package/bundled/docs/trailheads/from-component-frameworks.md +9 -10
- 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 +142 -0
- package/bundled/docs/trailheads.md +5 -5
- package/bundled/docs/where-values-come-from.md +5 -5
- package/bundled/docs/writing-plugins.md +69 -0
- package/bundled/ssqch.d.ts +150 -34
- 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 +13 -11
- package/lib/chunk-25WERNDD.js +112 -0
- package/lib/{chunk-H5K2ZE7B.js → chunk-2BJFGKOE.js} +13 -5
- package/lib/chunk-2FKYWYAB.js +268 -0
- package/lib/{chunk-LJOURBYT.js → chunk-3ZTRIO6O.js} +21 -19
- package/lib/{chunk-IOBC665M.js → chunk-4AZFCSGJ.js} +5 -3
- package/lib/{chunk-HWW5NCVJ.js → chunk-4Q6WMTER.js} +1 -1
- package/lib/{chunk-V2FSMOFX.js → chunk-55WXDGO4.js} +3 -3
- package/lib/{chunk-ZR3JYLFB.js → chunk-6FY77I4M.js} +331 -58
- package/lib/{chunk-JC54PHIT.js → chunk-6OUCRDYI.js} +514 -141
- package/lib/{chunk-ERAIEV3O.js → chunk-6U5VIQVY.js} +9 -7
- package/lib/{chunk-Z5OP43HU.js → chunk-7U5GWTEH.js} +455 -94
- package/lib/{chunk-CMJ7X5WW.js → chunk-AIJNG6MJ.js} +3 -2
- package/lib/{chunk-3K237XAX.js → chunk-C2Q7JKFI.js} +12 -10
- package/lib/{chunk-GS5B3CBW.js → chunk-DDV6JEC2.js} +1 -1
- package/lib/{chunk-A75EVUJX.js → chunk-DFJFHULZ.js} +47 -20
- package/lib/{chunk-KZZS4W2V.js → chunk-ENWDM2RW.js} +45 -42
- package/lib/{chunk-I3HYKEEW.js → chunk-ER72RPD6.js} +3 -3
- package/lib/chunk-F3JPNFCZ.js +23 -0
- package/lib/{chunk-B5E27PLU.js → chunk-FENJHLNM.js} +6 -3
- package/lib/{chunk-UU43WIZG.js → chunk-FJML7INB.js} +4 -2
- package/lib/{chunk-KCF2Z6N7.js → chunk-FQZDUDFK.js} +5 -3
- package/lib/{chunk-GJNIQAIH.js → chunk-GSNRAGKQ.js} +13 -6
- package/lib/{chunk-443ZQLVX.js → chunk-GU7BBYWB.js} +5 -4
- package/lib/{chunk-X2GAVYV2.js → chunk-HDKU6LRI.js} +110 -748
- package/lib/chunk-J3C2LEW7.js +121 -0
- package/lib/{chunk-XS4EJSEK.js → chunk-K5WZ2VYK.js} +7 -5
- package/lib/{chunk-3HZZY3Y7.js → chunk-OOKBXQAY.js} +7 -6
- package/lib/chunk-P2WS4RM4.js +707 -0
- package/lib/{chunk-RBNPBTDP.js → chunk-SNQOHNXE.js} +1 -1
- package/lib/{chunk-HFSWUTXX.js → chunk-SPIFZBIW.js} +1 -1
- package/lib/{chunk-QLUTNR37.js → chunk-T5IUI7W7.js} +12 -11
- package/lib/{chunk-ZINLHOX4.js → chunk-TGSVSG2G.js} +3 -2
- package/lib/{chunk-2L3HR67O.js → chunk-U2KEMVXO.js} +24 -16
- package/lib/{chunk-RYIWYWRQ.js → chunk-UHRBPZ4A.js} +7 -5
- package/lib/{chunk-2QTJTEBV.js → chunk-ULCT3PAV.js} +1 -1
- package/lib/{chunk-FCM3NYFR.js → chunk-UZNUS7RP.js} +12 -9
- package/lib/{chunk-GLJQ4C76.js → chunk-V3G2QGL3.js} +13 -106
- package/lib/{chunk-Z44IAMNG.js → chunk-VILOEVK7.js} +60 -28
- package/lib/chunk-VJWQSYEG.js +119 -0
- package/lib/{chunk-5ELAUHRL.js → chunk-WGAIE3DD.js} +23 -19
- package/lib/{chunk-OQGXZYZS.js → chunk-WUCRAV36.js} +13 -7
- package/lib/{chunk-RZYAIX2R.js → chunk-XYAWJTHM.js} +11 -10
- package/lib/{chunk-OSBEH67S.js → chunk-YA23NDMW.js} +5 -3
- package/lib/{chunk-AIMEXBTK.js → chunk-YNJNMQWU.js} +37 -142
- package/lib/{chunk-QJ5ZFTML.js → chunk-ZMG25MXF.js} +20 -18
- package/lib/cli.js +72 -35
- package/lib/elements.js +13 -11
- 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 +12 -11
- package/lib/links.js +13 -11
- package/lib/llms.js +613 -0
- package/lib/minify.js +14 -12
- package/lib/redirects.js +13 -11
- package/lib/robots.js +87 -0
- package/lib/rss.js +24 -13
- package/lib/sass.js +12 -11
- package/lib/sitemap.js +23 -18
- package/lib/ssqch.js +6 -5
- package/lib/vue.js +400 -0
- package/package.json +29 -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 +51 -31
- package/types/llms.d.ts +27 -0
- package/types/robots.d.ts +13 -0
- package/types/sass.d.ts +1 -1
- package/types/sitemap.d.ts +2 -2
- package/types/vue.d.ts +17 -0
- package/wasm/markdown.wasm +0 -0
- package/lib/chunk-RVXGUMFI.js +0 -21
- /package/lib/{chunk-ZR3JYLFB.js.LEGAL.txt → chunk-6FY77I4M.js.LEGAL.txt} +0 -0
- /package/lib/{chunk-AIMEXBTK.js.LEGAL.txt → chunk-YNJNMQWU.js.LEGAL.txt} +0 -0
package/bundled/docs/seo.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "SEO tags"
|
|
2
|
+
title: "Getting spotted: SEO tags"
|
|
3
3
|
description: "ssqch writes no <head> tags of its own, so a site's title, description, canonical link, Open Graph and Twitter tags are a partial in its layout."
|
|
4
4
|
---
|
|
5
5
|
ssqch writes no `<head>` tags of its own, so a site's title, description, canonical link, Open Graph and Twitter tags are a partial in its layout. A starting point (Nunjucks):
|
|
@@ -18,40 +18,4 @@ ssqch writes no `<head>` tags of its own, so a site's title, description, canoni
|
|
|
18
18
|
|
|
19
19
|
JSON-LD, if the site wants it, is a `json` (Liquid), `tojson` (Jinja) or `dump` (Nunjucks) of an object built in the template or by a filter.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
```liquid
|
|
24
|
-
{%- comment -%} _includes/seo.liquid {%- endcomment -%}
|
|
25
|
-
{%- assign site_title = site.title | default: site.name | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
26
|
-
{%- assign page_title = title | markdownify | strip_html | normalize_whitespace | escape_once | default: site_title -%}
|
|
27
|
-
{%- assign about = description | default: site.description | markdownify | strip_html | normalize_whitespace | escape_once -%}
|
|
28
|
-
{%- 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 -%}
|
|
29
|
-
{%- assign canonical = site.url | append: page.url -%}
|
|
30
|
-
{%- if image -%}{%- assign image_url = site.url | append: image -%}{%- endif -%}
|
|
31
|
-
{%- if date or tags -%}{%- assign published = page.date | date_to_xmlschema -%}{%- endif -%}
|
|
32
|
-
{%- if page.url == "/" or page.url == "/about/" -%}{%- assign ld_type = "WebSite" -%}{%- elsif published -%}{%- assign ld_type = "BlogPosting" -%}{%- else -%}{%- assign ld_type = "WebPage" -%}{%- endif -%}
|
|
33
|
-
<!-- Begin Jekyll SEO tag v2.8.0 -->
|
|
34
|
-
<title>{{ full_title }}</title>
|
|
35
|
-
<meta name="generator" content="{{ ssqch.generator }}" />
|
|
36
|
-
<meta property="og:title" content="{{ page_title }}" />
|
|
37
|
-
<meta property="og:locale" content="{{ lang | default: site.lang | default: "en_US" | replace: "-", "_" }}" />
|
|
38
|
-
{% if about %}<meta name="description" content="{{ about }}" />
|
|
39
|
-
<meta property="og:description" content="{{ about }}" />
|
|
40
|
-
{% endif %}{% if site.url %}<link rel="canonical" href="{{ canonical }}" />
|
|
41
|
-
<meta property="og:url" content="{{ canonical }}" />
|
|
42
|
-
{% endif %}<meta property="og:site_name" content="{{ site_title }}" />
|
|
43
|
-
{% if image_url %}<meta property="og:image" content="{{ image_url }}" />
|
|
44
|
-
{% endif %}{% if published %}<meta property="og:type" content="article" />
|
|
45
|
-
<meta property="article:published_time" content="{{ published }}" />
|
|
46
|
-
{% else %}<meta property="og:type" content="website" />
|
|
47
|
-
{% endif %}<meta name="twitter:card" content="{% if image_url %}summary_large_image{% else %}summary{% endif %}" />
|
|
48
|
-
{% if image_url %}<meta property="twitter:image" content="{{ image_url }}" />
|
|
49
|
-
{% endif %}<meta property="twitter:title" content="{{ page_title }}" />
|
|
50
|
-
{% if site.twitter.username %}<meta name="twitter:site" content="@{{ site.twitter.username | remove: "@" }}" />
|
|
51
|
-
{% endif %}{% if site.facebook.publisher %}<meta property="article:publisher" content="{{ site.facebook.publisher }}" />
|
|
52
|
-
{% endif %}<script type="application/ld+json">
|
|
53
|
-
{"@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>
|
|
54
|
-
<!-- End Jekyll SEO tag -->
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
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.
|
|
21
|
+
A Jekyll site's `{% seo %}` (jekyll-seo-tag) becomes an include that writes the same tags: it's in [the Jekyll trailhead](trailheads/from-jekyll.md#from-jekyll-seo-tag), and `ssqch scout` drafts it.
|
|
@@ -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.
|
|
@@ -28,6 +28,7 @@ title: Squatch Snacks
|
|
|
28
28
|
- **Nunjucks syntax:** `{% elseif %}`, `===`, `{ title: x }`, `{% for key, value in object %}` and Nunjucks' own filters work in `.jinja` files as in `.njk`. Not supported: extensions that parse a tag's arguments themselves.
|
|
29
29
|
- **Two flavors:** `.njk` prints values as Nunjucks does, as a site from Eleventy expects (`true`, a list as `a,b`, an object as `[object Object]`, `none` as nothing, and `dump` as compact JSON, escaped unless it's followed by `| safe`; `dump(2)` indents it). `.jinja` and `.j2` print as Jinja does (`True`, `['a', 'b']`, a spaced, unescaped `dump`, and `tojson` with a dict's keys sorted, as Jinja's `json.dumps(sort_keys=True)` writes them). A date prints as ISO 8601 in both, whatever the machine's time zone.
|
|
30
30
|
- **The final newline:** a `.jinja` or `.j2` template (a page, a layout, an include, an import) loses one newline at its end, as Jinja's do (`keep_trailing_newline=False`), so `{% include "nav.jinja" %}` adds no blank line after the nav, and a page ends where its last tag does. `.njk` keeps it, as Nunjucks does. Templates written for Jinja (a MkDocs theme) print the same whitespace as they did there.
|
|
31
|
+
- **A key with a method's name:** a dict's `items`, `keys`, `values`, `get` and `update` are its methods where it has no key of that name, as in Jinja, whose `x["items"]` falls back to the method too. So `{% if link.items %}` is true for every dict: a nav entry without children included (VitePress's nav and sidebar use `items`). Ask for the key: `{% if link.get("items") %}` or `{% if "items" in link %}`. Where the key is there, `link.items` is its value, and `link.items()` is still the method.
|
|
31
32
|
- **Strings:** `"\u003ch1"`, `"\x3c"` and `"\U0001F332"` are the characters they name in both flavors, as in Python and JavaScript, and `\n`, `\t`, `\r`, `\\`, `\"` and `\'` work as usual. `in` searches a safe string's text (`{% if "<h1" not in page.content %}`), as Jinja searches its `Markup`.
|
|
32
33
|
- **Where Nunjucks isn't Jinja:** a variable set inside a loop or an `if` keeps its value after it (`{% set total = 0 %}{% for x in xs %}{% set total = total + x %}{% endfor %}` ends with the sum; `namespace()` still works), and a variable set in an include stays in the include, so set it in the page, or have the include print it. `{% break %}`, `{% continue %}`, `{% with %}`, `{% autoescape %}`, `{% for x in xs if x.ok %}` and `recursive` loops are errors that name their line and say what to write instead (an `{% if %}` inside the loop, `xs | selectattr("ok")`, a macro that calls itself). `loop.previtem`, `loop.nextitem` and `loop.depth` are undefined. Numbers have no separate float type (`{{ 4 / 2 }}` prints `2`), and `+` and `*` are JavaScript's: join lists with `xs | chain(ys)`.
|
|
33
34
|
- **Errors** name the template and line: `broken.njk:2: syntax error`. An error in a layout (a template that another `{% extends %}`) or after an `{% include %}` names that template's own line, not the page's `{% block %}` or the include's.
|
|
@@ -4,12 +4,13 @@ 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`).
|
|
11
11
|
- **Front matter:** YAML between `---` lines, TOML between `+++` lines, or JSON after `---json` (`---yaml` and `---toml` work too). `.markdown` files are Markdown, like `.md`.
|
|
12
12
|
- **Navigation:** `navTree(nav, page.url)` takes a tree from data (`_data/nav.yml`: entries with `title`, `url`, and children under `children`, `items` or `pages`) and marks each entry `current`, `ancestor` or `open`, for a sidebar that highlights where you are. `navPager(nav, page.url)` returns `{ previous, next }` in reading order (a collection works as the tree too: `navPager(collections.posts, page.url).next` is the next post, which is Eleventy's `collections.posts | getNextCollectionItem(page)`, and that and `getPreviousCollectionItem` work as they are), and `navBreadcrumbs(nav, page.url)` the entries from the top down to the page. To build the tree from front matter instead, give pages `nav: { title, parent, order }` (or `nav: true`) and use `pagesTree(collections.docs)`: an entry's key is its `nav.key`, or else its title; `parent` names another entry's key, and a `parent` no page has becomes a heading (an entry with that title and no `url`) holding its children. The title is `nav.title`, the page's `title`, or `nav.key`; `nav.url` replaces the page's URL (a link elsewhere), and any other `nav` key (`excerpt`) is copied onto the entry. `pagesTree(collections.all, { root: "Feature" })` (`{{ collections.all | pagesTree: root: "Feature" }}` in Liquid) is the tree below the key `Feature`, page or heading, which is eleventy-navigation's `eleventyNavigation: "Feature"`; an unknown option is an error. URLs match with or without `index.html` and the last `/`.
|
|
13
|
+
- **Components:** a PascalCase tag in a page or a layout, `<VueSchoolLink href="https://vueschool.io/lessons/x" title="Free lesson">Watch it</VueSchoolLink>` or `<Badge type="tip" text="new" />`, renders `_includes/components/VueSchoolLink.*` in its place, a template in any engine, as VitePress, Astro and MDX pages use components. It gets the page's data and `component`: `component.name`, `component.props` (each attribute: `href="x"` is `"x"`, a bare `disabled` is `true`, a `kebab-case` name is there in camelCase too, and Vue's bindings are read against the page's data: `:text="title"` is the page's title, `:count="3"` is 3, `:items="['a', 'b']"` a list; anything more is the expression as written), `component.content` (what's between its tags, as HTML, with the components inside it rendered: print it with `| safe`) and `component.attrs` (the plain attributes as written, ` class="x" href="y"`, to put on the element the template writes). Vue's directives and events (`v-if`, `@click`, `#title`) are left out of both. The page's components render with its body, so its layouts and `templateContent` get the HTML, and a layout's own (`<SiteFooter />`) after the layouts. What's inside `<pre>`, `<code>`, `<script>`, `<style>`, `<textarea>` and comments isn't read, so a code sample's `<Badge />` stays text; HTML's names are lower case and SVG's camelCase ones start lower case, so only PascalCase tags are components, and a custom element (`<trail-map>`) has a hyphen. A PascalCase tag with no template is a warning that names the pages it's on (browsers would drop the tag and show what's inside it), and is left as written. A component with state (a counter, a REPL) needs JavaScript in the browser: a custom element from `ssqch/elements` for that part, or, for Vue's own `.vue` components, `vuePlugin()` from `ssqch/vue`, which renders the tags `_includes/components/` has no template for, and with `hydrate` runs them in the browser too.
|
|
13
14
|
- **Dates:** a page's `date` comes from its data, then from the start of its file name (`2024-06-01-post.md`), then from when the file last changed. `computed.date` works too. Collections are oldest first; undated pages come after the dated ones, in path order, so a fresh checkout or an edit (which changes file times) doesn't reorder them.
|
|
14
15
|
- **`SOURCE_DATE_EPOCH`:** set it (whole seconds since 1970, the reproducible-builds convention: `SOURCE_DATE_EPOCH=1767225600 ssqch build`) to pin the build's time, as Jekyll's `time:` does. `now()` in every engine, Liquid's `"now"`, Edge's `new Date()` and the date of every page without one become that time, so two builds of the same files write the same pages. A value that isn't a number is an error before the build starts. A site's own JavaScript (`Date.now()` in a filter) isn't changed.
|
|
15
16
|
- **Drafts:** `draft: true` builds the page in development (`ssqch serve`, or `--env development`) and leaves it out of production builds, collections included.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "Trailhead: moving from Astro,
|
|
3
|
-
navTitle: "From Astro,
|
|
2
|
+
title: "Trailhead: moving from Astro, Next.js or Gatsby"
|
|
3
|
+
navTitle: "From Astro, Next.js, Gatsby"
|
|
4
4
|
description: "These are component frameworks."
|
|
5
5
|
command: "ssqch docs --from astro"
|
|
6
6
|
---
|
|
@@ -10,7 +10,7 @@ These are component frameworks: a page is a tree of components, rendered on a se
|
|
|
10
10
|
2. **Presentational components** (cards, callouts, layouts, navigation): become templates, with no JavaScript in the browser.
|
|
11
11
|
3. **Interactive components** (a search box, tabs with state, a live editor): stay JavaScript, as custom elements that load on the pages that use them, or as an app that lives beside the site.
|
|
12
12
|
|
|
13
|
-
On the sites studied for this guide, most components were in the second pile: about 80% of getbootstrap.com's (Astro)
|
|
13
|
+
On the sites studied for this guide, most components were in the second pile: about 80% of getbootstrap.com's (Astro). A site whose pages are mostly the third pile (react.dev, with a live editor in most pages) is an app, and should stay one.
|
|
14
14
|
|
|
15
15
|
The [`component-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/component-docs/) example is distilled from getbootstrap.com: components in place of MDX, live examples with their source, and values read from Sass files. [`islands`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/islands/) shows interactive parts as custom elements.
|
|
16
16
|
|
|
@@ -21,13 +21,13 @@ The [`component-docs`](https://github.com/reverentgeek/sitesquatch/tree/main/exa
|
|
|
21
21
|
| A blog, docs or marketing site with a few interactive widgets | Yes: content and templates in ssqch, widgets as custom elements |
|
|
22
22
|
| Docs where every page embeds a live playground | Partly: the prose pages, with the playground as its own bundle that pages load |
|
|
23
23
|
| Server-rendered per request (auth, personalization, API routes, ISR) | No: ssqch only builds static files. Keep those routes where they are and move the static section. |
|
|
24
|
-
| A framework's own docs (
|
|
24
|
+
| A framework's own docs (react.dev) | No: they exist to show the framework |
|
|
25
25
|
|
|
26
26
|
Moving one section at a time works: build the docs or blog with ssqch into a folder, and let the host serve it under its path (`base: "/docs/"`).
|
|
27
27
|
|
|
28
28
|
## Content
|
|
29
29
|
|
|
30
|
-
| Astro,
|
|
30
|
+
| Astro, Next.js, Gatsby | SiteSquatch |
|
|
31
31
|
| --- | --- |
|
|
32
32
|
| Markdown with YAML front matter | The same. `title`, `description`, `date`, `tags` are read as they are. |
|
|
33
33
|
| Content collections with a Zod schema (`src/content/config.ts`) | `schemas` in the config: `{ posts: { fields: { title: "string", date: "date", tags: "string[]" } } }`, checked on every build, with types from `ssqch types` |
|
|
@@ -35,10 +35,10 @@ Moving one section at a time works: build the docs or blog with ssqch into a fol
|
|
|
35
35
|
| `getStaticPaths`, `[slug].astro`, `createPages` | Pagination over data with a `permalink` per item: one template, one page per entry |
|
|
36
36
|
| Remote data at build time | `fetch()` in a data file, with `{ cache: "1h" }` so rebuilds don't refetch |
|
|
37
37
|
| File-based routing (`src/pages/about.astro`) | The same idea: `src/about.md` is `/about/`. `permalink` overrides it. |
|
|
38
|
-
| `:::tip` containers (
|
|
38
|
+
| `:::tip` containers (Starlight) | The same syntax, built in |
|
|
39
39
|
| `{#custom-id}` on headings, `[[toc]]` | `{#custom-id}` works; the table of contents is `toc(page.headings)` in the layout |
|
|
40
40
|
| Code blocks with Shiki, line highlighting `{1,3}`, titles | `markdown: { highlight: true }`, `{1,3}` in the fence's info string; a `fence` render hook for titles and copy buttons |
|
|
41
|
-
| Extra Shiki languages (
|
|
41
|
+
| Extra Shiki languages (Astro `shikiConfig.langs`) | `markdown: { highlight: { languages } }`: an alias (`mdx: "markdown"`), a function that returns tokens, or a `.sublime-syntax` file. Shiki's TextMate JSON grammars don't load as they are (`ssqch docs languages`) |
|
|
42
42
|
| Twoslash, or anything that needs a compiler at build time | A `beforeBuild` command that writes HTML or JSON for templates to include |
|
|
43
43
|
| `<Image>` / `gatsby-plugin-image` | `imagePlugin()`: every `<img>`, including Markdown images, becomes a responsive `<picture>` |
|
|
44
44
|
| i18n routing | Not yet |
|
|
@@ -69,7 +69,7 @@ This **cannot** be undone.
|
|
|
69
69
|
|
|
70
70
|
| Component | Becomes |
|
|
71
71
|
| --- | --- |
|
|
72
|
-
| A layout (`<BaseLayout>`, `layout.tsx
|
|
72
|
+
| A layout (`<BaseLayout>`, `layout.tsx`) | A layout in `_includes/`, chosen by `layout` in front matter or directory data |
|
|
73
73
|
| A presentational component with props (`<Card title>`) | A Jinja macro (`{% macro card(title) %}`, with `caller()` for its body), an Edge component (`_includes/components/card.edge`, with `$props` and slots), or a Handlebars partial |
|
|
74
74
|
| A component that wraps Markdown (`<Aside>`, `<Tabs>`) | A container: `_includes/containers/aside.jinja` gets the rendered body as `container.content` |
|
|
75
75
|
| Something that changes how Markdown elements render (`components={{ a, h2, pre }}`) | Render hooks: `_includes/hooks/link.*`, `heading.*`, `fence.*` |
|
|
@@ -96,7 +96,7 @@ Write each one as a custom element, with what a visitor sees before (or without)
|
|
|
96
96
|
| `client:idle` | `ssqch:load="idle"` on the tag |
|
|
97
97
|
| `client:visible` | `ssqch:load="visible"` |
|
|
98
98
|
| `client:only`, a component with no server-rendered HTML | An element with a fallback inside it (a link, a static version, or nothing) |
|
|
99
|
-
|
|
|
99
|
+
| `dynamic(() => ..., { ssr: false })` (Next.js) | The same |
|
|
100
100
|
|
|
101
101
|
An element's script can import your existing framework code: a Preact, Lit or Vue component mounted inside `connectedCallback` is still an island, bundled by your own esbuild or Vite step into the elements folder (`beforeBuild: { run: "esbuild ..." }`). What goes away is hydrating the whole page.
|
|
102
102
|
|
|
@@ -105,7 +105,6 @@ What doesn't have an equivalent: client-side routing between pages (links are or
|
|
|
105
105
|
## Per framework
|
|
106
106
|
|
|
107
107
|
- **Astro:** `.astro` components are the closest to templates: the frontmatter script becomes data (front matter, `_data`, or a filter) and the template below it becomes Jinja or Edge. Starlight sites map onto `ssqch init --starter docs`.
|
|
108
|
-
- **VitePress:** `.vitepress/config.js` `themeConfig.sidebar` becomes `_data/nav.yml`; `:::` containers, `{#id}` and line highlighting already match. Vue components in Markdown are the work.
|
|
109
108
|
- **Next.js:** only statically exported pages (`output: "export"`) move. `next/link` and `next/image` become `<a>` and `<img>`; `getStaticProps` becomes a data file.
|
|
110
109
|
- **Gatsby:** source plugins become data files (`fetch`, or reading files with `node:fs`), page queries become collections, and `gatsby-node.js` `createPages` becomes pagination. remark plugins map to the `markdown` options, render hooks and containers.
|
|
111
110
|
|
|
@@ -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 |
|