docs: #229 standalone markdown plugin

netlify.toml

@@ -16,4 +16,9 @@
 [[redirects]]
   status = 301
   from = "/docs/plugins/typescript/"
-  to = "/docs/resources/typescript/"
+  to = "/docs/resources/typescript/"
+
+[[redirects]]
+  status = 301
+  from = "/docs/resources/markdown/"
+  to = "/docs/plugins/markdown/"

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.
 

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.
 

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.
+
+<!-- prettier-ignore-start -->
+
+<app-ctc-block variant="snippet">
+
+  ```md
+  ---
+  label: "My Blog Post from 3/5/2020"
+  ---
+
+  # My Blog Post
+  ```
+
+</app-ctc-block>
+
+<!-- prettier-ignore-end -->
+
+## Title
+
+To set the `<title>` 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</title>
+```
+
+## 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.
+
+<!-- prettier-ignore-start -->
+
+<app-ctc-block variant="snippet">
+
+  ```md
+  ---
+  layout: blog
+  ---
+
+  # My First Blog Post
+
+  This is my first blog post, I hope you like it!
+  ```
+
+</app-ctc-block>
+
+<!-- prettier-ignore-end -->
+
+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.
+
+<!-- prettier-ignore-start -->
+
+<app-ctc-block variant="snippet">
+
+  ```md
+  ---
+  imports:
+    - /components/my-component/component.js type="module" foo="bar"
+    - /components/my-component/component.css
+  ---
+
+  # My Demo Page
+  ```
+
+</app-ctc-block>
+
+<!-- prettier-ignore-end -->
+
+You will then see the following emitted for file
+
+```html
+<script type="module" src="/components/my-component/component.js" type="module" foo="bar"></script>
+<link rel="stylesheet" href="/components/my-component/component.css" />
+```
+
+## 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/).
+
+<!-- prettier-ignore-start -->
+
+<app-ctc-block variant="snippet">
+
+  ```md
+  ---
+  author: Jon Doe
+  date: 04/07/2020
+  ---
+
+  # First Post
+
+  My first post
+  ```
+
+</app-ctc-block>
+
+<!-- prettier-ignore-end -->

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
 ---
 

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 `<h2>` tags:
-
-<!-- prettier-ignore-start -->
-
-<app-ctc-block variant="snippet" heading="src/pages/blog/first-post.md">
-
-  ```md
-  ---
-  author: Project Evergreen
-  published: 2024-01-01
-  tocHeading: 2
-  ---
-
-  # First Post
-
-  This is my first post.
-
-  ## Overview
-
-  Lorum Ipsum
-
-  ## First Point
-
-  Something something...
-  ```
-
-</app-ctc-block>
-
-<!-- prettier-ignore-end -->
-
-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!

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 `<body>` and `<head>` 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:
 
    <!-- prettier-ignore-end -->
 
+Frontmatter is also supported for HTML files:
+
+<!-- prettier-ignore-start -->
+
+<app-ctc-block variant="snippet">
+
+  ```html
+  ---
+  layout: blog
+  ---
+
+  <html>
+    <body>
+      <h1>My First Post</h1>
+      <p>Lorum Ipsum</p>
+    </body>
+  <html>
+  ```
+
+</app-ctc-block>
+
+<!-- prettier-ignore-end -->
+
 ## 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 `<page-outlet></page-outlet>` placeholder that can be used to position where the content from the processed page layout will appear.

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:
 

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 `<body><body>` 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 `<script>` or `<link>` tags in a layout. _Using this option will take precedence over `getBody`_.
 - **getBody**: Return a string of HTML for the contents of the page
 - **getLayout**: Return a string of HTML to act as the [page's layout](/docs/pages/layouts/#pages)
-- **getFrontmatter**: Provide an object of [frontmatter](/docs/resources/markdown/#frontmatter) properties. Useful in conjunction with [content as data](/docs/content-as-data/), or otherwise setting static configuration / metadata through SSR.
+- **getFrontmatter**: Provide an object of [frontmatter](/docs/content-as-data/frontmatter/) properties. Useful in conjunction with [content as data](/docs/content-as-data/), or otherwise setting static configuration / metadata through SSR.
 
 <!-- eslint-disable no-unused-vars -->
 
@@ -198,7 +198,7 @@ You can pull in data from Greenwood's [compilation](/docs/reference/appendix/#co
 
 ### Frontmatter
 
-Any Greenwood [supported frontmatter](/docs/resources/markdown/#frontmatter) can be returned here, including the [collection key](/docs/content-as-data/collections/). _This is only run once when the server is started_ to populate pages metadata, which is helpful if you want your dynamic route to show up in a collection with other static pages. You can even define a `layout` and reuse all your existing [layouts](/docs/pages/layouts/), even for server routes!
+Any Greenwood [supported frontmatter](/docs/content-as-data/frontmatter/) can be returned here, including the [collection key](/docs/content-as-data/collections/). _This is only run once when the server is started_ to populate pages metadata, which is helpful if you want your dynamic route to show up in a collection with other static pages. You can even define a `layout` and reuse all your existing [layouts](/docs/pages/layouts/), even for server routes!
 
 <!-- prettier-ignore-start -->
 

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
 ---
 

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.                |

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
 ---