noblog 0.2.3 → 0.3.0-beta.2

package/skills/noblog-config/assets/nobloger.yaml

@@ -0,0 +1,30 @@
+# Matches Nobloger's MarkdownPostLayout and blog listing contract.
+version: 1
+notion:
+  properties:
+    title: Name
+    description: description
+    tags: tags
+    publishedAt: date
+output:
+  savePath: src/pages/posts/
+  storePath: .noblog/pages/
+  layoutPath: ../../layouts/MarkdownPostLayout.astro
+  recursive: true
+frontmatter:
+  fields:
+    layout:
+      from: layoutPath
+    title:
+      from: title
+      required: true
+    pubDate:
+      from: publishedAt
+      as: string
+      required: true
+    tags:
+      from: tags
+      default: []
+    description:
+      from: description
+      omitEmpty: true

package/skills/noblog-config/assets/thought-lite.yaml

@@ -0,0 +1,47 @@
+# Matches ThoughtLite's `note` collection; re-check the installed version.
+version: 1
+notion:
+  properties:
+    title: Name
+    publishedAt: date
+    description: description
+    tags: tags
+    series: Series
+    sensitive: Sensitive
+    top: Top
+    archived: archived
+output:
+  # The collection reads canonical files directly from this store.
+  storePath: src/content/note/
+  # Required database-post links stay outside the collection glob.
+  savePath: .noblog/note-links/
+  recursive: true
+frontmatter:
+  fields:
+    title:
+      from: title
+      required: true
+    timestamp:
+      from: publishedAt
+      as: date
+      required: true
+    series:
+      from: series
+      omitEmpty: true
+    tags:
+      from: tags
+      omitEmpty: true
+    description:
+      from: description
+      omitEmpty: true
+    sensitive:
+      from: sensitive
+      default: false
+    toc:
+      value: true
+    top:
+      from: top
+      default: 0
+    draft:
+      from: archived
+      default: false

package/skills/noblog-config/references/config-schema.md

