@jtakeit/astro 0.1.0

package/template/figures.mjs

@@ -0,0 +1,122 @@
+/**
+ * A picture in a post is a figure, and pictures side by side are a row.
+ *
+ * ── the shape, and why it is not a new syntax ───────────────────────────────
+ *
+ * Markdown gives a body one shape of picture: `![alt](x.jpg)`, alone, as wide
+ * as the stylesheet says. There is no caption and no way to say "these three
+ * belong together" — and inventing a syntax for it would make the body a
+ * private dialect. A `.md` file in `jtk/content/` is committed, read by
+ * people and written by agents, and the one thing it has to stay is markdown.
+ *
+ * It turns out CommonMark says both things already, and nobody was listening:
+ *
+ *   ![](one.jpg)             one paragraph, one image   → a figure
+ *
+ *   ![](one.jpg)             ONE paragraph, three       → a row
+ *   ![](two.jpg)
+ *   ![](three.jpg)
+ *
+ * Images on consecutive lines with no blank line between them are a single
+ * paragraph. That is plain CommonMark, it renders anywhere, and it is already
+ * an honest statement that they belong together — so it is the row, with
+ * nothing added. A blank line between them is somebody saying they are
+ * separate, and this believes them.
+ *
+ * The caption is the title slot, which CommonMark has had all along:
+ *
+ *   ![A healed sleeve](healed.jpg "Three weeks later, unretouched")
+ *
+ * `alt` stays the description somebody hears; the title becomes the caption
+ * somebody reads. Two jobs that already had two slots. Left alone it would
+ * render as a tooltip, which is nobody's idea of a caption.
+ *
+ * ── what comes out ─────────────────────────────────────────────────────────
+ *
+ *   <figure class="fl-figure"><img …><figcaption>…</figcaption></figure>
+ *
+ *   <div class="fl-row fl-row--3">
+ *     <figure class="fl-figure"><img …></figure>
+ *     …
+ *   </div>
+ *
+ * `fl-row--2`, `--3`, `--4`; four means four or more and the stylesheet wraps.
+ * Those two class names are the whole surface — a site restyles them and does
+ * not invent others, which is what keeps "what a body can look like" a decision
+ * the kit made once rather than one every site makes again.
+ *
+ * ── where it sits in the pipeline ──────────────────────────────────────────
+ *
+ * A user hast plugin runs **before** Astro's image marker, which is what makes
+ * this safe: the marker finds `<img>` by tag anywhere in the tree, so wrapping
+ * one changes nothing about how it is optimised. It also strips every property
+ * off an `<img>` except `className`, which is why the caption has to be taken
+ * off the picture here rather than read off the built page later.
+ */
+
+/** How many pictures a row names before the stylesheet is left to wrap them. */
+const WIDEST = 4;
+
+export function figures() {
+  return {
+    name: 'jtakeit-figures',
+    element: {
+      filter: ['p'],
+      visit(node, ctx) {
+        const pictures = onlyPictures(node);
+        if (pictures === null) return;
+
+        const made = pictures.map(figureOf);
+        ctx.replaceNode(node, made.length === 1 ? made[0] : rowOf(made));
+      },
+    },
+  };
+}
+
+/**
+ * The pictures in this paragraph, if that is all it holds.
+ *
+ * A paragraph with a picture and a sentence is a paragraph with a picture in
+ * it, and turning that into a figure would take the sentence out of the text it
+ * belongs to. The whitespace is what the newlines left behind, not content.
+ */
+function onlyPictures(node) {
+  const pictures = [];
+
+  for (const child of node.children ?? []) {
+    if (child.type === 'text' && String(child.value ?? '').trim() === '') continue;
+    if (child.type === 'element' && child.tagName === 'img') {
+      pictures.push(child);
+      continue;
+    }
+    return null;
+  }
+
+  return pictures.length === 0 ? null : pictures;
+}
+
+function figureOf(image) {
+  const { title, ...rest } = image.properties ?? {};
+  const said = typeof title === 'string' ? title.trim() : '';
+
+  const children = [{ type: 'element', tagName: 'img', properties: rest, children: [] }];
+  if (said !== '') {
+    children.push({
+      type: 'element',
+      tagName: 'figcaption',
+      properties: {},
+      children: [{ type: 'text', value: said }],
+    });
+  }
+
+  return { type: 'element', tagName: 'figure', properties: { className: ['fl-figure'] }, children };
+}
+
+function rowOf(made) {
+  return {
+    type: 'element',
+    tagName: 'div',
+    properties: { className: ['fl-row', `fl-row--${Math.min(made.length, WIDEST)}`] },
+    children: made,
+  };
+}

