rfc/issue 1167 content as data

[thescientist13]

Related Issue

resolves #1167

For a demo of all these features see ProjectEvergreen/www.greenwoodjs.dev#49

Summary of Changes

1. Introduced Collections as the successor to Menus with test cases
2. Add support for "rich" frontmatter with test cases
3. Introduce a first party "content" server with helper query utilities
4. Refactor and clean up graph properties, with better defaults (and updated website frontmatter accordingly)
5. Apply appropriate Netlify redirects in netlify.toml
6. Refreshed content as data and adjacent docs, moved more of the GraphQL docs to the plugin's README

TODOs

1. Rename interpolateFrontmatter -> activeFrontmatter
2. Frontmatter / graph node properties refactoring (and update website as needed)
   • rename linkheadings -> toc
   • What is the meaningful difference between id and label? path and filename? anything else worth cleaning up? - better generated id, and gave better definitions to everything else
   • Rename index -> order
   • rename menu -> collection
   • default title and label should be the same and actually meaningful)
   • Change path -> url (instance of URL or at least the href property for serializing)
   • Something more predictable for outputPath - renamed to outputHref
     • https://github.com/ProjectEvergreen/greenwood/pull/1224/files#diff-7bec4c1c598f208ba9ec341822f12eace13bede43b5b4d07a9502faf68b3b95dR194
     • bug/issue 1223 support nested pages and API for and adapters #1237
   • it (id) doesn't "scale", e.g. for nested pages - see nested SSR pages (and API routes) are throwing a module not found error (needs additional patch for adapters) #1223
3. GraphQL refactoring
   • Delete config schema for GraphQL
   • align with CLI collection utils (ideally)
4. Make more / less content as data available through active frontmatter + test cases

   <!-- so would be nice if we could use other content as data, e.g. -->
   <app-toc route="${globalThis.page.route}"></app-toc>
   
   <!-- for now, just using userland frontmatter -->
   <app-toc route="${globalThis.page.route}"></app-toc>

5. downstream observations - content/issue 33 guides pages www.greenwoodjs.dev#94
   • title not populating as active frontmatter (is this because we set it to null?)
   • why do run an unshift on content as data in the graph?
6. realized in feature/issue 34 blog landing page and all posts www.greenwoodjs.dev#84 that we were never checking for activeFrontmatter when rendering page layout <title>
7. prune collections serializing to only the bare essentials for CSR (data, route, ???)
8. use content server port as dev server += 1
9. how to sync queries.js (rename to client) host and port with greenwood config / content server
10. hashing / hydration techniques from GraphQL world, e.g. APOLLO DATA
    • fix apollo data bug - data client is not rehydrating from existing WINDOW.APOLLO_STATE on initial load #349
    • reduce duplicate fetches for cache.json by storing in client.js memory #347
11. looks like import map merging was broken when no import map exists? - feature/issue 34 blog landing page and all posts www.greenwoodjs.dev#84
    • also make sure only one import map exists
    • needs to account for import map configuration now
12. collection APIs develop specs?
13. Documentation
    • rename menus -> collections
    • rename interpolateFrontmatter -> activeFrontmatter
    • graph property changes
    • ${graph.page.data.foo}
    • data/client.js
    • update GraphQL plugin README
    • external sources plugin
    • adapters
14. we already get frontmatter contents in the graph phase, but we re-get it in html resource plugin
15. need relaxed node modules plugin intercept patch?
16. how come Response merging isn't working?
17. make sure client.js and GraphQL resolvers are handling basePath
18. build graphQL resolvers off of greenwood internal functions / content API endpoint - I think would rather wait until support hot reloading content as data changes during development #1278
19. content as data work should probably happen in the plugin (instead of in HTML plugin)
20. clean up TODOs / console logging

Thoughts / Observations

1. alternate namespace to globalThis ?

   <title>${globalThis.page.title}</title>

2. Is a content server OK for now?
   • Could we just intercept API requests instead using a resource plugin instead?
   • should we inline for production builds instead of using fetch requests, e.g. <script type="application/json" GWD-DATA ...></script>
   • leave no trace? 🏕️
3. I wonder if there is a case to rename graph to pages instead? A graph implies nodes, some sort of linking structure, etc which it is definitely not in its current state.
4. Messy / noisy output for “rich” activeFrontmatter :/
   • can we at least prune some stuff?
   • at least recommend prerender + static opt (e.g. in JS) 👇
5. Related to prerendering and Rendering Strategies (prerender vs SSR vs CSR) #951
   • prerender caveat - only your components run once, not your generic inline <script> tags!
   • When to use active frontmatter vs CSR + prerendering vs hydration?
   • with active frontmatter, it's there in the HTML. With CSR prerender, no remnants left behind, a la carte via <script type="application/json">
   • This all feels somewhat "RSC-y" (e.g. fetch data close to your components). I think if we can come up with some sort of hydration / islands story here, this could become a really nice pattern, at least for static sites (what happens when you're graph "gets huge" though? Just read from the DOM to hydrate?
   • to the above point, instead of data-gwd-opt="static", should we create something like use static? 🤔
   • or could WCC "unwrap" a light DOM component? (e.g. <my-heading><h1>Hello World!</h1></my-heading> -> <h1>Hello World!</h1> 🤔 🤔
6. as far as renaming things, I suppose we could potentially align with the xxxHref naming convention to
   • context - e.g. outputDir, scratchDir, userWorkspace and append Href
   • bundled resources - e.g. optimizedFileName, etc