From 39b0d2c5fe900b8a19fcd7adee2a8b4f209ae334 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Tue, 22 Dec 2020 12:28:42 -0500 Subject: [PATCH 1/9] WIP updating docs section of pages --- packages/cli/src/lifecycles/config.js | 2 +- www/package.json | 2 +- www/pages/docs/build.md | 3 + www/pages/docs/component-model.md | 93 +++++++++++++++------------ www/pages/docs/configuration.md | 34 ++++++---- www/pages/docs/front-matter.md | 5 +- www/pages/docs/index.md | 50 +++++++++----- www/pages/docs/markdown.md | 83 ++++++++++++++++-------- www/styles/page.css | 1 - 9 files changed, 169 insertions(+), 104 deletions(-) diff --git a/packages/cli/src/lifecycles/config.js b/packages/cli/src/lifecycles/config.js index 806ffbe72..e3173b6a0 100644 --- a/packages/cli/src/lifecycles/config.js +++ b/packages/cli/src/lifecycles/config.js @@ -11,7 +11,7 @@ let defaultConfig = { host: 'localhost' }, // TODO optimization: 'spa', - publicPath: '/', + publicPath: '/', // TODO title: 'My App', meta: [], plugins: [], diff --git a/www/package.json b/www/package.json index 2384c7233..ce779787d 100644 --- a/www/package.json +++ b/www/package.json @@ -1,6 +1,6 @@ { "name": "@greenwood/www", - "version": "0.10.0-alpha.0", + "version": "0.10.0-alpha.1", "private": true, "description": "Greenwood website workspace.", "repository": "https://github.com/ProjectEvergreen/greenwood", diff --git a/www/pages/docs/build.md b/www/pages/docs/build.md index 84f2d3725..931d4ed4f 100644 --- a/www/pages/docs/build.md +++ b/www/pages/docs/build.md @@ -7,7 +7,9 @@ linkheadings: 3 --- # Build Configurations +> β›” [_**Coming Soon!**_](https://github.com/ProjectEvergreen/greenwood/issues/426) + \ No newline at end of file diff --git a/www/pages/docs/component-model.md b/www/pages/docs/component-model.md index c0732d3d2..c4215fa23 100644 --- a/www/pages/docs/component-model.md +++ b/www/pages/docs/component-model.md @@ -6,11 +6,21 @@ index: 1 --- ## Component Model -In this section we'll review a little bit about how you can use Web Components in Greenwood. Both the native `HTMLElement` and `LitElement` are available by default. +Greenwood aims to support and optimize around the standard capabilities of the web platform and its features. In particular, the concept of using Web Components as a way to add interactivity and dynamic content into your application and... that can all be prerendered for you, just like you could do with any server side templating language. -### HTMLElement +The options for how to design your app efficetively come down to what you're trying to build, so if that's with the native `HTMLElement` or something based on it like **LitElement** (installed seperately), **Greenwood** will take care of the rest. -_footer.js_ +Below are a couple examples to get you going. + +> _Check out our [README](https://github.com/ProjectEvergreen/greenwood#built-with-greenwood) for more examples of sites built with **Greenwood** to see what's possible._ + +## Example + +Below is an example of creating a footer component using native `HTMLElement` within a page template of a Greenwood project. This is all just normal HTML / CSS / JS. + +### Component + +Our component, in a file called _src/components/footer.js_ could look like this ```js class FooterComponent extends HTMLElement { @@ -26,81 +36,80 @@ class FooterComponent extends HTMLElement { this.root.innerHTML = this.getTemplate(); } - // create templates that interpolate variables and HTML! + // function can be called anything you want + // return a string to be set to innerHTML, can include variable interpolation! getTemplate() { const year = new Date().getFullYear(); - return \`
This is the header component. © \${year}
\`; + return ``; } } -customElements.define('x-footer', FooterComponent); +customElements.define('my-footer', FooterComponent); ``` -You can then import it in a template and use it within your templates `render` function. +> _You can use anything you want for the element's tag name (e.g. `app-footer`, `x-footer`, etc), it just needs to have a `-` in the name_. -```javascript -import { html, LitElement } from 'lit-element'; -import '../components/footer'; +### Usage -class PageTemplate extends LitElement { +You can then use it within a page template. - constructor() { - super(); - } +```html + + - render() { - return html\` -
- -
- -
-
- \`; - } -} + + + -customElements.define('page-template', PageTemplate); + + + + + ``` -### LitElement -A simple example of a web component utilizing a basic [LitElement](https://lit-element.polymer-project.org/) base class +### Alternaties +An alternaative like [**LitElement**](https://lit-element.polymer-project.org/) would work the same way. -_hello-world.js_ +> _Make sure you have installed LitElement with **npm** first!_ + +_src/components/greeting.js_ ```javascript import { html, LitElement } from 'lit-element'; -class HelloWorld extends LitElement { +class GreetingComponent extends LitElement { constructor() { super(); } render() { - return html\` + return html`

Hello World!