package/template/gitignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+.astro/
+.env
+.env.*
+.DS_Store
+
+# Assembled at build time by the platform's pipeline from jtk/content/*.json.
+# A build artifact that happens to sit at the repository root; a stale copy in
+# git is a second answer to "what does this site say".
+jtk-content.json
+
+# An entry's pictures, downloaded beside the entry at build time: a picture in
+# a post's body is markdown — `![alt](media/<site>/<hash>.jpg)` — resolved
+# relative to the file, so the build puts the file exactly where the body says.
+jtk/content/**/media/

package/template/jtakeit-meta.mjs

@@ -0,0 +1,112 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { specimenAddresses } from './specimens.mjs';
+import { BLOCKS, COLLECTIONS, LOCALES } from './src/content/blocks.ts';
+
+/**
+ * `_meta.json` — what the edge needs to know that the HTML cannot say.
+ *
+ * Cloudflare Pages read `_redirects` and `_headers` out of the build. The
+ * studio serves sites from its own Worker instead, and this file is what
+ * replaced them: one small object beside the pages, written by the build.
+ *
+ * ── drafts, and why the list has to exist ───────────────────────────────────
+ *
+ * An entry nobody has finished is **built** — that is how its author looks at
+ * it before it is out — and it is in no listing, no feed and no sitemap. What
+ * stops a stranger reading it is the edge, and the edge is serving static
+ * objects: it has no way to tell a draft from a page except to be told. This is
+ * being told.
+ *
+ * It is the same mechanism that already decides who sees `data-jtk-path`: one
+ * artifact, one place that decides who sees what is in it.
+ *
+ * ── and the specimens, which have no file at all ────────────────────────────
+ *
+ * The build also draws one page per arrangement, so that the admin can lift
+ * this site's own markup for a block a post has just been given. They are
+ * generated from the declaration rather than written, so looking for their
+ * documents finds nothing — and a draft nobody can find is a draft the edge
+ * hands to anybody. They are derived the same way the loader derives them,
+ * from `specimens.mjs`, which is why that rule lives in one file.
+ *
+ * The file is written whatever happens, empty lists and all, because a missing
+ * one and an empty one mean different things to whoever is debugging.
+ *
+ * ── the disclosure is not here any more ────────────────────────────────────
+ *
+ * It briefly was: a version number this file wrote, which the platform read and
+ * believed. It is gone, and what replaced it is better in the way that matters
+ * — the platform now reads the built pages and looks for the address itself,
+ * so what used to be a claim is a check. See PROCESSING_URL in
+ * src/content/blocks.ts.
+ */
+export function jtakeitMeta() {
+  return {
+    name: 'jtakeit-meta',
+    hooks: {
+      'astro:build:done': async ({ dir, logger }) => {
+        const drafts = [
+          ...(await hiddenEntries()),
+          ...specimenAddresses(COLLECTIONS, BLOCKS, LOCALES),
+        ].sort();
+        const meta = { redirects: [], drafts };
+
+        await writeFile(join(fileURLToPath(dir), '_meta.json'), JSON.stringify(meta, null, 2) + '\n');
+        if (drafts.length > 0) {
+          logger.info(`${drafts.length} unfinished entr${drafts.length === 1 ? 'y' : 'ies'} — served only to an editing session`);
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Every entry whose document says it is not on the site yet.
+ *
+ * A document, not frontmatter: an entry is a page of blocks in a `.json` file
+ * now, and this went on reading `.md` after that changed — so it found no
+ * drafts at all, and every unfinished post was served to anybody who guessed
+ * the address. Nothing failed and nothing was logged, which is how a silent
+ * list stays wrong.
+ */
+async function hiddenEntries() {
+  const root = join(process.cwd(), 'jtk', 'content');
+  const out = [];
+
+  const walk = async (at) => {
+    let entries;
+    try {
+      entries = await readdir(at, { withFileTypes: true });
+    } catch {
+      return; // a site with no content directory is a site with no drafts
+    }
+
+    for (const entry of entries) {
+      const full = join(at, entry.name);
+      if (entry.isDirectory()) {
+        // The pictures the build downloaded beside an entry.
+        if (entry.name !== 'media') await walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.json')) continue;
+
+      let document;
+      try {
+        document = JSON.parse(await readFile(full, 'utf8'));
+      } catch {
+        continue; // unreadable JSON is the build's error to report, not this one
+      }
+      // Only an entry carries this key at all; a page has no `visible` and is
+      // not a draft. `=== false` and not falsy: absent means listed.
+      if (document?.visible === false) {
+        const name = relative(root, full).split(sep).join('/').replace(/\.json$/, '');
+        out.push(`/${name}/`);
+      }
+    }
+  };
+
+  await walk(root);
+  return out.sort();
+}

package/template/jtk/content/index.json

@@ -0,0 +1,38 @@
+{
+  "path": "/",
+  "seo": {
+    "title": "",
+    "description": ""
+  },
+  "blocks": [
+    {
+      "_key": "hero0001",
+      "type": "hero",
+      "v": 1,
+      "eyebrow": "",
+      "title": "",
+      "lead": "",
+      "cta_label": "",
+      "cta_href": "#contact",
+      "image": "",
+      "image_alt": ""
+    },
+    {
+      "_key": "ctab0001",
+      "type": "cta_banner",
+      "v": 1,
+      "title": "",
+      "lead": "",
+      "cta_label": "",
+      "cta_href": "#contact",
+      "form": true
+    },
+    {
+      "_key": "ques0001",
+      "type": "questions",
+      "v": 1,
+      "title": "",
+      "items": []
+    }
+  ]
+}

package/template/jtk/design.json

@@ -0,0 +1,24 @@
+{
+  "v": 2,
+  "field": "",
+  "scrim": true,
+  "ground": "",
+  "colors": [],
+  "paper": "",
+  "ink": "",
+  "accent": "",
+  "surface": {
+    "pattern": "",
+    "scope": "page",
+    "size": "",
+    "weight": "",
+    "opacity": 0,
+    "draw": false,
+    "edge": "",
+    "reveal": ""
+  },
+  "photos": {
+    "treatment": "",
+    "amount": 0
+  }
+}

package/template/markdown.mjs

@@ -0,0 +1,36 @@
+import { figures } from './figures.mjs';
+
+/**
+ * How this site turns markdown into HTML, in one place because two things ask.
+ *
+ * `astro.config.mjs` asks, for every `.md` Astro renders itself. And
+ * `src/lib/entryLoader.ts` asks, because a post's prose is a *string* inside a
+ * JSON document now and Astro's own `renderMarkdown` builds its renderer
+ * **without** the configured plugins — that is its code, not a setting: it
+ * passes `image`, `syntaxHighlight`, `shikiConfig`, `gfm` and `smartypants`,
+ * and nothing else.
+ *
+ * So a body rendered through the loader would silently lose `figures.mjs`: a
+ * row of three photographs would come out as three paragraphs, on the page but
+ * not in the preview beside the editor, which is the worst way to find out.
+ * The loader builds the same renderer with the same options, and this is the
+ * one place either of them reads.
+ */
+/**
+ * The default layout for a picture that has no props to carry one — which is
+ * every picture in a body, because a body is markdown.
+ *
+ * Typed, because without the annotation `{ layout: 'constrained' }` widens to
+ * `{ layout: string }` and `string` is not an `ImageLayout`. Under `// @ts-check`
+ * that is an error in astro.config.mjs rather than a note here.
+ *
+ * This belongs to the **site's** image config and to nothing else. The markdown
+ * processor also takes an `image` option, and it is a different thing entirely
+ * — `{ domains, remotePatterns }`, about which remote pictures may be fetched —
+ * so this must not be handed to it. It was, and it meant nothing there.
+ *
+ * @type {import('astro').AstroUserConfig['image']}
+ */
+export const IMAGE = { layout: 'constrained' };
+
+export const HAST_PLUGINS = [figures()];