sequoia
A CLI for publishing standard.site documents to ATProto sequoia.pub
standard site lexicon cli publishing
Star 112
Fork 8
Watch

Support atUri in Zola [extra] frontmatter without breaking update detection #61

Open kool.gv.uy
Open opened by kool.gv.uy

Sequoia's documentation on inject says:

If you prefer manual control, you can skip this step and configure your SSG to read the atUri field from frontmatter instead.

This works for SSGs where atUri can be exposed as a top-level frontmatter field, but it does not work cleanly with Zola.

In Zola, custom frontmatter intended for templates is conventionally placed under [extra], e.g.:

+++
title = "My post"
date = 2025-01-05

[extra]
atUri = "at://did:plc:.../site.standard.document/3mqq6f23k322y"
+++

Zola can then access it as page.extra.atUri.

However, Sequoia's publish/update detection checks post.frontmatter.atUri. The nested [extra].atUri is therefore not recognized as the document's AT URI. When the post's content changes, Sequoia detects the content hash change but sees no atUri and classifies the post as a new document rather than an update.

This results in a new rkey being created for an existing article, producing duplicate site.standard.document records.

For example:

Existing:
at://did:plc:.../site.standard.document/3mqq6f23k322y

After editing:
at://did:plc:.../site.standard.document/3mtrzfxfjqs2v

The update path itself works correctly when atUri is available to Sequoia: updateDocument() correctly uses the existing collection/rkey and putRecord() preserves the rkey.

Expected behavior #

If an SSG stores atUri in [extra], Sequoia should either:

  • support a configurable/mapped location for atUri, or
  • recognize rawFrontmatter.extra.atUri when determining whether a changed post should be updated.

In particular, the documentation's recommendation to have an SSG read atUri from frontmatter should work with Zola without causing existing documents to be silently duplicated.

stevedylan.dev

Thanks for catching this! Will see if I can make a fix this weekend.

heaths.dev

Just as an FYI, I fixed a bug a while ago that was the opposite: we added it to the end, but it needed to be in the root of the TOML. This is effectively asking for exactly the opposite. Seems a mapping of TOML structure is needed in configuration or we'll just end up reverting the previous fix.

stevedylan.dev

I wonder if we could add something like this?

Make the location configurable, defaulting to root. Add atUri?: string to FrontmatterMapping (types.ts:1-10) accepting a dotted path, e.g. "extra.atUri", and honor it in the two places that touch the field — the read at markdown.ts:117 and the write at markdown.ts:385. The root default from 252bbc6 (issue #46) is preserved for everyone else, and the Zola user opts in. updateFrontmatterWithAtUri would need the mapping threaded through from publish.ts:389 and sync.ts:205, plus a sequoia.schema.json entry.

heaths.dev

Or do we tie this in with trying to understand different SSG behaviors, such that we know to add atUri for Zola in addition to how to (try our best) map file paths to stubs? Maybe a bit too much to bite off at once?

arsdehnel.com

At some point does it make sense to maybe draw a line between what the cli needs and what the SSG frameworks expect such that there could be sort of "plugins" for each framework? Like instead of configuring property-by-property there is a explicit way to say "I'm using Zola".

That could also open up a space for writing a user-specific implementation for sites that are more one-off or have extended the frameworks in ways you wouldn't want to try to handle via config.

stevedylan.dev

I really like the idea of plugins for Sequoia 👀

arsdehnel.com
Sign up or Sign in to add to the discussion.