Skip to content

Commit 0615084

Browse files
thescientist13thescientist13
authored
docs: #229 standalone markdown plugin (#242)
1 parent 4fd081d commit 0615084

File tree

19 files changed

+384
-242
lines changed

19 files changed

+384
-242
lines changed

‎netlify.toml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,9 @@
1616
[[redirects]]
1717
status = 301
1818
from = "/docs/plugins/typescript/"
19-
to = "/docs/resources/typescript/"
19+
to = "/docs/resources/typescript/"
20+
21+
[[redirects]]
22+
status = 301
23+
from = "/docs/resources/markdown/"
24+
to = "/docs/plugins/markdown/"

‎src/pages/docs/content-as-data/active-frontmatter.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
layout: docs
3-
order: 4
3+
order: 5
44
tocHeading: 2
55
---
66

77
# Active Frontmatter
88

9-
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.
9+
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.
1010

1111
Really useful for passing page content or collections as attributes to a custom element.
1212

‎src/pages/docs/content-as-data/collections.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ tocHeading: 2
66

77
# Collections
88

9-
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.
9+
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.
1010

1111
See our [reference docs on Greenwood's available types](/docs/reference/appendix/#types) for more information on authoring with TypeScript.
1212

‎src/pages/docs/content-as-data/frontmatter.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
layout: docs
3+
order: 4
4+
tocHeading: 2
5+
---
6+
7+
# Frontmatter
8+
9+
[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.
10+
11+
Greenwood defines the following properties that you can use in HTML or [markdown](/docs/plugins/markdown/) out of the box:
12+
13+
- Label
14+
- Title
15+
- Layout
16+
- Imports
17+
- Custom Data
18+
19+
## Label
20+
21+
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.
22+
23+
<!-- prettier-ignore-start -->
24+
25+
<app-ctc-block variant="snippet">
26+
27+
```md
28+
---
29+
label: "My Blog Post from 3/5/2020"
30+
---
31+
32+
# My Blog Post
33+
```
34+
35+
</app-ctc-block>
36+
37+
<!-- prettier-ignore-end -->
38+
39+
## Title
40+
41+
To set the `<title>` for a given page, you can customize the **title** variable. Otherwise, the `<title>` will be inferred from the file name.
42+
43+
<!-- prettier-ignore-start -->
44+
45+
<app-ctc-block variant="snippet">
46+
47+
```md
48+
---
49+
title: My Blog Post
50+
---
51+
52+
# This is a post
53+
54+
The is a markdown file with the title defined in frontmatter.
55+
```
56+
57+
</app-ctc-block>
58+
59+
<!-- prettier-ignore-end -->
60+
61+
In this example, the `<title>` tag will be the value of **title**.
62+
63+
```html
64+
<title>My Blog Post</title>
65+
```
66+
67+
## Layouts
68+
69+
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.
70+
71+
<!-- prettier-ignore-start -->
72+
73+
<app-ctc-block variant="snippet">
74+
75+
```md
76+
---
77+
layout: blog
78+
---
79+
80+
# My First Blog Post
81+
82+
This is my first blog post, I hope you like it!
83+
```
84+
85+
</app-ctc-block>
86+
87+
<!-- prettier-ignore-end -->
88+
89+
In this example, _src/layouts/blog.html_ will be used to wrap the content of this markdown page.
90+
91+
> **Note:** By default, Greenwood will look for and use _src/layouts/page.html_ for all pages by default.
92+
93+
## Imports
94+
95+
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.
96+
97+
<!-- prettier-ignore-start -->
98+
99+
<app-ctc-block variant="snippet">
100+
101+
```md
102+
---
103+
imports:
104+
- /components/my-component/component.js type="module" foo="bar"
105+
- /components/my-component/component.css
106+
---
107+
108+
# My Demo Page
109+
```
110+
111+
</app-ctc-block>
112+
113+
<!-- prettier-ignore-end -->
114+
115+
You will then see the following emitted for file
116+
117+
```html
118+
<script type="module" src="/components/my-component/component.js" type="module" foo="bar"></script>
119+
<link rel="stylesheet" href="/components/my-component/component.css" />
120+
```
121+
122+
## Custom Data
123+
124+
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/).
125+
126+
<!-- prettier-ignore-start -->
127+
128+
<app-ctc-block variant="snippet">
129+
130+
```md
131+
---
132+
author: Jon Doe
133+
date: 04/07/2020
134+
---
135+
136+
# First Post
137+
138+
My first post
139+
```
140+
141+
</app-ctc-block>
142+
143+
<!-- prettier-ignore-end -->

‎src/pages/docs/content-as-data/graph-ql.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: GraphQL
33
label: GraphQL
44
layout: docs
5-
order: 5
5+
order: 6
66
tocHeading: 2
77
---
88

‎src/pages/docs/content-as-data/pages-data.md‎

Lines changed: 0 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -54,66 +54,6 @@ This is the data you would get back:
5454
}
5555
```
5656

57-
## Table of Contents
58-
59-
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.
60-
61-
Taking our previous example, if we were to configure this for `<h2>` tags:
62-
63-
<!-- prettier-ignore-start -->
64-
65-
<app-ctc-block variant="snippet" heading="src/pages/blog/first-post.md">
66-
67-
```md
68-
---
69-
author: Project Evergreen
70-
published: 2024-01-01
71-
tocHeading: 2
72-
---
73-
74-
# First Post
75-
76-
This is my first post.
77-
78-
## Overview
79-
80-
Lorum Ipsum
81-
82-
## First Point
83-
84-
Something something...
85-
```
86-
87-
</app-ctc-block>
88-
89-
<!-- prettier-ignore-end -->
90-
91-
We would get this additional content as data out:
92-
93-
```json
94-
{
95-
"id": "blog-first-post",
96-
"title": "First Post",
97-
"label": "First Post",
98-
"route": "/blog/first-post/",
99-
"data": {
100-
"author": "Project Evergreen",
101-
"published": "2024-01-01",
102-
"tocHeading": 2,
103-
"tableOfContents": [
104-
{
105-
"content": "Overview",
106-
"slug": "overview"
107-
},
108-
{
109-
"content": "First Point",
110-
"slug": "first-point"
111-
}
112-
]
113-
}
114-
}
115-
```
116-
11757
## External Content
11858

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

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ tocHeading: 2
99
Greenwood defines two types of layouts that can be used to wrap your pages with common HTML
1010

1111
- _App Layout_: The ["app shell"](https://developers.google.com/web/fundamentals/architecture/app-shell) that will wrap all pages.
12-
- _Page Layouts_: Layouts that can be re-used across multiple pages and defined using [frontmatter](/docs/resources/markdown/#frontmatter).
12+
- _Page Layouts_: Layouts that can be re-used across multiple pages and defined using [**frontmatter**](/docs/content-as-data/frontmatter/)
1313

1414
Greenwood will handle merging the `<body>` and `<head>` tag contents when building up your pages and layouts.
1515

@@ -74,7 +74,7 @@ You can create more layouts and use them for pages with the following steps:
7474
layout: blog
7575
---
7676

77-
## My First Post
77+
# My First Post
7878

7979
Lorum Ipsum
8080
```
@@ -83,6 +83,29 @@ You can create more layouts and use them for pages with the following steps:
8383

