From 47a07c62be2008c7f42ac7c03b340bb6df92028e Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Sat, 6 Sep 2025 10:16:16 -0400 Subject: [PATCH 1/7] remove markdown configuration from config docs --- src/pages/docs/reference/configuration.md | 52 ----------------------- 1 file changed, 52 deletions(-) diff --git a/src/pages/docs/reference/configuration.md b/src/pages/docs/reference/configuration.md index 7fefb4ca..8761707e 100644 --- a/src/pages/docs/reference/configuration.md +++ b/src/pages/docs/reference/configuration.md @@ -23,9 +23,6 @@ export default { }, isolation: false, layoutsDirectory: "layouts", // e.g. ./src/layouts - markdown: { - plugins: [], - }, optimization: "default", pagesDirectory: "pages", // e.g. ./src/pages plugins: [], @@ -207,55 +204,6 @@ By default the directory Greenwood will use to look for your layouts is in _layo -## Markdown - -You can install [**remark**](https://remark.js.org/) or [**rehype**](https://github.com/rehypejs/rehype) compatible plugins to extend Greenwood's markdown rendering and transformation capabilities by passing them as an array to the `markdown` setting. - -After installing the package, pass the plugin name as a string: - - - - - - ```js - export default { - markdown: { - plugins: ["rehype-slug", "remark-gfm"], - }, - }; - ``` - - - - - -If you need to pass options to a markdown plugin, you can use object syntax with the plugin name and the options it takes. - - - - - - ```js - export default { - markdown: { - plugins: [ - "rehype-slug", - "remark-gfm", - { - name: "rehype-autolink-headings", - options: { - behavior: "append" - }, - }, - ], - }, - }; - ``` - - - - - ## Optimization Greenwood provides a number of different ways to send hints to Greenwood as to how JavaScript and CSS tags in your HTML should get loaded by the browser. Greenwood supplements, and builds up on top of existing [resource "hints" like `preload` and `prefetch`](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content). From d8604bc016fae9fa4eddba52659b2b552a4349d7 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Sat, 6 Sep 2025 10:16:30 -0400 Subject: [PATCH 2/7] merge markdown docs --- src/pages/docs/resources/markdown.md | 134 +++++++++++++++++++++++++-- 1 file changed, 126 insertions(+), 8 deletions(-) diff --git a/src/pages/docs/resources/markdown.md b/src/pages/docs/resources/markdown.md index d6270dc4..0ba4683c 100644 --- a/src/pages/docs/resources/markdown.md +++ b/src/pages/docs/resources/markdown.md @@ -6,24 +6,42 @@ tocHeading: 2 # Markdown -In this section we'll cover some of the Markdown related features of **Greenwood**, which by default supports the [CommonMark](https://commonmark.org/help/) specification and [**unifiedjs**](https://unifiedjs.com/) as the markdown / content framework. +For authoring in markdown, Greenwood provides a plugin that you can install, which by default supports the [CommonMark](https://commonmark.org/help/) specification and uses [**unifiedjs**](https://unifiedjs.com/) as the markdown / content framework. See the [plugin's README](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-markdown) for additional information, like standalone usage. -## Plugins +## Installation -Using your _greenwood.config.js_ you can have additional [markdown customizations and configurations](/docs/reference/configuration/#markdown). +You can use your favorite JavaScript package manager to install this plugin: -For example, to use the [**remark-github**](https://github.com/remarkjs/remark-github) plugin: + + + + ```shell + npm i -D @greenwood/plugin-markdown + ``` + + ```shell + yarn add @greenwood/plugin-markdown --dev + ``` + + ```shell + pnpm add -D @greenwood/plugin-markdown + ``` + + + + + +Then add this plugin to your _greenwood.config.js_. ```js - // npm i -D remark-github + import { greenwoodPluginMarkdown } from "@greenwood/plugin-markdown"; + export default { - markdown: { - plugins: ["remark-github"], - }, + plugins: [greenwoodPluginMarkdown()], }; ``` @@ -31,6 +49,106 @@ For example, to use the [**remark-github**](https://github.com/remarkjs/remark-g +## Usage + +Now you can start authoring your pages in markdown: + +```shell +src/ + pages/ + blog/ + first-post.md + second-post.md + index.md +``` + +## Types + +Types should automatically be inferred through this package's exports map, but can be referenced explicitly in both JavaScript (JSDoc) and TypeScript files if needed. + + + + + + ```js + /** @type {import('@greenwood/plugin-markdown').MarkdownPlugin} */ + ``` + + + + + + + + + + ```ts + import type { MarkdownPlugin } from '@greenwood/plugin-markdown'; + ``` + + + + + +## Options + +### Plugins + +You can install **remark** or **rehype** compatible plugins to extend this plugin's markdown rendering and transformation capabilities by passing their names in as an array. + +For example, after installing something like **rehype-slug**, pass the name as a string when adding the plugin to your Greenwood config file: + + + + + + ```js + import { greenwoodPluginMarkdown } from '@greenwood/plugin-markdown'; + + export default { + plugins: [ + greenwoodPluginMarkdown({ + // npm i -D rehype-slug + plugins: [ + "rehype-slug" + ], + }) + ] + } + ``` + + + + + +If you need to pass options to a markdown plugin, you can use object syntax with the plugin name and the options it takes. + + + + + + ```js + import { greenwoodPluginMarkdown } from '@greenwood/plugin-markdown'; + + export default { + plugins: [ + greenwoodPluginMarkdown({ + plugins: [ + "rehype-slug", + { + name: "rehype-autolink-headings", + options: { + behavior: "append" + }, + }, + ], + }) + ] + } + ``` + + + ## Syntax Highlighting Although Greenwood does not provide any syntax highlighting by default, you can add support for [**Prism**](https://prismjs.com/), for example. From e89df2f11dd437e60e124988565c05765ebaa3cd Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Sat, 6 Sep 2025 10:21:14 -0400 Subject: [PATCH 3/7] move markdown docs from resources to plugins --- netlify.toml | 7 ++++++- src/pages/docs/plugins/css-modules.md | 2 +- src/pages/docs/plugins/index.md | 2 ++ src/pages/docs/plugins/lit-ssr.md | 2 +- src/pages/docs/{resources => plugins}/markdown.md | 2 +- src/pages/docs/plugins/postcss.md | 2 +- src/pages/docs/plugins/raw.md | 2 +- 7 files changed, 13 insertions(+), 6 deletions(-) rename src/pages/docs/{resources => plugins}/markdown.md (99%) diff --git a/netlify.toml b/netlify.toml index b880a3e6..fcaaf3eb 100644 --- a/netlify.toml +++ b/netlify.toml @@ -16,4 +16,9 @@ [[redirects]] status = 301 from = "/docs/plugins/typescript/" - to = "/docs/resources/typescript/" \ No newline at end of file + to = "/docs/resources/typescript/" + +[[redirects]] + status = 301 + from = "/docs/resources/markdown/" + to = "/docs/plugins/markdown/" \ No newline at end of file diff --git a/src/pages/docs/plugins/css-modules.md b/src/pages/docs/plugins/css-modules.md index 9d9e76f7..0b987678 100644 --- a/src/pages/docs/plugins/css-modules.md +++ b/src/pages/docs/plugins/css-modules.md @@ -2,7 +2,7 @@ title: CSS Modules label: CSS Modules layout: docs -order: 2 +order: 3 tocHeading: 2 --- diff --git a/src/pages/docs/plugins/index.md b/src/pages/docs/plugins/index.md index 1043ec89..b2ef02cb 100644 --- a/src/pages/docs/plugins/index.md +++ b/src/pages/docs/plugins/index.md @@ -12,6 +12,7 @@ tocHeading: 2 ## Featured +- [Markdown](/docs/plugins/markdown/) - Author your pages in markdown - [Lit SSR](/docs/plugins/lit-ssr/) - For Lit users, a custom renderer plugin to support Lit+SSR - [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 @@ -31,6 +32,7 @@ Below is the official list of supported first-party plugins available by the Gre | [Import Raw](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-import-raw) | Enables usage of ESM syntax for loading arbitrary file contents as a string. | | [JSX](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-import-jsx) | Enables usage of ESM syntax for loading [**WCC**](https://github.com/ProjectEvergreen/wcc) compatible JSX. | | [Lit SSR](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-renderer-lit) | A server-side rendering plugin for Lit based Greenwood projects. | +| [Markdown](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-markdown) | Author your pages in markdown using the [**unified**](https://unifiedjs.com/) ecosystem. | | [Netlify](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-adapter-netlify) | Deploy serverless and edge functions to [**Netlify**](https://www.netlify.com/). | | [Polyfills](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-polyfills) | Web Component related polyfills for older browsers. | | [PostCSS](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-postcss) | Allows usage of [**PostCSS**](https://postcss.org/) plugins and configuration in your project. | diff --git a/src/pages/docs/plugins/lit-ssr.md b/src/pages/docs/plugins/lit-ssr.md index 90de209f..4148cfc9 100644 --- a/src/pages/docs/plugins/lit-ssr.md +++ b/src/pages/docs/plugins/lit-ssr.md @@ -2,7 +2,7 @@ title: Lit SSR label: Lit SSR layout: docs -order: 1 +order: 2 tocHeading: 2 --- diff --git a/src/pages/docs/resources/markdown.md b/src/pages/docs/plugins/markdown.md similarity index 99% rename from src/pages/docs/resources/markdown.md rename to src/pages/docs/plugins/markdown.md index 0ba4683c..c27d2e80 100644 --- a/src/pages/docs/resources/markdown.md +++ b/src/pages/docs/plugins/markdown.md @@ -1,6 +1,6 @@ --- layout: docs -order: 5 +order: 1 tocHeading: 2 --- diff --git a/src/pages/docs/plugins/postcss.md b/src/pages/docs/plugins/postcss.md index 8bce1d35..f87c257f 100644 --- a/src/pages/docs/plugins/postcss.md +++ b/src/pages/docs/plugins/postcss.md @@ -2,7 +2,7 @@ title: PostCSS label: PostCSS layout: docs -order: 4 +order: 5 tocHeading: 2 --- diff --git a/src/pages/docs/plugins/raw.md b/src/pages/docs/plugins/raw.md index 007b35a9..dcfa2659 100644 --- a/src/pages/docs/plugins/raw.md +++ b/src/pages/docs/plugins/raw.md @@ -1,6 +1,6 @@ --- layout: docs -order: 3 +order: 4 tocHeading: 2 --- From 34b8c4ed8dc5101f5ab32c95cd8abece5143dfab Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 8 Sep 2025 21:49:22 -0400 Subject: [PATCH 4/7] update getting started guide with markdown plugin install steps --- .../guides/getting-started/walkthrough.md | 43 ++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/src/pages/guides/getting-started/walkthrough.md b/src/pages/guides/getting-started/walkthrough.md index 050715df..fe1f09d7 100644 --- a/src/pages/guides/getting-started/walkthrough.md +++ b/src/pages/guides/getting-started/walkthrough.md @@ -78,7 +78,48 @@ Our home page will be simple landing page with links to our blog post pages: -For the blog post pages, let's create a folder called _blog/_ in our pages directory and then create two markdown files called _first-post.md_ and _second-post.md_: +For the blog post pages, we're going to use Greenwood's [markdown plugin](/docs/plugins/markdown) for authoring these pages. + +First, let's install the plugin: + + + + + ```shell + npm i -D @greenwood/plugin-markdown + ``` + + ```shell + yarn add @greenwood/plugin-markdown --dev + ``` + + ```shell + pnpm add -D @greenwood/plugin-markdown + ``` + + + + + +And then create a _greenwood.config.js_ file: + + + + + + ```js + import { greenwoodPluginMarkdown } from "@greenwood/plugin-markdown"; + + export default { + plugins: [greenwoodPluginMarkdown()], + }; + ``` + + + + + +Now we create a folder called _blog/_ in our pages directory and then create two markdown files called _first-post.md_ and _second-post.md_: From 6f3423ee85c2b4d77c8e3b42df888f19f2721db1 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 8 Sep 2025 21:50:31 -0400 Subject: [PATCH 5/7] move ToC headings section to markdown plugin --- src/pages/docs/content-as-data/pages-data.md | 60 ------------------- src/pages/docs/plugins/markdown.md | 62 +++++++++++++++++++- 2 files changed, 61 insertions(+), 61 deletions(-) diff --git a/src/pages/docs/content-as-data/pages-data.md b/src/pages/docs/content-as-data/pages-data.md index 89a7aea9..61ffeada 100644 --- a/src/pages/docs/content-as-data/pages-data.md +++ b/src/pages/docs/content-as-data/pages-data.md @@ -54,66 +54,6 @@ This is the data you would get back: } ``` -## Table of Contents - -Additionally for markdown pages, you can add a frontmatter property called `tocHeading` that will read all the HTML heading tags that match that number, and provide that as a subset of the data object. This is most useful for generating the table of contents for a page. - -Taking our previous example, if we were to configure this for `