@@ -0,0 +1,110 @@
+# Noblog YAML configuration reference
+
+## Precedence and credentials
+
+Generation resolves settings in this order:
+
+```text
+built-in defaults < YAML configuration < explicit CLI flags and SAVE_PATH
+```
+
+`--config PATH` selects the YAML file. `config check --config PATH` reads and validates only that file; it does not require Notion credentials or access the network.
+
+Credentials belong only in `NOTION_API_SECRET` and `NOBLOG_DATABASE_ID`, supplied through the environment or `.env`. Unknown YAML keys are rejected, and there are no credential fields.
+
+## Output
+
+```yaml
+version: 1
+output:
+  savePath: src/pages/posts/
+  storePath: .noblog/pages/
+  layoutPath: ../../layouts/MarkdownPostLayout.astro
+  recursive: true
+  childPageMarker: "⸎"
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `savePath` | `./src/pages/posts/` | Receives relative symlinks for database posts. The positional `SAVE_PATH` and YAML key configure it. |
+| `storePath` | `.noblog/pages/` | Receives every real Markdown file in a flat page-ID layout. Override with `--store`. |
+| `layoutPath` | `../../layouts/MarkdownPostLayout.astro` | Interpreted relative to `savePath`; Noblog writes the equivalent store-relative import. Override with `--layout`. |
+| `recursive` | `true` | Collect and render child pages recursively. |
+| `childPageMarker` | `⸎` (U+2E0E EDITORIAL CORONIS) | Non-empty prefix added to child-page links. Set it to the marker the theme recognizes. |
+
+All paths are resolved from the generation working directory. Child pages have no public symlinks. Child-page links are written as `<marker> [title](./<page-id>.md)`. The theme must load and route the canonical store itself when child pages should have routes.
+
+## Notion property mapping
+
+```yaml
+notion:
+  properties:
+    title: Name
+    publishedAt: Published
+    series: Series
+```
+
+Keys are logical sources available to frontmatter fields; values are exact, case-sensitive Notion property names. Custom keys such as `series` must be declared here before `from: series` is valid.
+
+Without explicit mappings, conventional sources use `description`, `tags`, `date`, and `archived`. The title source uses the last Notion title property. Explicit entries override those conventions individually.
+
+Supplying `notion.properties` without `frontmatter.fields` enables the declarative equivalent of the legacy fields: `layout`, `title`, `description`, `tags`, `pubDate`, and `archived`. Explicit `frontmatter.fields` instead emits exactly the declared fields.
+
+## Frontmatter fields
+
+```yaml
+frontmatter:
+  fields:
+    title:
+      from: title
+      required: true
+    timestamp:
+      from: publishedAt
+      as: date
+      required: true
+    series:
+      from: series
+      omitEmpty: true
+    draft:
+      from: archived
+      default: false
+    toc:
+      value: true
+    provider:
+      value:
+        name: Notion
+        options: [canonical, symlinks]
+```
+
+Each field must have exactly one source:
+
+- `from`: a built-in source or a key declared under `notion.properties`.
+- `value`: a static native YAML value.
+
+Built-in sources are `title`, `description`, `tags`, `publishedAt`, `archived`, `layoutPath`, `pageId`, and `isDatabasePage`.
+
+Modifiers:
+
+- `default`: used when the resolved value is empty.
+- `required`: fail generation when the value remains empty after applying the default. Errors include the field and page ID.
+- `omitEmpty`: omit an empty value after default/required processing.
+- `as: string`: convert a string, number, or boolean to a string. Date-like strings are quoted in output so downstream YAML parsers do not coerce them.
+- `as: date`: convert a valid date string or finite number to a YAML timestamp.
+
+Empty means `undefined`, `null`, `""`, or `[]`. `false` and `0` are not empty. Resolution order is source/static value, default, required check, omission, then conversion.
+
+Static values may be strings, finite numbers, booleans, null, arrays, or nested objects. Notion sources normalize to strings, numbers, booleans, string arrays, or undefined; see the property-type reference.
+
+## Schema and validation
+
+The published JSON Schema is `schema/config.json`, also exported as `noblog/config.schema.json`. It is generated from the runtime Zod schema. For a project-local installation, an editor modeline can use:
+
+```yaml
+# yaml-language-server: $schema=./node_modules/noblog/schema/config.json
+```
+
+The JSON Schema describes structure and types. Runtime validation additionally rejects unknown custom `from` sources that are not built in or declared under `notion.properties`; always finish with `noblog config check`.
+
+## Programmatic escape hatch
+
+Applications can bypass declarative fields by passing a `FrontmatterAdapter` in `RenderOptions`. It receives `{ page, metadata, layoutPath, isDatabasePage }` and returns a plain object. Root `undefined` values are omitted; arrays, null, dates, and class instances are not valid roots. `createFrontmatterAdapter(fields)` exposes the same declarative behavior to library consumers.

package/skills/noblog-config/references/notion-property-types.md

@@ -0,0 +1,42 @@
+# Notion property normalization
+
+Noblog reads the actual Notion property type. It does not use a property named `title` or `date` as a substitute for checking its type.
+
+| Notion type | Normalized value |
+| --- | --- |
+| `title`, `rich_text` | Concatenated plain-text string |
+| `multi_select` | Array of option names |
+| `select`, `status` | Selected name string, or undefined |
+| `checkbox` | Native boolean |
+| `number` | Native number, or undefined for null |
+| `date` | Start date string, or undefined |
+| `url`, `email`, `phone_number` | String, or undefined for null |
+| `people` | Array of names, falling back to IDs for partial users |
+| `relation` | Array of related page IDs |
+| `files` | Array of uploaded-file or external URLs |
+| `formula` | Normalized formula string, number, boolean, or date start |
+| `created_time`, `last_edited_time` | Notion timestamp string |
+| `created_by`, `last_edited_by` | Name, falling back to ID |
+| `unique_id` | `PREFIX-number`, or the number as a string without a prefix |
+| Unsupported types, missing properties | Undefined |
+
+The `date` source remains a string until a field requests `as: date`. This distinction matters: `as: string` preserves a quoted date-like string, while `as: date` emits a native YAML timestamp for themes whose schemas call `z.date()` or `z.coerce.date()`.
+
+People, relations, and files are arrays even when Notion contains one item. Apply `omitEmpty` if an empty array should not be emitted. A missing property and an unsupported type both become undefined, allowing `default`, `required`, and `omitEmpty` to handle them consistently.
+
+For formula values, Noblog follows the formula's own result type. Verify formulas returning null with the theme's required/optional rules.
+
+Custom source names are logical keys, not necessarily Notion names:
+
+```yaml
+notion:
+  properties:
+    timestampSource: Published At
+frontmatter:
+  fields:
+    timestamp:
+      from: timestampSource
+      as: date
+```
+
+Here `timestampSource` is declared locally and `Published At` must exactly match Notion.

package/skills/noblog-config/references/theme-examples.md

@@ -0,0 +1,41 @@
+# Theme examples
+
+These examples are snapshots, not substitutes for inspecting the installed theme. The assets contain complete YAML starting points.
+
+Child-page links are prefixed by `output.childPageMarker`, which defaults to `⸎` (U+2E0E EDITORIAL CORONIS). Set it to the marker the theme recognizes.
+
+## Nobloger
+
+Evidence inspected: `src/layouts/MarkdownPostLayout.astro` and `src/pages/blog/index.astro` in [humbornjo/nobloger](https://github.com/humbornjo/nobloger).
+
+Nobloger uses file-based Markdown routes and `Astro.glob("@/pages/posts/*.md")`. Its layout/list contract uses required `title` and string `pubDate`, plus `tags` and optional `description`. Therefore [`assets/nobloger.yaml`](../assets/nobloger.yaml):
+
+- keeps database-post symlinks in `src/pages/posts/` for existing routes;
+- stores all real files in `.noblog/pages/`;
+- emits `layout` and a quoted string `pubDate`;
+- omits empty descriptions and does not invent fields from other themes.
+
+The existing glob does not list child pages in the hidden store. A theme route must explicitly load that store to expose children. Noblog does not recreate the removed `nob_children` routes.
+
+## ThoughtLite
+
+Evidence inspected: `src/content.config.ts` in [tuyuritio/astro-theme-thought-lite](https://github.com/tuyuritio/astro-theme-thought-lite). Its `note` collection loads `./src/content/note/**/*.md` and validates `title`, native date `timestamp`, optional `series`, `tags`, `description`, and native `sensitive`, `toc`, `top`, and `draft` controls.
+
+[`assets/thought-lite.yaml`](../assets/thought-lite.yaml):
+
+- puts the canonical store directly at `src/content/note/`, where the collection can load root and child pages;
+- keeps required database-post symlinks in `.noblog/note-links/`, separate from collection input;
+- uses `as: date` for `timestamp` and native booleans/numbers elsewhere;
+- maps `archived` to `draft` as an explicit policy choice, not a universal Notion convention;
+- uses static `toc: true` to demonstrate a theme-level constant;
+- emits no Markdown `layout`, because this collection schema does not declare one.
+
+Before using it, confirm that the installed version has the same collection glob and fields, and decide whether archived Notion pages should really become drafts. Also confirm `Sensitive`, `Series`, and `Top` exist with those exact names or change the mappings.
+
+## Adapting another theme
+
+1. Copy no asset until its schema and routing evidence match.
+2. For file-based routes, keep public views in the routed directory and arrange separate store loading for children.
+3. For a content collection, point `storePath` at the collection input only when all generated pages should belong to that collection. Keep `savePath` distinct; Noblog cannot create a symlink onto its own canonical file.
+4. Match native schema types. Use `as: date` for date schemas, and avoid stringifying booleans or numbers unless consumers explicitly require strings.
+5. Validate the final file with `noblog config check --config PATH` and report any remaining route work.

package/dist/cmds/generate.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=generate.d.ts.map

package/dist/cmds/generate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cmds/generate.ts"],"names":[],"mappings":""}