astro-atmosphere-publishing 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.1.1 (7 November 2026)
+
+- **@mentions, #hashtags and links in announcements work**, as in the Bluesky app: they become links, and mentioned accounts are notified. The preview lists what each announcement will link.
+- **`share` setting:** how much of each post goes into its record's searchable text: `"more"` (default, as before: everything above `<!--more-->`, or the whole post without a marker), `"intro"` (the first paragraph when there's no marker), `"full"` or `"none"`. Set it for the site, a collection, or a post (`share:` in its frontmatter). Nothing changes for existing sites.
+
+## 0.1.0 (7 November 2026)
 
 First release, built from saltedlolly.com's own publishing script.
 

package/README.md

@@ -92,12 +92,26 @@ npx atmosphere-publishing publish   # do it
 
 `publish` needs `ATPROTO_HANDLE` and `ATPROTO_APP_PASSWORD`, from the environment or a `.env` file. Then commit `src/data/atmosphere-publishing.json`, build and deploy.
 
+## How much of each post is shared
+
+Each record carries the post's title, description, tags, dates and cover image, plus searchable text: always plain text, with no formatting, images or link addresses. Reader apps link to your site to read the post. The `share` setting decides how much text that is:
+
+| `share` | Searchable text |
+| --- | --- |
+| `"more"` (default) | Everything above `<!--more-->`, or the whole post when there's no marker |
+| `"intro"` | Everything above `<!--more-->`, or just the first paragraph when there's no marker |
+| `"full"` | The whole post |
+| `"none"` | None: the record keeps its title and description |
+
+Set it for the whole site (`share` in the settings), a collection, or one post (`share: full` in its frontmatter).
+
 ## Announcements
 
 - **New posts** (published within `announceWithinDays`, default 14) are announced, dated now.
 - The announcement's text is the post's own wording, `announce: "…"` in its frontmatter, shown above the link card. **Write it for every post:** the card already shows the title and description, so say something new. Without it, the announcement is the link card alone.
 - **Older posts** are announced only when they ask (`announce: "…"`, or `announce: true` for the card alone). Their announcement is dated to the post itself, so Bluesky files it in the past and it doesn't reach followers' timelines, but it still gives the post a comment thread.
 - `announce: false` never announces a post.
+- @mentions, #hashtags and links in the wording work as in the Bluesky app: they become links, and mentioned accounts are notified. The preview lists what each announcement will link.
 - Each post is announced once.
 
 ## With Atmosphere Comments for Astro
@@ -160,7 +174,8 @@ Commit the state file even when publishing fails part-way: it's saved after ever
 | `site` | required | Your site's address. |
 | `account` | required | The publishing account's DID. |
 | `publication.name`, `.description`, `.icon` | name required | The publication record. |
-| `collections` | required | One or more: `files` (a glob) and `path` (a function), plus optional overrides: `id`, `title`, `description`, `textContent`, `tags`, `publishedAt`, `updatedAt`, `cover`, `draft` and `archived` (posts never treated as new, such as ones imported from an old site). Each takes the post (`id`, `file`, `folder`, `data` for the frontmatter, `body`). |
+| `collections` | required | One or more: `files` (a glob) and `path` (a function), plus optional overrides: `id`, `title`, `description`, `share`, `textContent`, `tags`, `publishedAt`, `updatedAt`, `cover`, `draft` and `archived` (posts never treated as new, such as ones imported from an old site). Each takes the post (`id`, `file`, `folder`, `data` for the frontmatter, `body`). |
+| `share` | default `"more"` | How much of each post goes into its record (see "How much of each post is shared"). |
 | `announceWithinDays` | default 14 | How recent a post must be to count as new. |
 | `langs` | default `["en"]` | The announcements' languages. |
 
@@ -168,11 +183,11 @@ Commit the state file even when publishing fails part-way: it's saved after ever
 
 - Node 22.13 or later, Astro 5 or later.
 - Markdown (`.md`, `.mdx`) posts. Collections from other loaders (a CMS, say) aren't supported yet.
-- Records carry plain text for search, not the full formatted post.
+- Records carry plain text for search (see `share`), not the full formatted post.
 
 ## Saying thanks
 