` tags: - - - - - - ```md - --- - author: Project Evergreen - published: 2024-01-01 - tocHeading: 2 - --- - - # First Post - - This is my first post. - - ## Overview - - Lorum Ipsum - - ## First Point - - Something something... - ``` - - - - - -We would get this additional content as data out: - -```json -{ - "id": "blog-first-post", - "title": "First Post", - "label": "First Post", - "route": "/blog/first-post/", - "data": { - "author": "Project Evergreen", - "published": "2024-01-01", - "tocHeading": 2, - "tableOfContents": [ - { - "content": "Overview", - "slug": "overview" - }, - { - "content": "First Point", - "slug": "first-point" - } - ] - } -} -``` - ## External Content Using our [Source plugin](/docs/reference/plugins-api/#source), just as you can get your content as data _out_ of Greenwood, so can you provide your own sources of content (as data) _to_ Greenwood. This is great for pulling content from a headless CMS, database, or anything else you can imagine! diff --git a/src/pages/docs/plugins/markdown.md b/src/pages/docs/plugins/markdown.md index c27d2e80..4e09e859 100644 --- a/src/pages/docs/plugins/markdown.md +++ b/src/pages/docs/plugins/markdown.md @@ -6,7 +6,7 @@ tocHeading: 2 # Markdown -For authoring in markdown, Greenwood provides a plugin that you can install, which by default supports the [CommonMark](https://commonmark.org/help/) specification and uses [**unifiedjs**](https://unifiedjs.com/) as the markdown / content framework. See the [plugin's README](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-markdown) for additional information, like standalone usage. +For authoring in markdown, Greenwood provides a plugin that you can install which by default supports the [CommonMark](https://commonmark.org/help/) specification and uses [**unifiedjs**](https://unifiedjs.com/) as the markdown / content framework. See the [plugin's README](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-markdown) for additional information, like standalone usage. ## Installation @@ -351,6 +351,66 @@ You can also define any custom frontmatter property you want and that will be ma +## Table of Contents + +You can add a frontmatter property called `tocHeading` that will read all the HTML heading tags that match that number in your markdown, and provide that as a subset of the data object in your [pages data schema](/docs/content-as-data/pages-data/#schema). This is most useful for generating the table of contents for a page. + +For example: + + + + + + ```md + --- + author: Project Evergreen + published: 2024-01-01 + tocHeading: 2 + --- + + # First Post + + This is my first post. + + ## Overview + + Lorum Ipsum + + ## First Point + + Something something... + ``` + + + + + +We would get this additional content as data: + +```json +{ + "id": "blog-first-post", + "title": "First Post", + "label": "First Post", + "route": "/blog/first-post/", + "data": { + "author": "Project Evergreen", + "published": "2024-01-01", + "tocHeading": 2, + "tableOfContents": [ + { + "content": "Overview", + "slug": "overview" + }, + { + "content": "First Point", + "slug": "first-point" + } + ] + } +} +``` + ## Active Frontmatter With [`activeContent`](/docs/reference/configuration/#active-content) enabled, any of these properties would be available in your HTML or markdown through Greenwood's [content as data features](/docs/content-as-data/). From 1a117507c61831ce978c03632a797ef8c8310b21 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Sat, 13 Sep 2025 13:33:02 -0400 Subject: [PATCH 6/7] create dedicated frontmatter page in content as data docs --- .../content-as-data/active-frontmatter.md | 4 +- src/pages/docs/content-as-data/collections.md | 2 +- src/pages/docs/content-as-data/frontmatter.md | 143 ++++++++++++++++++ src/pages/docs/content-as-data/graph-ql.md | 2 +- src/pages/docs/pages/layouts.md | 27 +++- src/pages/docs/pages/routing.md | 2 +- src/pages/docs/pages/server-rendering.md | 6 +- src/pages/docs/plugins/markdown.md | 142 +---------------- src/pages/docs/resources/index.md | 2 +- src/pages/guides/tutorials/theme-packs.md | 2 +- 10 files changed, 180 insertions(+), 152 deletions(-) create mode 100644 src/pages/docs/content-as-data/frontmatter.md diff --git a/src/pages/docs/content-as-data/active-frontmatter.md b/src/pages/docs/content-as-data/active-frontmatter.md index 7211323d..73f7da35 100644 --- a/src/pages/docs/content-as-data/active-frontmatter.md +++ b/src/pages/docs/content-as-data/active-frontmatter.md @@ -1,12 +1,12 @@ --- layout: docs -order: 4 +order: 5 tocHeading: 2 --- # Active Frontmatter -Active Frontmatter enables the ability to apply static substitutions in your pages and layouts based on the frontmatter content of your pages, and inspired by JavaScript [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) syntax. +Active Frontmatter enables the ability to apply static substitutions in your pages and layouts based on the [frontmatter](/docs/content-as-data/frontmatter/) content of your pages, and inspired by JavaScript [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) syntax. Really useful for passing page content or collections as attributes to a custom element. diff --git a/src/pages/docs/content-as-data/collections.md b/src/pages/docs/content-as-data/collections.md index cfecbc87..832f9607 100644 --- a/src/pages/docs/content-as-data/collections.md +++ b/src/pages/docs/content-as-data/collections.md @@ -6,7 +6,7 @@ tocHeading: 2 # Collections -Collections are a feature in Greenwood by which you can use [frontmatter](/docs/resources/markdown/#frontmatter) to group pages that can then be referenced through [JavaScript](/docs/content-as-data/data-client/) or [active frontmatter](/docs/content-as-data/active-frontmatter/). This can be a useful way to group pages for things like navigation menus based on the content in your pages directory. +Collections are a feature in Greenwood by which you can use [frontmatter](/docs/content-as-data/frontmatter/) to group pages that can then be referenced through [JavaScript](/docs/content-as-data/data-client/) or [active frontmatter](/docs/content-as-data/active-frontmatter/). This can be a useful way to group pages for things like navigation menus based on the content in your pages directory. See our [reference docs on Greenwood's available types](/docs/reference/appendix/#types) for more information on authoring with TypeScript. diff --git a/src/pages/docs/content-as-data/frontmatter.md b/src/pages/docs/content-as-data/frontmatter.md new file mode 100644 index 00000000..7a322a47 --- /dev/null +++ b/src/pages/docs/content-as-data/frontmatter.md @@ -0,0 +1,143 @@ +--- +layout: docs +order: 4 +tocHeading: 2 +--- + +# Frontmatter + +[Frontmatter](https://www.npmjs.com/package/front-matter) is a [YAML](https://yaml.org/) block at the top of a file that gives you the ability to define variables that are made available to Greenwood's [build process and then your HTML](/docs/content-as-data/). You can also use it to import additional static assets like JS and CSS files. + +Greenwood defines the following properties that you can use in HTML or [markdown](/docs/plugins/markdown) out of the box: + +- Label +- Title +- Layout +- Imports +- Custom Data + +## Label + +By default Greenwood will aim to create a label for your page based on filename path, but you can override it if desired. This can be useful if you want to create a custom value to display for a link with custom formatting or text. + + + + + + ```md + --- + label: "My Blog Post from 3/5/2020" + --- + + # My Blog Post + ``` + + + + + +## Title + +To set the `` for a given page, you can customize the **title** variable. Otherwise, the `<title>` will be inferred from the file name. + +<!-- prettier-ignore-start --> + +<app-ctc-block variant="snippet"> + + ```md + --- + title: My Blog Post + --- + + # This is a post + + The is a markdown file with the title defined in frontmatter. + ``` + +</app-ctc-block> + +<!-- prettier-ignore-end --> + +In this example, the `<title>` tag will be the value of **title**. + +```html +<title>My Blog Post +``` + +## Layouts + +When creating multiple [page layouts](/docs/pages/layouts/), you can use the **layout** frontmatter key to configure Greenwood to use that layout to wrap a given page. + + + + + + ```md + --- + layout: blog + --- + + # My First Blog Post + + This is my first blog post, I hope you like it! + ``` + + + + + +In this example, _src/layouts/blog.html_ will be used to wrap the content of this markdown page. + +> **Note:** By default, Greenwood will look for and use _src/layouts/page.html_ for all pages by default. + +## Imports + +If you want to include scripts or styles on a _per **page** basis_ (typically when using markdown), you can provide filepaths and attributes using the `imports` key. This is great for one off use cases where you don't want to ship a third party lib in all your layouts, or as a demo for a particular blog post. You can also add attributes by space delimiting them after the path. + + + + + + ```md + --- + imports: + - /components/my-component/component.js type="module" foo="bar" + - /components/my-component/component.css + --- + + # My Demo Page + ``` + + + + + +You will then see the following emitted for file + +```html + + +``` + +## Custom Data + +You can also define any custom frontmatter property you want and that will be made available on the `data` property of [the page object](/docs/content-as-data/pages-data/). + + + + + + ```md + --- + author: Jon Doe + date: 04/07/2020 + --- + + # First Post + + My first post + ``` + + + + diff --git a/src/pages/docs/content-as-data/graph-ql.md b/src/pages/docs/content-as-data/graph-ql.md index 80d80a81..a0c7a22d 100644 --- a/src/pages/docs/content-as-data/graph-ql.md +++ b/src/pages/docs/content-as-data/graph-ql.md @@ -2,7 +2,7 @@ title: GraphQL label: GraphQL layout: docs -order: 5 +order: 6 tocHeading: 2 --- diff --git a/src/pages/docs/pages/layouts.md b/src/pages/docs/pages/layouts.md index acb54c80..1919f689 100644 --- a/src/pages/docs/pages/layouts.md +++ b/src/pages/docs/pages/layouts.md @@ -9,7 +9,7 @@ tocHeading: 2 Greenwood defines two types of layouts that can be used to wrap your pages with common HTML - _App Layout_: The ["app shell"](https://developers.google.com/web/fundamentals/architecture/app-shell) that will wrap all pages. -- _Page Layouts_: Layouts that can be re-used across multiple pages and defined using [frontmatter](/docs/resources/markdown/#frontmatter). +- _Page Layouts_: Layouts that can be re-used across multiple pages and defined using [**frontmatter**](/docs/content-as-data/frontmatter/) Greenwood will handle merging the `` and `` tag contents when building up your pages and layouts. @@ -74,7 +74,7 @@ You can create more layouts and use them for pages with the following steps: layout: blog --- - ## My First Post + # My First Post Lorum Ipsum ``` @@ -83,6 +83,29 @@ You can create more layouts and use them for pages with the following steps: +Frontmatter is also supported for HTML files: + + + + + + ```html + --- + layout: blog + --- + + + +