8484
<!-- prettier-ignore-end -->
8585

86+
Frontmatter is also supported for HTML files:
87+
88+
<!-- prettier-ignore-start -->
89+
90+
<app-ctc-block variant="snippet">
91+
92+
```html
93+
---
94+
layout: blog
95+
---
96+
97+
<html>
98+
<body>
99+
<h1>My First Post</h1>
100+
<p>Lorum Ipsum</p>
101+
</body>
102+
<html>
103+
```
104+
105+
</app-ctc-block>
106+
107+
<!-- prettier-ignore-end -->
108+
86109
## App Layout
87110

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Greenwood supports file-based routing, which means that filenames in the _pages/
1010

1111
## Static Pages
1212

13-
For static content, Greenwood support HTML and [markdown](/docs/resources/markdown/) as page formats.
13+
For static content, Greenwood supports HTML and markdown [(with a plugin)](/docs/plugins/markdown/) as page formats.
1414

1515
For example, given the following folder structure:
1616

‎src/pages/docs/pages/server-rendering.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@ The above would serve content in a browser at the path _/users/_.
2222

2323
## Usage
2424

25-
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.
25+
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.
2626

2727
- **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`_.
2828
- **getBody**: Return a string of HTML for the contents of the page
2929
- **getLayout**: Return a string of HTML to act as the [page's layout](/docs/pages/layouts/#pages)
30-
- **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.
30+
- **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.
3131

3232
<!-- eslint-disable no-unused-vars -->
3333

@@ -198,7 +198,7 @@ You can pull in data from Greenwood's [compilation](/docs/reference/appendix/#co
198198
199199
### Frontmatter
200200

201-
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!
201+
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!
202202

203203
<!-- prettier-ignore-start -->
204204

‎src/pages/docs/plugins/css-modules.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: CSS Modules
33
label: CSS Modules
44
layout: docs
5-
order: 2
5+
order: 3
66
tocHeading: 2
77
---
88

0 commit comments

Comments
 (0)