From 6fbeaa016ad732734c6d205309b33e654ab7ad38 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Fri, 6 Aug 2021 11:45:24 -0400 Subject: [PATCH 1/6] forgot to link to actual repo --- www/pages/guides/theme-packs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/pages/guides/theme-packs.md b/www/pages/guides/theme-packs.md index ded5dd762..17b1ea073 100644 --- a/www/pages/guides/theme-packs.md +++ b/www/pages/guides/theme-packs.md @@ -7,7 +7,7 @@ index: 2 ## Creating a Theme Pack -Introduced as a concept in the [Context Plugin docs](/plugins/context/), a theme pack is what Greenwood uses to refer to a plugin that aims to provide a set of reasuale templates, pages and more to a user (think of [**CSS Zen Garden**](http://www.csszengarden.com/)). A good example (and the one used in this guide!) is greenwood-starter-presentation, which provides the starting point for creating a slide deck entirely from markdown, using Greenwood! +Introduced as a concept in the [Context Plugin docs](/plugins/context/), a theme pack is what Greenwood uses to refer to a plugin that aims to provide a set of reasuale templates, pages and more to a user (think of [**CSS Zen Garden**](http://www.csszengarden.com/)). A good example (and the one used in this guide!) is [greenwood-starter-presentation](https://github.com/thescientist13/greenwood-starter-presentation), which provides the starting point for creating a slide deck entirely from markdown, using Greenwood! > _Support for pages [coming soon](https://github.com/ProjectEvergreen/greenwood/issues/681)_! From 16233dee89aab8e3d0b047fdee88abf13fe7a44b Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Fri, 6 Aug 2021 18:40:55 -0400 Subject: [PATCH 2/6] remove copy past comments and amend development example to handle paths with query strings --- www/pages/guides/theme-packs.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/www/pages/guides/theme-packs.md b/www/pages/guides/theme-packs.md index 17b1ea073..d6183ad39 100644 --- a/www/pages/guides/theme-packs.md +++ b/www/pages/guides/theme-packs.md @@ -146,7 +146,6 @@ module.exports = () => [{ And our final _greenwood.config.js_ would look like this, which add a "one-off" [resource plugin](/plugins/resource/) to tell Greenwood to route requests to your theme pack files from their _node_modules_ path to the source directory of your repository for development. ```js -// shared from another test const myThemePackPlugin = require('./my-theme-pack'); const packageName = require('./package.json').name; const path = require('path'); @@ -163,7 +162,7 @@ class MyThemePackDevelopmentResource extends ResourceInterface { } async resolve(url) { - return Promise.resolve(url.replace(`/node_modules/${packageName}/dist/`, path.join(process.cwd(), '/src/'))); + return Promise.resolve(this.getBareUrlPath(url).replace(`/node_modules/${packageName}/dist/`, path.join(process.cwd(), '/src/'))); } } @@ -196,7 +195,7 @@ When it comes to publishing, it should be fairly straightforward, you'll just wa "dist/" ], "scripts": { - "prepublish": "rm -rf dist/ && mkdir dist/ && cd src/ && cp -rv templates ../dist && cp -rv pages ../dist" + "prepublish": "rm -rf dist/ && mkdir dist/ && cd src/ && cp -rv templates ../dist" } } ``` @@ -210,7 +209,6 @@ With the above in place the package published, user's would just need to do the ``` 1. Add the plugin to their _greenwood.config.js_ ```js - // shared with another test develop.plugins.context const myThemePackPlugin = require('my-theme-pack'); module.exports = { From 0d8399950d4a8be8d7d2b9ba41c63a52e797ed13 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Tue, 10 Aug 2021 16:54:01 -0400 Subject: [PATCH 3/6] theme pack guide clarifications and added FAQ --- www/pages/guides/theme-packs.md | 102 +++++++++++++++++--------------- www/pages/plugins/context.md | 7 ++- 2 files changed, 59 insertions(+), 50 deletions(-) diff --git a/www/pages/guides/theme-packs.md b/www/pages/guides/theme-packs.md index d6183ad39..60676c0a9 100644 --- a/www/pages/guides/theme-packs.md +++ b/www/pages/guides/theme-packs.md @@ -7,24 +7,24 @@ index: 2 ## Creating a Theme Pack -Introduced as a concept in the [Context Plugin docs](/plugins/context/), a theme pack is what Greenwood uses to refer to a plugin that aims to provide a set of reasuale templates, pages and more to a user (think of [**CSS Zen Garden**](http://www.csszengarden.com/)). A good example (and the one used in this guide!) is [greenwood-starter-presentation](https://github.com/thescientist13/greenwood-starter-presentation), which provides the starting point for creating a slide deck entirely from markdown, using Greenwood! +Introduced as a concept in the [Context Plugin docs](/plugins/context/), a theme pack is what Greenwood uses to refer to a plugin that aims to provide a set of reasuale templates, pages and more to a user (think of [**CSS Zen Garden**](http://www.csszengarden.com/)). A good example (and the one this guide is based on) is [**greenwood-starter-presentation**](https://github.com/thescientist13/greenwood-starter-presentation), which provides the starting point for creating a [slide deck entirely from markdown](https://github.com/thescientist13/knowing-your-tco), using Greenwood! -> _Support for pages [coming soon](https://github.com/ProjectEvergreen/greenwood/issues/681)_! ### Prerequistes This guide will walk through the process of setting up Greenwood to support the developing and publishing of your package (theme pack) to npm. To try and focus on just the theme pack aspects, this guide assumes a couple things: -- You are already familiar with [setting up](/getting-started/) a Greenwood project. -- You are familiar with [publishing packages to npm](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages). -- Assumes a Unix "like" environment (in regards to commands and file path examples used), though the same can definifitely be done on Windows. +1. You are already familiar with [setting up](/getting-started/) a Greenwood project. +1. You are familiar with [publishing packages to npm](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages). +1. Assumes a Unix "like" environment (in regards to commands and file path examples used), though the same can definifitely be done on Windows. We encourage using Greenwood to develop your theme pack mainly so that you can ensure a seamless experience when publishing to npm knowing that things should just work. ™️ ### Project Setup For the sake of development, you can create as much as you need to recreate a user workspace and to simulate what your theme pack would look like. Think of it like creating a [Storybook](https://storybook.js.org/) for your theme pack. -For this guide, we will be publishing _templates/_ and _styles/_ to npm, and so _pages/_ will just be used as a way to pull in the template for local development and testing purposes. + +For this guide, we will be publishing _templates/_ and _styles/_ to npm. The _pages/_ diretory is just being used to pull in the template for local development and testing purposes for the plugin author. ```shell src/ pages/ @@ -72,8 +72,10 @@ _blog-post.html_ ```html + + - + @@ -110,41 +112,7 @@ You're all ready for development! 🙌 ### Development -The main consideration needed for development is that your files won't be in _node_modules_, which is what the case would be for users when you publish. So for that reason, we need to add a little boilerplate to _my-theme-pack.js_. There might be others way to solve it, but it just checks if the packages is installed and: -1. If it _is_ installed, then use `__dirname` (which would resolve to somewhere inside _node_modules_) as the base path -1. If it _is not_ installed (like for local development) then you can use use whatever location you have defined in your repository. Most common would just be to use `process.cwd` - -So using our current example, our final _my-theme-pack.js_ would look like this: -```js -const os = require('os'); -const path = require('path'); -const packageJson = require('./package.json'); -const { spawnSync } = require('child_process'); - -module.exports = () => [{ - type: 'context', - name: 'my-theme-pack:context', - provider: () => { - const { name } = packageJson; - const baseDistDir = `node_modules/${name}/dist`; - const command = os.platform() === 'win32' ? 'npm.cmd' : 'npm'; - const ls = spawnSync(command, ['ls', name]); - const isInstalled = ls.stdout.toString().indexOf('(empty)') < 0; - - const templateLocation = isInstalled - ? path.join(__dirname, `${baseDistDir}/templates`) - : path.join(process.cwd(), 'src/templates'); - - return { - templates: [ - templateLocation - ] - }; - } -}]; -``` - -And our final _greenwood.config.js_ would look like this, which add a "one-off" [resource plugin](/plugins/resource/) to tell Greenwood to route requests to your theme pack files from their _node_modules_ path to the source directory of your repository for development. +The main consideration needed for development is that your files won't be in _node_modules_, which is what the case would be for users when you publish. So for that reason, we need to add a little boilerplate to the _greenwood.config.js_ in your project to add a "one-off" [resource plugin](/plugins/resource/) to tell Greenwood to resolve requests to your theme pack files to the directory in your project you're using for development. ```js const myThemePackPlugin = require('./my-theme-pack'); const packageName = require('./package.json').name; @@ -182,7 +150,7 @@ module.exports = { ### Publishing -When it comes to publishing, it should be fairly straightforward, you'll just want to do the following +When it comes to publishing, it should be fairly straightforward, and you'll just want to do the following: 1. Add _dist/_ to _.gitignore_ (or whatever `files` location you want to use for publishing) 1. Add a `prepublish` script to your _package.json_ to create the _dist/_ directory with all the needed _templates/_ and _styles/_ ```json @@ -195,13 +163,16 @@ When it comes to publishing, it should be fairly straightforward, you'll just wa "dist/" ], "scripts": { - "prepublish": "rm -rf dist/ && mkdir dist/ && cd src/ && cp -rv templates ../dist" + "prepublish": "rm -rf dist/ && mkdir dist/ && rsync -rv --exclude 'pages/' src/ dist" } } ``` +1. Now, when you run `npm publish` a fresh _dist/_ folder will be made and [included in your package](https://unpkg.com/browse/greenwood-starter-presentation/) -### Installation and Usage -With the above in place the package published, user's would just need to do the following +### Installation and Usage for Users +With the above in place the package published, you're now ready to share your theme pack with other Greenwood users! + +For users, they would just need to do the following: 1. Install the plugin from npm ```shell @@ -223,9 +194,44 @@ With the above in place the package published, user's would just need to do the template: 'blog-post' --- - My Blog Post using Theme Packs! + My Blog Post using Theme Packs! 💯 ``` Success! 🥳 -> _Don't forget, user's can also [include additional CSS / JS files in their frontmatter](/docs/front-matter/#imports), to further extend, customize, and override your templates!_ \ No newline at end of file +> _Don't forget, user's can also [include additional CSS / JS files in their frontmatter](/docs/front-matter/#imports), to further extend, customize, and override your templates!_ + + +### FAQ + +#### _Can I include pages as part of a theme pack?_ + +Support for [including pages as part of a theme pack](https://github.com/ProjectEvergreen/greenwood/issues/681) is planned and coming soon, pretty much as soon as we can support [external data sources](https://github.com/ProjectEvergreen/greenwood/issues/21) in the CLI. + + +#### _I'm getting an (Rollup) error when trying to build or test my theme pack for production_ +If you try and run `yarn build` or `yarn serve` in a repo where you are creating the theme pack, as per the guide here, you may see this error if you reference assets like `