- \`; + `; } } -customElements.define('hello-world', HelloWorld); +customElements.define('x-greeting', GreetingComponent); ``` -Which can then imported and used with +```html + + -```javascript -import './hello-world.js' + + + -render() { - return html\` - - \` -} + + + + + ``` ## References diff --git a/www/pages/docs/configuration.md b/www/pages/docs/configuration.md index 8abb173da..1e9c0b2af 100644 --- a/www/pages/docs/configuration.md +++ b/www/pages/docs/configuration.md @@ -9,7 +9,7 @@ linkheadings: 3 ## Configuration These are all the supported configuration options in Greenwood, which you can define in a _greenwood.config.js_ file in your project's root directory. -A **greenwood.config.js** file with default values would be: +A **greenwood.config.js** file reflecting default values would be: ```js module.exports = { workspace: 'src', // path.join(process.cwd(), 'src') @@ -18,7 +18,7 @@ module.exports = { host: 'localhost' }, publicPath: '/', - title: 'Greenwood App', + title: 'My App', meta: [] }; ``` @@ -39,11 +39,10 @@ module.exports = { ``` ### Markdown -Using your `greenwood.config.js`, within your project's root directory, you can add additional [unifiedjs presets](https://github.com/unifiedjs/unified#preset) and settings to the [wc-markdown-loader](https://github.com/hutchgrant/wc-markdown-loader/blob/master/src/parser.js#L30). +You can provide custom **unifiedjs** [presets](https://github.com/unifiedjs/unified#preset) and [plugins](https://github.com/unifiedjs/unified#plugin) to further custonmize and process your markdown past what [Greenwood does by default](https://github.com/ProjectEvergreen/greenwood/blob/release/0.10.0/packages/cli/src/transforms/transform.md.js#L68). #### Example -*greenwood.config.js* ```js module.exports = { markdown: { @@ -56,14 +55,11 @@ module.exports = { } ``` -Keep in mind, the point in the chain in which [these configured presets will be inserted](https://github.com/hutchgrant/wc-markdown-loader/blob/master/src/parser.js#L30) is in rehype and ends with converting rehype to html. - - ### Meta You can use the `meta` option for the configuration of [`` tags](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML) within the `` tag of the generated _index.html_ file. This is especially useful for providing text and images for social sharing and link previews like for Slack, text messages, and social media shares, in particular when using the [Open Graph](https://ogp.me/) set of tags. #### Example -This is an example of the `meta` configuration for the Greenwood website. +This is an example of the `meta` configuration for the [Greenwood website](https://github.com/ProjectEvergreen/greenwood/blob/master/greenwood.config.js). ```js const FAVICON_HREF = '/assets/favicon.ico'; @@ -99,7 +95,9 @@ Which would be equivalent to: ``` ### Optimization -Greenwood supports a couple different options for how it will generate a production build, depending on how much JavaScript you will need to serve your users. +> β›” [_**Coming Soon!**_](https://github.com/ProjectEvergreen/greenwood/issues/354) + + ### Public Path -The `publicPath` options allows configuring additional URL segments to customize the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) for your site. + +> β›” _**Coming Soon!**_ + + ### Title -A `` element for all pages can be configured with the `title` option. +A default `<title>` element for all pages can be configured with the `title` option. #### Example An example of configuring your app's title: @@ -140,13 +143,16 @@ module.exports = { ``` ### Workspace -Workspace path for your project where all your project files will be located. You can change it by passing a string. Using an absolute path is recommended. +Path to where all your project files will be located. Using an absolute path is recommended. #### Example + +Setting the workspace path to be the _www/_ folder in the current directory from where Greenwood is being run. + ```js const path = require('path'); module.exports = { - workspace: path.join(__dirname, 'www'), + workspace: path.join(process.cwd(), 'www') } ``` \ No newline at end of file diff --git a/www/pages/docs/front-matter.md b/www/pages/docs/front-matter.md index 22d86d937..3fce1344b 100644 --- a/www/pages/docs/front-matter.md +++ b/www/pages/docs/front-matter.md @@ -26,8 +26,9 @@ Which will compile to the element: `<wc-md-mypage></wc-md-mypage>` ### Imports +> β›” _**Coming Soon!**_ -If you want to import custom files such as a custom element, you can use the predefined variable `imports`. +<!-- If you want to include files on a _per **page** basis_, you can use the predefined `imports` feature from Greenwood. This is great for one off use cases where you dont want to ship a third party lib in all your templates, but just for this one particular page. This is effectively a naive form of code splitting. πŸ€“ #### Example ```md @@ -38,7 +39,7 @@ imports: ``` -See our [Markdown Docs](/docs/markdown#imports) for more information about rendering custom elements in markdown files. +See our [Markdown Docs](/docs/markdown#imports) for more information about rendering custom elements in markdown files. --> ### Template diff --git a/www/pages/docs/index.md b/www/pages/docs/index.md index 04a6a45c9..00f361515 100644 --- a/www/pages/docs/index.md +++ b/www/pages/docs/index.md @@ -21,36 +21,56 @@ $ yarn add @greeenwood/cli --dev ``` Though we recommend installing it locally to your project, you can also run Greenwood globally. For global usage we recommend using `npx` + ```bash -$ npx @greenwood/cli <build> +$ npx @greenwood/cli <command> ``` ### CLI -With Greenwood installed, you can run its CLI to generate your site. The commands available are: -- `develop`: Develop your project with a local development server. -- `build`: For generating a production ready static site. +With Greenwood installed, you can run its CLI to generate your site. The principal commands available are: +- `greenwood develop`: Starts a local development server for your project. +- `greenwood build`: Generates a production build of your project. +- `greenwood serve`: Generates a production build of the project and serves it locally on a simple web server. +- `greenwood eject`: Ejects configurations (Rollup, PostCSS, etc) to your working directory for additional customizations. -As mentioned above, it is recommended to install Greenwood locally into your project. From there, you can define npm scripts in _package.json_ like so: +You can define npm scripts in _package.json_ like so to automate your workflows: ```json -"scripts": { - "build": "greenwood build", - "start": "greenwood develop", - "serve": "greenwood serve" +{ + + "scripts": { + "build": "greenwood build", + "start": "greenwood develop", + "serve": "greenwood serve" + } + } ``` -Then you can run: -- `greenwood build`: Generates a production build of your project -- `greenwood develop`: Starts a local development server for your project -- `greenwood serve`: Generates a production build of the project and serves it locally on a simple web server. -- `greenwood eject`: Ejects configurations to your working directory for additional customizations. +Then from the command line you can use npm or Yarn to run them: + +```bash + # start up the dev server +$ npm start +$ yarn start + +# generate a static build to deploy +$ npm run build +$ yarn build + +# generate a static build and preview it locally +$ npm run serve +$ yarn serve +``` ### Sections + +To continue learning more abuut Greenwood, please feel free to browse the other sections of our documentation. + - [Component Model](/docs/component-model/): Examples of using custom elements in Greenwood. - [Configuration](/docs/configuration/): Available configuration options for the Greenwood CLI. - [Front Matter](/docs/front-matter/): Page level configurations through page markdown. - [Markdown](/docs/markdown/): Using markdown and related authoring capabilities supported by Greenwood. - [Styles and Assets](/docs/css-and-images/): How to style and theme your project with CSS. - [Templates](/docs/layouts/): Controlling the layout of your pages. -- [Tech Stack](/docs/tech-stack/): What's under the hood. +- [Tech Stack](/docs/tech-stack/): What's under the hood. \ No newline at end of file diff --git a/www/pages/docs/markdown.md b/www/pages/docs/markdown.md index a29540678..b5f81f715 100644 --- a/www/pages/docs/markdown.md +++ b/www/pages/docs/markdown.md @@ -7,35 +7,11 @@ linkheadings: 3 --- ## Markdown -In this section we'll cover some of the Markdown related feature of Greenwood, which by default supports the [CommonMark](https://commonmark.org/help/) specification. - -### Syntax Highlighting -When rendering code fencing, if you add the language after the fencing, the included [prismjs](https://prismjs.com/) library will add syntax highlighting. - -e.g. use: - -````js -\`\`\`js -const hello = "world"; - -<p>\${hello}</p> -\`\`\` -```` - -To get the result: - -```js -const hello = "world"; - -<p>\${hello}</p> -``` - -> **Note:** As demonstrated in the above example, backticks and `\$` characters require `\\` to escape correctly. - -> See our [website theme](https://github.com/ProjectEvergreen/greenwood/blob/master/www/styles/page.css#L1) for more examples on how to style PrismJS. - +In this section we'll cover some of the Markdown related feature of **Greenwood**, which by default supports the [CommonMark](https://commonmark.org/help/) specification and [**unifiedjs**](https://unifiedjs.com/) as the markdown / content framework. ### Imports +> β›” _**Coming Soon!**_ +<!-- From within the markdown you can also render components, not just their syntax, by importing them via [front-matter](/docs/front-matter). #### Example @@ -52,5 +28,56 @@ imports: > See our [component model docs](/docs/component-model) for more information on authoring custom elements / components. For information on configuring additional page meta data, see our section on [front-matter](/docs/front-matter/). +--> + ### Configuration -Using your `greenwood.config.js`, within your project's root directory, you can have additional [markdown customizations and configurations](/docs/configuration#markdown) using unified presets. \ No newline at end of file +Using your _greenwood.config.js_ you can have additional [markdown customizations and configurations](/docs/configuration#markdown) using unified presets and plugins. + +For example, to add support for [**Prism**](https://prismjs.com/) for syntax highlighting, after installing `@mapbox/rehype-prism` via **npm**, just add following to your config file: + +```js +module.exports = { + + ... + + markdown: { + settings: { /* whatever you need */ }, + plugins: [ + '@mapbox/rehype-prism' + ] + } + +}; +``` + +### Syntax Highlighting + +Although Greenwood does not provide any syntax highlighting by default, as demonstrated in the section above, it easy to add Prism markdown processing to your project. + + +From there, just include a theme from a CSS file in your project, ex: + +```css +/* https://prismjs.com/examples.html */ +@import url('../../node_modules/prismjs/themes/prism-tomorrow.css'); +``` + +Then if you add the language after the fencing **prismjs** will add syntax highlighting to your code fences. + +Write the following in your markdown + +````js +```js +const hello = 'world'; + +<p>${hello}</p> +``` +```` + +To get the result: + +```js +const hello = 'world'; + +<p>${hello}</p> +``` \ No newline at end of file diff --git a/www/styles/page.css b/www/styles/page.css index faf0fb2ff..4185889dd 100644 --- a/www/styles/page.css +++ b/www/styles/page.css @@ -1,5 +1,4 @@ /* TODO restore to nested styles */ -/* TODO handle prismjs */ /* https://prismjs.com/examples.html */ @import url('../../node_modules/prismjs/themes/prism-tomorrow.css'); From 904ea5401646b773648925ab253272643cb771c6 Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 22 Dec 2020 14:46:58 -0500 Subject: [PATCH 2/9] all docs updated first draft --- packages/cli/src/commands/develop.js | 2 +- www/pages/docs/css-and-images.md | 161 +++++++++------------------ www/pages/docs/data.md | 7 +- www/pages/docs/layouts.md | 142 +++++++++++++++-------- www/pages/docs/menus.md | 5 + www/pages/docs/tech-stack.md | 22 ++-- 6 files changed, 171 insertions(+), 168 deletions(-) diff --git a/packages/cli/src/commands/develop.js b/packages/cli/src/commands/develop.js index fdb1b920e..4f8006f28 100644 --- a/packages/cli/src/commands/develop.js +++ b/packages/cli/src/commands/develop.js @@ -12,7 +12,7 @@ module.exports = runDevServer = async () => { const { userWorkspace } = compilation.context; devServer(compilation).listen(port, () => { - console.info(`Started local development at localhost:${port}`); + console.info(`Started local development server at localhost:${port}`); const liveReloadServer = livereload.createServer({ exts: ['html', 'css', 'js', 'md'], applyCSSLive: false // https://github.com/napcs/node-livereload/issues/33#issuecomment-693707006 diff --git a/www/pages/docs/css-and-images.md b/www/pages/docs/css-and-images.md index 8b005e1d5..11514eb32 100644 --- a/www/pages/docs/css-and-images.md +++ b/www/pages/docs/css-and-images.md @@ -7,95 +7,41 @@ linkheadings: 3 --- ## Styles and Assets -Greenwood provides a couple ways to help style and theme your site. +**Greenwood** generally does not have any opinion on how you structure your site, aside from the pre-determined _pages/_ and (optional) _templates/_ directories. It supports all standard files that you can open in a web browser. -By default Greenwood supports directory detection for the following folder names within your workspace -- _src/assets_ - Location for all your site images, fonts, JSON, etc and will be bundled automatically for you by Greenwood. -- _src/styles_ - Recommended location for your template and theme CSS files -> Be aware of the [limitations of the Shadow DOM](https://css-tricks.com/web-standards-meet-user-land-using-css-in-js-to-style-custom-elements/) with regard to which styles you can expect to apply globally vs. within a Shadow DOM. +### Styles +Styles can be done in any standards compliant way that will work in a browser. So just as in HTML, you can do anything you need like below: +```html +<!DOCTYPE html> +<html lang="en" prefix="og:http://ogp.me/ns#"> -### Theming -To enable theming through global styles, create a file in your workspace styles directory called _theme.css_, e.g. _src/styles/theme.css_ and import it into your page templates. Greenwood will include this in a `<style>` tag in the `<head>` of the generated pages. + <head> + <style> + html { + background-color: white; + } + body { + font-family: 'Source Sans Pro', sans-serif; + line-height:1.4; + } + </style> -#### Example -The below is an example of using _theme.css_ to load a Google font and apply a global browser reset for all pages. -```css -/* theme.css */ -@import url('//fonts.googleapis.com/css?family=Source+Sans+Pro&display=swap'); - -* { - margin: 0; - padding: 0; - font-family: 'Source Sans Pro', sans-serif; -} -``` - -```javascript -// page-template.js -import { html, LitElement } from 'lit-element'; -import '../styles/theme.css'; - -class PageTemplate extends LitElement { - - constructor() { - super(); - } - - ... + <link rel="stylesheet" href="/styles/some-page.css"/> + </head> -} - -customElements.define('page-template', PageTemplate); + <body> + <!-- content goes here --> + </body> + +</html> ``` -### Shadow DOM -For any of your components and page templates, it is recommended to use the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) within your LitElement's `render` function. You can also import the CSS too. - -#### Example - -```javascript -import { html, LitElement } from 'lit-element'; -import pageTemplateCss '../styles/page-template.css'; // if you like your CSS-in-JS - -class PageTemplate extends LitElement { - - constructor() { - super(); - } +### Assets - render() { - return html\` - - <style> - ${pageTemplateCss} - </style> - - <style> - :host { - h1 { - color: blue; - border: 1px solid #020202; - } - } - </style> - - <div> - - <entry></entry> - - </div> - \`; - } -} - -customElements.define('page-template', PageTemplate); -``` - -### Assets and Images -They say a picture is worth 1000 words, so by default Greenwood will look for an _assets/_ folder in your workspace and automatically copy / bundle whatever it sees there. +For convenience, **Greenwood** does support an "assets" directory wherein anything copied into that will be present in the build output directory. This is the recommended location for all your local images, fonts, etc. Effectively anything that is not part of an `import`, `@import`, `<script>`, `<style>` or `<link>` will not be handled by **Greenwood**. #### Example To use an image in a markdown file, you would reference it as so using standard markdown syntax: @@ -106,31 +52,32 @@ To use an image in a markdown file, you would reference it as so using standard ![my-image](/assets/images/my-image.png) ``` -If you like your all-the-things-in-JS, you can also use `import` in a custom element. - -```javascript -import { html, LitElement } from 'lit-element'; -import logo from '../../assets/images/logo.png'; - -class HeaderComponent extends LitElement { - render() { - return html\` - <style> - img { - border-radius: 0 !important; - min-height: 233px; - max-height: 233px; - object-fit: cover; - } - </style> - - <header> - <h1>Welcome!</h1> - <img alt="brand logo" src="\${logo}" /> - </header> - \`; - } -} - -customElements.define('x-header', HeaderComponent); -``` \ No newline at end of file +You can do the same in your HTML + +```html +<header> + <h1>Welcome to My Site!</h1> + <img alt="logo" src="/assets/images/logo.png" /> +</header> +``` + + +> If you like your all-the-things-in-JS approach, Greenwood can be extended with [plugins](/plugins/) to support "webpack" like behavior as seeb in the below example: +> +> ```javascript +> import { html, LitElement } from 'lit-element'; +> import logo from '../../assets/images/logo.png'; +> +> class HeaderComponent extends LitElement { +> render() { +> return html` +> <header> +> <h1>Welcome to My Site!</h1> +> <img alt="brand logo" src="${logo}" /> +> </header> +> `; +> } +> } +> +> customElements.define('x-header', HeaderComponent); +> ``` \ No newline at end of file diff --git a/www/pages/docs/data.md b/www/pages/docs/data.md index f34608ab7..1911c7d29 100644 --- a/www/pages/docs/data.md +++ b/www/pages/docs/data.md @@ -9,6 +9,9 @@ linkheadings: 3 ## Data Sources +> β›” [_**Coming Soon!**_](https://github.com/ProjectEvergreen/greenwood/issues/278) + +<!-- ### Overview Having to repeat things when programming is no fun, and that's why (web) component based development is so useful! As websites start to grow, there comes a point where being able to have access to the content and structure of your site's layout and configuration as part of the development process becomes essential towards maintainability, performance, and scalability. @@ -355,4 +358,6 @@ customElements.define('app-header', HeaderComponent); ``` ### External Sources -Coming [soon](https://github.com/ProjectEvergreen/greenwood/issues/21)! \ No newline at end of file +Coming [soon](https://github.com/ProjectEvergreen/greenwood/issues/21)! + +--> \ No newline at end of file diff --git a/www/pages/docs/layouts.md b/www/pages/docs/layouts.md index 0888c59f9..40a48b327 100644 --- a/www/pages/docs/layouts.md +++ b/www/pages/docs/layouts.md @@ -6,74 +6,101 @@ index: 6 linkheadings: 3 --- -## Templates -Greenwood has two types of templates: -- App Template: The [app shell](https://developers.google.com/web/fundamentals/architecture/app-shell) if you will, that wraps all pages. This is provided for you by Greenwood, but you can override if needed. (though not recommended) -- Page Template:. Nested within the app template, and how you define different pages / layouts for your site. Common layouts would be used for a home page, documentation pages, blog posts, etc. +## Templates and Pages +Greenwood has two types of templates to help Γ₯layout your pages: -### Page Template -In order to make a page template, you need to create a `LitElement` based custom element that contains a predefined `<entry></entry>` element. The `<entry></entry>` element is where your markdown page content will be placed once compiled. You need to do this in a file within your _templates/_ directory named _<type>-template.js_. +- _App Template_: The ["app shell"](https://developers.google.com/web/fundamentals/architecture/app-shell) if you will, that would wrap all pages. One is provided for you by Greenwood, but you can override it if needed. +- _Page Templates_: A template for each unique page layout within your site. Common layouts are great for documentation and blog sites, but also great for single pages as well (like a splash layout for the home page). -Here is an example `page-template.js` (the [default](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/templates/page-template.js) one included with Greenwood which is the default page-template.js if no other is defined). You can just copy / paste this to start your own page template. +> _**Note**: [For now](https://github.com/ProjectEvergreen/greenwood/issues/435), all paths in template files need to start with a `/` and omit the workspace directory._ -```js -import { html, LitElement } from 'lit-element'; +### Page Templates +Pages in your project will generally want a template so you can control the output of the HTML and include all your own custom components and styles. By default alll pages will default to looking for a _page.html_ in _templates/ directory within your workspace. -class PageTemplate extends LitElement { - render() { - return html\` - <div class='gwd-wrapper'> - <div class='gwd-page-template gwd-content'> - <entry></entry> - </div> - </div> - \`; - } -} -customElements.define('page-template', PageTemplate); +In order to make a page template, you just need to write up some HTML that can be enhanced with these special custom elements: +- Include `<content-outlet></content-outlet>` to position where the processed markdown from the page will appear +- Include `<meta-outlet></meta-outlet>` to position where `<meta>` tags should go + + +Below is an example of a simple _page.html_. You can just copy / paste this to start your own page templates and by default all your pages will start rendering using this layout. + +```html +<!DOCTYPE html> +<html lang="en" prefix="og:http://ogp.me/ns#"> + + <head> + <meta-outlet></meta-outlet> + </head> + + <body> + <header> + <h1>Welcome to my site!</h1> + </header> + + <content-outlet></content-outlet> + + </body> + +</html> ``` -> **Note**: the filename must be in the format `<label>-template.js` and the `customElements` name must be `page-template`. +You can create more templates and use them for pages by doing two things: +1. Create a new template, e.g. _templates/blog-post.html_ +1. In your frontmatter, specify to use that template + ```md + --- + template: 'blog-post' + --- + + ## My blog Post + Lorum Ipsum + ``` -With a completed page-template.js present in your `src/templates/` folder you can define which page uses it via front-matter at the top of any markdown file. See [Front Matter Docs](/docs/front-matter#define-template) for more information. Simply including a file named `page-template.js` will overwrite the greenwood default template for all markdown files, without needing to declare the template at the top of markdown file. +> _See our [Front Matter Docs](/docs/front-matter#define-template) for more information._ ### App Template -In order to make an app template, you need to create a `LitElement` component that contains a predefined hook `MYROUTES` aswell the component element itself **must be defined as `eve-app`**. You need to do this in a file name and path _`<workspace>`/templates/app-template.js_. +If you want to customize the outer most wrapping layout of your site, in the _templates/_ directory you can do this by creating an _app.html_ file. Like a page template, this will just be another HTML document, with some additional capabilities: +- Include `<page-outlet></page-outlet>` to position where the content from the processed page template will appear +- Include `<meta-outlet></meta-outlet>` to position where `<meta>` tags goes. _Make sure not to include this in your page templates!_ + +As with page templates, app templates are just HTML. -First, we need our app template to use routes, by default greenwood uses [**lit-redux-router**](https://github.com/fernandopasik/lit-redux-router). To do this we define a `<routes></routes>` element in our app-template.js where our routes will be placed when compiled. +```html +<!DOCTYPE html> +<html lang="en" prefix="og:http://ogp.me/ns#"> -Here is an example app-template: + <head> + <meta-outlet></meta-outlet> + </head> -```js -import { html, LitElement } from 'lit-element'; + <body> + <header> + <h1>Welcome to My Site!</h1> + </header> + + <section> + <page-outlet></page-outlet> + </section> -// Add the <routes></routes> predefined hook. This is where all your routes will be loaded. -// You may also opt to define a custom 404 route here. -// You must define the app-template with the element name eve-app -class AppComponent extends LitElement { - render() { - return html\` - <routes></routes> - <lit-route><h1>404 Not found</h1></lit-route> - \`; - } -} + <footer> + <h1>© My Site</h1> + </footer> -customElements.define('eve-app', AppComponent); + </body> + +</html> ``` -* `app-template.js` requires `<routes></routes>` element to place routes -* `app-template.js` must have a component name `eve-app` -* `app-template.js` must maintain filename and path `<your-workspace>/templates/app-template.js` +> _When an app template is present, Greenwood will merge the `<head>` and `<body>` tags for both app and page templates into one HTML document structure for you._ -> A working example can be found in the [greenwood source](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/templates/app-template.js) which is the default _app-template.js_ if no other is defined. A production example can be found in [greenwood's website](https://github.com/ProjectEvergreen/greenwood/blob/master/www/templates/app-template.js). +> _**Tip:** If you use an _.html_ file instead of _.md_ for a page, you can use that as a page template override. (since there will be no frontmatter). This way you don't have to make a template for a one off page like a home page._ ### Pages -You can create all your pages in a _pages/_ directory in your projects workspace. You can also create nested pages and the page paths will map accordingly. +You can create all your pages in a _pages/_ directory in your project's workspace which will in turn map to the generated file output and routes of your site. For example, given this folder structure: ```shell @@ -83,11 +110,28 @@ For example, given this folder structure: β”œβ”€β”€ blog β”‚Β Β  β”œβ”€β”€ first-post.md β”‚Β Β  └── second-post.md - Β  └── index.md - + β”œβ”€β”€ about.md + Β  └── index.html ``` -You will have the following page URLs: +You will have the following page URLs accessible in the browser: - _/_ +- _/about/_ - _/blog/first-post/_ -- _/blog/second-post/_ \ No newline at end of file +- _/blog/second-post/_ + +And the following file output in the _public/_ directory +```shell +. +└── public + β”œβ”€β”€ blog + β”‚Β Β  β”œβ”€β”€ first-post + β”‚ β”‚Β  └── index.html + β”‚Β Β  └── second-post + β”‚ └── index.html + β”œβ”€β”€ about + β”‚Β  └── index.html + Β  └── index.html +``` + +> _See our [Front Matter Docs](/docs/front-matter#define-template) for more information on how you can extend fontmatter in **Greenwood**._ \ No newline at end of file diff --git a/www/pages/docs/menus.md b/www/pages/docs/menus.md index fea1bd614..6c6671d32 100644 --- a/www/pages/docs/menus.md +++ b/www/pages/docs/menus.md @@ -7,6 +7,10 @@ linkheadings: 3 --- ## Menus + +> β›” [_**Coming Soon!**_](https://github.com/ProjectEvergreen/greenwood/issues/278) + +<!-- In this section we'll touch on the menu related feature of Greenwood which utilizes [data sources](/docs/data) within a component to query for [front matter](/docs/front-matter) declared menus. ### Declare Menu @@ -288,3 +292,4 @@ The object result for `/about` is: } ``` +--> \ No newline at end of file diff --git a/www/pages/docs/tech-stack.md b/www/pages/docs/tech-stack.md index e9eff21d4..d18e5a1a0 100644 --- a/www/pages/docs/tech-stack.md +++ b/www/pages/docs/tech-stack.md @@ -8,22 +8,24 @@ linkheadings: 3 ## Tech Stack -Greenwood uses a variety of open source JavaScript tools to help faciliate development and production building of Greenwood projects. By putting all these tools together and configuring them for you, Greenwood helps you focus more on what matters; building your project. Greenwood takes are of performance and optimizations for you and provides a static build of your project that you can host on any web server or cloud host, be it Netlify, S3 / CloudFront, Express, Apache, etc. It's entirely up to you and what fits your workflow the best. +Greenwood uses a variety of open source JavaScript tools to help faciliate development and production building of Greenwood projects. By putting all these tools together and configuring them for you, Greenwood helps you focus more on what matters; building your project. Greenwood takes care of the performance and optimizations for you and provides static build output that you can host on any web server or cloud host, be it Netlify, S3 / CloudFront, Express, Apache, etc. It's entirely up to you and what fits your workflow the best. ### NodeJS -For development, Greenwood requires **NodeJS** (LTS) to be available on the command line. This allows us (and you!) to tap into all the amazing web development tools and libraries available on npm. +For development, Greenwood requires **NodeJS** (LTS) to be available on the command line. This allows us (and you!) to tap into all the amazing web development tools and libraries available on **npm** for your project. -To generate your site, we use [puppeteer](https://developers.google.com/web/tools/puppeteer/). +To pre-render a site, we use [puppeteer](https://developers.google.com/web/tools/puppeteer/). -### Web Components -In addition to the native **HTMLElement**, Greenwood provides [**LitElement**](https://lit-element.polymer-project.org/) out of the box. Although not tested, Greenwood should be compatible with just about any modern library on npm. +### Unified +For processing markdown, **Greenwood** taps into the unified ecosystem taking afvantage of and supporting tools like **remark** and **rehype** -To assist with development, Greenwood alos provides the following by default: -- [lit-redux-router](https://github.com/fernandopasik/lit-redux-router): Routing library -- [@evergreen-wc](https://github.com/hutchgrant/evergreen-web-components) Custom Elements component library +### Browsers + +Web standards like Web Components and ES Modules, coupled with network standards like HTTP caching, makes the browser a great platfoprm not only for the browsing experience, but also for the developer experience as well. Philosohies adopted by Greenwood like Bundleless development take full advantage of what the platform offers to enabled rapid development as well as ensure performant and optimized sites for users. + + +### Rollup +Greenwood makes use of [**Rollup**](https://rollupjs.org/) as part of build phase to optimize all the HTML / CSS and JavaScript for a given project. This affords **Greenwood** the ability to bundle, minify and otherwise prepare the site for final deployement. -### Webpack -Greenwood makes use of **webpack** for the local development workflow and building your application for production. This is done through a combination of tools like **Babel** and **PostCSS**, which helps ensure Greenwood can deliver a modern and performant site for you and your users. ### Development To assist in the project's development and maintenance, we also use these tools: From ae023549cb4c15a00462593a5496238df480c080 Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 22 Dec 2020 17:55:13 -0500 Subject: [PATCH 3/9] update getting started docs --- www/pages/getting-started/branding.md | 80 +++++++++-------- www/pages/getting-started/creating-content.md | 85 +++++++------------ www/pages/getting-started/index.md | 6 +- www/pages/getting-started/key-concepts.md | 57 +++++++------ www/pages/getting-started/project-setup.md | 20 ++--- 5 files changed, 115 insertions(+), 133 deletions(-) diff --git a/www/pages/getting-started/branding.md b/www/pages/getting-started/branding.md index 687c11b4c..4c1033cf1 100644 --- a/www/pages/getting-started/branding.md +++ b/www/pages/getting-started/branding.md @@ -34,54 +34,46 @@ class HeaderComponent extends HTMLElement { // create templates that interpolate variables and HTML! getTemplate() { - return \` + return ` <style> /* CSS will go here */ </style> <header>Welcome to my Blog!</header> - \`; + `; } } customElements.define('app-header', HeaderComponent); ``` -Now we can use it in both our templates, like so: -```javascript -import { html, LitElement } from 'lit-element'; -import '../components/header'; // import our custom element - -class PageTemplate extends LitElement { - - constructor() { - super(); - } +Now we can use it in both our templates by: +1. Referencing our component via a `<script>` tag with the `type="module"` attribute +1. Using our custom element's tag name of `<app-header>` in our `<body>` - render() { - return html\` - <div> - <!-- using our custom header --> - <app-header></app-header> +```html +<html> - <entry></entry> + <head> + <script type="module" src="/components/header.js"></script> + </head> + + <body> + <app-header></app-header> - <!-- you can add your custom footer here --> - </div> - \`; - } -} - -customElements.define('page-template', PageTemplate); + <content-outlet></content-outlet> + </body> + +</html> ``` -> You now do the same for your `<footer>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. +> You can now do the same for a `<footer>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. ### CSS OK, so we've made some content and some custom components, but what about the look and feel? Yes, of course, let's add some CSS! -For global styles like Google fonts, Bootstrap, background colors, or browser resets, create a file called _src/styles/theme.css_ and Greenwood will make sure these styles get applied in the `<head>` of the doucment, outside of any Shadow DOMs. +For global styles like Google fonts, Bootstrap, background colors, or browser resets, let's create a file called _src/styles/theme.css_ that we can reference in all templates. Here are some styles you can add to your site to snap things into place a little bit. ```css @@ -99,20 +91,25 @@ body { } ``` -Now we can `import` this CSS file into our templates. -```javascript -import { html, LitElement } from 'lit-element'; -import '../components/header'; -import '../styles/theme.css'; // add this line - -class PageTemplate extends LitElement { - - ... - -} +Now we can `<link>` this CSS file into our template. Easy! πŸ’₯ +```html +<html> + + <head> + <script type="module" src="/components/header.js"></script> + <link rel="stylesheet" href="/styles/theme.css"> + </head> + + <body> + <app-header></app-header> + + <content-outlet></content-outlet> + </body> + +</html> ``` -Within our components, we can easily add some styles right within the component definition itself. For example in our header component, we can style it like this and take advantage of the Shadow DOM. +Within our components, we can easily add some styles right within the component definition itself. For example in our header component, we can style it like this and take advantage of [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). ```javascript class HeaderComponent extends HTMLElement { @@ -127,14 +124,15 @@ class HeaderComponent extends HTMLElement { } getTemplate() { - return \` + return ` <style> header { color: blue; } </style> + <header>This is the header component.</header> - \`; + `; } } diff --git a/www/pages/getting-started/creating-content.md b/www/pages/getting-started/creating-content.md index 272edc8df..f74c42a3e 100644 --- a/www/pages/getting-started/creating-content.md +++ b/www/pages/getting-started/creating-content.md @@ -7,7 +7,7 @@ linkheadings: 3 --- ## Overview -After setting up our [project workspace](/getting-started/project-setup/) and reviewing some of Greenwood's [key concepts](/getting-started/key-concepts/), it's now time to get to the good stuff: writing some content and building your first site! +After setting up our [project workspace](/getting-started/project-setup/) and reviewing some of **Greenwood**'s [key concepts](/getting-started/key-concepts/), it's now time to get to the good stuff: writing some content and building your first site! ### Objectives In this section, we'll walk through developing a site with Greenwood, and making some content. We'll provide all the code, so you can just follow along. By the end, you'll have a simple blog starter that you can build and deploy to any web server you like, be it Netlify, Apache, Express, or S3. What you do from there, is all up to you! @@ -16,8 +16,8 @@ What we'll cover in this section: 1. Home Page Template: Single column layout for our home page 1. Blog Page Template: Two column layout for our blog posts -1. Blog Posts: A couple sample pages of content to get you going written in markdown -1. Using Greenwood's development server +1. Blog Posts: A couple sample pages of contentΓ₯ written in markdown +1. Using Greenwood's built in local development server To go along with this guide, check out our [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started) that has a working example of all the code covered in this Getting Started guide. In the end, what you will end up with is a project looking something like this: ``` shell @@ -36,8 +36,8 @@ To go along with this guide, check out our [companion repo](https://github.com/P β”œβ”€β”€ styles β”‚Β Β  └── theme.css └── templates - β”œβ”€β”€ blog-template.js - └── page-template.js + β”œβ”€β”€ blog.html + └── page.html ``` ### Home Page Template @@ -46,59 +46,36 @@ Out of the box, Greenwood provides some default content, so even if we use our n Neat! But naturally you're here to learn how to make your own site, and this is our goal! The first step towards making your site is to create a home page. For this site, the home page will be a "full width" page. -For this template, create a _page-template.js_ in a directory located at _src/templates/_ (make the _templates/_ directory if it doesn't exist) and include this code in it: -```javascript -import { html, LitElement } from 'lit-element'; +For this template, create a _page.html_ in a _src/templates/_ (make the _templates/_ directory if it doesn't exist) and include this code in it: -class PageTemplate extends LitElement { +```html +<html> - constructor() { - super(); - } - - render() { - return html\` - <div> - <entry></entry> - </div> - \`; - } -} - -customElements.define('page-template', PageTemplate); + <body> + <content-outlet></content-outlet> + </body> + +</html> ``` -> We'll use this and our blog post template momentarily. - ### Blog Posts Template -We just made a template for our home page, but for our blog posts, we're going to want a different layout for that. So what do we do? Just create a new template! - -Create a _blog-template.js_ in _src/templates/_ and include this code in it. -```javascript -import { html, LitElement } from 'lit-element'; +We just made a template for our home page, but for our indivdual blog posts, we're going to want a different layout for those pages. So what do we do? Just create a new template! -class BlogTemplate extends LitElement { +Create a _blog.html_ in _src/templates/_ and include this code in it. +```html +<html> - constructor() { - super(); - } - - render() { - return html\` - <div> - <entry></entry> - </div> - \`; - } -} - -customElements.define('page-template', BlogTemplate); + <body> + <content-outlet></content-outlet> + </body> + +</html> ``` -> **Note**: in both cases, our custom element name is `page-template`. +> _Right now both of these templates are the same, but we'll be customizing these both shortly._ πŸ‘‡ ### Creating Pages -To make our home page which will use the default _page-template.js_ layout we just created, create an _index.md_ file in the _src/pages/_ directory. +To make our home page which will use the default _page.html_ layout we just created, create an _index.md_ file in the _src/pages/_ directory. ```md ## Home Page @@ -106,14 +83,14 @@ To make our home page which will use the default _page-template.js_ layout we ju This is the Getting Started home page! ### My Posts -- [my-second-post](/blog/second-post/) -- [my-first-post](/blog/first-post/) +- [My Second Blog Post](/blog/second-post/) +- [My First Blog Post](/blog/first-post/) ``` -For your blog posts, we can give them their own unique URLs by simply putting them in their own directory and by default Greenwood will "slugify" based on that file path. +For these blog posts, we can give them their own unique URLs by simply putting them in their own directory and by default Greenwood will "slugify" based on that file path and generate routes / pages accordingly. -You'll want to create a folder called _blog/_ in _src/pages/_ (make that _pages/_ directory if it doesn't exist) and then create two markdown files called _first-post.md_ and _second-post.md_. +You'll want to create a folder called _blog/_ in _src/pages/_ and then create two markdown files called _first-post.md_ and _second-post.md_. _first-post.md_ ```md @@ -134,12 +111,12 @@ template: 'blog' --- ## My Second Blog Post -Lorem Ipsum +Sed ut perspiciatis [back](/) ``` -We are using something called ["front matter"](/docs/front-matter) to specify that these pages should use the _blog-template.js_ you just created. +We are using something called ["front matter"](/docs/front-matter) to specify that these pages should use the _blog_ template we just created. ### Development Server At this point we have two page templates and three pages of content, so let's fire up the Greenwood development server and see what things look like! @@ -154,4 +131,4 @@ Once the development server is ready, it will let you know that you can now open ![greenwood-getting-started-unstyled](https://s3.amazonaws.com/hosted.greenwoodjs.io/getting-started-repo-unstyled-partial.png) -Congrats, you've got your first Greenwood site running! It's coming along but still needs a little work. In the [next section](/getting-started/branding/) we'll create some reusable Web Components for the site's header and footer as well as some CSS for styling. \ No newline at end of file +Congrats, you've got your first **Greenwood** site running! It's coming along but still needs a little work. In the [next section](/getting-started/branding/) we'll create some reusable Web Components for the site's header and footer as well as introduce some CSS for styling. \ No newline at end of file diff --git a/www/pages/getting-started/index.md b/www/pages/getting-started/index.md index db45243b5..beeebf4bc 100644 --- a/www/pages/getting-started/index.md +++ b/www/pages/getting-started/index.md @@ -6,7 +6,7 @@ index: 3 --- ## Introduction -First off, thank you for taking the time to check out Greenwood! As a tool, we hope that you find Greenwood to provide a productive and frictionless developer experience for you that results in performant and engaging experiences for your users. Under the hood Greenwood is using NodeJS, webpack, babel and a lot of other amazing JavaScript tools to power a modern development workflow based on first class support for the modern web like Web Components, FlexBox, CSS Grid, ECMAScript modules, and all your favorite features! +First off, thank you for taking the time to check out **Greenwood**! As a tool, we hope that you find Greenwood to provide a productive and frictionless developer experience for you that results in performant and engaging experiences for your users. Under the hood Greenwood is using the power of the modern web ([and friends !](/docs/tech-stack/)) to drive a modern development workflow that helps you deliver a modern and perfmant applicatiot site for your users... using the web languages you already know. ## Your First Project To get things started, we first want to make sure everyone can get their first project up and running as easily and quickly as possible, and so through this guide, we will help walk you through everything you need to get started with your first project, including: @@ -35,7 +35,7 @@ $ npm -v # for example $ node -v -v10.15.1 +v12.13.0 $ npm -v 6.4.1 @@ -57,7 +57,7 @@ $ npm run develop #### Experience No advanced JavaScript / CSS experience is needed for using Greenwood. Just knowing some [markdown](https://daringfireball.net/projects/markdown/) and following some basic steps from the command line will be enough to get you up and running quickly. -We like to think that that as your experience grows, so can the way you build your site. Greenwood has very few opinions on how you structure your site or what you're trying to build or how and so our hope is to provide you a developer experience that is conducive to modern web development. +We like to think that that as your experience grows, so can the way you build your site. Greenwood has very few opinions on how you structure your project (aside from pages and templates), or what you're trying to build, or how. _Our hope is to provide you a developer experience that is conducive to modern web development and the expectations around it_. ## Tutorials So if you're ready to get started, let's get [your first project setup](/getting-started/project-setup/)! Or if you just want to "code and go", check out our [quick start](/getting-started/quick-start/). diff --git a/www/pages/getting-started/key-concepts.md b/www/pages/getting-started/key-concepts.md index 22b7c51af..56de15c71 100644 --- a/www/pages/getting-started/key-concepts.md +++ b/www/pages/getting-started/key-concepts.md @@ -14,8 +14,8 @@ Although Greenwood works without any configuration or setup, (go ahead, run `npm For this reason, the minimum requirements for a site that you will want to be familiar with are: 1. Workspace -1. Template(s) -1. Page(s) +1. Templates +1. Pages In this section, we hope you'll get a better understanding of key concepts and how they can be used to create as many layouts and pages as you need to build out your own site however you need. @@ -44,30 +44,39 @@ So using the project structure we setup previously, adding your own custom page β”œβ”€β”€ package.json └── src └── templates - └── page-template.js + └── page.html ``` -For reference, here's what the default page template included by Greenwood looks like (using `LitElement`). -```javascript -import { html, LitElement } from 'lit-element'; - -class PageTemplate extends LitElement { - render() { - return html\` - <div class='gwd-wrapper'> - <div class='gwd-page-template gwd-content'> - <entry></entry> - </div> - </div> - \`; - } -} - -customElements.define('page-template', PageTemplate); +Any regular HTML will do. You will just need to include a `<content-outlet></content-outlet>` HTML tag for where you will want your page content to appear. +```html +<html> + + <head> + <style> + body { + color: 'royal-blue'; + } + </style> + </head> + + <body> + <header> + <h1>My Website</h1> + </header> + + <section> + <content-outlet></content-outlet> + </section> + + <footer> + <span>© My Website</span> + </footer> + </body> + +</html> ``` -> Don't worry too much about the capitalized expression, this is discussed in more detail in our [docs](/docs/template/). Also, as seen here, Greenwood provides a version of [**LitElement**](https://lit-element.polymer-project.org/) by default that you can use for your own components if you would like. - +Don't worry too much about the `<content-outlet></content-outlet>`, this is discussed in more detail in our [docs](/docs/layouts/). ### Pages Pages are how you will create the content for your site by (generally) creating markdown files. Simply make a _pages/_ directory in your workspace and Greenwood will start building them automatically. By default, pages will build using the default page template: _page-template.js_. @@ -81,14 +90,14 @@ By adding a home page (_index.md_), your directory structure for a basic Greenwo β”œβ”€β”€ pages β”‚Β Β  └── index.md └── templates - └── page-template.js + └── page.html ``` And the sample home page provided by Greenwood out of the box looks like this: ```md ### Greenwood -This is the home page built by Greenwood. Make your own pages in src/pages/index.js! +This is the home page built by Greenwood. ``` diff --git a/www/pages/getting-started/project-setup.md b/www/pages/getting-started/project-setup.md index bea4b7497..7e4b574c9 100644 --- a/www/pages/getting-started/project-setup.md +++ b/www/pages/getting-started/project-setup.md @@ -36,23 +36,21 @@ All set! ### Configuring Workflows With Greenwood installed, let's create a couple of **npm** scripts so that we can automate our development workflows with easy to remember commands. -In _package.json_, edit the `scripts` section accordingly: +In _package.json_, edit the `scripts` section accordingly by adding: ```json -// before -"scripts": { - "test": "echo \"Error: no test specified\" && exit 1" -}, +{ + "scripts": { + "...": "....", -// after -"scripts": { - "build": "greenwood build", - "start": "greenwood develop" + "build": "greenwood build", + "start": "greenwood develop" + } }, ``` Now, you'll be able to do two things: -1. `npm start` - Start a local development server with file watching and reloading. -1. `npm run build` - Generate a static version of the project that you can then upload to a web server. +1. `npm start` - Start a local development server with file watching and live reloading. +1. `npm run build` - Generate a static build of the project that you can upload to a web server. You can go ahead and try out both of these tasks now, and you should see Greenwood's default generated output, letting you know you've set everything up correctly. From 1047fd7769c5df76e3e8d6436ad320008657cb31 Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 22 Dec 2020 18:03:51 -0500 Subject: [PATCH 4/9] unescape escaped code fences --- www/pages/about/how-it-works.md | 4 ++-- www/pages/docs/data.md | 24 +++++++++---------- www/pages/docs/menus.md | 10 ++++---- .../guides/cloudflare-workers-deployment.md | 4 ++-- www/pages/guides/firebase.md | 2 +- www/pages/guides/netlify-cms.md | 4 ++-- www/pages/guides/s3-cloudfront.md | 4 ++-- www/pages/plugins/index-hooks.md | 8 +++---- www/pages/plugins/webpack.md | 2 +- 9 files changed, 31 insertions(+), 31 deletions(-) diff --git a/www/pages/about/how-it-works.md b/www/pages/about/how-it-works.md index fc908811d..ff68aa202 100644 --- a/www/pages/about/how-it-works.md +++ b/www/pages/about/how-it-works.md @@ -36,7 +36,7 @@ import { html, LitElement } from 'lit-element'; class HomeTemplate extends LitElement { render() { - return html\` + return html` <style> /* some CSS if you need it */ </style> @@ -51,7 +51,7 @@ class HomeTemplate extends LitElement { <button onclick="inlineScript()">For a good time, click here.</button> <entry></entry> </div> - \`; + `; } } diff --git a/www/pages/docs/data.md b/www/pages/docs/data.md index 1911c7d29..bd6f624af 100644 --- a/www/pages/docs/data.md +++ b/www/pages/docs/data.md @@ -31,15 +31,15 @@ Instead, Greenwood uses GraphQL + Apollo to make that a reality! So instead of ```javascript render() { - return html\` + return html` <ul> ${pages.map((page) => { - return html\` + return html` <li><a href=\"${page.path}\">${page.title}</a></li> - \`; + `; })} </ul> - \`; + `; } ``` @@ -55,7 +55,7 @@ To kick things off, let's review what is available to you. Currently, the main This is what the schema looks like: ```javascript graph { - id, // (string) the unique ID given to the generated component as it's selector e.g. \`<wc-md-id></wc-md-id>\` + id, // (string) the unique ID given to the generated component as it's selector e.g. `<wc-md-id></wc-md-id>` link, // (string) A URL link, typically derived from the filesystem path, e.g. /blog/2019/first-post/ @@ -285,14 +285,14 @@ Or within your component ```javascript import gql from 'graphql-tag'; // comes with Greenwood -const query = gql\` +const query = gql` { user(id: 5) { firstName lastName } } -\` +` ``` Then you can use `import` anywhere in your components! @@ -336,21 +336,21 @@ class HeaderComponent extends LitElement { render() { const { navigation } = this; - return html\` + return html` <header class="header"> <nav> <ul> ${navigation.map(({ item }) => { - return html\` - <li><a href="\${item.link}" title="Click to visit the \${item.label} page">\${item.label}</a></li> - \`; + return html` + <li><a href="${item.link}" title="Click to visit the ${item.label} page">${item.label}</a></li> + `; })} </ul> </nav> </header> - \`; + `; } } diff --git a/www/pages/docs/menus.md b/www/pages/docs/menus.md index 6c6671d32..045d222a7 100644 --- a/www/pages/docs/menus.md +++ b/www/pages/docs/menus.md @@ -110,17 +110,17 @@ class HeaderComponent extends LitElement { render() { const { navigation } = this; - return html\` + return html` <nav> <ul> ${navigation.map(({ item }) => { - return html\` - <li><a href='\${item.link}' title='Click to visit the \${item.label} page'>\${item.label}</a></li> - \`; + return html` + <li><a href='${item.link}' title='Click to visit the ${item.label} page'>${item.label}</a></li> + `; })} </ul> </nav> - \`; + `; } } customElements.define('eve-header', HeaderComponent); diff --git a/www/pages/guides/cloudflare-workers-deployment.md b/www/pages/guides/cloudflare-workers-deployment.md index 9e61cf78d..1c8446961 100644 --- a/www/pages/guides/cloudflare-workers-deployment.md +++ b/www/pages/guides/cloudflare-workers-deployment.md @@ -95,8 +95,8 @@ jobs:    - name: Publish    uses: cloudflare/wrangler-action@1.1.0    with: -    apiKey: \$\{\{ secrets\.\CF_WORKERS_KEY \}\} -    email: \$\{\{ secrets\.\CF_WORKERS_EMAIL \}\} +    apiKey: ${{ secrets.CF_WORKERS_KEY }} +    email: ${{ secrets.CF_WORKERS_EMAIL }}     environment: "production" ``` diff --git a/www/pages/guides/firebase.md b/www/pages/guides/firebase.md index 36d4e33eb..0825d99ad 100644 --- a/www/pages/guides/firebase.md +++ b/www/pages/guides/firebase.md @@ -91,7 +91,7 @@ jobs: - name: Firebase Deploy run: | sudo npm install -g firebase-tools - firebase deploy --token \$\{\{ secrets.FIREBASE_TOKEN \}\} -P your-firebase-project-name + firebase deploy --token ${{ secrets.FIREBASE_TOKEN }} -P your-firebase-project-name ``` In the same directory as main.yml create a file 'chromium-lib-install.sh' diff --git a/www/pages/guides/netlify-cms.md b/www/pages/guides/netlify-cms.md index affdc7615..c196c1e3d 100644 --- a/www/pages/guides/netlify-cms.md +++ b/www/pages/guides/netlify-cms.md @@ -75,11 +75,11 @@ Along with the admin UI, we also need to readd the identity widget script elemen ```javascript render() { - return html\` + return html` ... <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script> ... - \` + ` } ``` diff --git a/www/pages/guides/s3-cloudfront.md b/www/pages/guides/s3-cloudfront.md index dda6f9aaf..6bea76aaa 100644 --- a/www/pages/guides/s3-cloudfront.md +++ b/www/pages/guides/s3-cloudfront.md @@ -79,8 +79,8 @@ jobs: - name: Publish to AWS S3 uses: opspresso/action-s3-sync@master env: - AWS_ACCESS_KEY_ID: \$\{\{ secrets\.AWS_SECRET_ACCESS_KEY_ID \}\} - AWS_SECRET_ACCESS_KEY: \$\{\{ secrets\.AWS_SECRET_ACCESS_KEY \}\} + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_SECRET_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: "us-east-2" FROM_PATH: "./public" DEST_PATH: "s3://your-s3-bucket-name" #your target s3 bucket name goes here diff --git a/www/pages/plugins/index-hooks.md b/www/pages/plugins/index-hooks.md index ecb773e49..aaed0f2cc 100644 --- a/www/pages/plugins/index-hooks.md +++ b/www/pages/plugins/index-hooks.md @@ -28,14 +28,14 @@ module.exports = { provider: (compilation) => { // you can access things like config, context if you need from compilation return { - hookGreenwoodAnalytics: \` + hookGreenwoodAnalytics: ` <script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-XXXXXXX', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script> - \` + ` } } }] @@ -80,9 +80,9 @@ module.exports = { provider: (compilation) => { // you can access things like config, context if you need from compilation return { - myCustomHook: \` + myCustomHook: ` <div>My custom HTML here</div> - \` + ` ] } }] diff --git a/www/pages/plugins/webpack.md b/www/pages/plugins/webpack.md index ce52fb194..97428e7fe 100644 --- a/www/pages/plugins/webpack.md +++ b/www/pages/plugins/webpack.md @@ -26,7 +26,7 @@ module.exports = { plugins: [{ type: 'webpack', provider: () => { - return new webpack.BannerPlugin(\`My App v\${version}\`); + return new webpack.BannerPlugin(`My App v${version}`); } }] From c016516eb52f1ce0bec1966112df32518d47cfa6 Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 22 Dec 2020 18:12:54 -0500 Subject: [PATCH 5/9] delete dead code --- packages/cli/src/commands/eject.js | 1 + packages/cli/src/lifecycles/context.js | 59 ----------- packages/cli/src/templates/404.html | 16 --- packages/cli/src/templates/app-template.js | 13 --- packages/cli/src/templates/base-template.js | 104 -------------------- packages/cli/src/templates/hello.md | 6 -- packages/cli/src/templates/index.html | 26 ----- packages/cli/src/templates/index.md | 7 -- packages/cli/src/templates/page-template.js | 15 --- 9 files changed, 1 insertion(+), 246 deletions(-) delete mode 100644 packages/cli/src/templates/404.html delete mode 100644 packages/cli/src/templates/app-template.js delete mode 100644 packages/cli/src/templates/base-template.js delete mode 100644 packages/cli/src/templates/hello.md delete mode 100644 packages/cli/src/templates/index.html delete mode 100644 packages/cli/src/templates/index.md delete mode 100644 packages/cli/src/templates/page-template.js diff --git a/packages/cli/src/commands/eject.js b/packages/cli/src/commands/eject.js index c324856d5..f95556bc6 100644 --- a/packages/cli/src/commands/eject.js +++ b/packages/cli/src/commands/eject.js @@ -8,6 +8,7 @@ module.exports = ejectConfigFiles = async (copyAllFiles) => { if (copyAllFiles) { configFilePaths = fs.readdirSync(path.join(__dirname, '../config')); } else { + // TODO configFilePaths = [ 'webpack.config.common.js', 'webpack.config.develop.js', diff --git a/packages/cli/src/lifecycles/context.js b/packages/cli/src/lifecycles/context.js index d02f189c3..79affdc01 100644 --- a/packages/cli/src/lifecycles/context.js +++ b/packages/cli/src/lifecycles/context.js @@ -1,7 +1,5 @@ const fs = require('fs'); const path = require('path'); -// const defaultTemplatesDir = path.join(__dirname, '../templates/'); -// const defaultConfigDir = path.join(__dirname, '../config'); const scratchDir = path.join(process.cwd(), './.greenwood/'); const outputDir = path.join(process.cwd(), './public'); const dataDir = path.join(__dirname, '../data'); @@ -11,63 +9,6 @@ module.exports = initContexts = async({ config }) => { return new Promise(async (resolve, reject) => { try { - // TODO - // const userAppTemplate = path.join(userTemplatesDir, 'app-template.js'); - // const userPageTemplate = path.join(userTemplatesDir, 'page-template.js'); - // const indexPageTemplate = 'index.html'; - // const notFoundPageTemplate = '404.html'; - // const webpackProd = 'webpack.config.prod.js'; - // const webpackDev = 'webpack.config.develop.js'; - // const babelConfig = 'babel.config.js'; - // const postcssConfig = 'postcss.config.js'; - - // const userHasWorkspace = await fs.exists(userWorkspace); - // const userHasWorkspacePages = await fs.exists(userPagesDir); - // const userHasWorkspaceTemplates = await fs.exists(userTemplatesDir); - // const userHasWorkspacePageTemplate = await fs.exists(userPageTemplate); - // const userHasWorkspaceAppTemplate = await fs.exists(userAppTemplate); - // const userHasWorkspaceIndexTemplate = await fs.exists(path.join(userTemplatesDir, 'index.html')); - // const userHasWorkspaceNotFoundTemplate = await fs.exists(path.join(userTemplatesDir, '404.html')); - // const userHasWorkspaceWebpackProd = await fs.exists(path.join(process.cwd(), webpackProd)); - // const userHasWorkspaceWebpackDevelop = await fs.exists(path.join(process.cwd(), webpackDev)); - // const userHasWorkspaceBabel = await fs.exists(path.join(process.cwd(), babelConfig)); - // const userHasWorkspacePostCSS = await fs.exists(path.join(process.cwd(), postcssConfig)); - - // let context = { - // dataDir, - // scratchDir, - // publicDir, - // pagesDir: userHasWorkspacePages ? userPagesDir : defaultTemplatesDir, - // templatesDir: userHasWorkspaceTemplates ? userTemplatesDir : defaultTemplatesDir, - // userWorkspace: userHasWorkspace ? userWorkspace : defaultTemplatesDir, - // pageTemplatePath: userHasWorkspacePageTemplate - // ? userPageTemplate - // : path.join(defaultTemplatesDir, 'page-template.js'), - // appTemplatePath: userHasWorkspaceAppTemplate - // ? userAppTemplate - // : path.join(defaultTemplatesDir, 'app-template.js'), - // indexPageTemplatePath: userHasWorkspaceIndexTemplate - // ? path.join(userTemplatesDir, indexPageTemplate) - // : path.join(defaultTemplatesDir, indexPageTemplate), - // notFoundPageTemplatePath: userHasWorkspaceNotFoundTemplate - // ? path.join(userTemplatesDir, notFoundPageTemplate) - // : path.join(defaultTemplatesDir, notFoundPageTemplate), - // indexPageTemplate, - // notFoundPageTemplate, - // assetDir: path.join(userHasWorkspace ? userWorkspace : defaultTemplatesDir, 'assets'), - // webpackProd: userHasWorkspaceWebpackProd - // ? path.join(process.cwd(), './', webpackProd) - // : path.join(defaultConfigDir, webpackProd), - // webpackDevelop: userHasWorkspaceWebpackDevelop - // ? path.join(process.cwd(), './', webpackDev) - // : path.join(defaultConfigDir, webpackDev), - // babelConfig: userHasWorkspaceBabel - // ? path.join(process.cwd(), './', babelConfig) - // : path.join(defaultConfigDir, babelConfig), - // postcssConfig: userHasWorkspacePostCSS - // ? path.join(process.cwd(), './', postcssConfig) - // : path.join(defaultConfigDir, postcssConfig) - // }; const userWorkspace = path.join(config.workspace); const pagesDir = path.join(userWorkspace, 'pages/'); const userTemplatesDir = path.join(userWorkspace, 'templates/'); diff --git a/packages/cli/src/templates/404.html b/packages/cli/src/templates/404.html deleted file mode 100644 index 983391817..000000000 --- a/packages/cli/src/templates/404.html +++ /dev/null @@ -1,16 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - -<head> - <meta charset="utf-8" /> - - <title>404 - Not Found - - <%= htmlWebpackPlugin.options.hookSpaIndexFallback %> - - - - -