-It's free and open source (MIT). If it's useful, a link to [the post about it on saltedlolly.com](https://saltedlolly.com) helps other developers find it. You can also support the work through [GitHub Sponsors](https://github.com/sponsors/saltedlolly) or [Ko-fi](https://ko-fi.com/saltedlolly).
+It's free and open source (MIT). If it's useful, a link to [the post about it on saltedlolly.com](https://saltedlolly.com/atmosphere-publishing-for-astro/) helps other developers find it. You can also support the work through [GitHub Sponsors](https://github.com/sponsors/saltedlolly) or [Ko-fi](https://ko-fi.com/saltedlolly).
 
 ## License
 

package/bin/cli.mjs

@@ -9,8 +9,8 @@
 // there is read too, if present.
 import { existsSync } from "node:fs";
 import { loadConfig } from "../lib/config.mjs";
-import { describe, plan, publish } from "../lib/publish.mjs";
-import { reader } from "../lib/account.mjs";
+import { describe, linkedFor, plan, publish } from "../lib/publish.mjs";
+import { publicAgent, reader } from "../lib/account.mjs";
 import { saveState } from "../lib/state.mjs";
 import { syncState } from "../lib/sync.mjs";
 
@@ -21,7 +21,8 @@ async function main() {
   if (existsSync(".env")) process.loadEnvFile(".env");
   const config = await loadConfig();
   if (command === "preview") {
-    const lines = describe(await plan(config), config);
+    const result = await plan(config);
+    const lines = describe(result, config, undefined, await linkedFor(result, publicAgent()));
     if (!lines.some((line) => !line.startsWith("note:"))) {
       for (const line of lines) console.log(`  • ${line}`);
       console.log("Everything is already published and up to date.");

package/index.d.ts

@@ -23,7 +23,7 @@ export type CollectionSettings = {
   title?: (post: Entry) => string;
   /** Default: the frontmatter's description, or the first paragraph. */
   description?: (post: Entry) => string;
-  /** Plain text for search. Default: the text above <!--more-->, or the whole post. */
+  /** Plain text for search, replacing `share`'s choice. */
   textContent?: (post: Entry) => string;
   tags?: (post: Entry) => string[];
   /** Default: pubDate, publishDate or date. */
@@ -32,12 +32,16 @@ export type CollectionSettings = {
   updatedAt?: (post: Entry) => string | Date | undefined;
   /** The cover image file, relative to the post's folder. Default: heroImage, cover or image. */
   cover?: (post: Entry) => string | undefined;
+  /** How much text this collection's records share (see AtmospherePublishingConfig.share). A post's own `share:` overrides it. */
+  share?: Share;
   /** Default: the frontmatter's draft. Drafts are never published. */
   draft?: (post: Entry) => boolean;
   /** Posts that are never "new" (imported from an old site, say), so they're only announced when they ask. */
   archived?: (post: Entry) => boolean;
 };
 
+export type Share = "more" | "intro" | "full" | "none";
+
 export type AtmospherePublishingConfig = {
   /** Your site's address, e.g. "https://example.com". */
   site: string;
@@ -50,6 +54,14 @@ export type AtmospherePublishingConfig = {
     icon?: string;
   };
   collections: CollectionSettings[];
+  /**
+   * How much of each post goes into its record's searchable text (always plain text):
+   * "more" (default) everything above <!--more-->, or the whole post when there's no marker;
+   * "intro" everything above <!--more-->, or the first paragraph when there's no marker;
+   * "full" the whole post; "none" nothing (the record keeps its title and description).
+   * A collection's `share`, or a post's own `share:` in its frontmatter, overrides it.
+   */
+  share?: Share;
   /** Posts published within this many days are announced as new. Default 14. */
   announceWithinDays?: number;
   /** The announcements' languages. Default ["en"]. */

package/lib/account.mjs

@@ -33,6 +33,9 @@ export async function signIn(account) {
   return agent;
 }
 
+/** Bluesky's public service, for looking up handles without signing in (the preview's @mentions). */
+export const publicAgent = () => new AtpAgent({ service: "https://public.api.bsky.app" });
+
 /** An agent for reading the account's public records, without signing in. */
 export async function reader(account) {
   return new AtpAgent({ service: await hostOf(account) });

package/lib/config.mjs

@@ -4,6 +4,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { SHARE_OPTIONS } from "./text.mjs";
 
 export const CONFIG_FILE = "atmosphere-publishing.config.mjs";
 export const STATE_FILE = "src/data/atmosphere-publishing.json";
@@ -27,6 +28,7 @@ export async function loadConfig(root = process.cwd()) {
   if (!DID.test(config?.account ?? "")) problems.push("`account` must be the DID of the account that publishes (did:plc:… or did:web:…)");
   if (!config?.publication?.name) problems.push("`publication.name` is required");
   if (!config?.collections?.length) problems.push("`collections` must list at least one collection");
+  if (config?.share !== undefined && !SHARE_OPTIONS.includes(config.share)) problems.push(`\`share\` must be one of ${SHARE_OPTIONS.join(", ")}`);
   for (const [index, collection] of (config?.collections ?? []).entries()) {
     if (!collection.files) problems.push(`collections[${index}].files must be a glob such as "src/content/blog/**/*.md"`);
     if (typeof collection.path !== "function") problems.push(`collections[${index}].path must be a function giving each post's address`);
@@ -39,6 +41,7 @@ export async function loadConfig(root = process.cwd()) {
     publication: { description: "", ...config.publication },
     collections: config.collections,
     announceWithinDays: config.announceWithinDays ?? 14,
+    share: config.share ?? "more",
     langs: config.langs ?? ["en"],
     stateFile: path.join(root, STATE_FILE),
   };

package/lib/entries.mjs

@@ -4,7 +4,7 @@
 import { glob, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { firstParagraph, plainParagraphs, previewMarkdown } from "./text.mjs";
+import { SHARE_OPTIONS, firstParagraph, sharedText } from "./text.mjs";
 
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
@@ -39,6 +39,9 @@ export async function readEntries(config) {
       const publishedAt = dateOf((collection.publishedAt ?? ((e) => e.data.pubDate ?? e.data.publishDate ?? e.data.date))(entry));
       if (!publishedAt || Number.isNaN(publishedAt.valueOf())) throw new Error(`${relative}: no publication date (pubDate, publishDate or date).`);
       const postPath = collection.path({ ...entry, publishedAt });
+      // How much text the record shares: the post's own `share:`, then the collection's, then the site's.
+      const share = entry.data.share ?? collection.share ?? config.share;
+      if (!SHARE_OPTIONS.includes(share)) throw new Error(`${relative}: share must be one of ${SHARE_OPTIONS.join(", ")}.`);
       const cover = (collection.cover ?? ((e) => e.data.heroImage ?? e.data.cover ?? e.data.image))(entry);
       // The field order matters: it is part of each record's fingerprint.
       posts.push({
@@ -47,7 +50,7 @@ export async function readEntries(config) {
         path: postPath,
         title: (collection.title ?? ((e) => e.data.title))(entry),
         description: (collection.description ?? ((e) => e.data.description || firstParagraph(e.body)))(entry),
-        textContent: (collection.textContent ?? ((e) => plainParagraphs(previewMarkdown(e.body)).join("\n\n")))(entry),
+        textContent: (collection.textContent ?? ((e) => sharedText(e.body, share)))(entry),
         tags: (collection.tags ?? ((e) => e.data.tags ?? []))(entry),
         publishedAt,
         updatedAt: dateOf((collection.updatedAt ?? ((e) => e.data.updatedDate ?? e.data.updatedAt))(entry)),

package/lib/publish.mjs

@@ -3,7 +3,8 @@
 // posts (or older posts that ask), which becomes the post's comment thread.
 import { readEntries } from "./entries.mjs";
 import { STANDARD_SITE, isEmpty, readState, saveState } from "./state.mjs";
-import { signIn } from "./account.mjs";
+import { RichText } from "@atproto/api";
+import { publicAgent, signIn } from "./account.mjs";
 import { syncState } from "./sync.mjs";
 import {
   DOCUMENT,
@@ -20,6 +21,33 @@ const rkeyOf = (uri) => uri.split("/").pop();
 /** The post's own `announce: "…"` wording, or none: the link card alone already shows its title and introduction. */
 export const announcementText = (post) => (typeof post.announce === "string" ? post.announce : "");
 
+/**
+ * The announcement's text with its @mentions, #hashtags and links marked, as
+ * the Bluesky app does, so they're links and mentioned accounts are notified.
+ * A mention of a handle that doesn't exist stays plain text.
+ */
+export async function richTextOf(text, agent) {
+  const rich = new RichText({ text });
+  try {
+    await rich.detectFacets(agent);
+  } catch {
+    rich.detectFacetsWithoutResolution();
+  }
+  // A handle that couldn't be found leaves a mention with no account: Bluesky
+  // rejects those, so they stay plain text.
+  rich.facets = (rich.facets ?? []).filter(
+    (facet) => !facet.features.some((feature) => feature.$type === "app.bsky.richtext.facet#mention" && !feature.did),
+  );
+  return rich;
+}
+
+/** What the announcement's text will link, for the preview. */
+export function linkedParts(rich, text) {
+  const bytes = new TextEncoder().encode(text);
+  const decode = (start, end) => new TextDecoder().decode(bytes.slice(start, end));
+  return (rich.facets ?? []).map((facet) => decode(facet.index.byteStart, facet.index.byteEnd));
+}
+
 /** New posts are announced with today's date, so followers see them. */
 export const isNew = (post, config) =>
   !post.archived && (Date.now() - post.publishedAt.valueOf()) / 86_400_000 <= config.announceWithinDays;
@@ -57,8 +85,8 @@ export async function plan(config, state = readState(config.stateFile)) {
   return { posts, state, pubHash, publicationChange, changes, orphans };
 }
 
-/** The plan in plain words, as the preview prints it. */
-export function describe(result, config, handle) {
+/** The plan in plain words, as the preview prints it. `linked` lists, by post id, what each announcement will link. */
+export function describe(result, config, handle, linked = {}) {
   const lines = [];
   if (result.publicationChange) lines.push(`${result.publicationChange} the publication record (${config.site})`);
   for (const { post, action, announce } of result.changes) {
@@ -74,6 +102,7 @@ export function describe(result, config, handle) {
         (text ? text.split("\n").map((line) => `    │ ${line}`).join("\n") : "    │ (no announce: wording, so no text: just the link card)") +
         `\n    │ [link card: ${post.title} — ${post.url}]\n` +
         "    └────────────────────────────────────────\n" +
+        (text ? `    Linked: ${linked[post.id]?.length ? linked[post.id].join(", ") : "nothing (no @mentions, #hashtags or links found)"}\n` : "") +
         `    To change the wording, add  announce: "…"  to ${post.source};\n` +
         "    announce: false  skips the announcement.",
     );
@@ -82,6 +111,16 @@ export function describe(result, config, handle) {
   return lines;
 }
 
+/** What each planned announcement will link, by post id (mentions are checked with `agent`). */
+export async function linkedFor(result, agent) {
+  const linked = {};
+  for (const { post, announce } of result.changes) {
+    const text = announcementText(post);
+    if (announce && text) linked[post.id] = linkedParts(await richTextOf(text, agent), text);
+  }
+  return linked;
+}
+
 /** Publishes everything the plan lists. Saves the state file after each record, so an interruption loses nothing. */
 export async function publish(config, log = console.log) {
   const agent = await signIn(config.account);
@@ -93,7 +132,7 @@ export async function publish(config, log = console.log) {
     await saveState(config.stateFile, state);
   }
   const result = await plan(config, state);
-  const lines = describe(result, config, agent.session.handle);
+  const lines = describe(result, config, agent.session.handle, await linkedFor(result, agent));
   if (!lines.some((line) => !line.startsWith("note:"))) {
     for (const line of lines) log(`  • ${line}`);
     log("Everything is already published and up to date.");
@@ -124,8 +163,10 @@ export async function publish(config, log = console.log) {
   for (const { post, announce } of result.changes) {
     const cover = post.coverFile ? await upload(await coverImage(post.coverFile), "image/jpeg") : undefined;
     if (announce) {
+      const rich = await richTextOf(announcementText(post), agent);
       const created = await agent.post({
-        text: announcementText(post),
+        text: rich.text,
+        ...(rich.facets?.length && { facets: rich.facets }),
         langs: config.langs,
         createdAt: announcementDate(post, config).toISOString(),
         embed: { $type: "app.bsky.embed.external", external: { uri: post.url, title: post.title, description: post.description, thumb: cover } },

package/lib/publishers/standard-site.mjs

@@ -58,7 +58,7 @@ export function documentRecord(post, publicationUri, cover, announcement) {
     path: post.path,
     title: post.title,
     description: post.description,
-    textContent: post.textContent,
+    ...(post.textContent && { textContent: post.textContent }),
     tags: post.tags,
     publishedAt: post.publishedAt.toISOString(),
     ...(post.updatedAt && { updatedAt: post.updatedAt.toISOString() }),

package/lib/text.mjs

@@ -30,6 +30,28 @@ export function previewMarkdown(markdown) {
   return MORE_MARKER.test(markdown) ? markdown.split(MORE_MARKER)[0] : markdown;
 }
 
+/**
+ * The searchable text for a post's record, by the `share` setting:
+ *   "more"   everything above <!--more-->, or the whole post when there's no marker (default)
+ *   "intro"  everything above <!--more-->, or the first paragraph when there's no marker
+ *   "full"   the whole post
+ *   "none"   nothing (the record still has the title and description)
+ * Always plain text: no formatting, images or link addresses.
+ */
+export function sharedText(markdown, share = "more") {
+  if (share === "none") return "";
+  if (share === "full") return plainParagraphs(markdown.replace(MORE_MARKER, "")).join("\n\n");
+  if (share === "intro" && !MORE_MARKER.test(markdown)) {
+    const [first = ""] = plainParagraphs(
+      markdown.split(/\n{2,}/).filter((paragraph) => !paragraph.trim().startsWith("#")).join("\n\n"),
+    );
+    return first;
+  }
+  return plainParagraphs(previewMarkdown(markdown)).join("\n\n");
+}
+
+export const SHARE_OPTIONS = ["more", "intro", "full", "none"];
+
 /** The first paragraph with text (headings skipped), cut to 160 characters. */
 export function firstParagraph(markdown) {
   const text = plainParagraphs(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-atmosphere-publishing",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Publish your Astro site to the Atmosphere with Standard.site: records for every post, Bluesky announcements, and the tags that connect each page to them. Pairs with Atmosphere Comments for Astro.",
   "type": "module",
   "license": "MIT",