stevedylan.dev / sequoia
A CLI for publishing standard.site documents to ATProto sequoia.pub
standard site lexicon cli publishing
fork atom

Sub-directories, hidden 'index` docs, and Hugo shortcodes #3

closed opened by byjp.me edited

I'm so happy Sequoia was published today; I was just thinking about integrating standard.site to my blog, this is perfect timing! Thanks!

I've come across a few issues, and I wanted to check whether they're "real" or my poor configuration, and offer help to fix if needed.

Here's a post of mine:

Issues#

  1. Subdirectories

    This markdown file is stored at 40th-puzzle-box/what-a-gift/index.md (inside the content/posts dir I've configured as contentDir with Sequoia) but the AT record has path: "/posts/index" — Sequoia has missed two layers of subdirectory there. Can I enable subdirectory support?

  2. Hidden 'index' docs

    Hugo allows us to use index.md files within a folder to allow keeping assets in the same dir (like I have here) — but Sequoia isn't aware of this, so is incorrectly guessing the canonicalUrl as https://www.byjp.me/posts/index, instead of https://www.byjp.me/posts/40th-puzzle-box/what-a-gift/. How do I configure the removal of /index URL suffixes?

  3. Using post summary as textContent

    My posts make heavy use of Hugo shortcodes, (they {{< look like this >}}), there's no reasonable way Sequoia could parse them, but I had assumed that it would pull the summary instead (as I thought I'd configured that). Can I configure Sequoia to use my summary as textContent, instead of the markdown body?

Thanks again, please let me know where I can help!

stevedylan.dev edited

Hey JP! Thank you so much for trying out Sequoia and for opening this issue; amazing details!! 🔥 Definitely not an issue on your part with the config; these are gaps in Sequoia I missed since I was testing with simpler blog setups. However all of these seem fixable!

  1. I definitely need to find a better solution for this as right now my construction is a bit simple. There's probably a better way to grab the slug/path of a post instead of what I'm doing now, which is just combining the path prefix from the config with the post path.

  2. I think this is tied to number 1 due to how I'm currently constructing the pieces:

export async function createDocument(
  agent: AtpAgent,
  post: BlogPost,
  config: PublisherConfig,
  coverImage?: BlobObject
): Promise<string> {
  const pathPrefix = config.pathPrefix || "/posts";
  const postPath = `${pathPrefix}/${post.slug}`;
  const textContent = stripMarkdownForText(post.content);
  const publishDate = new Date(post.frontmatter.publishDate);

  const record: Record<string, unknown> = {
    $type: "site.standard.document",
    title: post.frontmatter.title,
    site: config.publicationUri,
    path: postPath,
    textContent: textContent.slice(0, 10000),
    publishedAt: publishDate.toISOString(),
    canonicalUrl: `${config.siteUrl}${postPath}`,
  };

I believe once we figure out what happens with subdirectories in issue 1, we can figure out what to do with issue 2. Likely will be a simple trim if it exists but curious to see what happens!

  1. I think we can make this a config option! Right now your config is using summary for the post description, but what we really need is another field for textContent that you can configure to be something other than the contents of the markdown, like the summary frontmatter field. No problem at all!

I'll try some experimenting with all of these over the weekend, if you happen to have time to test yourself please let me know what you find along the way. Once again thanks for your support! 🙏

byjp.me (author)

This is super — thank you! I’ll do some exploring of the codebase when I get a moment, this is exciting stuff!

One thing that may help (or complicate 😅) things, Hugo lets you customise the path of a post with frontmatter config (either the slug or the full URL).

Perhaps we’d need:

  • the default case of using the full path to the markdown file as the path + slug
  • an optional “remove these file names from the end” (for removing “index”)
  • an optional config to use the slug from frontmatter
  • an optional config to use the url from frontmatter

Let me know if anything here doesn’t make sense, or otherwise seems incompatible with other work you’ve done!

Oh, and on our third point, the PDS entry doesn’t show a description field, despite the Sequoia config mapping summary to description; is something broken or poorly configured there too?

Thanks again!

stevedylan.dev

Oooh that makes a lot of sense too; I think most SSGs let you configure slugs, so I 100% agree we need to support this. Going to play around and see what some config options look like and how we can get it fixed. Will let you know soon! :)

That is odd; in theory it should be reading that summary and using it for the description. Will look into that too because it might be a bug I missed!

stevedylan.dev edited

I think I've got a pretty good solution setup in PR #3 if you want to take a look!

I've also deployed a beta version of the CLI with these changes if you'd like to test it:

npm i -g sequoia-cli@0.2.1-beta.0
byjp.me (author)

Thank you @stevedylan.dev! These all work excellently with sub-folders as needed 😊

You're meeting all my needs here, but (if I'm understanding corrrectly) then I think the way you've modelled either the filename as the post path or the url as slugField or path as slugField means that you aren't supporting Hugo's "fallback" approach to these, which is:

  • If url is set in frontmatter, then use that
  • If not, then if path is set in frontmatter, use that
  • If not, then use the file path as the URL

All of these could be present in the same site (though I don't use url or path in mine, but I'd be happy to add if you'd like to test!). Am I understanding correctly that sequoia doesn't currently support that?

stevedylan.dev

@byjp.me Hmm that is a good point. Right now it is using the slugSource making it a either/or choice and there is no fallback, but I think there should be some kind of logic to do that. Perhaps a config like this

 {
    "siteUrl": "https://example.com",
    "contentDir": "content/posts",
    "pathPrefix": "/blog",
    "publicationUri": "at://did:plc:.../site.standard.publication/...",
   	"frontmatter": {
		"slugField": "path"
	},
  }

Means Sequoia would take the following logic:

  • If path is in the frontmatter then use that
  • If not, use the file path as the URL

There would be no need to set a slugSource because the fact that the slugField in the frontmatter exists in the config means Sequoia should look for it first. It would be a simplified version of Hugo's approach as I am trying to keep Sequoia SSG agnostic and the url property in their frontmatter can be quite complex and not something I'm ready to support just yet.

This will be a small tweak to the existing PR so I'll go ahead and do that but would love your feedback if you have more thoughts!

stevedylan.dev

Did some more testing and everything looks good! Had weird issues with Tangled when I tried to rebase so ended up having to merge locally and then push it up. Will mark this as closed but if you have any other issues that come up please let me know so I can take care of them in another PR!

sign up or login to add to the discussion
Labels

None yet.

assignee

None yet.

Participants 2
AT URI
at://did:plc:ephkzpinhaqcabtkugtbzrwu/sh.tangled.repo.issue/3mdojjlkjpg22