My First Post

+

Lorum Ipsum

+ + + ``` + + + + + ## App Layout To customize the outer most wrapping HTML of _all_ your pages, create an _app.html_ file. This is most useful for global page elements like headers, navigation, and footers. Like a page layout, this will just be another HTML document (or JS / TS file) with a `` placeholder that can be used to position where the content from the processed page layout will appear. diff --git a/src/pages/docs/pages/routing.md b/src/pages/docs/pages/routing.md index a0fd461f..a389c812 100644 --- a/src/pages/docs/pages/routing.md +++ b/src/pages/docs/pages/routing.md @@ -10,7 +10,7 @@ Greenwood supports file-based routing, which means that filenames in the _pages/ ## Static Pages -For static content, Greenwood support HTML and [markdown](/docs/resources/markdown/) as page formats. +For static content, Greenwood supports HTML and markdown [(with a plugin)](/docs/plugins/markdown/) as page formats. For example, given the following folder structure: diff --git a/src/pages/docs/pages/server-rendering.md b/src/pages/docs/pages/server-rendering.md index 8eab6e6c..c4b290e8 100644 --- a/src/pages/docs/pages/server-rendering.md +++ b/src/pages/docs/pages/server-rendering.md @@ -22,12 +22,12 @@ The above would serve content in a browser at the path _/users/_. ## Usage -In your page file, Greenwood supports the following functions that you can `export` for providing server rendered content and [frontmatter](/docs/resources/markdown/) to produce the `` content for your page. +In your page file, Greenwood supports the following functions that you can `export` for providing server rendered content and frontmatter assist in producing the content for your pages. - **default** (recommended): Use the custom elements API to render out your page content, aka **Web (Server) Components**. This rendering is only done server-side (and thus needs to be SSR compatible). To have client side imports, use the imports field in `getFrontmatter` or add them as ` - -``` - -### Layouts - -When creating multiple [page layouts](/docs/pages/layouts/), you can use the **layout** frontmatter key to configure Greenwood to use that layout to wrap a given page. - - - - - - ```md - --- - layout: blog - --- - - # My First Blog Post - - This is my first blog post, I hope you like it! - ``` - - - - - -In this example, _src/layouts/blog.html_ will be used to wrap the content of this markdown page. - -> **Note:** By default, Greenwood will look for and use _src/layouts/page.html_ for all pages by default. - -### Custom Data - -You can also define any custom frontmatter property you want and that will be made available on the `data` property of [the page object](/docs/content-as-data/pages-data/). - - - - - - ```md - --- - author: Jon Doe - date: 04/07/2020' - --- - - # First Post - - My first post - ``` - - - - - ## Table of Contents -You can add a frontmatter property called `tocHeading` that will read all the HTML heading tags that match that number in your markdown, and provide that as a subset of the data object in your [pages data schema](/docs/content-as-data/pages-data/#schema). This is most useful for generating the table of contents for a page. +This plugin supports the addition of a [frontmatter](/docs/content-as-data/frontmatter/) property called `tocHeading` that will read all the HTML heading tags that match that number in your markdown, and provide that as a subset of the data object in your [pages data schema](/docs/content-as-data/pages-data/#schema). This is most useful for generating the table of contents for a page. For example: @@ -424,7 +286,7 @@ With [`activeContent`](/docs/reference/configuration/#active-content) enabled, a author: Project Evergreen --- - ## My Post + # My Post Authored By: ${globalThis.page.data.author} ``` diff --git a/src/pages/docs/resources/index.md b/src/pages/docs/resources/index.md index 4697e0b5..b49aff11 100644 --- a/src/pages/docs/resources/index.md +++ b/src/pages/docs/resources/index.md @@ -12,4 +12,4 @@ In this section we'll cover common web formats and languages supported by Greenw - [JavaScript](/docs/resources/scripts/) - [CSS](/docs/resources/styles/) - [Assets](/docs/resources/assets/) -- [Markdown](/docs/resources/markdown/) +- [TypeScript](/docs/resources/typescript/) diff --git a/src/pages/guides/tutorials/theme-packs.md b/src/pages/guides/tutorials/theme-packs.md index 361b4f93..09244e9e 100644 --- a/src/pages/guides/tutorials/theme-packs.md +++ b/src/pages/guides/tutorials/theme-packs.md @@ -332,7 +332,7 @@ For users, they would just need to do the following: Success! 🥳 -> Don't forget, user's can also [include additional CSS / JS files in their frontmatter](/docs/resources/markdown/#frontmatter), to further extend, customize, and override your layouts! +> Don't forget, user's can also [include additional CSS / JS files in their frontmatter](/docs/content-as-data/frontmatter/#imports), to further extend, customize, and override your layouts! ## FAQ From 5ba12add21c5528417d67c986b1671b7a816ca2f Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Sat, 13 Sep 2025 13:43:52 -0400 Subject: [PATCH 7/7] misc links fixes and grammar --- src/pages/docs/content-as-data/frontmatter.md | 2 +- src/pages/guides/getting-started/walkthrough.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/content-as-data/frontmatter.md b/src/pages/docs/content-as-data/frontmatter.md index 7a322a47..98bca687 100644 --- a/src/pages/docs/content-as-data/frontmatter.md +++ b/src/pages/docs/content-as-data/frontmatter.md @@ -8,7 +8,7 @@ tocHeading: 2 [Frontmatter](https://www.npmjs.com/package/front-matter) is a [YAML](https://yaml.org/) block at the top of a file that gives you the ability to define variables that are made available to Greenwood's [build process and then your HTML](/docs/content-as-data/). You can also use it to import additional static assets like JS and CSS files. -Greenwood defines the following properties that you can use in HTML or [markdown](/docs/plugins/markdown) out of the box: +Greenwood defines the following properties that you can use in HTML or [markdown](/docs/plugins/markdown/) out of the box: - Label - Title diff --git a/src/pages/guides/getting-started/walkthrough.md b/src/pages/guides/getting-started/walkthrough.md index fe1f09d7..d87d83f2 100644 --- a/src/pages/guides/getting-started/walkthrough.md +++ b/src/pages/guides/getting-started/walkthrough.md @@ -78,7 +78,7 @@ Our home page will be simple landing page with links to our blog post pages: -For the blog post pages, we're going to use Greenwood's [markdown plugin](/docs/plugins/markdown) for authoring these pages. +For the blog post pages, we're going to use Greenwood's [markdown plugin](/docs/plugins/markdown/) for authoring these pages. First, let's install the plugin: @@ -101,7 +101,7 @@ First, let's install the plugin: -And then create a _greenwood.config.js_ file: +Then create a _greenwood.config.js_ file and import the plugin: @@ -119,7 +119,7 @@ And then create a _greenwood.config.js_ file: -Now we create a folder called _blog/_ in our pages directory and then create two markdown files called _first-post.md_ and _second-post.md_: +Now we can create a folder called _blog/_ in our pages directory and then create two markdown files called _first-post.md_ and _second-post.md_: