regen-network / regen-data-standards

3 stars 2 forks source link

Use content collections for schema pages #10

Open paul121 opened 1 month ago

paul121 commented 1 month ago

Just discussed with @paul121. Let's merge this but in follow ups work on the Astro routing of this and decide whether we want to continue with Astro.glob or use content collections for the schema pages, so that the URL behavior is better.

Originally posted by @aaronc in https://github.com/regen-network/regen-data-standards/pull/5#pullrequestreview-2322601550

paul121 commented 1 month ago

For integration with Astro, what do we think of this approach? I considered trying to use astro's 'content collections' concept that is already implemented for taxonomy terms. In theory we could dump generated markdown into src/content/schemas but one downside is that the generated markdown doesn't include any frontmatter that these content collections expect you to have. It seems that we can provide jinja2 templates for the gen-doc command where we could potentially include frontmatter... but still, it's more work, and I think we want the schema markdown to follow a different editing flow than taxonomy terms, so it might be better to not use 'content collections'.

In the description of #5 I mentioned that I originally considered using content collections for these schemas. But I still don't see the real advantage in using them over Astro.glob.

I don't think this would fix the behavior I discovered where Cloudflare changes routes to have a trailing slash and breaks the auto-generated relative links from LinkMl, so we would still need the build.format = file config. Changing this config removed the trailing slash from both taxonomy and schema pages. https://github.com/regen-network/regen-data-standards/pull/5#issuecomment-2360035208

paul121 commented 1 month ago

Also worth noting that the upcoming Astro v5 is deprecating Astro.glob and changing content collections to use a new "Content Layer API" which has better support for loading "content collections" from more sources. If we refactor I think we should consider using these new APIs. https://5-0-0-beta.docs.astro.build/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api