404 Not Found

- - \ No newline at end of file diff --git a/packages/cli/src/templates/app-template.js b/packages/cli/src/templates/app-template.js deleted file mode 100644 index f26096e26..000000000 --- a/packages/cli/src/templates/app-template.js +++ /dev/null @@ -1,13 +0,0 @@ -import { html, LitElement } from 'lit-element'; - -class AppComponent extends LitElement { - - render() { - return html` - -

404 Not found

 - `; - } -} - -customElements.define('eve-app', AppComponent); diff --git a/packages/cli/src/templates/base-template.js b/packages/cli/src/templates/base-template.js deleted file mode 100644 index 2028a48a0..000000000 --- a/packages/cli/src/templates/base-template.js +++ /dev/null @@ -1,104 +0,0 @@ -import { html, LitElement } from 'lit-element'; -import { connectRouter } from 'lit-redux-router'; -import { applyMiddleware, createStore, compose as origCompose, combineReducers } from 'redux'; -import { lazyReducerEnhancer } from 'pwa-helpers/lazy-reducer-enhancer.js'; -import thunk from 'redux-thunk'; -import client from '@greenwood/cli/data/client'; -import ConfigQuery from '@greenwood/cli/data/queries/config'; -import GraphQuery from '@greenwood/cli/data/queries/graph'; -import '@greenwood/cli/templates/app-template'; -// eslint-disable-next-line no-underscore-dangle -const compose = window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ || origCompose; - -const store = createStore((state) => state, - compose(lazyReducerEnhancer(combineReducers), applyMiddleware(thunk)) -); - -import '../index/index'; - -connectRouter(store); - -class BaseAppComponent extends LitElement { - - async connectedCallback() { - super.connectedCallback(); - const route = window.location.pathname; - const response = await Promise.all([ - await client.query({ - query: ConfigQuery - }), - await client.query({ - query: GraphQuery - }) - ]); - const { config } = response[0].data; - const currentPage = response[1].data.graph.filter((page) => { - return route === page.link; - })[0]; - - const currentPageTitleSuffix = !currentPage || currentPage.link === '/' - ? '' - : ` - ${currentPage.title}`; - const fullTitle = `${config.title}${currentPageTitleSuffix}`; - - this.setDocumentTitle(fullTitle); - this.setMeta(config.meta, currentPage); - } - - setDocumentTitle(title = 'test') { - const head = document.head; - const titleElement = head.getElementsByTagName('title')[0]; - - titleElement.innerHTML = title; - } - - setMeta(meta = [], currentPage = {}) { - let header = document.head; - - meta.forEach(metaItem => { - const metaType = metaItem.rel // type of meta - ? 'rel' - : metaItem.name - ? 'name' - : 'property'; - const metaTypeValue = metaItem[metaType]; // value of the meta - let meta = document.createElement('meta'); - - if (metaType === 'rel') { - // change to a tag instead - meta = document.createElement('link'); - - meta.setAttribute('rel', metaTypeValue); - meta.setAttribute('href', metaItem.href); - } else { - const metaContent = metaItem.property === 'og:url' - ? `${metaItem.content}${currentPage.link}` - : metaItem.content; - - meta.setAttribute(metaType, metaItem[metaType]); - meta.setAttribute('content', metaContent); - } - - const oldmeta = header.querySelector(`[${metaType}="${metaTypeValue}"]`); - - // rehydration - if (oldmeta) { - header.replaceChild(meta, oldmeta); - } else { - header.appendChild(meta); - } - }); - } - - createRenderRoot() { - return this; - } - - render() { - return html` - - `; - } -} - -customElements.define('app-root', BaseAppComponent); \ No newline at end of file diff --git a/packages/cli/src/templates/hello.md b/packages/cli/src/templates/hello.md deleted file mode 100644 index d0c315dca..000000000 --- a/packages/cli/src/templates/hello.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -label: 'hello' ---- -### Hello World - -This is an example page built by Greenwood. Make your own in _src/pages_! \ No newline at end of file diff --git a/packages/cli/src/templates/index.html b/packages/cli/src/templates/index.html deleted file mode 100644 index ac454b28e..000000000 --- a/packages/cli/src/templates/index.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - <%= htmlWebpackPlugin.options.hookGreenwoodPolyfills %> - - <%= htmlWebpackPlugin.options.hookGreenwoodAnalytics %> - - <%= htmlWebpackPlugin.options.hookGreenwoodSpaIndexFallback %> - - - - - - - - - - \ No newline at end of file diff --git a/packages/cli/src/templates/index.md b/packages/cli/src/templates/index.md deleted file mode 100644 index 35a27e304..000000000 --- a/packages/cli/src/templates/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -label: 'index' ---- - -### Greenwood - -This is the home page built by Greenwood. Make your own pages in src/pages/index.js! \ No newline at end of file diff --git a/packages/cli/src/templates/page-template.js b/packages/cli/src/templates/page-template.js deleted file mode 100644 index 894fa40e0..000000000 --- a/packages/cli/src/templates/page-template.js +++ /dev/null @@ -1,15 +0,0 @@ -import { html, LitElement } from 'lit-element'; - -class PageTemplate extends LitElement { - render() { - return html` -
