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" fetching helper query utilities
4. Put content as data and active frontmatter behind the same config key (activeContent)
5. Refactor and clean up graph properties, with better defaults (and updated website frontmatter accordingly)
6. Apply appropriate Netlify redirects in netlify.toml
7. Refreshed content as data and adjacent docs, moved more of the GraphQL docs to the plugin's README
8. Handles Graph schema consistency enhancements #552

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 + docs
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? - seems like we're fine without, maybe landed in another commit?
16. how come Response merging isn't working? - seems to work fine 🤷‍♂️
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
21. move active frontmatter (back) to standard HTML plugin? - will leave it where it is
22. handle hidden files / undefined error - https://github.com/ProjectEvergreen/greenwood/pull/1266/files#r1792691572
23. (nice to have) GraphQL plugin enhancements - this might require work (including for contentAsData to link queries to specific page)
    • 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

Thoughts / Observations

1. alternate namespace to globalThis ? - Content as Data v2 #1286

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

2. Is a content server OK for now? - Content as Data v2 #1286
   • 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>
3. leave no trace, at least make it configuration option to avoid unnecessary work? 🏕️ - Yes
4. 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. - Content as Data v2 #1286
5. should we consolidate activeFrontmatter + contentAsData options? Maybe boil it down to activeContent? - we shall!
6. Messy / noisy output for “rich” activeFrontmatter :/ - Content as Data v2 #1286
   • can we at least prune some stuff?
   • at least recommend prerender + static opt (e.g. in JS) 👇
7. Rendering Strategies (prerender vs SSR vs CSR) #951 - will handle this as part of Docs Page www.greenwoodjs.dev#31
   • 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> 🤔 🤔
8. as far as renaming things, I suppose we could potentially align with the xxxHref naming convention to - Content as Data v2 #1286
   • context - e.g. outputDir, scratchDir, userWorkspace and append Href
   • bundled resources - e.g. optimizedFileName, etc