ssqch 0.10.0 → 0.11.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 +62 -16
- package/bundled/completions/elvish +28 -12
- package/bundled/completions/fish +36 -23
- package/bundled/completions/powershell +30 -12
- package/bundled/completions/zsh +40 -19
- package/bundled/docs/agents.md +12 -1
- package/bundled/docs/build-summary.md +31 -1
- package/bundled/docs/comparing-builds.md +37 -5
- package/bundled/docs/configuring.md +30 -5
- package/bundled/docs/field-guide.md +1 -1
- package/bundled/docs/github-pages.md +1 -1
- package/bundled/docs/index.md +1 -1
- package/bundled/docs/known-gaps.md +1 -1
- package/bundled/docs/markdown.md +63 -5
- package/bundled/docs/multilingual.md +20 -3
- package/bundled/docs/nav.yml +1 -0
- package/bundled/docs/netlify.md +2 -2
- package/bundled/docs/plugins.md +4 -4
- package/bundled/docs/seo.md +39 -1
- package/bundled/docs/template-languages.md +6 -4
- package/bundled/docs/templates.md +3 -3
- package/bundled/docs/trailheads/from-eleventy.md +25 -13
- package/bundled/docs/trailheads/from-hugo.md +103 -0
- package/bundled/docs/trailheads/from-jekyll.md +49 -15
- package/bundled/docs/trailheads/from-mkdocs.md +54 -9
- package/bundled/docs/trailheads/from-zola.md +2 -2
- package/bundled/docs/trailheads.md +22 -5
- package/bundled/docs/where-values-come-from.md +1 -1
- package/bundled/mkdocs/404.jinja +6 -0
- package/bundled/ssqch.d.ts +78 -18
- package/lib/assets.js +11 -12
- package/lib/{chunk-3HHRKG33.js → chunk-2L3HR67O.js} +71 -19
- package/lib/{chunk-LCPSKHAV.js → chunk-2QTJTEBV.js} +1 -1
- package/lib/{chunk-RVBNVGZV.js → chunk-3HZZY3Y7.js} +5 -6
- package/lib/{chunk-RKFZSVNF.js → chunk-3K237XAX.js} +10 -11
- package/lib/{chunk-HXCLCXRT.js → chunk-443ZQLVX.js} +5 -3
- package/lib/{chunk-Q4LFTYK2.js → chunk-5ELAUHRL.js} +20 -20
- package/lib/{chunk-SA5KSJ4Y.js → chunk-A75EVUJX.js} +10 -12
- package/lib/{chunk-BGCBSQ4A.js → chunk-AIMEXBTK.js} +163 -29
- package/lib/{chunk-Y2ESFAAD.js → chunk-B5E27PLU.js} +10 -41
- package/lib/{chunk-RJFWTW2Y.js → chunk-CMJ7X5WW.js} +3 -3
- package/lib/{chunk-NKXEPHRZ.js → chunk-ERAIEV3O.js} +106 -4
- package/lib/{chunk-E5UB2YY7.js → chunk-FCM3NYFR.js} +11 -9
- package/lib/{chunk-3EPHKJEG.js → chunk-GJNIQAIH.js} +8 -8
- package/lib/{chunk-CB6YFUXU.js → chunk-GLJQ4C76.js} +40 -21
- package/lib/{chunk-DDV6JEC2.js → chunk-GS5B3CBW.js} +1 -1
- package/lib/chunk-H5K2ZE7B.js +219 -0
- package/lib/{chunk-NFJJKDRI.js → chunk-HFSWUTXX.js} +1 -1
- package/lib/{chunk-4Q6WMTER.js → chunk-HWW5NCVJ.js} +1 -1
- package/lib/{chunk-LAV3DEY4.js → chunk-I3HYKEEW.js} +1 -1
- package/lib/{chunk-JWCCVTTR.js → chunk-IOBC665M.js} +2 -4
- package/lib/chunk-JC54PHIT.js +7992 -0
- package/lib/{chunk-2LEOPLTZ.js → chunk-KCF2Z6N7.js} +3 -5
- package/lib/{chunk-DMVJ53SM.js → chunk-KZZS4W2V.js} +15 -15
- package/lib/{chunk-RM5Q3KFB.js → chunk-LJOURBYT.js} +14 -13
- package/lib/chunk-OQGXZYZS.js +45 -0
- package/lib/chunk-OSBEH67S.js +6296 -0
- package/lib/{chunk-DW7VMJEZ.js → chunk-QJ5ZFTML.js} +14 -13
- package/lib/{chunk-NUUEOGLZ.js → chunk-QLUTNR37.js} +11 -11
- package/lib/{chunk-HGJ5VWUR.js → chunk-RBNPBTDP.js} +1 -1
- package/lib/{chunk-F65YUXZ7.js → chunk-RIAOXEXC.js} +10 -4
- package/lib/chunk-RVXGUMFI.js +21 -0
- package/lib/{chunk-N4O5MDIB.js → chunk-RYIWYWRQ.js} +5 -7
- package/lib/{chunk-EEJDLCD3.js → chunk-RZYAIX2R.js} +12 -11
- package/lib/{chunk-7HXCQEGA.js → chunk-V2FSMOFX.js} +3 -3
- package/lib/{chunk-HDQ4SRWM.js → chunk-X2GAVYV2.js} +525 -75
- package/lib/chunk-XS4EJSEK.js +279 -0
- package/lib/chunk-YCOTX2VM.js +37 -0
- package/lib/{chunk-QMA7CK7B.js → chunk-Z44IAMNG.js} +137 -32
- package/lib/chunk-Z5OP43HU.js +2945 -0
- package/lib/{chunk-JXZT5L7W.js → chunk-ZINLHOX4.js} +2 -3
- package/lib/{chunk-SRNLKWXL.js → chunk-ZR3JYLFB.js} +893 -12382
- package/lib/cli.js +82 -41
- package/lib/elements.js +11 -12
- package/lib/image.js +11 -11
- package/lib/links.js +11 -12
- package/lib/minify.js +71 -13
- package/lib/redirects.js +11 -12
- package/lib/rss.js +13 -11
- package/lib/sass.js +13 -245
- package/lib/sitemap.js +19 -18
- package/lib/ssqch.js +6 -5
- package/package.json +1 -1
- package/types/index.d.ts +59 -13
- package/types/minify.d.ts +15 -3
- package/types/sass.d.ts +2 -0
- package/types/sitemap.d.ts +2 -2
- package/wasm/markdown.wasm +0 -0
- package/wasm/minify.wasm +0 -0
- package/wasm/sass.wasm +0 -0
- package/lib/chunk-5DNDSNTP.js +0 -1541
- package/lib/chunk-VJWQSYEG.js +0 -119
- package/lib/chunk-ZM6TU2JB.js +0 -1287
- /package/lib/{chunk-BGCBSQ4A.js.LEGAL.txt → chunk-AIMEXBTK.js.LEGAL.txt} +0 -0
- /package/lib/{chunk-SRNLKWXL.js.LEGAL.txt → chunk-ZR3JYLFB.js.LEGAL.txt} +0 -0
package/bundled/docs/seo.md
CHANGED
|
@@ -16,4 +16,42 @@ ssqch writes no `<head>` tags of its own, so a site's title, description, canoni
|
|
|
16
16
|
<meta name="twitter:card" content="summary_large_image">
|
|
17
17
|
```
|
|
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
|
+
|
|
21
|
+
**From jekyll-seo-tag:** 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):
|
|
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.
|
|
@@ -19,16 +19,18 @@ 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.
|
|
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 (`mkdocsTemplates` 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.
|
|
26
26
|
- **Your own tags:** a config filter is a tag too, in `.njk` and `.jinja` files alike. `{% image "/a.png", "A pine" %}` prints what `image("/a.png", "A pine")` returns, without escaping it. With a closing tag, the function gets what's between them first: `{% callout "tip" %}...{% endcallout %}` calls `callout(content, "tip")`. That covers the built-in filters as well, so `{% markdown %}...{% endmarkdown %}` renders Markdown inside a template.
|
|
27
|
-
- **Includes and inheritance:** `{% include %}`, `{% extends %}` with `{% block %}`, `{% import %}` and `{% from ... import %}` read from `_includes`. Front-matter `layout` works too.
|
|
27
|
+
- **Includes and inheritance:** `{% include %}`, `{% extends %}` with `{% block %}`, `{% import %}` and `{% from ... import %}` read from `_includes`. Front-matter `layout` works too. Jinja's `self` renders a block by name anywhere in the template, as the page's templates have it (the child's over the parent's): `<title>{% block title %}Camp{% endblock %}</title> ... <h1>{{ self.title() }}</h1>`; a block nothing defines is undefined, and a variable named `self` is that variable.
|
|
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
|
-
- **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`). A date prints as ISO 8601 in both, whatever the machine's time zone.
|
|
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
|
+
- **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
|
+
- **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`.
|
|
30
32
|
- **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)`.
|
|
31
|
-
- **Errors** name the template and line: `broken.njk:2: syntax error`.
|
|
33
|
+
- **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.
|
|
32
34
|
|
|
33
35
|
|
|
34
36
|
## Edge
|
|
@@ -9,14 +9,14 @@ The lay of the land:
|
|
|
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
|
-
- **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, 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
|
|
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
13
|
- **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
14
|
- **`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
15
|
- **Drafts:** `draft: true` builds the page in development (`ssqch serve`, or `--env development`) and leaves it out of production builds, collections included.
|
|
16
16
|
- **Excerpts and reading time:** `page.excerpt` is the HTML before a `<!-- more -->` comment, or else the first paragraph, for layouts and collections (`post.page.excerpt` in a list of posts). `readingTime(content)` is the minutes it takes to read some HTML at 200 words a minute (`readingTime(content, 250)` for another pace), at least 1.
|
|
17
|
-
- **Slugs:** `slugify("Pine Cone Crunch!")` is `pine-cone-crunch`: lowercase letters and digits, with a dash for each run of anything else (apostrophes are dropped, and letters outside ASCII are kept). It's the same function in every template language (`{{ title | slugify }}` in Jinja, Nunjucks and Liquid), and a config filter named `slugify` replaces it. `slugify(title, { separator: "_" })` (or `slugify(title, "_")`, `{{ title | slugify: "_" }}` in Liquid) puts another separator between the words, for URLs like `/recipes/taco_bake/`. Apostrophes are dropped (`Drew's Brownies` is `drews-brownies`); `apostrophes: "separate"` splits words there instead (`drew-s-brownies`), for a site whose URLs were made that way. Another option is an error. Before replacing a site's own slug filter with `slugify`, build with both and compare with `ssqch diff`: one changed URL is a broken link. Data files can import it, and `slugger()`, from `ssqch`.
|
|
17
|
+
- **Slugs:** `slugify("Pine Cone Crunch!")` is `pine-cone-crunch`: lowercase letters and digits, with a dash for each run of anything else (apostrophes are dropped, and letters outside ASCII are kept). It's the same function in every template language (`{{ title | slugify }}` in Jinja, Nunjucks and Liquid), and a config filter named `slugify` replaces it. `slugify(title, { separator: "_" })` (or `slugify(title, "_")`, `{{ title | slugify: "_" }}` in Liquid) puts another separator between the words, for URLs like `/recipes/taco_bake/`. Apostrophes are dropped (`Drew's Brownies` is `drews-brownies`); `apostrophes: "separate"` splits words there instead (`drew-s-brownies`), for a site whose URLs were made that way. `ascii: true` takes accents off and spells out a few letters and symbols first, as the slugify package (Eleventy's `slugify`) does (`Thomas Sjögren` is `thomas-sjogren`, `Straße & 50%` is `strasse-and-50-percent`; other scripts stay as they are), and `stripTags: true` drops HTML tags first (`Use <code>title</code>` is `use-title`). Another option is an error. Before replacing a site's own slug filter with `slugify`, build with both and compare with `ssqch diff`: one changed URL is a broken link. Data files can import it, and `slugger()`, from `ssqch`.
|
|
18
18
|
- **Choosing engines:** pages are Jinja (`.jinja`) unless you list other languages in `templateFormats`, and `.md` files run through Jinja first, then Markdown (change that with `markdownEngine` and `htmlEngine`). Layouts follow the same rules, so a `.html` layout is a Jinja template by default. A template's `render` front matter overrides it: `render: md` for Markdown only (handy for a post full of `{{ }}` code samples), `render: [edge, md]` for a chain, or `render: false` to write the body as it is. A layout chain can mix languages (a Markdown post in a Liquid layout that sits in an Edge one). Around here that's called trail mix.
|
|
19
|
-
- **Text files with front matter** (Jekyll renders any file that starts with `---`, like a `.js` or `.txt` file): give the extension an engine that hands the text back, `engines: { js: (s) => s }`, add it to `templateFormats`, and in that folder's directory data (`assets/js/js.json`) set `"render": "liquid,js"` (Liquid first, or the engine you use) and `"permalink": "
|
|
19
|
+
- **Text files with front matter** (Jekyll renders any file that starts with `---`, like a `.js` or `.txt` file): give the extension an engine that hands the text back, `engines: { js: (s) => s }`, add it to `templateFormats`, and in that folder's directory data (`assets/js/js.json`), or in each file's front matter, set `"render": "liquid,js"` (Liquid first, or the engine you use) and `"permalink": "{{ page.filePathStem }}.js"` (`filePathStem` starts with its own `/`), so the file keeps its name instead of becoming `app/index.html`. `ssqch scout` drafts all three for a Jekyll site. The config and the modules it imports are never pages, so `lib/filters.js` stays code. A `.scss` file with front matter needs nothing: `sassPlugin()` blanks it.
|
|
20
20
|
- **Everything else:** layout chaining, `page.*`, `templateContent` in collections, and an error when two pages would write the same file. Every template can read `ssqch.version`, `ssqch.env`, `ssqch.serving` and `ssqch.generator`.
|
|
21
21
|
|
|
22
22
|
Templates are [Jinja](template-languages.md#jinja-and-nunjucks) by default; [Edge](template-languages.md#edge), [Liquid](template-languages.md#liquid), [Nunjucks](template-languages.md#jinja-and-nunjucks), [Handlebars and Mustache](template-languages.md#handlebars-and-mustache) and [EJS](template-languages.md#ejs) are a `templateFormats` entry away, and one site can use several.
|
|
@@ -7,9 +7,11 @@ SiteSquatch keeps many of the same ideas as Eleventy (a data cascade, collection
|
|
|
7
7
|
|
|
8
8
|
The [ReverentGeek blog](https://github.com/reverentgeek/blog) made this move (from Eleventy with Edge templates), and the [`blog-categories`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/blog-categories/) example is distilled from eslint.org, an Eleventy site.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Scouting
|
|
11
11
|
|
|
12
|
-
`ssqch
|
|
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 renames `*.11tydata.*` data files and the `eleventy:` image attributes below (Eleventy's front matter keys work as they are), writes a first `ssqch.config.js` from the Eleventy config (folders, passthrough copies, watch targets, template engines, `pathPrefix`, and filters and shortcodes that use only their own arguments, copied as written, in the config's own indentation), swaps `@11ty/eleventy` for `ssqch` in `package.json` and its scripts (`eleventy` is `ssqch build`, `eleventy --serve` is `ssqch serve`), and lists what's left, including a lockfile to update or a stale one from another package manager, each with its file and line: every filter, shortcode, collection, transform and plugin, and what it becomes. It changes nothing on its own: `--write-draft` writes the new files and `--patch move.patch` the edits, to read and `git apply`. Run it again during the move to see what's left.
|
|
13
|
+
|
|
14
|
+
**What scout also finds:** what the site's own modules add: the config is followed through its relative imports (`registerSiteFilters(eleventyConfig)` in `lib/`, a plugin of the site's own), and each module's filters, shortcodes, collections and transforms are listed with its own file and line, the self-contained filters copied into the draft as the config's are. Eleventy's packages in data files and other modules (eleventy-img or eleventy-fetch run by a data file) are listed with what replaces them. The packages that came with `@11ty/eleventy` and that the site's own code imports without listing them (`slugify` in the config, `browser-sync` in a gulpfile, `gray-matter` in a data file): it adds each to `package.json` beside where Eleventy was, at the version installed, since the output can depend on it, or, with no `node_modules` to read the version from, lists it to add by hand. The filters and shortcodes the templates use that nothing defines (not the template language, not ssqch, not the Eleventy config), each with how many templates use it and the first place: Eleventy's built-ins (`log`, `getCollectionItem` and `getCollectionItemIndex`, which it ports into the draft's `filters`, and `slug`, which it says how to port: Eleventy's keeps punctuation ssqch's `slugify` drops), the RSS and navigation plugins' (and what replaces them), and any other name, which is usually a plugin's or a helper module's. markdown-it's `breaks`, `linkify` and `typographer` and markdown-it-implicit-figures come along as the draft's `markdown` options, and so do the defaults where the two Markdowns write different markup, each with a comment: `headingIds: false` when the site has no markdown-it-anchor (Eleventy's headings had no ids; the ReverentGeek blog had 380), and `indentedCode: false` for Eleventy 3 (and Eleventy 2 without a library of its own), which turns indented code blocks off. Take a line out to move to ssqch's. It also lists what changes the output before the first diff: a Date printed as it is (`{{ date }}`: `Date.toString()` in Eleventy, ISO 8601 in ssqch), date code that reads the machine's time zone (`toLocaleDateString` without `timeZone`, luxon's `fromJSDate` without `zone`), `pagination` over `collections`, templates in a folder that's passed through (Eleventy rendered them, ssqch copies them), a script that runs `ssqch build` beside another command with `&`, and a second build tool (a gulpfile, webpack, PostCSS) with what ssqch has for each part it does. With markdown-it-anchor (and no `slugify` of the site's), the draft has `headingIds: "markdown-it-anchor"`; with `dataTemplateEngine`, a data file's `{{ '/about/' | url }}` becomes `"/about/"`; `ignores.add()` joins `.eleventyignore` in `ignore`; and a file passed through twice is listed once.
|
|
13
15
|
|
|
14
16
|
## The config
|
|
15
17
|
|
|
@@ -43,7 +45,7 @@ export default defineConfig(({ env }) => ({
|
|
|
43
45
|
| `on("eleventy.before")`, `on("eleventy.after")` | `beforeBuild`, `afterBuild` |
|
|
44
46
|
| `dir` | `dirs` (`dir` works too) |
|
|
45
47
|
| `markdownTemplateEngine`, `htmlTemplateEngine` | `markdownEngine`, `htmlEngine` (Eleventy's names work too) |
|
|
46
|
-
| `setLibrary("md", markdownIt(...).use(...))` | `markdown: { ... }` options, render hooks and containers (below) |
|
|
48
|
+
| `setLibrary("md", markdownIt(...).use(...))` | `markdown: { ... }` options, render hooks and containers (below), or keep your markdown-it as it is: `engines: { md }` ([Your own Markdown library](../markdown.md#your-own-markdown-library)) |
|
|
47
49
|
| `pathPrefix` | `base: "/repo/"` (`pathPrefix` works too). Links in templates need no `url` filter (it works, and gives the URL back as it is): ssqch adds the base to every URL from the site's root in the HTML it writes, and `withBase()` covers scripts and JSON. |
|
|
48
50
|
|
|
49
51
|
The config is ESM, though your own CommonJS files (`require`, `module.exports`) load too. ssqch runs on Node, like Eleventy, so a site's packages run as they are: luxon, date-fns, lodash, markdown-it, slugify-style helpers and the libraries Eleventy brought along all work, and so do servers, child processes and native addons.
|
|
@@ -65,7 +67,7 @@ Where Eleventy's word means the same thing in ssqch, it works as it is: `ssqch d
|
|
|
65
67
|
| `page.url`, `page.fileSlug`, `page.inputPath`, `page.outputPath`, `page.date` | The same, plus `page.headings` and `page.excerpt` in layouts. Dates in file names (`2024-06-01-post.md`) work the same way. |
|
|
66
68
|
| `layouts: "_includes/layouts"` and `layout: post` | `dirs: { layouts: "_includes/layouts" }` |
|
|
67
69
|
| `addDataExtension("yml", ...)` with js-yaml | Built in: YAML, TOML and JSON data files load as they are, and `readData(path)` from `ssqch` reads one in code |
|
|
68
|
-
| `eleventyNavigation` | `nav` front matter with the same `key`, `parent`, `order` and `
|
|
70
|
+
| `eleventyNavigation` | `nav` front matter with the same `key`, `parent`, `order`, `title` and `url`, turned into a tree with `pagesTree(collections.all)`, and `collections.all | eleventyNavigation: "Feature"` is `pagesTree(collections.all, { root: "Feature" })` (a `parent` no page has is a heading, and `title` falls back to `key`, as in eleventy-navigation); or a data file such as `_data/nav.yml`. `navTree`, `navPager` and `navBreadcrumbs` mark the current page, and give previous/next and the trail. To keep eleventy-navigation's filter instead, leave the front matter as it is and define the filter with the package's function: `import navigation from "@11ty/eleventy-navigation/eleventy-navigation.js"`, then `filters: { eleventyNavigation: (pages, key) => navigation.findNavigationEntries(pages, key) }` (`ssqch scout` leaves the front matter alone when templates call that filter). |
|
|
69
71
|
| `eleventy.env`, `process.env.ELEVENTY_ENV` | The `ssqch` template global (`ssqch.env`, `ssqch.serving`), and `SSQCH_ENV` |
|
|
70
72
|
|
|
71
73
|
## Plugins
|
|
@@ -74,12 +76,13 @@ Where Eleventy's word means the same thing in ssqch, it works as it is: `ssqch d
|
|
|
74
76
|
| --- | --- |
|
|
75
77
|
| `@11ty/eleventy-img` | `imagePlugin()` from `ssqch/image`: every `<img>` becomes a `<picture>` |
|
|
76
78
|
| `@11ty/eleventy-plugin-rss` | `rssPlugin()` from `ssqch/rss` |
|
|
77
|
-
| `@11ty/eleventy-plugin-syntaxhighlight` | `markdown: { highlight: true }` |
|
|
79
|
+
| `@11ty/eleventy-plugin-syntaxhighlight` | `markdown: { highlight: true }`, or `highlight: { classes: "prism", css: false }` to keep your Prism theme's CSS ([Another highlighter's classes](../markdown.md#another-highlighters-classes)) |
|
|
78
80
|
| A Prism language added in the plugin's `init({ Prism })`, or its `alias` option | `markdown: { highlight: { languages } }`: a function that returns `[text, kind]` tokens, another language's name (`cho: "chordpro"`), or a `.sublime-syntax` file (`ssqch docs languages`) |
|
|
79
81
|
| markdown-it-anchor | Heading IDs are built in; add anchor links with a heading render hook |
|
|
80
82
|
| markdown-it-footnote | Built in |
|
|
81
83
|
| markdown-it-container | Built in: `::: name` |
|
|
82
84
|
| markdown-it-attrs | `{#id .class}` on headings |
|
|
85
|
+
| markdown-it-implicit-figures | `markdown: { figures: true }` |
|
|
83
86
|
| An HTML minifier transform | `minifyPlugin()` from `ssqch/minify` |
|
|
84
87
|
| A link checker | `linksPlugin()` from `ssqch/links` |
|
|
85
88
|
| A sitemap template | `sitemapPlugin({ url })` from `ssqch/sitemap` |
|
|
@@ -99,7 +102,7 @@ Nunjucks (`.njk`) renders with Nunjucks, the library Eleventy uses (ssqch's fork
|
|
|
99
102
|
- **A data file can start with a byte-order mark** (SQL Server's and Excel's exports do): ssqch skips it in JSON, YAML, TOML, JavaScript and templates, as Node does.
|
|
100
103
|
- **A folder of full-size photos** is what `imagePlugin()` from `ssqch/image` is for: every `<img>` gets sized, modern-format copies in a `<picture>`, and `image()` in a data file gives the URLs and dimensions without markup.
|
|
101
104
|
- **A printed date is ISO 8601** (`2024-06-01T00:00:00.000Z`), not JavaScript's `Date.toString()`, which depends on the machine's time zone. Format dates with a filter.
|
|
102
|
-
- **Markdown differs from markdown-it in a few places:** bare domains like `example.com` aren't links (only `https://` and `www.` URLs are, as on GitHub)
|
|
105
|
+
- **Markdown differs from markdown-it in a few places:** bare domains like `example.com` aren't links (only `https://` and `www.` URLs are, as on GitHub) unless `markdown: { autolinks: "fuzzy" }`, and with `indentedCode: false`, indented HTML renders as HTML (markdown-it wraps it in `<p>`). markdown-it's `breaks` and markdown-it-implicit-figures are `markdown: { breaks: true, figures: true }` ([markdown-it's habits](../markdown.md#markdown-its-habits)); `ssqch scout` carries them, `linkify` and `typographer` into the draft config.
|
|
103
106
|
- **The layout is chosen before `computed` runs.** A computed `layout` that's plain text (`eleventyComputed: { layout: "article" }`) is used; one that depends on the page is an error. Set it in the front matter or a data file.
|
|
104
107
|
- **`computed` doesn't see `collections`.** Build lists that need collections in a filter or a collection instead.
|
|
105
108
|
- **Includes come from `_includes`** (and themes), not from the project root as in Eleventy's Nunjucks. To show a source file in a page, read it in a filter: `filters: { readFile: (p) => fs.readFileSync(p, "utf8") }`.
|
|
@@ -111,10 +114,15 @@ Nunjucks (`.njk`) renders with Nunjucks, the library Eleventy uses (ssqch's fork
|
|
|
111
114
|
|
|
112
115
|
A big site moves most safely in two steps: first the same pages, byte for byte, then ssqch's own features one at a time. For the first step, keep Eleventy's template libraries and let ssqch do the rest (finding pages, the data cascade, pagination, collections, layouts, transforms, writing):
|
|
113
116
|
|
|
114
|
-
- **Markdown
|
|
115
|
-
- **
|
|
117
|
+
- **Markdown:** your markdown-it as it is, `engines: { md }` (the instance you gave `setLibrary("md", ...)`), and `markdownEngine: "liquid"`, since Eleventy runs Markdown through Liquid first. Indented code blocks depend on the Eleventy version: Eleventy 3 turns them off in every markdown-it, a site's own included (`md.disable("code")` in your instance, for the same output), Eleventy 2 only in its own, and Eleventy 1 leaves them on. `cache: true` keeps what it renders between `ssqch serve`'s rebuilds ([Your own Markdown library](../markdown.md#your-own-markdown-library)).
|
|
118
|
+
- **Liquid and Nunjucks:** ssqch's Liquid is liquidjs, as Eleventy's is, and its Nunjucks a fork of Nunjucks, so most pages match as they are. Its Liquid follows Ruby's in a few places, as Jekyll's does (math on text, `split`); `ssqch diff` shows the pages that differ.
|
|
119
|
+
- **Front matter strings:** `permalink` and `computed` strings never go through an engine of your own: they render with ssqch's template language (for a `.md` page, the `markdownEngine`), so your markdown-it never sees them.
|
|
116
120
|
- **Install what Eleventy brought along:** liquidjs, nunjucks, gray-matter and luxon came with `@11ty/eleventy`, and a site's data files often import them without listing them. Pin the versions Eleventy had (`npm ls liquidjs nunjucks`), since the output depends on them.
|
|
117
|
-
- **
|
|
121
|
+
- **Plugins' filters, as they were:** the RSS plugin's are its exports (`const rss = require("@11ty/eleventy-plugin-rss")`, then `filters: { absoluteUrl: rss.absoluteUrl, htmlToAbsoluteUrls: (html, base) => (html ? rss.convertHtmlToAbsoluteUrls(html, base, { closingSingleTag: "slash" }) : ""), rssDate: rss.dateToRfc3339 }`), and eleventy-navigation's is `findNavigationEntries` (above).
|
|
122
|
+
- **Dates printed bare:** `{{ date }}` is `Date.toString()` in Eleventy (`Mon Mar 08 2021 00:00:00 GMT+0000 (Coordinated Universal Time)` with `TZ=UTC`) and ISO 8601 in ssqch. To match first, a transform can put Eleventy's text back; then format the date in the template (`{{ date | dateformat("iso") }}`), which also stops the page depending on the build machine's time zone. `ssqch diff` counts the two forms as dates and groups them.
|
|
123
|
+
- **Pages with the same date** (every undated page, with `SOURCE_DATE_EPOCH` or a baseline's pinned times) sort by path, folder by folder; Eleventy compares the paths as text, so `about-us.md` comes before `about/index.md` there and after it here. For Eleventy's order in a list that shows it (a sitemap over `collections.all`), sort in the template or define the collection: `collections: { all: (pages) => [...pages.all()].sort((a, b) => a.date - b.date || (a.inputPath < b.inputPath ? -1 : a.inputPath > b.inputPath ? 1 : 0)) }`.
|
|
124
|
+
- **Undated pages' dates:** Eleventy gives them the file's creation time, so a sitemap's `<lastmod>` is the checkout's time and changes on every clone. `ssqch baseline` pins file times to the commit's; set `SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)` for `ssqch build`, and the two agree.
|
|
125
|
+
- **Compare bytes:** `ssqch diff --exact`. Without `--exact`, whitespace between tags, image ids and how tags are written (attribute order, quotes, entities) are ignored.
|
|
118
126
|
|
|
119
127
|
Then move one feature at a time to ssqch's (Markdown, highlighting, minifying, the table of contents), with `ssqch diff` after each.
|
|
120
128
|
|
|
@@ -132,12 +140,16 @@ Pages render one at a time on one thread (there are no worker threads), so if a
|
|
|
132
140
|
|
|
133
141
|
## Checking the move
|
|
134
142
|
|
|
135
|
-
Build the old site with Eleventy and the new one with ssqch, and compare the two output folders:
|
|
143
|
+
Build the old site with Eleventy and the new one with ssqch, and compare the two output folders. `ssqch baseline` makes Eleventy's build from fresh copies with the clock pinned, three times, and says what changes by itself:
|
|
136
144
|
|
|
137
145
|
```sh
|
|
138
|
-
ssqch
|
|
146
|
+
ssqch baseline "npx @11ty/eleventy" --commit <the commit before the import>
|
|
147
|
+
ssqch build
|
|
148
|
+
ssqch diff .cache/ssqch/baseline/ref-1 dist # or ref-common, when the builds vary
|
|
139
149
|
```
|
|
140
150
|
|
|
141
|
-
It lists the URLs that were added and removed and what changed on each page, ignoring whitespace between tags
|
|
151
|
+
It lists the URLs that were added and removed and what changed on each page, ignoring whitespace between tags, fingerprinted file names, eleventy-img's and `imagePlugin()`'s image ids, and markup browsers read the same (attribute order, `defer="defer"`, `<br/>`, `'`); `--ignore <regex>` drops differences you expect (a generator meta tag, say). The link checker (`linksPlugin()`) catches pages and anchors that moved, and a `schemas` entry catches front matter that didn't survive the trip.
|
|
152
|
+
|
|
153
|
+
If the site has a second build tool (Gulp, webpack, PostCSS) writing into the same folder, keep it for the first step: build with `ssqch build && <the tool>` (ssqch never touches files it didn't write) and give `ssqch baseline` both commands (`ssqch baseline "npx @11ty/eleventy && npx gulp build"`). ssqch needs Node 22.18 or newer, so a site pinned to an older Node moves its other tools too: build the old site once on the new Node and compare it with the old Node's build, so a difference the new Node makes isn't blamed on ssqch. When `ssqch baseline` says files vary, three builds show that they do, not which version is usual: `--runs 20` (or more) counts each version, and `.cache/ssqch/baseline/ref-common` has each file's most common one to compare with.
|
|
142
154
|
|
|
143
|
-
`ssqch
|
|
155
|
+
`ssqch scout` drafts the mechanical renames above for you; see [Scouting](#scouting). For the whole loop as steps a coding agent can follow (reference builds, the biggest group of differences first, when to stop), see [Moving a site with an agent](../agents.md#moving-a-site-with-an-agent).
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Trailhead: moving from Hugo"
|
|
3
|
+
navTitle: "From Hugo"
|
|
4
|
+
description: "Hugo and SiteSquatch both build pages from Markdown with front matter, a data folder, layouts and static files."
|
|
5
|
+
---
|
|
6
|
+
Hugo and SiteSquatch both build pages from Markdown with front matter, a data folder, layouts and static files. Hugo's content usually moves as it is: the gohugo.io docs (1,007 content files) moved with none of them changed, and 764 of 787 pages came out byte for byte the same. The templates are the work: Hugo's are Go templates, which ssqch doesn't run, and Jinja (ssqch's default) is the closest, since Go's `define` and `block` map onto Jinja's `extends` and `block`, and both trim whitespace with `{{- -}}`.
|
|
7
|
+
|
|
8
|
+
## Scouting
|
|
9
|
+
|
|
10
|
+
`ssqch scout` (see [Scouting a site](../trailheads.md#scouting-a-site)) lists what your site uses, each with its file and line: every shortcode with how many pages call it, the sections (`_index.md`) and `cascade`, the render hooks and ssqch's hook for each, the Go templates, and the Hugo Pipes and functions they call (`js.Build`, `css.TailwindCSS`, `.GetPage`, `.Related`). Its draft (`--write-draft`) is an `ssqch.config.js` that reads the content as Hugo does, and a container template to port for each of the site's own shortcodes:
|
|
11
|
+
|
|
12
|
+
```js
|
|
13
|
+
export default defineConfig({
|
|
14
|
+
dirs: { input: "content", output: "public", includes: "../_includes", data: "../data" },
|
|
15
|
+
// Hugo doesn't run template code in content, and its shortcodes on a line of their own are containers.
|
|
16
|
+
markdownEngine: false,
|
|
17
|
+
markdown: { shortcodes: "hugo", highlight: { classes: "pygments" } },
|
|
18
|
+
passthrough: [{ static: "." }],
|
|
19
|
+
data: { site: { title: "Trail Notes", url: "https://example.com", params: {} } },
|
|
20
|
+
plugins: [sitemapPlugin({ url: "https://example.com" }), linksPlugin({ fail: false })],
|
|
21
|
+
});
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## The config
|
|
25
|
+
|
|
26
|
+
| Hugo (`hugo.toml`) | SiteSquatch (`ssqch.config.js`) |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| `contentDir` (`content/`) | `dirs.input` |
|
|
29
|
+
| `layouts/` | `dirs.includes` (and `dirs.layouts`): templates you write in Jinja |
|
|
30
|
+
| `data/` | `dirs.data` |
|
|
31
|
+
| `static/` | `passthrough: [{ static: "." }]` |
|
|
32
|
+
| `publishDir` | `dirs.output` (`publishDir` works, and says ssqch's name) |
|
|
33
|
+
| `baseURL` | the site's address goes in data and in `sitemapPlugin({ url })`; `base` is the path only, for a site served under one (`/repo/`) |
|
|
34
|
+
| `title`, `params` | global data: `data: { site: { title, params } }`, read as `site.title` |
|
|
35
|
+
| `menus` | global data (`_data/nav.yml`), and `navTree` |
|
|
36
|
+
| `taxonomies` | tags are collections; a page per tag is a page paginated over `collections` |
|
|
37
|
+
| `outputs` (RSS, `_redirects`) | a page per output file, with its `permalink` (`/index.xml`) and `layout: false`; `rssPlugin()` for feeds |
|
|
38
|
+
| `markup.goldmark.parser.autoHeadingIDType` | `markdown.headingIds`: `"github"` (Hugo's default) or `"blackfriday"` |
|
|
39
|
+
| `markup.goldmark.extensions.typographer` | `markdown.smartPunctuation` (it writes characters, where Goldmark writes entities) |
|
|
40
|
+
| `markup.highlight` | `markdown.highlight`, with `classes: "pygments"` for Chroma's class names; inline styles (`noClasses`, Hugo's default) aren't in ssqch, so make a stylesheet (`hugo gen chromastyles`) |
|
|
41
|
+
| `minify` / `--minify` | `minifyPlugin()` from `ssqch/minify` (its own bytes, not Hugo's) |
|
|
42
|
+
| `cascade` | directory data (`posts/posts.json`), which every page below it gets |
|
|
43
|
+
| `aliases` | `redirectsPlugin()`: front matter `aliases` works as it is |
|
|
44
|
+
|
|
45
|
+
## Content
|
|
46
|
+
|
|
47
|
+
- **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 `markdown: { shortcodes: "hugo" }`, 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 isn't read: scout lists those, for a filter of your own.
|
|
49
|
+
- **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
|
+
- **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
|
+
- **Page bundles:** a folder with `index.md` and its images is a bundle in both; set `bundles: true`.
|
|
52
|
+
- **Headless pages** (`build.render: never`, snippets included elsewhere): `permalink: false`, or `ignore` them.
|
|
53
|
+
- **Summaries:** Hugo's `.Summary` is about the first 70 words, in whole paragraphs; ssqch's `page.excerpt` is what's before `<!-- more -->`, or else the first paragraph.
|
|
54
|
+
|
|
55
|
+
## Templates: Go templates in Jinja
|
|
56
|
+
|
|
57
|
+
| Go template | Jinja |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `{{ .Title }}`, `{{ .Params.x }}` | `{{ title }}`, `{{ params.x }}` (the page's data is the context) |
|
|
60
|
+
| `{{ site.Title }}`, `{{ .Site.Params.x }}` | `{{ site.title }}`, `{{ site.params.x }}` (global data) |
|
|
61
|
+
| `{{ with .Description }}{{ . }}{{ end }}` | `{% if description %}{{ description }}{% endif %}` |
|
|
62
|
+
| `{{ range .Pages }}...{{ end }}` | `{% for p in collections.x %}...{% endfor %}` |
|
|
63
|
+
| `{{ range $i, $p := ... }}` | `loop.index0` |
|
|
64
|
+
| `{{ partial "x.html" . }}` | `{% include "partials/x.jinja" %}` (it shares the context) |
|
|
65
|
+
| `{{ partial "x.html" (dict "a" 1) }}` | a macro: `{% from "partials/x.jinja" import x %}{{ x(a=1) }}` |
|
|
66
|
+
| a partial that `return`s a value | a filter in `ssqch.config.js` |
|
|
67
|
+
| `{{ define "main" }}` in `baseof.html` | `{% extends "baseof.jinja" %}{% block main %}...{% endblock %}` |
|
|
68
|
+
| `{{ block "x" . }}default{{ end }}` | `{% block x %}default{% endblock %}` |
|
|
69
|
+
| `{{- ... -}}` | `{%- ... -%}` and `{{- ... -}}` (the same trimming) |
|
|
70
|
+
| `{{/* comment */}}` | `{# comment #}` |
|
|
71
|
+
| `{{ .Content }}` | `{{ content }}` in a layout |
|
|
72
|
+
| `{{ .TableOfContents }}` | `{{ toc(page.headings) | safe }}` |
|
|
73
|
+
| `{{ .Date.Format "January 2, 2006" }}` | `{{ page.date | dateformat("%B %-d, %Y") }}` |
|
|
74
|
+
| `markdownify`, `.RenderString` | `markdown(text)`, `markdown(text, "inline")` |
|
|
75
|
+
| `urlize`, `anchorize` | `slugify` |
|
|
76
|
+
| `site.GetPage "/x"` | a filter over `collections.all` |
|
|
77
|
+
|
|
78
|
+
## Render hooks
|
|
79
|
+
|
|
80
|
+
| Hugo `layouts/_markup/` | ssqch `_includes/hooks/` |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `render-link.html` (`.Destination`, `.Text`, `.Title`) | `link.*` (`link.href`, `link.content`, `link.title`) |
|
|
83
|
+
| `render-image.html` | `image.*` (`image.src`, `alt`, `title`) |
|
|
84
|
+
| `render-heading.html` | `heading.*` |
|
|
85
|
+
| `render-codeblock.html` (`.Type`, `.Inner`, `.Attributes`) | `fence.*` (`fence.lang`, `fence.code`, `fence.info`), or `fence-<lang>.*` for one language |
|
|
86
|
+
| `render-blockquote.html` for alerts | GitHub's `> [!NOTE]` alerts are built in (`alerts`), styled by `containers/note.*` |
|
|
87
|
+
| `render-table.html`, `render-passthrough.html` | not in ssqch yet |
|
|
88
|
+
|
|
89
|
+
## Hugo Pipes
|
|
90
|
+
|
|
91
|
+
| Hugo | SiteSquatch |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `css.TailwindCSS` | Tailwind's CLI as a `beforeBuild` step |
|
|
94
|
+
| `js.Build` | esbuild as a `beforeBuild` step, or `ssqch/assets` |
|
|
95
|
+
| `css.Sass`, `toCSS` | `sassPlugin()` from `ssqch/sass` |
|
|
96
|
+
| `fingerprint` | `assetsPlugin()` from `ssqch/assets` |
|
|
97
|
+
| `minify` | `minifyPlugin()` |
|
|
98
|
+
| `resources.Get` | `passthrough` |
|
|
99
|
+
| `.Resize`, `.Fill` | `imagePlugin()` from `ssqch/image` makes responsive `<picture>`s; `image()` for one file |
|
|
100
|
+
|
|
101
|
+
## Build it both ways
|
|
102
|
+
|
|
103
|
+
`ssqch baseline "hugo --gc --minify" --from public` builds the site with Hugo, in fresh copies with the clock pinned; it copies `node_modules` into each copy, since Hugo's `js.Build` refuses one linked from outside. Then `TZ=UTC ssqch build`, and `ssqch scout --compare` (or `ssqch diff .cache/ssqch/baseline/ref-common public`) lists the biggest groups of differences first. `ssqch docs "moving a site with an agent"` has the whole loop.
|
|
@@ -5,7 +5,19 @@ description: "Jekyll sites move well."
|
|
|
5
5
|
---
|
|
6
6
|
Jekyll sites move well: Liquid runs as it is, `_layouts/`, `_includes/` and `_data/` keep their names, and `redirect_from`, `relative_url`, `markdownify` and `jsonify` work. What takes the time is the Ruby around the templates (Jekyll's `page` and `site`, its plugins) and kramdown, Jekyll's Markdown.
|
|
7
7
|
|
|
8
|
-
opensource.guide (382 pages in 29 languages, on GitHub Pages' gem) was moved this way as a study: the same 478 files, 95% of pages with the same text, and builds 5.9 times faster. Two thirds of the work was kramdown's `markdown="1"`, which ssqch
|
|
8
|
+
opensource.guide (382 pages in 29 languages, on GitHub Pages' gem) was moved this way as a study: the same 478 files, 95% of pages with the same text, and builds 5.9 times faster. Two thirds of the work was kramdown's `markdown="1"`, which ssqch reads now: `markdown: { htmlMarkdown: "kramdown" }` (below).
|
|
9
|
+
|
|
10
|
+
## Scouting
|
|
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`, `trimAfterFrontMatter`, 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 `jekyllTemplates`, 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
|
+
|
|
14
|
+
```sh
|
|
15
|
+
ssqch scout # what moving the site takes
|
|
16
|
+
ssqch scout --write-draft --patch move.patch # write the draft, and the edits as a patch
|
|
17
|
+
git apply move.patch # after reading it
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The [`jekyll-guides`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/jekyll-guides/) example is a small Jekyll site laid out as Jekyll lays one out, with these settings: its layouts and pages are written for Jekyll and run as they are.
|
|
9
21
|
|
|
10
22
|
## Build it both ways first
|
|
11
23
|
|
|
@@ -13,7 +25,7 @@ Build the Jekyll site from a fresh checkout twice and compare the two: a page th
|
|
|
13
25
|
|
|
14
26
|
## The config
|
|
15
27
|
|
|
16
|
-
Start with `templateFormats: ["liquid", "md", "html"]`, `markdownEngine: "liquid"` and `htmlEngine: "liquid"`, so Markdown and HTML pages run through Liquid first, as in Jekyll,
|
|
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" }`, and `trimAfterFrontMatter: true`, so a layout's body starts where Jekyll's does (Jekyll drops the blank lines after the closing `---`).
|
|
17
29
|
|
|
18
30
|
```js
|
|
19
31
|
import { defineConfig, readData } from "ssqch";
|
|
@@ -27,6 +39,9 @@ export default defineConfig({
|
|
|
27
39
|
markdownEngine: "liquid",
|
|
28
40
|
htmlEngine: "liquid",
|
|
29
41
|
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 },
|
|
30
45
|
ignore: ["Gemfile", "Gemfile.lock", "README.md", "script/**"],
|
|
31
46
|
data: { site },
|
|
32
47
|
plugins: [sitemapPlugin({ url: site.url }), redirectsPlugin()],
|
|
@@ -46,11 +61,15 @@ export default defineConfig({
|
|
|
46
61
|
|
|
47
62
|
## Templates
|
|
48
63
|
|
|
49
|
-
- **`page` and front matter:** in
|
|
50
|
-
- **`site.posts` and collections:** `
|
|
64
|
+
- **`page`, `site` and front matter:** `jekyllTemplates: true` (scout's draft turns it on) 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.
|
|
65
|
+
- **`site.posts` and collections:** with `jekyllTemplates`, `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
|
+
- **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
|
+
- **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
|
+
- **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 `jekyllTemplates`, `site.data.locales` works too.
|
|
51
70
|
- **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.
|
|
52
|
-
- **Plugin tags** (`{% seo %}`, `{% feed_meta %}`):
|
|
53
|
-
- **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).
|
|
71
|
+
- **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
|
+
- **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.
|
|
54
73
|
- **A table of contents:** `toc(page.headings, { class: "section-nav", itemClass: "toc-entry toc-h{level}" })` writes jekyll-toc's markup, so its CSS keeps working (`{{ page.headings | toc: class: "section-nav" }}` in Liquid). It reads the page's headings after it renders, so it goes in the layout.
|
|
55
74
|
- **Files with front matter:** Jekyll renders any file that starts with `---`. In ssqch a `.js` (or `.txt`) file needs an engine: `engines: { js: (s) => s }`, `"js"` in `templateFormats`, and `"render": "liquid,js"` with a `.js` permalink in that folder's directory data ("Text files with front matter" in [Templates and data](../templates.md)).
|
|
56
75
|
|
|
@@ -58,25 +77,40 @@ export default defineConfig({
|
|
|
58
77
|
|
|
59
78
|
| Jekyll | ssqch |
|
|
60
79
|
| --- | --- |
|
|
61
|
-
| jekyll-redirect-from | `redirect_from` works (ssqch calls it `aliases`), with `redirectsPlugin()`; `_includes/hooks/redirect.*` for its page's markup |
|
|
62
|
-
| jekyll-sitemap | `sitemapPlugin({ url })` |
|
|
80
|
+
| 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 })`; with an empty `url`, paths from the root, as jekyll-sitemap writes them, and a warning |
|
|
63
82
|
| jekyll-feed | `rssPlugin()` and a feed template |
|
|
64
83
|
| jekyll-seo-tag | A `seo` function (a tag), or an include with the tags you use |
|
|
65
84
|
| jekyll-toc | `toc(page.headings, ...)`, above |
|
|
66
85
|
| jekyll-github-metadata | Data in the config (`site.github.repository_nwo`) |
|
|
67
86
|
| github-pages' default theme (jekyll-theme-primer) | Nothing: it writes `/assets/css/style.css`. Check whether a page links to it. |
|
|
68
87
|
|
|
88
|
+
## Porting a site's own plugins
|
|
89
|
+
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
|
+
| In the Ruby | What it is | In ssqch |
|
|
93
|
+
| --- | --- | --- |
|
|
94
|
+
| `Liquid::Template.register_filter(Module)` | A filter for each method of the module | A function in `filters`: `posted_by: (date, author) => ...`; the method's arguments are the function's |
|
|
95
|
+
| `Liquid::Template.register_tag("name", Class)` | A tag | A function in `filters` is a tag too: `{% translation_status %}` calls `translation_status()` and prints what it returns; a block tag's function gets the content first |
|
|
96
|
+
| `@context.registers[:site]`, `@context.environments.first["page"]` | The site or the page, read from Liquid's context | A function sees only its arguments: pass what it reads (`{{ post.date \| posted_by: post.author, lang }}`), or keep site-wide lists in the module, filled by a collection function |
|
|
97
|
+
| `class X < Jekyll::Generator` that adds `Jekyll::Page`s | Pages made from data (archives by year and month) | A collection function that returns one object per page (`{ url, layout, title, posts }`), and one template paginated over it with `size: 1` and a `permalink` from the item |
|
|
98
|
+
| `Jekyll::Hooks.register :site, :post_read` that sets `page.data[...]` | Data on every page | `computed` in the config's `data` |
|
|
99
|
+
| `Jekyll::Hooks.register :site, :post_write` that writes files | Files written after the build: a search index, `llms.txt` | `afterBuild`: a function, or a program (`{ run: "npx pagefind --site _site" }`) |
|
|
100
|
+
| `Jekyll::Converter` | A file type of its own | An engine for its extension (`engines`) |
|
|
101
|
+
|
|
102
|
+
What a plugin printed with Ruby's own methods (`strftime`, `Time#to_s`, `Hash` order) has to be written the same way in JavaScript: Ruby's `sort` isn't stable, and a whole `Float` prints as `4.0`. If Jekyll's build needs a file a tool writes first (a Tailwind `compiled.css` that's in `.gitignore`), put that step in the baseline's command (`ssqch baseline "npm run build-css && bundle exec jekyll build"`) and in ssqch's: `beforeBuild: [{ run: "npm run build-css" }]`.
|
|
103
|
+
|
|
69
104
|
## Markdown
|
|
70
105
|
|
|
71
|
-
ssqch's Markdown is CommonMark; Jekyll's is kramdown. `markdown: { smartPunctuation: true, autolinks: false }` comes closest. What differs:
|
|
106
|
+
ssqch's Markdown is CommonMark; Jekyll's is kramdown. `markdown: { smartPunctuation: true, autolinks: false, htmlMarkdown: "kramdown", headingIds: "kramdown", encodeUrls: false }` comes closest. What differs:
|
|
72
107
|
|
|
73
|
-
- **`markdown="1"`** on an HTML element (kramdown reads its content as Markdown):
|
|
74
|
-
- **
|
|
75
|
-
- **Heading ids:** kramdown's GFM ids keep accents and other letters, as ssqch's do; headings inside HTML get kramdown's ASCII ids (`section`, `section-1`).
|
|
108
|
+
- **`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
|
+
- **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.
|
|
76
110
|
- **Bold next to punctuation** (`**完成。**下一步`) closes in kramdown but not in CommonMark.
|
|
77
|
-
- **Code:** GitHub Pages adds Rouge's `class="language-plaintext highlighter-rouge"` to code; ssqch doesn't (`markdown: { highlight: true }` highlights, with its own classes).
|
|
78
|
-
-
|
|
111
|
+
- **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; `encodeUrls: false` writes them as kramdown does. Smart quotes next to non-Latin letters can come out differently; readers see the same page.
|
|
79
113
|
|
|
80
114
|
## Checking the move
|
|
81
115
|
|
|
82
|
-
`ssqch diff` lists the files that differ and how. Most of what's left after the steps above is Markdown:
|
|
116
|
+
`ssqch baseline "bundle exec jekyll build"` builds the Jekyll site three times from fresh copies, with the clock pinned and the site's gems linked in (`.bundle` and its `BUNDLE_PATH`), into `.cache/ssqch/baseline/ref-1` to `-3`, with Jekyll's `site.time` pinned by a `time:` config of its own, and says what changes by itself; then `ssqch diff .cache/ssqch/baseline/ref-1 _site` lists the files that differ and how. Most of what's left after the steps above is Markdown: kramdown's spacing and quotes. `linksPlugin()` from `ssqch/links` checks every internal link and anchor on each build.
|
|
@@ -7,40 +7,85 @@ MkDocs and SiteSquatch both build a site from a folder of Markdown and one confi
|
|
|
7
7
|
|
|
8
8
|
The [`docs-sidebar`](https://github.com/reverentgeek/sitesquatch/tree/main/examples/sites/docs-sidebar/) example is distilled from the FastAPI docs (and hexo.io): a sidebar from a YAML nav, a table of contents, admonitions, code from files and Pagefind search.
|
|
9
9
|
|
|
10
|
+
## Scouting
|
|
11
|
+
|
|
12
|
+
`ssqch scout` (see [Scouting a site](../trailheads.md#scouting-a-site)) reads `mkdocs.yml` and the pages: each plugin and Markdown extension with ssqch's way to do it, and the MkDocs syntax the pages use, counted (links to `.md` files, admonitions, tabs, snippets, icons, mkautodoc's and mkdocstrings' `:::` blocks), and what MkDocs writes on its own (`search/search_index.json`, `404.html`, `sitemap.xml.gz`). Its reference build names the Python environment MkDocs needs (`pip install -r requirements.txt`, and a `.venv`'s `mkdocs` when there is one). Its draft (`--write-draft`) is an `ssqch.config.js` that reads the pages as MkDocs writes them, with no page changed, and the nav as `_data/nav.yml` (titles from the nav, or each page's first heading). On Material for MkDocs' own docs, the draft built every page from a fresh checkout:
|
|
13
|
+
|
|
14
|
+
```js
|
|
15
|
+
export default defineConfig({
|
|
16
|
+
dirs: { input: "docs", output: "site", includes: "../_includes", data: "../_data" },
|
|
17
|
+
base: "/mkdocs-material/", // site_url's path
|
|
18
|
+
markdownEngine: false, // MkDocs doesn't run template code in pages
|
|
19
|
+
markdown: { admonitions: "mkdocs", tabs: "mkdocs", sourceLinks: "relative", headingIds: "python-markdown", highlight: { classes: "pygments" } },
|
|
20
|
+
passthrough: [{ "docs/**/*.png": "." }, { "docs/CNAME": "CNAME" }], // MkDocs copies the docs folder's other files
|
|
21
|
+
// MkDocs warns about a broken link unless strict: true, and so does the draft.
|
|
22
|
+
plugins: [sitemapPlugin({ url: "https://squidfunk.github.io/mkdocs-material" }), redirectsPlugin({ redirects: { "/old/": "/new/" } }), linksPlugin({ fail: false })],
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## The theme
|
|
27
|
+
|
|
28
|
+
`mkdocsTemplates: 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 mkdocsTemplates` has the details.
|
|
29
|
+
|
|
30
|
+
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
|
+
|
|
32
|
+
```sh
|
|
33
|
+
M=$(python -c "import material, os; print(os.path.dirname(material.__file__))")/templates
|
|
34
|
+
mkdir -p theme/_includes && cp -R "$M"/. theme/_includes/ && mv theme/_includes/assets theme/assets
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
export default defineConfig({
|
|
39
|
+
dirs: { input: "docs", output: "site", includes: "overrides" }, // theme.custom_dir, from docs_dir
|
|
40
|
+
theme: "theme",
|
|
41
|
+
mkdocsTemplates: true,
|
|
42
|
+
markdownEngine: false,
|
|
43
|
+
markdown: { admonitions: "mkdocs", tabs: "mkdocs", sourceLinks: "relative", headingIds: "python-markdown", dialect: "python-markdown", highlight: { classes: "pygments" } },
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
On the httpx docs (Material, 24 pages), this config, with no template changed and no code of the site's own, built every page with Material's nav, table of contents, header and footer byte for byte as MkDocs wrote them; the differences left were highlighted code (Pygments' tokens), the two pages mkautodoc writes from Python, and the search index. What it doesn't do: MkDocs' plugins (Material's search index, `sitemap.xml.gz`, its blog and social cards), and Python's own code in hooks.
|
|
48
|
+
|
|
10
49
|
## The config
|
|
11
50
|
|
|
12
51
|
| `mkdocs.yml` | `ssqch.config.js` |
|
|
13
52
|
| --- | --- |
|
|
14
53
|
| `docs_dir`, `site_dir` | `dirs: { input, output }` |
|
|
15
54
|
| `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. |
|
|
16
|
-
| `theme: material` and its options |
|
|
17
|
-
| `theme.custom_dir` / `overrides/` (Jinja) |
|
|
55
|
+
| `theme: material` and its options | The theme's own templates with `mkdocsTemplates: true` ([The theme](#the-theme), below), or templates of your own (start from `docs-sidebar`) |
|
|
56
|
+
| `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 |
|
|
18
57
|
| `extra:` | `_data/site.yml` |
|
|
19
58
|
| `use_directory_urls: true` | The default: `install.md` is `/install/` |
|
|
20
|
-
| `plugins: [search]` | [Pagefind](https://pagefind.app) after the build: `afterBuild: { run: "npx -y pagefind --site dist" }` |
|
|
59
|
+
| `plugins: [search]` (on when `plugins` isn't set) | [Pagefind](https://pagefind.app) after the build: `afterBuild: { run: "npx -y pagefind --site dist" }`. Material's own search box reads MkDocs' `search/search_index.json`, which isn't in ssqch yet: a page that loops over `collections.all` can write it |
|
|
21
60
|
| `mkdocs-redirects` | `redirectsPlugin({ redirects })` from `ssqch/redirects`, or `aliases` on each page |
|
|
22
61
|
| `git-revision-date-localized` | `lastModified: "git"`, then `page.lastModified` |
|
|
23
62
|
| `mkdocs-macros` (Jinja in Markdown) | Built in: Markdown runs through Jinja first (`markdownEngine: "jinja"`, the default) |
|
|
24
63
|
| `extra_css` with Sass | `sassPlugin()` from `ssqch/sass` |
|
|
25
|
-
| `strict: true` | `linksPlugin()`
|
|
64
|
+
| `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 `mkdocsTemplates`, 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`) |
|
|
26
66
|
|
|
27
67
|
## Markdown extensions
|
|
28
68
|
|
|
29
69
|
| Python-Markdown / PyMdown | SiteSquatch |
|
|
30
70
|
| --- | --- |
|
|
31
|
-
| `admonition`: `!!! note "Title"` and an indented body |
|
|
32
|
-
| `pymdownx.details`: `??? note` |
|
|
33
|
-
| `pymdownx.tabbed`: `=== "Tab"` | `:::: tabs` holding `::: tab Name` containers (see `versioned-docs`) |
|
|
71
|
+
| `admonition`: `!!! note "Title"` and an indented body | `markdown: { admonitions: "mkdocs" }` 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. |
|
|
72
|
+
| `pymdownx.details`: `??? note` | `admonitions: "mkdocs"` too: `<details class="note">`, open with `???+`. Or a container whose template writes `<details>` (see `docs-sidebar`'s `details` container) |
|
|
73
|
+
| `pymdownx.tabbed`: `=== "Tab"` | `markdown: { tabs: "mkdocs" }` reads them as they are, in the alternate style's markup. Or `:::: tabs` holding `::: tab Name` containers (see `versioned-docs`) |
|
|
34
74
|
| `pymdownx.superfences` custom fences (`mermaid`) | A `fence-mermaid` hook |
|
|
35
|
-
| `pymdownx.highlight`, `hl_lines="2 3"` | `markdown: { highlight:
|
|
75
|
+
| `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
|
+
| `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 |
|
|
36
77
|
| `pymdownx.snippets`: `--8<-- "file.py"` | `{% include "samples/file.py" %}` inside the fence |
|
|
37
|
-
| `toc` with `permalink: true` |
|
|
78
|
+
| `toc` with `permalink: true` | `markdown: { headingIds: "python-markdown" }` gives toc's default ids (a repeated heading gets `_1`, as toc writes it); a heading hook adds the permalink. `toc(page.headings)` builds the table of contents. |
|
|
38
79
|
| `attr_list`: `## Title { #id }` | `## Title {#id}` |
|
|
80
|
+
| Links to other pages' `.md` files | `markdown: { 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 |
|
|
39
81
|
| `footnotes`, `tables` | Built in |
|
|
40
82
|
| `def_list` | `markdown: { definitionLists: true }` |
|
|
41
83
|
| `md_in_html` (`markdown="1"`) | The `markdown` filter, or a container |
|
|
42
84
|
| `pymdownx.emoji` (`:smile:`) | Not built in; write the emoji |
|
|
43
85
|
|
|
86
|
+
> [!NOTE]
|
|
87
|
+
> **Byte for byte:** a move that has to match MkDocs' output exactly needs four things from Python today: Pygments for highlighted code (codehilite's markup and tokens), mkautodoc or mkdocstrings for API pages, Material's search indexer for `search/search_index.json`, and Python's gzip for `sitemap.xml.gz`. Run them once per build in `beforeBuild` or `afterBuild`. For the rest of Python-Markdown's ways (raw HTML blocks to their closing tag, lists nested at four spaces, `"` as it is in text, `<hr />`), set `markdown: { dialect: "python-markdown" }`. The fresh httpx move matched MkDocs byte for byte this way.
|
|
88
|
+
|
|
44
89
|
## Pages
|
|
45
90
|
|
|
46
91
|
Front matter (`title`, `description`, and anything else) is the same YAML. MkDocs reads a page's title from its first heading when there's no `title`; in ssqch, give each page a `title` or use `page.headings[0].text` in the layout. A schema makes the first a rule: `schemas: { docs: { files: "docs/**/*.md", fields: { title: "string" } } }` fails the build for a page without one.
|