-
- -
-
- `; - } -} - -customElements.define('page-template', PageTemplate); \ No newline at end of file From bd799dc96aa5bb0252bee31b1220322a97b08a8e Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 28 Dec 2020 12:40:03 -0500 Subject: [PATCH 6/9] update tests and docs based on webpack features removed --- .github/CONTRIBUTING.md | 4 +- packages/cli/src/data/queries/config.gql | 4 +- packages/cli/src/data/schema/config.js | 4 +- packages/cli/src/lifecycles/config.js | 27 +-- .../build.config.error-public-path.spec.js | 45 ----- .../greenwood.config.js | 3 - .../build.config.public-path.spec.js | 63 ------- .../greenwood.config.js | 3 - .../build.default.webpack.spec.js | 66 ------- .../webpack.config.common.js | 173 ------------------ .../webpack.config.develop.js | 93 ---------- .../webpack.config.prod.js | 17 -- packages/cli/test/unit/data/mocks/config.js | 1 - .../cli/test/unit/data/schema/config.spec.js | 24 --- www/pages/docs/configuration.md | 29 +-- www/pages/docs/css-and-images.md | 2 +- www/pages/docs/data.md | 8 +- 17 files changed, 12 insertions(+), 554 deletions(-) delete mode 100644 packages/cli/test/cases/build.config.error-public-path/build.config.error-public-path.spec.js delete mode 100644 packages/cli/test/cases/build.config.error-public-path/greenwood.config.js delete mode 100644 packages/cli/test/cases/build.config.public-path/build.config.public-path.spec.js delete mode 100644 packages/cli/test/cases/build.config.public-path/greenwood.config.js delete mode 100644 packages/cli/test/cases/build.default.webpack/build.default.webpack.spec.js delete mode 100644 packages/cli/test/cases/build.default.webpack/webpack.config.common.js delete mode 100644 packages/cli/test/cases/build.default.webpack/webpack.config.develop.js delete mode 100644 packages/cli/test/cases/build.default.webpack/webpack.config.prod.js diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b518c385a..27ace0b20 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -87,7 +87,7 @@ Below are some tips to help with running / debugging tests: > **PLEASE DO NOT COMMIT ANY OF THESE ABOVE CHANGES THOUGH** ### Writing Tests -Cases follow a convention starting with the command (e.g. `build`) and and the capability and features being tested, like configuration with a particular option (e.g. `publicPath`): +Cases follow a convention starting with the command (e.g. `build`) and and the capability and features being tested, like configuration with a particular option (e.g. `port`): ```shell ...spec.js ``` @@ -95,7 +95,7 @@ Cases follow a convention starting with the command (e.g. `build`) and and the c Examples: - _build.default.spec.js_ - Would test `greenwood build` with no config and no workspace. - _build.config.workspace-custom.spec.js_ - Would test `greenwood build` with a config that had a custom `workspace` -- _build.config.workspace-public-path.spec.js_ - Would test `greenwood build` with a config that had a custom `workspace` and `publicPath` set. +- _build.config.workspace-dev-server-port.spec.js_ - Would test `greenwood build` with a config that had a custom `workspace` and `devServer.port` set. ### Notes Here are some thigns to keep in mind while writing your tests, due to the asynchronous nature of Greenwwood: diff --git a/packages/cli/src/data/queries/config.gql b/packages/cli/src/data/queries/config.gql index 24d57c5fd..1dcc9ac4e 100644 --- a/packages/cli/src/data/queries/config.gql +++ b/packages/cli/src/data/queries/config.gql @@ -1,8 +1,7 @@ query { config { devServer { - port, - host + port }, meta { name, @@ -13,7 +12,6 @@ query { href }, optimization, - publicPath, title, workspace } diff --git a/packages/cli/src/data/schema/config.js b/packages/cli/src/data/schema/config.js index 7c715ba9f..f02ae577c 100644 --- a/packages/cli/src/data/schema/config.js +++ b/packages/cli/src/data/schema/config.js @@ -7,8 +7,7 @@ const getConfiguration = async (root, query, context) => { // https://www.greenwoodjs.io/docs/configuration const configTypeDefs = gql` type DevServer { - port: Int, - host: String + port: Int } type Meta { @@ -24,7 +23,6 @@ const configTypeDefs = gql` devServer: DevServer, meta: [Meta], optimization: String, - publicPath: String, title: String, workspace: String } diff --git a/packages/cli/src/lifecycles/config.js b/packages/cli/src/lifecycles/config.js index e3173b6a0..d73fc9aa7 100644 --- a/packages/cli/src/lifecycles/config.js +++ b/packages/cli/src/lifecycles/config.js @@ -1,17 +1,13 @@ const fs = require('fs'); const path = require('path'); -const url = require('url'); // TODO const optimizations = ['strict', 'spa']; - let defaultConfig = { workspace: path.join(process.cwd(), 'src'), devServer: { - port: 1984, - host: 'localhost' + port: 1984 }, // TODO optimization: 'spa', - publicPath: '/', // TODO title: 'My App', meta: [], plugins: [], @@ -27,7 +23,7 @@ module.exports = readAndMergeConfig = async() => { if (fs.existsSync(path.join(process.cwd(), 'greenwood.config.js'))) { const userCfgFile = require(path.join(process.cwd(), 'greenwood.config.js')); - const { workspace, devServer, publicPath, title, markdown, meta } = userCfgFile; + const { workspace, devServer, title, markdown, meta } = userCfgFile; // workspace validation if (workspace) { @@ -61,15 +57,6 @@ module.exports = readAndMergeConfig = async() => { customConfig.title = title; } - if (publicPath) { - if (typeof publicPath !== 'string') { - reject('Error: greenwood.config.js publicPath must be a string'); - } else { - customConfig.publicPath = publicPath; - // console.log('custom publicPath provided => ', customConfig.publicPath); - } - } - if (meta && meta.length > 0) { customConfig.meta = meta; } @@ -102,16 +89,6 @@ module.exports = readAndMergeConfig = async() => { if (devServer && Object.keys(devServer).length > 0) { - if (devServer.host) { - // eslint-disable-next-line max-depth - if (url.parse(devServer.host).pathname === null) { - reject(`Error: greenwood.config.js devServer host type must be a valid pathname. Passed value was: ${devServer.host}`); - } else { - customConfig.devServer.host = devServer.host; - // console.log(`custom host provided => ${customConfig.devServer.host}`); - } - } - if (devServer.port) { // eslint-disable-next-line max-depth if (!Number.isInteger(devServer.port)) { diff --git a/packages/cli/test/cases/build.config.error-public-path/build.config.error-public-path.spec.js b/packages/cli/test/cases/build.config.error-public-path/build.config.error-public-path.spec.js deleted file mode 100644 index 1ab35ad82..000000000 --- a/packages/cli/test/cases/build.config.error-public-path/build.config.error-public-path.spec.js +++ /dev/null @@ -1,45 +0,0 @@ -/* - * Use Case - * Run Greenwood build command with a bad value for workspace directory in a custom config. - * - * User Result - * Should throw an error. - * - * User Command - * greenwood build - * - * User Config - * { - * publicPath: 123 - * } - * - * User Workspace - * Greenwood default - */ -const expect = require('chai').expect; -const TestBed = require('../../../../../test/test-bed'); - -describe('Build Greenwood With: ', function() { - let setup; - - before(async function() { - setup = new TestBed(); - await setup.setupTestBed(__dirname); - }); - - describe('Custom Configuration with a bad value for Public Path', function() { - it('should throw an error that publicPath must be a string', async function() { - try { - await setup.runGreenwoodCommand('build'); - } catch (err) { - expect(err).to.contain('greenwood.config.js publicPath must be a string'); - } - }); - - }); - - after(function() { - setup.teardownTestBed(); - }); - -}); \ No newline at end of file diff --git a/packages/cli/test/cases/build.config.error-public-path/greenwood.config.js b/packages/cli/test/cases/build.config.error-public-path/greenwood.config.js deleted file mode 100644 index 6cf29c5bd..000000000 --- a/packages/cli/test/cases/build.config.error-public-path/greenwood.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - publicPath: 123 -}; \ No newline at end of file diff --git a/packages/cli/test/cases/build.config.public-path/build.config.public-path.spec.js b/packages/cli/test/cases/build.config.public-path/build.config.public-path.spec.js deleted file mode 100644 index 363bf197e..000000000 --- a/packages/cli/test/cases/build.config.public-path/build.config.public-path.spec.js +++ /dev/null @@ -1,63 +0,0 @@ -/* - * Use Case - * Run Greenwood with string publicPath in config and default workspace. - * - * User Result - * Should generate a bare bones Greenwood build. (same as build.default.spec.js) with custom publicPath - * from which assets will be served - * - * User Command - * greenwood build - * - * User Config - * { - * publicPath: '/assets/' - * } - */ -const { JSDOM } = require('jsdom'); -const path = require('path'); -const expect = require('chai').expect; -const runSmokeTest = require('../../../../../test/smoke-test'); -const TestBed = require('../../../../../test/test-bed'); - -xdescribe('Build Greenwood With: ', function() { - const LABEL = 'Custom Public Path Configuration and Default Workspace'; - let setup; - - before(async function() { - setup = new TestBed(); - this.context = await setup.setupTestBed(__dirname); - }); - - describe(LABEL, function() { - before(async function() { - await setup.runGreenwoodCommand('build'); - }); - runSmokeTest(['not-found', 'hello'], LABEL); - - describe('Custom Configuration with a custom public path', function() { - - beforeEach(async function() { - dom = await JSDOM.fromFile(path.resolve(this.context.publicDir, './index.html')); - }); - - it('should serve assets from the configured publicPath', function() { - const publicPath = '/assets/'; - const scriptTags = dom.window.document.querySelectorAll('body script'); - const bundledScripts = Array.prototype.slice.call(scriptTags).filter(script => { - const src = script.src; - - return src.indexOf('index.') >= 0 && src.indexOf('.bundle.js') >= 0; - }); - - expect(bundledScripts[0].src.indexOf(publicPath) >= 0).to.be.equal(true); - }); - }); - - }); - - after(function() { - setup.teardownTestBed(); - }); - -}); \ No newline at end of file diff --git a/packages/cli/test/cases/build.config.public-path/greenwood.config.js b/packages/cli/test/cases/build.config.public-path/greenwood.config.js deleted file mode 100644 index 0ab84567b..000000000 --- a/packages/cli/test/cases/build.config.public-path/greenwood.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - publicPath: '/assets/' -}; \ No newline at end of file diff --git a/packages/cli/test/cases/build.default.webpack/build.default.webpack.spec.js b/packages/cli/test/cases/build.default.webpack/build.default.webpack.spec.js deleted file mode 100644 index 89c1f6951..000000000 --- a/packages/cli/test/cases/build.default.webpack/build.default.webpack.spec.js +++ /dev/null @@ -1,66 +0,0 @@ -/* - * Use Case - * Run Greenwood with a custom webpack config and default workspace. - * - * User Result - * Should generate a bare bones Greenwood build with custom webpack changes - * - * User Command - * greenwood build - * - * User Workspace - * Greenwood default - */ -const expect = require('chai').expect; -const fs = require('fs'); -const { JSDOM } = require('jsdom'); -const path = require('path'); -const runSmokeTest = require('../../../../../test/smoke-test'); -const TestBed = require('../../../../../test/test-bed'); -const { version } = require('../../../package.json'); - -xdescribe('Build Greenwood With: ', function() { - const mockBanner = `My Banner - v${version}`; - const LABEL = 'Custom Webpack Configuration'; - let setup; - - before(async function() { - setup = new TestBed(); - this.context = await setup.setupTestBed(__dirname); - }); - - describe(LABEL, function() { - before(async function() { - await setup.runGreenwoodCommand('build'); - }); - - runSmokeTest(['public', 'index', 'not-found', 'hello'], LABEL); - - describe('using a custom webpack.config.common.js with banner plugin', function() { - let bundleFile; - - beforeEach(async function() { - const dom = await JSDOM.fromFile(path.resolve(this.context.publicDir, 'index.html')); - const scriptTags = dom.window.document.querySelectorAll('body script'); - const bundleScripts = Array.prototype.slice.call(scriptTags).filter(script => { - const src = script.src; - - return src.indexOf('index.') >= 0 && src.indexOf('.bundle.js') >= 0; - }); - - bundleFile = bundleScripts[0].src.replace('file:///', ''); - }); - - it('should have the banner text in index.js', function() { - const fileContents = fs.readFileSync(path.resolve(this.context.publicDir, bundleFile), 'utf8'); - - expect(fileContents).to.contain(mockBanner); - }); - }); - }); - - after(function() { - setup.teardownTestBed(); - }); - -}); \ No newline at end of file diff --git a/packages/cli/test/cases/build.default.webpack/webpack.config.common.js b/packages/cli/test/cases/build.default.webpack/webpack.config.common.js deleted file mode 100644 index 7d51c1b57..000000000 --- a/packages/cli/test/cases/build.default.webpack/webpack.config.common.js +++ /dev/null @@ -1,173 +0,0 @@ -const CopyWebpackPlugin = require('copy-webpack-plugin'); -const fs = require('fs'); -const HtmlWebpackPlugin = require('html-webpack-plugin'); -const path = require('path'); -const webpack = require('webpack'); -const { version } = require('../../../package.json'); - -const getUserWorkspaceDirectories = (source) => { - return fs.readdirSync(source) - .map(name => path.join(source, name)) - .filter(path => fs.lstatSync(path).isDirectory()); -}; -const mapUserWorkspaceDirectories = (directoryPath, userWorkspaceDirectory) => { - const directoryName = directoryPath.replace(`${userWorkspaceDirectory}/`, ''); - const userWorkspaceDirectoryRoot = userWorkspaceDirectory.split('/').slice(-1); - - return new webpack.NormalModuleReplacementPlugin( - // https://github.com/ProjectEvergreen/greenwood/issues/132 - new RegExp(`\\.\\.\\/${directoryName}.+$(? { - - // workaround to ignore cli/templates default imports when rewriting - if (!new RegExp('\/cli\/templates').test(resource.content)) { - resource.request = resource.request.replace(new RegExp(`\\.\\.\\/${directoryName}`), directoryPath); - } - - // remove any additional nests, after replacement with absolute path of user workspace + directory - const additionalNestedPathIndex = resource.request.lastIndexOf('..'); - - if (additionalNestedPathIndex > -1) { - resource.request = resource.request.substring(additionalNestedPathIndex + 2, resource.request.length); - } - } - - ); -}; - -module.exports = ({ config, context }) => { - const { userWorkspace } = context; - - // dynamically map all the user's workspace directories for resolution by webpack - // this essentially helps us keep watch over changes from the user's workspace forgreenwood's build pipeline - const mappedUserDirectoriesForWebpack = getUserWorkspaceDirectories(userWorkspace) - .map((directory) => { - return mapUserWorkspaceDirectories(directory, userWorkspace); - }); - - // if user has an assets/ directory in their workspace, automatically copy it for them - const userAssetsDirectoryForWebpack = fs.existsSync(context.assetDir) ? [{ - from: context.assetDir, - to: path.join(context.publicDir, 'assets') - }] : []; - - const commonCssLoaders = [ - { loader: 'css-loader' }, - { - loader: 'postcss-loader', - options: { - config: { - path: path.join(__dirname, '../../..', './src/config', 'postcss.config.js') - } - } - } - ]; - - // gets Index Hooks to pass as options to HtmlWebpackPlugin - const customOptions = Object.assign({}, ...config.plugins - .filter((plugin) => plugin.type === 'index') - .map((plugin) => plugin.provider({ config, context })) - .filter((providerResult) => { - return Object.keys(providerResult).map((key) => { - if (key !== 'type') { - return providerResult[key]; - } - }); - })); - - // utilizes webpack plugins passed in directly by the user - const customWebpackPlugins = config.plugins - .filter((plugin) => plugin.type === 'webpack') - .map((plugin) => plugin.provider({ config, context })); - - return { - - resolve: { - extensions: ['.js', '.json', '.gql', '.graphql'], - alias: { - '@greenwood/cli/data': path.join(__dirname, '../../..', './src', './data'), - '@greenwood/cli/templates/app-template': path.join(context.scratchDir, 'app', 'app-template.js') - } - }, - - entry: { - index: path.join(context.scratchDir, 'app', 'app.js') - }, - - output: { - path: path.join(context.publicDir, '.', config.publicPath), - filename: '[name].[hash].bundle.js', - chunkFilename: '[name].[hash].bundle.js', - publicPath: config.publicPath - }, - - module: { - rules: [{ - test: /\.js$/, - loader: 'babel-loader', - options: { - configFile: path.join(__dirname, '../../..', './src/config', 'babel.config.js') - } - }, { - test: /\.md$/, - loader: 'wc-markdown-loader', - options: { - defaultStyle: false, - shadowRoot: false - } - }, { - test: /\.css$/, - exclude: new RegExp(`${config.themeFile}`), - loaders: [ - { loader: 'css-to-string-loader' }, - ...commonCssLoaders - ] - }, { - test: new RegExp(`${config.themeFile}`), - loaders: [ - { loader: 'style-loader' }, - ...commonCssLoaders - ] - }, { - test: /\.woff(2)?(\?v=[0-9]\.[0-9]\.[0-9])?$/, - loader: 'url-loader?limit=10000&mimetype=application/font-woff' - }, { - test: /\.(ttf|eot|svg|jpe?g|png|gif|otf)(\?v=[0-9]\.[0-9]\.[0-9])?$/, - loader: 'file-loader' - }, { - test: /\.(graphql|gql)$/, - loader: 'graphql-tag/loader' - }] - }, - - plugins: [ - new HtmlWebpackPlugin({ - filename: path.join(context.publicDir, context.indexPageTemplate), - template: path.join(context.scratchDir, context.indexPageTemplate), - chunksSortMode: 'dependency', - ...customOptions - }), - - new HtmlWebpackPlugin({ - filename: path.join(context.publicDir, context.notFoundPageTemplate), - template: path.join(context.scratchDir, context.notFoundPageTemplate), - chunksSortMode: 'dependency', - ...customOptions - }), - - ...mappedUserDirectoriesForWebpack, - - new CopyWebpackPlugin(userAssetsDirectoryForWebpack), - - new webpack.NormalModuleReplacementPlugin( - /\.md/, - (resource) => { - resource.request = resource.request.replace(/^\.\//, context.pagesDir); - } - ), - /// Custom plugin added to prove custom config is being used - new webpack.BannerPlugin(`My Banner - v${version}`), - ...customWebpackPlugins - ] - }; -}; \ No newline at end of file diff --git a/packages/cli/test/cases/build.default.webpack/webpack.config.develop.js b/packages/cli/test/cases/build.default.webpack/webpack.config.develop.js deleted file mode 100644 index ccf19c428..000000000 --- a/packages/cli/test/cases/build.default.webpack/webpack.config.develop.js +++ /dev/null @@ -1,93 +0,0 @@ -const path = require('path'); -const ManifestPlugin = require('webpack-manifest-plugin'); -const FilewatcherPlugin = require('filewatcher-webpack-plugin'); -const generateCompilation = require('../lifecycles/compile'); -const webpackMerge = require('webpack-merge'); -const commonConfig = require('./webpack.config.common.js'); - -let isRebuilding = false; - -const rebuild = async() => { - if (!isRebuilding) { - isRebuilding = true; - - // rebuild web components - await generateCompilation(); - - // debounce - setTimeout(() => { - isRebuilding = false; - }, 1000); - } -}; - -module.exports = ({ config, context, graph }) => { - config.publicPath = '/'; - - const configWithContext = commonConfig({ config, context, graph }); - const { devServer, publicPath } = config; - const { host, port } = devServer; - - // decorate HtmlWebpackPlugin instance with devServer specific SPA handling for index.html - configWithContext.plugins[0].options.hookGreenwoodSpaIndexFallback = ` - - `, - - // decorate HtmlWebpackPlugin instance with devServer specific SPA handling for 404.html - configWithContext.plugins[1].options.hookGreenwoodSpaIndexFallback = ` - - - - `; - - return webpackMerge(configWithContext, { - - mode: 'development', - - entry: [ - `webpack-dev-server/client?http://${host}:${port}`, - path.join(context.scratchDir, 'app', 'app.js') - ], - - devServer: { - port, - host, - disableHostCheck: true, - historyApiFallback: true, - hot: false, - inline: true - }, - - plugins: [ - new FilewatcherPlugin({ - watchFileRegex: [`/${context.userWorkspace}/`], - onReadyCallback: () => { - console.log(`Now serving Development Server available at ${host}:${port}`); - }, - onChangeCallback: async () => { - rebuild(); - }, - usePolling: true, - atomic: true, - ignored: '/node_modules/' - }), - - new ManifestPlugin({ - fileName: 'manifest.json', - publicPath - }) - ] - }); -}; \ No newline at end of file diff --git a/packages/cli/test/cases/build.default.webpack/webpack.config.prod.js b/packages/cli/test/cases/build.default.webpack/webpack.config.prod.js deleted file mode 100644 index 62764d0d7..000000000 --- a/packages/cli/test/cases/build.default.webpack/webpack.config.prod.js +++ /dev/null @@ -1,17 +0,0 @@ -const webpackMerge = require('webpack-merge'); -const commonConfig = require('./webpack.config.common.js'); - -module.exports = ({ config, context, graph }) => { - const configWithContext = commonConfig({ config, context, graph }); - - return webpackMerge(configWithContext, { - - mode: 'production', - - performance: { - hints: 'warning' - } - - }); - -}; \ No newline at end of file diff --git a/packages/cli/test/unit/data/mocks/config.js b/packages/cli/test/unit/data/mocks/config.js index c8efdbfae..0df1898c4 100644 --- a/packages/cli/test/unit/data/mocks/config.js +++ b/packages/cli/test/unit/data/mocks/config.js @@ -8,7 +8,6 @@ const MOCK_CONFIG = { { name: 'twitter:site', content: '@PrjEvergreen' }, { rel: 'icon', href: '/assets/favicon.ico' } ], - publicPath: '/some-dir', title: 'My App', workspace: 'src' } diff --git a/packages/cli/test/unit/data/schema/config.spec.js b/packages/cli/test/unit/data/schema/config.spec.js index b8959e94c..eb4ce3e4d 100644 --- a/packages/cli/test/unit/data/schema/config.spec.js +++ b/packages/cli/test/unit/data/schema/config.spec.js @@ -19,10 +19,6 @@ describe('Unit Test: Data', function() { it('should have the expected devServer.port', function() { expect(config.devServer.port).to.equal(devServer.port); }); - - it('should have the expected devServer.host', function() { - expect(config.devServer.host).to.equal(devServer.host); - }); }); describe('Meta', function() { @@ -33,24 +29,12 @@ describe('Unit Test: Data', function() { expect(nameMeta.name).to.equal(meta[0].name); }); - - it('should have the expected devServer.host', function() { - const nameMeta = config.meta[0]; - - expect(nameMeta.content).to.equal(meta[0].content); - }); it('should have the expected rel meta in the second index', function() { const relMeta = config.meta[1]; expect(relMeta.rel).to.equal(meta[1].rel); }); - - it('should have the expected devServer.host', function() { - const relMeta = config.meta[1]; - - expect(relMeta.content).to.equal(meta[1].content); - }); }); describe('Mode', function() { @@ -61,14 +45,6 @@ describe('Unit Test: Data', function() { }); - describe('Public Path', function() { - const { publicPath } = MOCK_CONFIG.config; - - it('should have the expected publicPath', function() { - expect(publicPath).to.equal(config.publicPath); - }); - }); - describe('Title', function() { const { title } = MOCK_CONFIG.config; diff --git a/www/pages/docs/configuration.md b/www/pages/docs/configuration.md index 1e9c0b2af..56cdaa2ba 100644 --- a/www/pages/docs/configuration.md +++ b/www/pages/docs/configuration.md @@ -17,24 +17,21 @@ module.exports = { port: 1984, host: 'localhost' }, - publicPath: '/', title: 'My App', meta: [] }; ``` ### Dev Server -Configuration for Greenwood's development server are available using the `devServer` option. Two options are available: +Configuration for Greenwood's development server is available using the `devServer` option. - `port`: Pick a different port when starting the dev server -- `host`: If you need to use a custom domain (using [pathname](https://nodejs.org/api/url.html#url_url_pathname)) when developing locally and generally used along with editing an `/etc/hosts` file. #### Example ```js module.exports = { devServer: { - port: 8181, - host: 'local.my-domain.com' - }, + port: 8181 + } } ``` @@ -111,26 +108,6 @@ module.exports = { ``` --> -### Public Path - -> β›” _**Coming Soon!**_ - - - ### Title A default `` element for all pages can be configured with the `title` option. diff --git a/www/pages/docs/css-and-images.md b/www/pages/docs/css-and-images.md index 11514eb32..c7e31db4c 100644 --- a/www/pages/docs/css-and-images.md +++ b/www/pages/docs/css-and-images.md @@ -62,7 +62,7 @@ You can do the same in your HTML ``` -> If you like your all-the-things-in-JS approach, Greenwood can be extended with [plugins](/plugins/) to support "webpack" like behavior as seeb in the below example: +> If you like your all-the-things-in-JS approach, Greenwood can be extended with [plugins](/plugins/) to support "webpack" like behavior as seen in the below example: > > ```javascript > import { html, LitElement } from 'lit-element'; diff --git a/www/pages/docs/data.md b/www/pages/docs/data.md index bd6f624af..a05bb55b0 100644 --- a/www/pages/docs/data.md +++ b/www/pages/docs/data.md @@ -211,8 +211,7 @@ The Config query returns the configuration values from your _greenwood.config.js query { config { devServer { - port, - host + port }, meta { name, @@ -223,7 +222,6 @@ query { href }, optimization, - publicPath, title, workspace } @@ -255,14 +253,12 @@ This will return an object of youf _greenwood.config.js_ as an object. Example: ```javascript { devServer: { - port: 1984, - host: 'localhost' + port: 1984 }, meta: [ { name: 'twitter:site', content: '@PrjEvergreen' }, { rel: 'icon', href: '/assets/favicon.ico' } ], - publicPath: '/some-dir', title: 'My App', workspace: 'src' } From d46df95f07b8099de8b77c4c28393ff4ba40ef56 Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 29 Dec 2020 10:35:13 -0500 Subject: [PATCH 7/9] incorporate technical design docs --- .github/CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 8 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 27ace0b20..e02a3fe3f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,6 +3,53 @@ ## Welcome! We're excited for your interest in Greenwood, and maybe even your contribution! +> _We encourage all contributors to have first read about the project's vision and motivation's on the website's [About page](https://www.greenwoodjs.io/about/). Greenwood is opinionated in the sense that is designed to support development for the web platform and deliver a first class developer experience tailored around that, so that anyone can create a modern and performant website (or webapp, if you prefer). So if that page is the "why", this page is the "how"._ + +## Technical Design Overview + +The Greenwood GitHub repository is a combination [Yarn workspace](https://classic.yarnpkg.com/en/docs/workspaces/) and [Lerna monorepo](https://github.com/lerna/lerna). The root level _package.json_ defines the workspaces and shared tooling used throughout the project, like for linting, testing, etc. + +The two main directories are: +- [_packages/_](https://github.com/ProjectEvergreen/greenwood/tree/master/packages) - Packages published to NPM under the `@greenwood/` scope +- [_www/_](https://github.com/ProjectEvergreen/greenwood/tree/master/www) - [website](https://www.greenwoodjs.io) / documentation code + + +> _This guide is mainly intended to walk through the **cli** package, it being the principal pacakge within the project supporting all other packages._ + +### CLI + +The CLI is the main entry point for Greenwood, similar to how the [front-controller pattern](https://en.wikipedia.org/wiki/Front_controller) works. When users run a command like `greenwood build`, they are effectively invoking the file _src/index.js_ within the `@greenwood/cli` package. + +At a high level, this is how a command goes through the CLI: +1. Each documented command a user can run maps to a script in the _commands/_ directory. +1. Each command can invoke any number of lifecycles from the _lifecycles/_ directory. +1. Lifecycles capture specific steps needed to build a site, serve it, generate a content dependency graph, etc. + + +### Layout +The [layout](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/cli/src) of the CLI package is as follows: + +- _index.js_ - Front controller +- _commands/_ - map to runnable userland commands +- _config/_ - Tooling configuration that Greenwood creates +- _data/_ - Custom GraphQL server and client side utilities +- _lib/_ - Customfized Local third party libraries and utility files +- _lifecycles/_ - Tasks that can be composed by commands to support the full needs of that command +- _plugins/_ - Custom defaukt plugins maintained by the CLI project +- _templates/_ - Default templates and / or pages provided by Grennwood. + +We'll focus on the most important two here: + + +### Lifecycles +Aside from the config and graph lifecycles, all lifecycles (and config files and plugins) typically expect a compilation object to be passed in. + +Lifeycles include handling: +- starting a production or development server for a compilation +- optimizing a compilation for production +- prerendering a compilation for production +- fetching external (content) data sources + ## Issues Please make sure to have the following prepared (where applicable) @@ -14,8 +61,8 @@ Please make sure to have the following prepared (where applicable) ## Pull Requests Pull requests are the best! To best help facililate contributions to the project, here are some requests: -- We generally we prefer an issue be opened first, to help faciliate general discussion outside of the code review process itself and align on the ask and any expections. However, for typos in docs and minor "chore" like tasks a PR is usually sufficient. When in doubt, open an issue. -- For bugs, please consider reviewing the issue tracker. +- We generally prefer an issue be opened first, to help faciliate general discussion outside of the code review process itself and align on the ask and any expections. However, for typos in docs and minor "chore" like tasks a PR is usually sufficient. When in doubt, open an issue. +- For bugs, please consider reviewing the issue tracker first. - For branching, we generally follow the convention `<issue-label>/issue-<number>-<issue-title>`, e.g. _bug/issue-12-fixed-bug-with-yada-yada-yada_ - To test the CI build scripts locally, run the `yarn` commands mentioned in the below section on CI. @@ -31,13 +78,13 @@ A preview is also made available within the status checks section of the PR in G ## Local Development To develop for the project, you'll want to follow these steps: -1. Have [NodeJS LTS](https://nodejs.org) installed (>= 10.x) and [Yarn](https://yarnpkg.com/) +1. Have [NodeJS LTS](https://nodejs.org) installed (>= 12.x) and [Yarn](https://yarnpkg.com/) 1. Clone the repository 1. Run `yarn install` 1. Run `yarn lerna bootstrap` -### Tasks -The Greenwood website is currently built by Greenwood itself, and all files for it are located in this repository in the _www/_ directory. In addition to unit tests, you will want to verify all changes by running the website locally. +### Scripts +The [Greenwood website](https://www.greenwoodjs.io/) is currently built by Greenwood, and all files for it are located in this repository under the [_www/_ directory](https://github.com/ProjectEvergreen/greenwood/tree/master/www) workspace. In addition to unit tests, you will want to verify any changes by running the website locally. Below are the development tasks available for working on this project: - `yarn develop` - Develop for the website locally using the dev server at `localhost:1984` in your browser. @@ -45,7 +92,7 @@ Below are the development tasks available for working on this project: - `yarn serve` - Builds the website for production and runs it on a local webserver at `localhost:8000` ### Packages -Greenwood is organized into packages as a monorepo, managed by [Lerna](https://lerna.js.org/) and [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). You can find all of these in the _packages/_ directory. Each package will manage its own: +As mentioned above, Greenwood is organized into packages as a monorepo, managed by [Lerna](https://lerna.js.org/) and [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). You can find all of these in the _packages/_ directory. Each package will manage its own: - Dependencies - README - Test Cases @@ -65,7 +112,7 @@ Yarn workspaces will automatically handle installing _node_modules_ in the appro ## Unit Testing -[TDD](https://en.wikipedia.org/wiki/Test-driven_development) is the recommended approach for developing for Greenwood and for the style of test writing we use [BDD style testing](https://en.wikipedia.org/wiki/Behavior-driven_development); "cases". Cases are used to capture the various configurations and expected outputs of Greenwood when running its commands, in a way that is closer to how a user would be expecting Greenwood to work. +[TDD](https://en.wikipedia.org/wiki/Test-driven_development) is the recommended approach for developing for Greenwood and for the style of test writing we use [BDD style testing](https://en.wikipedia.org/wiki/Behavior-driven_development); "cases". Cases are used to capture the various configurations and expected outputs of Gre enwood when running its commands, in a way that is closer to how a user would be expecting Greenwood to work. ### Running Tests To run tests in watch mode, use: @@ -104,7 +151,7 @@ Here are some thigns to keep in mind while writing your tests, due to the asynch - Avoid arrow functions in mocha tests (e.g. `() => `) as this [can cause unexpected behaviors.](https://mochajs.org/#arrow-functions). Just use `function` instead. ## Internet Explorer -For situations that require testing Internet Explorer or Edge browser, Microsoft [provides Virtual Machines](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/) for various combinations of Windows and Internet Explorer versions. [VirtualBox](https://www.virtualbox.org/) is a good platform to use for these VMs. +For situations that require testing Internet Explorer or Edge browser, Microsoft provides [Virtual Machines](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/) for various combinations of Windows and Internet Explorer versions. [VirtualBox](https://www.virtualbox.org/) is a good platform to use for these VMs. To test from a VM, you can 1. Run `yarn serve` From 239702358e1bdb665a1d96433284d1214592c85a Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Tue, 29 Dec 2020 12:26:35 -0500 Subject: [PATCH 8/9] additional corrections and proof reading --- www/pages/docs/configuration.md | 2 +- www/pages/docs/front-matter.md | 13 +++---- www/pages/docs/index.md | 4 +- www/pages/docs/layouts.md | 6 +-- www/pages/docs/markdown.md | 5 ++- www/pages/docs/tech-stack.md | 4 +- www/pages/getting-started/branding.md | 39 +++++++++++-------- www/pages/getting-started/build-and-deploy.md | 2 +- www/pages/getting-started/creating-content.md | 2 +- www/pages/getting-started/index.md | 6 +-- www/pages/getting-started/next-steps.md | 17 ++------ www/pages/getting-started/project-setup.md | 4 +- 12 files changed, 51 insertions(+), 53 deletions(-) diff --git a/www/pages/docs/configuration.md b/www/pages/docs/configuration.md index 56cdaa2ba..25c4af377 100644 --- a/www/pages/docs/configuration.md +++ b/www/pages/docs/configuration.md @@ -7,7 +7,7 @@ linkheadings: 3 --- ## Configuration -These are all the supported configuration options in Greenwood, which you can define in a _greenwood.config.js_ file in your project's root directory. +These are all the supported configuration options in **Greenwood**, which you can define in a _greenwood.config.js_ file in your project's root directory. A **greenwood.config.js** file reflecting default values would be: ```js diff --git a/www/pages/docs/front-matter.md b/www/pages/docs/front-matter.md index 3fce1344b..8c35d7a06 100644 --- a/www/pages/docs/front-matter.md +++ b/www/pages/docs/front-matter.md @@ -12,18 +12,17 @@ linkheadings: 3 ### Element Label -When this markdown file is compiled to a component it will automatically generate a custom element tag name. If you want to use a custom element name of your own for your page, you can give the component a label using the predefined variable `label`. +By default Greenwood will aim to create a label for your page based on filename and context and include that in the graph. This can be useful for categorizing or organizing your content when rendering client side, or if you want to create a custom value to display for a link or in your HTML that may be different from what can be inferred from the file name. #### Example +_pages/blog/2020/03/05/index.md_ ```md --- -label: 'mypage' +label: 'My Blog Post from 3/5/2020' --- ``` -Which will compile to the element: `<wc-md-mypage></wc-md-mypage>` - ### Imports > β›” _**Coming Soon!**_ @@ -43,7 +42,7 @@ See our [Markdown Docs](/docs/markdown#imports) for more information about rende ### Template -When creating multiple page templates, you can use the `template` front-matter to configure Greenwood to use that template for a given page. +When creating multiple [page templates](/docs/layouts/), you can use the `template` front-matter to configure Greenwood to use that template for a given page. #### Example ```md @@ -55,9 +54,9 @@ template: 'home' This is the home page ``` -In this example, the _src/templates/home-template.js_ will be used to render the current markdown page. +In this example, the _src/templates/home.html_ will be used to render the current markdown page. -> **Note:** By default, Greenwood will use `src/templates/page-template.js` for all undefined template pages. +> **Note:** By default, Greenwood will use `src/templates/page.html` for all undefined template pages. ### Title diff --git a/www/pages/docs/index.md b/www/pages/docs/index.md index 00f361515..5813a72f7 100644 --- a/www/pages/docs/index.md +++ b/www/pages/docs/index.md @@ -6,7 +6,7 @@ index: 2 --- ## Documentation -This is the documentation space for Greenwood that we hope will help you get the most out of using it. If this is your first time with Greenwood, we recommend checking out our [Getting Started](/getting-started/) guide to get more familiar with setting up your first Greenwood project. +This is the documentation space for **Greenwood** that we hope will help you get the most out of using it. If this is your first time with Greenwood, we recommend checking out our [Getting Started](/getting-started/) guide to get more familiar with setting up your first Greenwood project. ### Installation @@ -65,7 +65,7 @@ $ yarn serve ### Sections -To continue learning more abuut Greenwood, please feel free to browse the other sections of our documentation. +To continue learning more about Greenwood, please feel free to browse the other sections of our documentation. - [Component Model](/docs/component-model/): Examples of using custom elements in Greenwood. - [Configuration](/docs/configuration/): Available configuration options for the Greenwood CLI. diff --git a/www/pages/docs/layouts.md b/www/pages/docs/layouts.md index 40a48b327..dfdbd2b61 100644 --- a/www/pages/docs/layouts.md +++ b/www/pages/docs/layouts.md @@ -8,15 +8,15 @@ linkheadings: 3 ## Templates and Pages -Greenwood has two types of templates to help Γ₯layout your pages: +Greenwood has two types of templates to help layout your pages: -- _App Template_: The ["app shell"](https://developers.google.com/web/fundamentals/architecture/app-shell) if you will, that would wrap all pages. One is provided for you by Greenwood, but you can override it if needed. +- _App Template_: The ["app shell"](https://developers.google.com/web/fundamentals/architecture/app-shell) that will wrap all pages. One is provided for you by Greenwood, but you can override it if needed. - _Page Templates_: A template for each unique page layout within your site. Common layouts are great for documentation and blog sites, but also great for single pages as well (like a splash layout for the home page). > _**Note**: [For now](https://github.com/ProjectEvergreen/greenwood/issues/435), all paths in template files need to start with a `/` and omit the workspace directory._ ### Page Templates -Pages in your project will generally want a template so you can control the output of the HTML and include all your own custom components and styles. By default alll pages will default to looking for a _page.html_ in _templates/ directory within your workspace. +Pages in your project will generally want a template so you can control the output of the HTML and include all your own custom components and styles. By default all pages will default to looking for a _page.html_ in _templates/ directory within your workspace. In order to make a page template, you just need to write up some HTML that can be enhanced with these special custom elements: diff --git a/www/pages/docs/markdown.md b/www/pages/docs/markdown.md index b5f81f715..5a30dae3d 100644 --- a/www/pages/docs/markdown.md +++ b/www/pages/docs/markdown.md @@ -11,6 +11,7 @@ In this section we'll cover some of the Markdown related feature of **Greenwood* ### Imports > β›” _**Coming Soon!**_ + <!-- From within the markdown you can also render components, not just their syntax, by importing them via [front-matter](/docs/front-matter). @@ -52,10 +53,10 @@ module.exports = { ### Syntax Highlighting -Although Greenwood does not provide any syntax highlighting by default, as demonstrated in the section above, it easy to add Prism markdown processing to your project. +Although Greenwood does not provide any syntax highlighting by default, as demonstrated in the section above, it is fairly easy to add something like Prism syntax highlighting to your project. -From there, just include a theme from a CSS file in your project, ex: +Here is an example of how to include a Prism theme from a CSS file into your project, ex: ```css /* https://prismjs.com/examples.html */ diff --git a/www/pages/docs/tech-stack.md b/www/pages/docs/tech-stack.md index d18e5a1a0..9ad74bf48 100644 --- a/www/pages/docs/tech-stack.md +++ b/www/pages/docs/tech-stack.md @@ -8,7 +8,7 @@ linkheadings: 3 ## Tech Stack -Greenwood uses a variety of open source JavaScript tools to help faciliate development and production building of Greenwood projects. By putting all these tools together and configuring them for you, Greenwood helps you focus more on what matters; building your project. Greenwood takes care of the performance and optimizations for you and provides static build output that you can host on any web server or cloud host, be it Netlify, S3 / CloudFront, Express, Apache, etc. It's entirely up to you and what fits your workflow the best. +**Greenwood** uses a variety of open source JavaScript tools to help faciliate development and production building of Greenwood projects. By putting all these tools together and configuring them for you, Greenwood helps you focus more on what matters; building your project. Greenwood takes care of the performance and optimizations for you and provides static build output that you can host on any web server or cloud host, be it Netlify, S3 / CloudFront, Express, Apache, etc. It's entirely up to you and what fits your workflow the best. ### NodeJS For development, Greenwood requires **NodeJS** (LTS) to be available on the command line. This allows us (and you!) to tap into all the amazing web development tools and libraries available on **npm** for your project. @@ -16,7 +16,7 @@ For development, Greenwood requires **NodeJS** (LTS) to be available on the comm To pre-render a site, we use [puppeteer](https://developers.google.com/web/tools/puppeteer/). ### Unified -For processing markdown, **Greenwood** taps into the unified ecosystem taking afvantage of and supporting tools like **remark** and **rehype** +For processing markdown, **Greenwood** taps into the unified ecosystem taking advantage of and supporting tools like **remark** and **rehype** ### Browsers diff --git a/www/pages/getting-started/branding.md b/www/pages/getting-started/branding.md index 4c1033cf1..c7d45bee8 100644 --- a/www/pages/getting-started/branding.md +++ b/www/pages/getting-started/branding.md @@ -16,9 +16,9 @@ In this section, we will add the following to your project: 1. Styles - Of course we want things to look nice too! We'll add some CSS to help hang things in just right the place. ### Web Components -Web Components are supported out of the box with Greenwood using `HTMLElement` or **LitElement**. For this guide, we'll use a "vanilla" custom element for our header, in _src/components/header.js_. +For this guide, we'll use a "vanilla" custom element for our footer, in _src/components/footer.js_. ```javascript -class HeaderComponent extends HTMLElement { +class FooterComponent extends HTMLElement { constructor() { super(); @@ -34,44 +34,49 @@ class HeaderComponent extends HTMLElement { // create templates that interpolate variables and HTML! getTemplate() { + const year = new Date().getFullYear(); + return ` <style> /* CSS will go here */ </style> - <header>Welcome to my Blog!</header> + <footer> + <h4>My Blog ©${year}</h4> + </footer> `; } } -customElements.define('app-header', HeaderComponent); +customElements.define('app-footer', FooterComponent); ``` Now we can use it in both our templates by: 1. Referencing our component via a `<script>` tag with the `type="module"` attribute -1. Using our custom element's tag name of `<app-header>` in our `<body>` +1. Using our custom element's tag name of `<app-footer` in our `<body>` ```html <html> <head> - <script type="module" src="/components/header.js"></script> + <script type="module" src="/components/footer.js"></script> </head> <body> - <app-header></app-header> - <content-outlet></content-outlet> + + <app-footer></app-footer> </body> </html> ``` +Now do the same for a `<app-header>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. -> You can now do the same for a `<footer>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. +> _You can find more information about component models and Greenwood [here](/docs/component-model/)._ ### CSS -OK, so we've made some content and some custom components, but what about the look and feel? Yes, of course, let's add some CSS! +OK, so we've made some content and some custom elements, but what about the look and feel? Yes, of course, let's add some CSS! For global styles like Google fonts, Bootstrap, background colors, or browser resets, let's create a file called _src/styles/theme.css_ that we can reference in all templates. @@ -101,9 +106,9 @@ Now we can `<link>` this CSS file into our template. Easy! πŸ’₯ </head> <body> - <app-header></app-header> - <content-outlet></content-outlet> + + <app-footer></app-footer> </body> </html> @@ -112,7 +117,7 @@ Now we can `<link>` this CSS file into our template. Easy! πŸ’₯ Within our components, we can easily add some styles right within the component definition itself. For example in our header component, we can style it like this and take advantage of [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). ```javascript -class HeaderComponent extends HTMLElement { +class FooterComponent extends HTMLElement { constructor() { super(); @@ -126,17 +131,19 @@ class HeaderComponent extends HTMLElement { getTemplate() { return ` <style> - header { + :host footer { color: blue; } </style> - <header>This is the header component.</header> + <footer> + <h4>My Blog ©${year}</h4> + </footer> `; } } -customElements.define('app-header', HeaderComponent); +customElements.define('app-footer', FooterComponent); ``` Taking this all the way with [the code from companion repo](https://vuejs.org/v2/guide/single-file-components.html), you should be able to get a result that looks like this: diff --git a/www/pages/getting-started/build-and-deploy.md b/www/pages/getting-started/build-and-deploy.md index 5b7c2841e..48bb06f79 100644 --- a/www/pages/getting-started/build-and-deploy.md +++ b/www/pages/getting-started/build-and-deploy.md @@ -7,7 +7,7 @@ index: 6 ## Build and Deploy -Congrats! After all your good work making your first site with Greenwood, it's now time to take it live! +Congrats! After all your good work making your first site with **Greenwood**, it's now time to take it live! ### Building For Production If you'll recall from the project setup section, we created an npm script for running Greenwood's build command. If you don't already have it in your _package.json_ you will want to add this to your scripts section. diff --git a/www/pages/getting-started/creating-content.md b/www/pages/getting-started/creating-content.md index f74c42a3e..a8b76b8d4 100644 --- a/www/pages/getting-started/creating-content.md +++ b/www/pages/getting-started/creating-content.md @@ -16,7 +16,7 @@ What we'll cover in this section: 1. Home Page Template: Single column layout for our home page 1. Blog Page Template: Two column layout for our blog posts -1. Blog Posts: A couple sample pages of contentΓ₯ written in markdown +1. Blog Posts: A couple sample pages of content written in markdown 1. Using Greenwood's built in local development server To go along with this guide, check out our [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started) that has a working example of all the code covered in this Getting Started guide. In the end, what you will end up with is a project looking something like this: diff --git a/www/pages/getting-started/index.md b/www/pages/getting-started/index.md index beeebf4bc..d5213b3a2 100644 --- a/www/pages/getting-started/index.md +++ b/www/pages/getting-started/index.md @@ -6,12 +6,12 @@ index: 3 --- ## Introduction -First off, thank you for taking the time to check out **Greenwood**! As a tool, we hope that you find Greenwood to provide a productive and frictionless developer experience for you that results in performant and engaging experiences for your users. Under the hood Greenwood is using the power of the modern web ([and friends !](/docs/tech-stack/)) to drive a modern development workflow that helps you deliver a modern and perfmant applicatiot site for your users... using the web languages you already know. +First off, thank you for taking the time to check out **Greenwood**! Under the hood Greenwood is taking advantage of the power of the modern web ([and friends !](/docs/tech-stack/)) to drive a modern development workflow that helps you deliver a modern, performant and pleasent experience for your users... using the web languages you already know! ## Your First Project -To get things started, we first want to make sure everyone can get their first project up and running as easily and quickly as possible, and so through this guide, we will help walk you through everything you need to get started with your first project, including: +To get things started, we first want to make sure everyone can get their first project up and running as easily and quickly as possible, and so through this guide, we will walk through everything you need to get started with your first project, including: -1. Setting up your workspace and installing Greenwood +1. Setting up your project workspace and installing Greenwood 1. Reviewing key concepts of Greenwood 1. Creating content and developing locally 1. Authoring Web Components and adding CSS diff --git a/www/pages/getting-started/next-steps.md b/www/pages/getting-started/next-steps.md index 237e81ada..388ef6264 100644 --- a/www/pages/getting-started/next-steps.md +++ b/www/pages/getting-started/next-steps.md @@ -7,11 +7,11 @@ index: 7 ## Next Steps -## About Greenwood +### Learn More Thank you so much for taking the time to go through our Getting Started guide and we hope it has given you a good overview of how to work with Greenwood and what some of the possibilities are. To learn more about the project we encourage you to review our [API docs](/docs/) to learn more about how you can use Greenwood or check out our repo to see what we're [working on next](https://github.com/ProjectEvergreen/greenwood/projects), or if you need to reach out, feel free to [open an issue](https://github.com/ProjectEvergreen/greenwood/issues)! -## Configuration -Although configuration is a topic all on its own, we do want to walk through setting up a configuration file for your project. As you may have noticed, the `<title>` of the site being made during the Getting Started section said _Greenwood App_. This is what Greenwood's configuration can be used for. +### Configuration +Although configuration is a topic all on its own, we do want to walk through setting up a configuration file for your project. As you may have noticed, the `<title>` of the site being made during the Getting Started section said _My Personal Blog_. This is what Greenwood's configuration can be used for. To change the title of the project (like in the companion repo), create a (NodeJS) module called _greenwood.config.js_ at the root of your project and configure the `export` object with a title property. @@ -23,20 +23,11 @@ module.exports = { That's it! You can learn more about configuring Greenwood [here](/docs/configuration). -## Companion Repo -You may have noticed that the Getting Started [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) itself is a bit more of a full fledged example then captured in this guide, like with the use use of ["Single File Components"](https://vuejs.org/v2/guide/single-file-components.html) (SFCs). - -This is was intentional for a couple of reasons: -- _Education_: There is always more than one way to solve a problem, and so we felt that the SFC approach was best for the guide so as to keep the number of steps needed as few and direct as possible. -- _Development_: The other side of the coin is that for us having the CSS in an external file helps with development and maintenance. _This is just a preference_. Please choose what fits your workflow best. -- _Maintenance_: We want to keep a loose coupling between the guide and the repository to avoid additional overhead maintaining the two and keeping them in sync. The goal of this guide is to focus on the overall experience of creating your first Greenwood project, not worrying about theming or project structure, since Greenwood generally supports just about any folder organization you could want and has no opinions on styles. - -## Resources +### Resources Since Greenwood aims to be a web "first" tool, all the great web development resources for the web already apply to Greenwood! Below are some resources that we think might be useful as part of a broader understanding of the topic of web development and that we have found invalualable for our own development and learning. - [MDN](https://developer.mozilla.org/) - Mozilla Developer Network has some of the best technical and sample content available for learning about all the features and capabilities of the web. - [Web Components](https://www.webcomponents.org/introduction) - A brief introduction to the specs that make up Web Components. - [CSS / Shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) - [CanIUse.com](https://caniuse.com/) - Find out what browser support various JS and CSS features have. -- [LitElement](https://lit-element.polymer-project.org/) / [LitHtml](https://lit-html.polymer-project.org/) - Helper libraries for working with Web Components that are available with Greenwood. - [VSCode](https://code.visualstudio.com/) - A very popular IDE for JavaScript development with a lot of great plugins and integrations for web development related tools. - [Git](https://git-scm.com/) / [GitHub](https://github.com/): Although git != GitHub, version control plays a very important part in modern software development. GitHub in particular provides a lot of great integrations with tools like [CircleCI](https://circleci.com/) and [GitHub Actions](https://github.com/features/actions) for CI, and [Netlify](https://www.netlify.com/) that can greatly automate a lot of the deployment process like building and deploying your apps. We plan to provide guides for these in the future, so stay tuned! diff --git a/www/pages/getting-started/project-setup.md b/www/pages/getting-started/project-setup.md index 7e4b574c9..d3062e305 100644 --- a/www/pages/getting-started/project-setup.md +++ b/www/pages/getting-started/project-setup.md @@ -7,7 +7,7 @@ linkheadings: 3 --- ## Overview -In the [previous section](/getting-started/), we shared a little bit about what Greenwood is and the high level goals of this guide. Now we are ready to help you start your first project! +In the [previous section](/getting-started/), we shared a little bit about what **Greenwood** is and the high level goals of this guide. Now we are ready to help you start your first project! In this section, we will kick off our Greenwood project by: @@ -18,7 +18,7 @@ In this section, we will kick off our Greenwood project by: > _This guide assumes you are starting from an **empty** directory (`git init` being the exception). We recommend going through this guide once to understand the basics and from there, you can explore our [documentation](/docs/) to learn more about all of Greenwood's capabilities._ ### Installing Greenwood -First thing we need to do is setup our project for installing Greenwood. With Greenwood installed, you will be able to use its CLI to power the development of your project though automated scripts and configuration. +With Greenwood installed, you will be able to use its CLI to power the development of your project though automated scripts and configuration. First thing we need to do is generate a _package.json_ file so we can install Greenwood. The easist way to do that is by running `npm init` from the root directory of where you want to start your project: ```shell From 407e35db9493242c4909ce8bdff5dba0b89f1aff Mon Sep 17 00:00:00 2001 From: Owen Buckley <owenbuckley13@gmail.com> Date: Wed, 30 Dec 2020 11:02:28 -0500 Subject: [PATCH 9/9] final docs tweaks --- www/pages/docs/layouts.md | 4 ++-- www/pages/docs/tech-stack.md | 6 +++--- www/pages/getting-started/branding.md | 26 +++++++++++++------------ www/pages/getting-started/next-steps.md | 2 +- 4 files changed, 20 insertions(+), 18 deletions(-) diff --git a/www/pages/docs/layouts.md b/www/pages/docs/layouts.md index dfdbd2b61..df60a3309 100644 --- a/www/pages/docs/layouts.md +++ b/www/pages/docs/layouts.md @@ -48,13 +48,13 @@ Below is an example of a simple _page.html_. You can just copy / paste this to You can create more templates and use them for pages by doing two things: 1. Create a new template, e.g. _templates/blog-post.html_ -1. In your frontmatter, specify to use that template +1. In your frontmatter, specify that `template` ```md --- template: 'blog-post' --- - ## My blog Post + ## My Blog Post Lorum Ipsum ``` diff --git a/www/pages/docs/tech-stack.md b/www/pages/docs/tech-stack.md index 9ad74bf48..3f7820222 100644 --- a/www/pages/docs/tech-stack.md +++ b/www/pages/docs/tech-stack.md @@ -11,7 +11,7 @@ linkheadings: 3 **Greenwood** uses a variety of open source JavaScript tools to help faciliate development and production building of Greenwood projects. By putting all these tools together and configuring them for you, Greenwood helps you focus more on what matters; building your project. Greenwood takes care of the performance and optimizations for you and provides static build output that you can host on any web server or cloud host, be it Netlify, S3 / CloudFront, Express, Apache, etc. It's entirely up to you and what fits your workflow the best. ### NodeJS -For development, Greenwood requires **NodeJS** (LTS) to be available on the command line. This allows us (and you!) to tap into all the amazing web development tools and libraries available on **npm** for your project. +For development, Greenwood requires **NodeJS** (LTS) to be available on the command line. This allows us (and you!) to tap into all the amazing web development tools and libraries available on **npm**. To pre-render a site, we use [puppeteer](https://developers.google.com/web/tools/puppeteer/). @@ -20,11 +20,11 @@ For processing markdown, **Greenwood** taps into the unified ecosystem taking ad ### Browsers -Web standards like Web Components and ES Modules, coupled with network standards like HTTP caching, makes the browser a great platfoprm not only for the browsing experience, but also for the developer experience as well. Philosohies adopted by Greenwood like Bundleless development take full advantage of what the platform offers to enabled rapid development as well as ensure performant and optimized sites for users. +Web standards like Web Components and ES Modules, coupled with network standards like HTTP caching, makes the browser a great platform not only for the browsing experience, but for the developer experience as well. Philosophies adopted by Greenwood like bundleless development take full advantage of what the platform offers, so as to enable rapid development as well as ensure performant and optimized sites for users. ### Rollup -Greenwood makes use of [**Rollup**](https://rollupjs.org/) as part of build phase to optimize all the HTML / CSS and JavaScript for a given project. This affords **Greenwood** the ability to bundle, minify and otherwise prepare the site for final deployement. +Greenwood makes use of [**Rollup**](https://rollupjs.org/) as part of build phase to optimize all the HTML / CSS and JavaScript for a given project. This affords **Greenwood** the ability to bundle, minify and otherwise prepare the site for final deployement in the best way possible based on the code you've written. ### Development diff --git a/www/pages/getting-started/branding.md b/www/pages/getting-started/branding.md index c7d45bee8..f409783b7 100644 --- a/www/pages/getting-started/branding.md +++ b/www/pages/getting-started/branding.md @@ -16,23 +16,25 @@ In this section, we will add the following to your project: 1. Styles - Of course we want things to look nice too! We'll add some CSS to help hang things in just right the place. ### Web Components -For this guide, we'll use a "vanilla" custom element for our footer, in _src/components/footer.js_. +For this guide, we'll use a "vanilla" custom element for our footer. + +Start by creating a file called _src/components/footer.js_ with the following code in it. ```javascript class FooterComponent extends HTMLElement { constructor() { super(); - // create a Shadow DOM + // creates a Shadow DOM root this.root = this.attachShadow({ mode: 'closed' }); } // run some code when the component is ready - // like initializing our component's DOM + // like initializing our component's DOM / innerHTML connectedCallback() { this.root.innerHTML = this.getTemplate(); } - // create templates that interpolate variables and HTML! + // create templates that can interpolate variables and HTML! getTemplate() { const year = new Date().getFullYear(); @@ -51,9 +53,9 @@ class FooterComponent extends HTMLElement { customElements.define('app-footer', FooterComponent); ``` -Now we can use it in both our templates by: -1. Referencing our component via a `<script>` tag with the `type="module"` attribute -1. Using our custom element's tag name of `<app-footer` in our `<body>` +Now we can use it in a template by: +1. Referencing our component file via a `<script>` tag with the `type="module"` attribute +1. Using our custom element's tag name of `<app-footer>` in our `<body>` ```html <html> @@ -71,20 +73,18 @@ Now we can use it in both our templates by: </html> ``` -Now do the same for a `<app-header>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. +Now you can do the same for an `<app-header>`. See the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started/) for a complete working example. > _You can find more information about component models and Greenwood [here](/docs/component-model/)._ ### CSS OK, so we've made some content and some custom elements, but what about the look and feel? Yes, of course, let's add some CSS! -For global styles like Google fonts, Bootstrap, background colors, or browser resets, let's create a file called _src/styles/theme.css_ that we can reference in all templates. +For global styles like Google fonts, Bootstrap, background colors, or browser resets, let's create a file called _src/styles/theme.css_ that we can reference in all our templates. Here are some styles you can add to your site to snap things into place a little bit. ```css /* theme.css */ -@import url('//fonts.googleapis.com/css?family=Source+Sans+Pro&display=swap'); - * { margin: 0; padding: 0; @@ -101,8 +101,10 @@ Now we can `<link>` this CSS file into our template. Easy! πŸ’₯ <html> <head> - <script type="module" src="/components/header.js"></script> + <link rel="preconnect" href="https://fonts.gstatic.com"> + <link rel="stylesheet" href="//fonts.googleapis.com/css2?family=Source+Sans+Pro&display=swap"> <link rel="stylesheet" href="/styles/theme.css"> + <script type="module" src="/components/header.js"></script> </head> <body> diff --git a/www/pages/getting-started/next-steps.md b/www/pages/getting-started/next-steps.md index 388ef6264..ca686b5ca 100644 --- a/www/pages/getting-started/next-steps.md +++ b/www/pages/getting-started/next-steps.md @@ -30,4 +30,4 @@ Since Greenwood aims to be a web "first" tool, all the great web development res - [CSS / Shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) - [CanIUse.com](https://caniuse.com/) - Find out what browser support various JS and CSS features have. - [VSCode](https://code.visualstudio.com/) - A very popular IDE for JavaScript development with a lot of great plugins and integrations for web development related tools. -- [Git](https://git-scm.com/) / [GitHub](https://github.com/): Although git != GitHub, version control plays a very important part in modern software development. GitHub in particular provides a lot of great integrations with tools like [CircleCI](https://circleci.com/) and [GitHub Actions](https://github.com/features/actions) for CI, and [Netlify](https://www.netlify.com/) that can greatly automate a lot of the deployment process like building and deploying your apps. We plan to provide guides for these in the future, so stay tuned! +- [Git](https://git-scm.com/) / [GitHub](https://github.com/): Although git != GitHub, version control plays a very important part in modern software development. GitHub in particular provides a lot of great integrations with tools like [CircleCI](https://circleci.com/) and [GitHub Actions](https://github.com/features/actions) for CI, and [Netlify](https://www.netlify.com/) that can greatly automate a lot of the deployment process like building and deploying your apps. We plan to provide guides for these in the future, so stay tuned! \ No newline at end of file