From f83ba840afa738e64ae76942ebaa7c321ecfb93e Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 11 Nov 2024 17:29:10 -0500 Subject: [PATCH] docs/post launch docs feedback and clarifications (#129) --- package-lock.json | 28 +++++++++---------- package.json | 8 +++--- .../content-as-data/active-frontmatter.md | 2 +- src/pages/docs/content-as-data/index.md | 7 ++++- src/pages/docs/introduction/setup.md | 5 ++++ src/pages/docs/pages/server-rendering.md | 2 +- src/pages/docs/plugins/index.md | 11 ++++++++ src/pages/docs/reference/configuration.md | 2 +- src/pages/docs/resources/scripts.md | 18 +++++++++++- src/pages/guides/hosting/aws.md | 2 +- 10 files changed, 61 insertions(+), 24 deletions(-) diff --git a/package-lock.json b/package-lock.json index ff922c99..597c7c24 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,9 +22,9 @@ "@eslint/json": "^0.5.0", "@eslint/markdown": "^6.2.0", "@esm-bundle/chai": "^4.3.4-fix.0", - "@greenwood/cli": "^0.30.0", - "@greenwood/plugin-css-modules": "^0.30.0", - "@greenwood/plugin-import-raw": "^0.30.0", + "@greenwood/cli": "^0.30.1", + "@greenwood/plugin-css-modules": "^0.30.1", + "@greenwood/plugin-import-raw": "^0.30.1", "@ls-lint/ls-lint": "^1.10.0", "@mapbox/rehype-prism": "^0.9.0", "@storybook/addon-essentials": "^8.0.6", @@ -2308,9 +2308,9 @@ "license": "MIT" }, "node_modules/@greenwood/cli": { - "version": "0.30.0", - "resolved": "https://registry.npmjs.org/@greenwood/cli/-/cli-0.30.0.tgz", - "integrity": "sha512-cCHjf5YRTMUbkiRLpetmTp1EnZhrc2z7bDZoVQMit1xoKgnaAY+LGkxonWKCI0dq1jie9cd6ZVmmoVHUaTpHEQ==", + "version": "0.30.1", + "resolved": "https://registry.npmjs.org/@greenwood/cli/-/cli-0.30.1.tgz", + "integrity": "sha512-GW58CowMPn7i8BlM5/DenuViVbTMjIFjIhQhUaqpljlL5koR2gvGwyMteBdL2GuMiaNDwDp63gx0GK5mu1Cbig==", "dev": true, "dependencies": { "@rollup/plugin-commonjs": "^25.0.0", @@ -2374,9 +2374,9 @@ } }, "node_modules/@greenwood/plugin-css-modules": { - "version": "0.30.0", - "resolved": "https://registry.npmjs.org/@greenwood/plugin-css-modules/-/plugin-css-modules-0.30.0.tgz", - "integrity": "sha512-2X32ERVPy00wi9WB/wo220AaFkxjfrQ6SjgZixeIQ2MxV7XMyrJAB8sSboXDkIxOVQgAJ1Y4yD/ogJZLfQ8nkA==", + "version": "0.30.1", + "resolved": "https://registry.npmjs.org/@greenwood/plugin-css-modules/-/plugin-css-modules-0.30.1.tgz", + "integrity": "sha512-wJ9uSlAt7J02vuIP1J2OYEcujDparmD2Tc6MFwHZMcfMvBuFMhC4mTuBZDXhzNdO3Kbc14CG5rbp9IWxlF5Rsg==", "dev": true, "dependencies": { "acorn": "^8.0.1", @@ -2387,7 +2387,7 @@ "sucrase": "^3.35.0" }, "peerDependencies": { - "@greenwood/cli": "^0.4.0" + "@greenwood/cli": "^0.30.0" } }, "node_modules/@greenwood/plugin-css-modules/node_modules/css-tree": { @@ -2419,12 +2419,12 @@ } }, "node_modules/@greenwood/plugin-import-raw": { - "version": "0.30.0", - "resolved": "https://registry.npmjs.org/@greenwood/plugin-import-raw/-/plugin-import-raw-0.30.0.tgz", - "integrity": "sha512-cJUG3REDsoNyk9p49oEXYq/BblzyIp+7Kh2Dhdpd7PmIduoHqJ+m9jT3VIFp6SoryLAxbMqgzEGioZVIXyRs5A==", + "version": "0.30.1", + "resolved": "https://registry.npmjs.org/@greenwood/plugin-import-raw/-/plugin-import-raw-0.30.1.tgz", + "integrity": "sha512-FhdzCj1GmpHcUyactNswU8SE+Q1ckmzyszBjBXR7Jt+E7oejkdWNOjAzgQpA4kWI42UT52oMXUJJDsv4Q6uZ/A==", "dev": true, "peerDependencies": { - "@greenwood/cli": "^0.4.0" + "@greenwood/cli": "^0.30.0" } }, "node_modules/@humanwhocodes/module-importer": { diff --git a/package.json b/package.json index f1c873f9..002a871b 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ }, "scripts": { "clean": "rimraf public .greenwood storybook-static", - "build": "node --loader ./node_modules/@greenwood/cli/src/loader.js ./node_modules/.bin/greenwood build", + "build": "node --loader ./node_modules/@greenwood/cli/src/loader.js ./node_modules/@greenwood/cli/src/index.js build", "dev": "greenwood develop", "serve": "npm run clean && npm run build && greenwood serve", "story:dev": "storybook dev -p 6006", @@ -47,9 +47,9 @@ "@eslint/json": "^0.5.0", "@eslint/markdown": "^6.2.0", "@esm-bundle/chai": "^4.3.4-fix.0", - "@greenwood/cli": "^0.30.0", - "@greenwood/plugin-css-modules": "^0.30.0", - "@greenwood/plugin-import-raw": "^0.30.0", + "@greenwood/cli": "^0.30.1", + "@greenwood/plugin-css-modules": "^0.30.1", + "@greenwood/plugin-import-raw": "^0.30.1", "@ls-lint/ls-lint": "^1.10.0", "@mapbox/rehype-prism": "^0.9.0", "@storybook/addon-essentials": "^8.0.6", diff --git a/src/pages/docs/content-as-data/active-frontmatter.md b/src/pages/docs/content-as-data/active-frontmatter.md index c768577a..c9e72100 100644 --- a/src/pages/docs/content-as-data/active-frontmatter.md +++ b/src/pages/docs/content-as-data/active-frontmatter.md @@ -56,7 +56,7 @@ Or HTML: ## Data Client -You can also access this content using our data client: +You can also access this content using our [data client](/docs/content-as-data/data-client/): ```js import { getContentByCollection } from "@greenwood/cli/src/data/client.js"; diff --git a/src/pages/docs/content-as-data/index.md b/src/pages/docs/content-as-data/index.md index 6495141c..fd061930 100644 --- a/src/pages/docs/content-as-data/index.md +++ b/src/pages/docs/content-as-data/index.md @@ -18,7 +18,12 @@ If you are developing a blog site, like in our [Getting Started](/guides/getting But what happens over time, when that list grows to 10, 50, 100+ posts? Imagine maintaining that list each time, over and over again? Or just remembering to update that list each time you publish a new post? Not only that, but wouldn't it also be great to sort, search, filter, and organize those posts to make them easier for users to navigate and find? -To assist with this, Greenwood provides a set of "content as data" capabilities on the left sidebar you can take advantage of. +To assist with this, Greenwood provides a set of "content as data" capabilities: + +- [Pages Data](/docs/content-as-data/pages-data/) - Learn about the data schema available for your content +- [Data Client](/docs/content-as-data/data-client/) - Utilities for getting your content as data +- [Collections](/docs/content-as-data/collections/) - Frontmatter based configuration for grouping related content +- [Active Frontmatter](/docs/content-as-data/active-frontmatter/) - Interpolate your page's frontmatter in your HTML > First thing though, make sure you've set the [`activeContent`](/docs/reference/configuration/#active-content) flag to `true` in your _greenwood.config.js_. > diff --git a/src/pages/docs/introduction/setup.md b/src/pages/docs/introduction/setup.md index 1ef355ae..28a58493 100644 --- a/src/pages/docs/introduction/setup.md +++ b/src/pages/docs/introduction/setup.md @@ -35,8 +35,13 @@ $ npm i -D @greenwood/cli@latest # yarn $ yarn add @greenwood/cli@latest --save-dev + +# pnpm +$ pnpm add -D @greenwood/cli@latest ``` +> For pnpm, it is currently required to create a _.npmrc_ file at the root of your project with the [**shamefully-hoist**](https://pnpm.io/blog/2020/10/17/node-modules-configuration-options-with-pnpm#the-worst-case---hoisting-to-the-root) flag set to `true`. + ## Commands The CLI supports three commands, that can be easily mapped to npm scripts in your _package.json_. You'll also want to make sure you've set the `type` field to **module**: diff --git a/src/pages/docs/pages/server-rendering.md b/src/pages/docs/pages/server-rendering.md index d2737c9c..12afa4c1 100644 --- a/src/pages/docs/pages/server-rendering.md +++ b/src/pages/docs/pages/server-rendering.md @@ -244,7 +244,7 @@ export default class PostPage extends HTMLElement { To use custom imports on the server side for prerendering or SSR use cases (ex. CSS, JSON), you will need to invoke Greenwood using **NodeJS** from the CLI and pass it the `--loaders` flag along with the path to Greenwood's provided loader function. ```shell -$ node --loader ./node_modules/@greenwood/cli/src/loader.js ./node_modules/.bin/greenwood +$ node --loader ./node_modules/@greenwood/cli/src/loader.js ./node_modules/@greenwood/cli/src/index.js ``` Then you will be able to run this, or for any custom format you want using a plugin. diff --git a/src/pages/docs/plugins/index.md b/src/pages/docs/plugins/index.md index f8cc4891..0ee45117 100644 --- a/src/pages/docs/plugins/index.md +++ b/src/pages/docs/plugins/index.md @@ -1,6 +1,7 @@ --- layout: docs order: 4 +tocHeading: 2 --- @@ -9,6 +10,16 @@ order: 4 > When installing plugins with **npm**, make sure to add the `--legacy-peer-deps` flag, or add an _.npmrc_ file in the root of your project with `legacy-peer-deps=true` set. +## Featured + +- [Lit SSR](/docs/plugins/lit-ssr/) - For Lit users, a custom renderer plugin to support Lit+SSR +- [TypeScript](/docs/plugins/typescript/) - A plugin for transforming files written in TypeScript +- [PostCSS](/docs/plugins/postcss/) - Leverage PostCSS plugins, like [Tailwind](/guides/ecosystem/tailwind/) +- [CSS Modules](/docs/plugins/css-modules/) - Support for [CSS Modules](https://github.com/css-modules/css-modules) ™️ syntax +- [Raw Loader](/docs/plugins/raw/) - Import arbitrary text files as ESM + +## All Plugins + Below is the official list of supported first-party plugins available by the Greenwood team with links to the plugin specific README for full installation and usage documentation.
diff --git a/src/pages/docs/reference/configuration.md b/src/pages/docs/reference/configuration.md index 54bc5f70..cdf8f3d2 100644 --- a/src/pages/docs/reference/configuration.md +++ b/src/pages/docs/reference/configuration.md @@ -8,7 +8,7 @@ tocHeading: 2 This section details all the supported configuration options available with **Greenwood**, which you can define in a _greenwood.config.js_ file at root of your project. -The below is a _greenwood.config.js_ file reflecting default values: +Below is a _greenwood.config.js_ file reflecting default values: ```js export default { diff --git a/src/pages/docs/resources/scripts.md b/src/pages/docs/resources/scripts.md index 1f455b3d..fd958551 100644 --- a/src/pages/docs/resources/scripts.md +++ b/src/pages/docs/resources/scripts.md @@ -75,7 +75,7 @@ Below are some examples: // after having installed Lit import { html, LitElement } from "lit"; -export class SimpleGreeting extends LitElement { +class SimpleGreeting extends LitElement { static properties = { name: { type: String }, }; @@ -110,3 +110,19 @@ The rule of thumb is: - If it's a package from npm installed in **dependencies**, you can use bare specifiers and no extension - Otherwise, you will need to use a relative path and the extension + +## Prerendering + +If you have enabled [prerendering](/docs/reference/configuration/#prerender) and using Greenwood's default [renderer (WCC)](/docs/reference/appendix/#dom-emulation), make sure that any custom elements you want prerendered have a `default` export for their `class` definition. + +```js +export default class Card extends HTMLElement { + connectedCallback() { + if (!this.shadowRoot) { + // ... + } + } +} + +customElements.define("x-card", Card); +``` diff --git a/src/pages/guides/hosting/aws.md b/src/pages/guides/hosting/aws.md index 3c2881f9..ebfd9f95 100644 --- a/src/pages/guides/hosting/aws.md +++ b/src/pages/guides/hosting/aws.md @@ -22,7 +22,7 @@ In this section, we'll share the steps for up S3 and Cloudfront together for sta > Keep an eye out for prompts from AWS to enable IAM rules for your function and make sure to invalidate the Cloudfront distribution between tests, since error pages / responses will get cached. -You should now be able to access your site at _http://.cloudfront.net/_! 🏆 +You should now be able to access your site at _http://{your-dist}.cloudfront.net/_! 🏆 Now at this point, if you have any routes like `/search/`, you'll notice they are not working unless _index.html_ is appended to the path. To enable routing (URL rewriting) for cleaner URLs, follow the _Configure Trigger_ section of [this guide](https://aws.amazon.com/blogs/compute/implementing-default-directory-indexes-in-amazon-s3-backed-amazon-cloudfront-origins-using-lambdaedge/) to attach the Lambda as a [**Lambda@Edge**](https://aws.amazon.com/lambda/edge/) function that will run on every incoming request.