diff --git a/docs/blog.md b/docs/blog.md index c1ab29f95..e7757e047 100644 --- a/docs/blog.md +++ b/docs/blog.md @@ -62,6 +62,6 @@ The following table shows all available options: | option | description | default | | -------------- | ------------------------------------------------------ | --------- | -| `name` | define the name for the created post | 'blog-X' | -| `target` | define the target directory for the new post file | 'blog' | -| `metaDataFile` | use a meta data yaml template from a file for the post | undefined | +| `name` | Define the name for the created post | 'blog-X' | +| `target` | Define the target directory for the new post file | 'blog' | +| `metaDataFile` | Use a meta data yaml template from a file for the post | undefined | diff --git a/docs/getting-started.md b/docs/getting-started.md index cdb3a170c..f51201697 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -112,7 +112,9 @@ Now, it is possible to loop through the links inside the template by opening the At this point, you have your Angular project with Scully successfully installed. -#### IMPORTANT: _Scully requires the distribution files in the `./dist/my-scully-app` folder._ +#### IMPORTANT: + +_Scully requires the distribution files in the `./dist/my-scully-app` folder._ **NOTE:** If the angular application outputs the distribution files directly into the root folder `./dist`. Scully is not able to copy all files. This is an OS file-system issue. diff --git a/docs/getting-started_es.md b/docs/getting-started_es.md index cf26ff6a1..1b39071fa 100644 --- a/docs/getting-started_es.md +++ b/docs/getting-started_es.md @@ -57,9 +57,13 @@ CREATE scully.config.js (65 bytes) UPDATE package.json (1507 bytes) ``` -#### IMPORTANTE: _Scully requiere que el router esté presente en su aplicación, no olvide agregarlo._ +#### IMPORTANTE: -#### IMPORTANTE: _Scully requiere que los archivos de distribución estén en una subcarpeta de `./dist`_ +_Scully requiere que el router esté presente en su aplicación, no olvide agregarlo._ + +#### IMPORTANTE: + +_Scully requiere que los archivos de distribución estén en una subcarpeta de `./dist`_ Si tienes una aplicación Angular, que genera los archivos de distribución directamente en la raíz de `./dist` Scully no puede copiar todos los archivos del dist. Este es un problema del sistema de archivos del sistema operativo. No podemos copiar recursivamente en una subcarpeta de dist. La solución es configurar la opción `architect-> build-> options-> outputPath` en una subcarpeta. diff --git a/docs/learn.md b/docs/learn.md index 10e21db09..02d61d7fb 100644 --- a/docs/learn.md +++ b/docs/learn.md @@ -1,3 +1,8 @@ -# Scully Learn +--- +title: Learn +order: 1100 +--- -[Full Documentation ➡️](scully.md) +# Learn Scully + +Coming soon! diff --git a/docs/plugins.md b/docs/plugins.md index d7c4560a9..ae390f5f8 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -5,62 +5,75 @@ order: 700 # Plugins -Scully uses a plugin system to allow users to define new ways for Scully to pre-render your app. There are three main +Scully uses a plugin system that allows users to define new ways for Scully to pre-render an application. There are three main types of plugins: 1. [Router Plugins](#router-plugin) 1. [Render Plugins](#render-plugin) 1. [File Handler Plugins](#file-plugin) -See [how to register a plugin](#register-plugin). - -See our [Recommended Plugins](recommended-plugins.md) page to find a list of available plugins. +You can find a list of available plugins in the [recommended plugins](recommended-plugins.md) documentation. --- -## Register Plugin +## Registering a Plugin -The `registerPlugin` is the method created to add new plugins to scully. This method has 4 parameters: +The `registerPlugin` method adds a new plugin to Scully. This method has 4 parameters: - type - name - plugin - validator -### type: PluginTypes +### type: string -`type` is a reference to the type of plugin. It could be `render`, `router` or `fileHandler`. +`type` - Indicates the type of plugin. It can be `render`, `router` or `fileHandler`. ### name: string -`name` is a reference to the name of the plugin. +`name` - The plugin's name. ### plugin: any -`plugin` is a reference to the plugin function. +`plugin` - The plugin's function. ### validator: function -`validator` is a reference to the validations function. It should return an array of errors. +`validator` - A validations function. It should return an array of errors. + +> Tip: Add color to the validator errors by using the colors in the `log.ts` file. -> Cool tip: you can add color to the validator errors using the colors inside the `log.ts` file. +##### Example: -### IMPORTANT +```typescript +import {yellow} from '@scullyio/scully/utils/log'; -Scully plugins are files with `.js` extension, which should be exported and used in `scully.config.js` -file using the `require()` method. +// Omitted code ... -## Router Plugins +const validator = async options => { + const errors = []; -### What is a Router Plugin? + if (options.numberOfPages && typeof options.numberOfPages !== 'number') { + errors.push( + `my-custom-plugin numberOfPages should be a number, not a ${yellow(typeof options.numberOfPages)}` + ); + } + + return errors; +}; +``` -Scully needs **router plugins** to discover data needed to pre-render your app's views. Any route that has a route -parameter in it will require you to configure a **router plugin** that teaches Scully how to get the data needed for -those route parameters. +### IMPORTANT: -Suppose your app has a route `{path: 'user/:userId', component: UserComponent}`. In order for Scully to pre-render your -app, it needs to know the complete list of User IDs that will be used in that route parameter `:userId`. If your app -had 5 users with the IDs 1, 2, 3, 4, and 5, then Scully would need to render the following routes: +_A Scully plugin must have a `.js` file extension, and it should be exported. In order to be used, it has to be required in the `scully.config.js` file by using the `require()` method._ + +## Router Plugins + +Any route in the application that contains a router-parameter must be configure in a **router plugin**. The plugin teaches Scully how Scully how to get the required data to be pre-render in the web-pages from the route-params. + +Suppose your application has a route like this: `{path: 'user/:userId', component: UserComponent}`. In order for Scully to pre-render the +website, it needs to know the complete list of User IDs that will be used in that route parameter `:userId`. If the app +had 5 users with the IDs 1, 2, 3, 4, and 5; Scully would need to render the following routes: ``` /user/1 @@ -70,7 +83,7 @@ had 5 users with the IDs 1, 2, 3, 4, and 5, then Scully would need to render the /user/5 ``` -A **router plugin** is used to convert the raw route config into a list of routes that Scully can then crawl/render. +A **router plugin** is used to convert the raw route-config into a list of routes that Scully can then crawl/render. ## `HandledRoute` interface @@ -84,35 +97,31 @@ export interface HandledRoute { } ``` -The `HandledRoute` interface provides you properties to develop your own plugin. +The `HandledRoute` interface provides the needed properties to develop your own plugin. ### route: string -`route` is a reference to the route to handle in your project. +`route` - An application route to be handled by Scully. ### type: RoutesTypes -`type` is a reference of the router plugin. - -It should be to the type of the existing Route plugin. +`type` - Indicates the type of plugin. It can be `render`, `router` or `fileHandler`. ### postRenderers?: string[] -`postRenderers` is a reference to plugins you want to be executed after Scully's render process. +`postRenderers` - Array of plugins to be executed after Scully's render process. ### templateFile?: string -`templateFile` is a reference to the name of the template to render the content. +`templateFile` - The file's name containing the template to be rendered. -**Important**, It's not a reference to the angular template.\_ +### IMPORTANT: -### data?: RouteData +_It is not a reference to the angular template._ -`data` is a reference to all the metadata we want to add into the static file, it could be: +### data?: RouteData -- title -- author -- A custom property. +`data` - the metadata to be added into the static file. ```typescript export interface RouteData { @@ -124,25 +133,27 @@ export interface RouteData { ### Router Plugin Interface -A **router plugin** is a function that returns a `Promise`. Let's look at the interface of the route -plugin as well as the `HandledRoute`. +A **router plugin** is a function that returns a `Promise`. The `HandledRoute` interface looks like this: ```typescript interface HandledRoute { route: string; } +``` + +A router plugin function should be as follows: +```typescript function exampleRouterPlugin(route: string, config: any): Promise { - // must return a promise here + // Must return a promise } ``` -The `HandledRoute[]` gets added into the `scully-routes.json` that is generated when you run `npm run scully`. +The `HandledRoute[]` gets added into the `scully-routes.json` file generated by the `npm run scully` command. -### How To Make A Router Plugin +### Making A Router Plugin -In our previous example of an app with the route `/user/:userId` where we have five distinct userIds, here is a **router -plugin** that would turn the raw route into five distinct HandledRoutes. +Lets implement the **router plugin** that turns the raw route into five distinct HandledRoutes from the previous example of an application containing the following route: `/user/:userId`. ```javascript const {registerPlugin} = require('@scullyio/scully'); @@ -156,16 +167,17 @@ function userIdPlugin(route: string, config = {}): Promise { {route: '/user/5'}, ]); } -// DON'T FORGET THIS STEP + +// DO NOT FORGET TO REGISTER THE PLUGIN const validator = async conf => []; registerPlugin('router', 'userIds', userIdPlugin, validator); ``` -Once we have built a plugin, we can configure our `scully.config.js` to use our plugin. +After implementing the plugin, configure the `scully.config.js` in order to use it. -### How To Configure A Router Plugin +### Configuring a Router Plugin -The following configuration uses our `userIds` router plugin to get the `HandledRoute[]` for our app: +The following configuration uses the `userIds` router plugin to get the `HandledRoute[]` for the above implementation: ```javascript // scully.config.js @@ -179,8 +191,8 @@ exports.config = { }; ``` -The following is an example that uses the [jsonplaceholder](http://localhost:8200/) to fetch a list of -User IDs for my app. It uses the [JSON Plugin](../scully/routerPlugins/jsonRoutePlugin.ts) which is already part of Scully. +The following example uses the [jsonplaceholder](http://localhost:8200/) to fetch a list of +user ID's for the application. It uses the [JSON Plugin](../scully/routerPlugins/jsonRoutePlugin.ts) which is part of Scully. ```javascript // scully.config.js @@ -198,14 +210,17 @@ exports.config = { }; ``` -The above snippet tells Scully that when it sees a route that matches `/user/:userId` it should use the `json` plugin -to fetch some JSON via HTTP. After declaring the type of `json`, the above example has a key `userId`. The value for -`userId` contains two pieces of data. First, the url that the JSON plugin should go to to get this required JSON. The -second is `property`. The JSON plugin will pluck the provided property name from each of the items in the array. This -means that the array returned by the jsonplaceholder api will each have an `id` property. So instead of returning a list -users, it will return a list of userIds. +The above example tells Scully to use the `json` plugin for fetching some JSON data via HTTP whenever it finds a route matching `/user/:userId`. +The `userId`'s value contains two pieces of data. First, the url that the JSON plugin should go to in order to get the required JSON. +Second, the `id` property. -The JSON Plugin will optionally accept also a header configuration where you can set specific header that you may have to sent when requesting an API: +The JSON plugin will pluck the provided property name from each of the items in the `HandledRoute[]` array. In other words, +the data array returned by the `jsonplaceholder` API, each containing an `id` property. Therefore, returning return a list of `userIds` instead of a list +of users. + +The JSON plugin also accepts any header needed when making an API request. + +##### Example: ```javascript // scully.config.js @@ -227,38 +242,35 @@ exports.config = { ### Router Plugin Examples -For those looking to build router plugins for their app, here are links to the built-in **router plugins** in Scully: +Here are some links to built-in **router plugins** in Scully: - [JSON Plugin](../scully/routerPlugins/jsonRoutePlugin.ts) - [Content Folder Plugin](../scully/routerPlugins/contentFolderPlugin.ts) -[Back to top](#plugins) - --- ## Render Plugins -### What is a Render Plugin? +A **render plugin** is used to transform the rendered HTML. -A **render plugin** is used to transform the HTML that your app rendered. After your Angular app renders the page, -that rendered content/HTML is passed to a **render plugin** where it can be further modified. An example of why you -would want to use a render plugin: to transform a page that contains markdown into a page that contains the rendered -markdown. +After the Angular application renders, the HTML content is passed to a **render plugin** where it can be further modified. + +A render plugin could be used to transform a page containing markdown into a page that renders it. ### Render Plugin Interface A **render plugin** is a function that returns a `Promise`. The string in the promise must be the transformed -HTML. Here is what the interface looks like: +HTML. The interface looks like this: ```typescript function exampleContentPlugin(HTML: string, route: HandledRoute): Promise { - // must return a promise here + // Must return a promise } ``` -### How To Make A Render Plugin +### Making A Render Plugin -The following is a sample **render plugin** that adds a title to the head of a page if it doesn't find one. +The following **render plugin** example adds a title to the header to a page if it does not find one. ```typescript const {registerPlugin} = require('@scullyio/scully'); @@ -273,17 +285,17 @@ function defaultTitlePlugin(html, route) { } return Promise.resolve(html); } -// DON'T FORGET THIS STEP + +// DON NOT FORGET REGISTER THE PLUGIN const validator = async conf => []; registerPlugin('render', 'defaultTitle', defaultTitlePlugin, validator); module.exports.defaultTitlePlugin = defaultTitlePlugin; ``` -In this example, the HTML that the Angular app rendered is transformed to include a title (if one wasn't found). This -is the primary function of a render plugin. +In the above example, the Angular app's HTML content is transformed to include a title because anyone was found. -Here is another example that would replace any instances of `:)` with a smiley emoji: +The next example replaces any instances of `:)` with an smiley emoji. ```typescript const {registerPlugin} = require('@scullyio/scully'); @@ -291,7 +303,7 @@ const {registerPlugin} = require('@scullyio/scully'); function smileEmojiPlugin(html, route) { return Promise.resolve(html.replace(/\:\)/g, '😊')); } -// This registers your plugin as +// DON NOT FORGET REGISTER THE PLUGIN const validator = async conf => []; registerPlugin('render', 'smiles', smileEmojiPlugin, validator); @@ -300,64 +312,52 @@ module.exports.smileEmojiPlugin = smileEmojiPlugin; ### Render Plugin Examples -Here are links to the built-in **render plugins** in Scully: +Here are some links to built-in **render plugins** in Scully: - [Route Content Renderer Plugin](../scully/renderPlugins/routeContentRenderer.ts) - [Content Folder Plugin](../scully/) -[Back to top](#plugins) - --- ## File Handler Plugins -### What is a File Handler Plugin? - -A **file handler plugin** is used by the `contentFolder` plugin during the `render` process. As the `contentFolder` -plugin processes the folders for markdown files or whatever they contain, it ends that process by seeing if a -`fileHandler` plugin exists for that file extenion type. +A **file handler plugin** is used by the `contentFolder` plugin during the `render` process. The `contentFolder` +plugin processes the folders for markdown files or other file type the folders may contain. The `render` process any existing `fileHandler` plugin for any file extension type. Scully comes with two built-in `fileHandler` plugins. The [markdown plugin](../scully/fileHanderPlugins/markdown.ts) and -the [asciidoc plugin](../scully/fileHanderPlugins/asciidoc.ts). These two plugins are there to handle and process the -content of those types of files as they are read from the file system. +the [asciidoc plugin](../scully/fileHanderPlugins/asciidoc.ts). These plugins handle and process the +content of those file types as they are read from the file system. -Suppose you wanted to support `.docx` files, or `.csv` files, or anything else. You would want to add a file handler -for those types of files. The `contentFolder` plugin will take care of reading those files from the filesystem, but -what if you wanted to transform them somehow AFTER the `contentFolder` plugin reads them. You would need a `fileHandler` -plugin for this. +If you want to support `.docx` files, or `.csv` files, or any other file type; a file handler for those file types need to be added. +The `contentFolder` plugin takes care of reading those files from the filesystem. However, if the files need to be transformed after the `contentFolder` plugin reads them; +A `fileHandler` plugin is required. ### File Handler Plugin Interface -A **file handler plugin** is a function that returns a `Promise`. Here is what the interface looks like: +A **file handler plugin** is a function that returns a `Promise`. The interface looks like follows: ```typescript function exampleFileHandlerPlugin(rawContent: string): Promise { - // must return a promise here + // Must return a promise } ``` -### How To Make A File Handler Plugin +### Making A File Handler Plugin -The following is a sample **file handler plugin** that handles CSV by wrapping it in a code block. You could of course, -do something much more elaborate like create a table or a grid for this data. Example: +The following **file handler plugin** example handles `.cvs` files by wrapping them into a code block. You could write a much more elaborate plugin that creates a table or a grid for the data. ```typescript function csvFilePlugin(raw) { return Promise.resolve(`
${code}
`); } -// This registers your plugin +// DO NOT FORGET TO REGISTER THE PLUGIN registerPlugin('fileHandler', 'csv', {handler: csvFilePlugin}); - module.exports.csvFilePlugin = csvFilePlugin; ``` ### File Handler Plugin Examples -Here are links to the built-in **render plugins** in Scully: +Here are some links to built-in **render plugins** in Scully: - [asciidoc Plugin](../scully/fileHanderPlugins/asciidoc.ts) - [markdown Plugin](../scully/fileHanderPlugins/markdown.ts) - -[Back to top](#plugins) - -[Full Documentation ➡️](scully.md) diff --git a/docs/pre-requisites.md b/docs/pre-requisites.md index 919c914cb..133da7f62 100644 --- a/docs/pre-requisites.md +++ b/docs/pre-requisites.md @@ -23,7 +23,9 @@ Then, create a new application. ng new my-scully-app ``` -#### IMPORTANT: _Scully depends on the application's router module in order to generate the website's pages_ +#### IMPORTANT: + +_Scully depends on the application's router module in order to generate the website's pages_ Add a router module with the following command: @@ -33,7 +35,9 @@ ng generate module app-routing --flat --module=app Find more info about the Angular CLI here [👉 angular.io/cli](https://angular.io/cli) -#### IMPORTANT: _Scully uses Chromium. Therefore, your Operating System, as well as its administrator rights must allow its installation and execution._ +#### IMPORTANT: + +_Scully uses Chromium. Therefore, your Operating System, as well as its administrator rights must allow its installation and execution._ ### Node version: diff --git a/docs/recommended-plugins.md b/docs/recommended-plugins.md index 14a2fe9da..cf926af0e 100644 --- a/docs/recommended-plugins.md +++ b/docs/recommended-plugins.md @@ -1,26 +1,29 @@ +--- +title: Recommended Plugins +order: 1200 +--- + # Community Plugins -The following is a list of our recommended Scully plugins. +The following list contains recommended plugins for Scully. -_If you would like to add a plugin to this list, please submit a PR to the `docs/recommended-plugins.md`._ +_If you would like to add a plugin to the list, please submit a PR to the `docs/recommended-plugins.md`._ ## Official Plugins -- `json` router plugin -- `contentFolder` router and render plugin -- `ignored` router plugin -- `adoc` render plugin -- `md` render plugin +- `json` - Router plugin +- `contentFolder` - Router and render plugin +- `ignored` - Router plugin +- `adoc` - Render plugin +- `md` - Render plugin ## Community Plugins -- `minifyHtml` render plugin - [https://www.npmjs.com/package/scully-plugin-minify-html](https://www.npmjs.com/package/scully-plugin-minify-html) -- `disableAngular` render plugin - [https://www.npmjs.com/package/scully-plugin-disable-angular](https://www.npmjs.com/package/scully-plugin-disable-angular) -- `toc` render plugin - [https://www.npmjs.com/package/scully-plugin-toc](https://www.npmjs.com/package/scully-plugin-toc) -- `regexHtml` render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-regex](https://www.npmjs.com/package/@gammastream/scully-plugin-regex) -- `sitemap` render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-sitemap](https://www.npmjs.com/package/@gammastream/scully-plugin-sitemap) -- `http404` render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-http404](https://www.npmjs.com/package/@gammastream/scully-plugin-http404) -- `fouc` render plugin - [https://www.npmjs.com/package/@notiz/scully-plugin-fouc](https://www.npmjs.com/package/@notiz/scully-plugin-fouc) -- `lazyImages` render plugin - [https://www.npmjs.com/package/@notiz/scully-plugin-lazy-images](https://www.npmjs.com/package/@notiz/scully-plugin-lazy-images) - -[Full Documentation ➡️](scully.md) +- `minifyHtml` - Render plugin - [https://www.npmjs.com/package/scully-plugin-minify-html](https://www.npmjs.com/package/scully-plugin-minify-html) +- `disableAngular` - Render plugin - [https://www.npmjs.com/package/scully-plugin-disable-angular](https://www.npmjs.com/package/scully-plugin-disable-angular) +- `toc` - Render plugin - [https://www.npmjs.com/package/scully-plugin-toc](https://www.npmjs.com/package/scully-plugin-toc) +- `regexHtml` - Render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-regex](https://www.npmjs.com/package/@gammastream/scully-plugin-regex) +- `sitemap` - Render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-sitemap](https://www.npmjs.com/package/@gammastream/scully-plugin-sitemap) +- `http404` - Render plugin - [https://www.npmjs.com/package/@gammastream/scully-plugin-http404](https://www.npmjs.com/package/@gammastream/scully-plugin-http404) +- `fouc` - Render plugin - [https://www.npmjs.com/package/@notiz/scully-plugin-fouc](https://www.npmjs.com/package/@notiz/scully-plugin-fouc) +- `lazyImages` - Render plugin - [https://www.npmjs.com/package/@notiz/scully-plugin-lazy-images](https://www.npmjs.com/package/@notiz/scully-plugin-lazy-images) diff --git a/docs/release-for-v8.md b/docs/release-for-v8.md index 0e84dcfc1..656bd7fc0 100644 --- a/docs/release-for-v8.md +++ b/docs/release-for-v8.md @@ -1,8 +1,9 @@ --- -author: Sander Elias +title: Angular v8.x.x Release +order: 1300 --- -# Release an V8 library update. +# Step for Releasing a v8.x.x library 1. checkout the `angular-8` branch 2. `rm -fr node_modules` remove version 9 diff --git a/docs/scully-cmd-line.md b/docs/scully-cmd-line.md index 3fd1182fa..b449f69f8 100644 --- a/docs/scully-cmd-line.md +++ b/docs/scully-cmd-line.md @@ -3,9 +3,9 @@ title: Command Line Options order: 400 --- -# Scully command line options +# Scully Command Line Options -Scully CLI has the following options available: +The Scully CLI has the following options available: - [Scully command line options](#scully-command-line-options) @@ -25,13 +25,13 @@ Scully CLI has the following options available: - [ssl-key](#ssl-key) - [tds](#tds) -## serve +## Serve ```bash npx scully serve ``` -This starts the scully server helper on its own. You can use this to inspect the result from Scully, or to speed up the scully proccess a bit. it does not _build_ the project, it only serves the angular build files, and the scully result files. +Starts the scully server. This process does not _build_ the project. It only serves the Agular build files, and the Scully static files. ## noWatch @@ -39,7 +39,7 @@ This starts the scully server helper on its own. You can use this to inspect the npx scully --nw ``` -By default, Scully has the watchMode active, if you prefer to run scully only once, use this flag. +By default, Scully has the watchMode active. Use this flag to run scully only once. ## showBrowser @@ -47,7 +47,7 @@ By default, Scully has the watchMode active, if you prefer to run scully only on npx scully --showBrowser ``` -Alias `--sb`. This will show the chromium browser that is rendering your application. Can be used to diagnose some issues +Alias `--sb`. Shows the chromium browser rendering the application. ## showGuessError @@ -55,7 +55,7 @@ Alias `--sb`. This will show the chromium browser that is rendering your applica npx scully --showGuessError ``` -Alias `--sge`. This shows errors from Guess-Parse to the console. +Alias `--sge`. Displays Guess-Parse's errors in the console. ## configFile @@ -63,7 +63,7 @@ Alias `--sge`. This shows errors from Guess-Parse to the console. npx scully --configFile someName ``` -Alias `--cf`. loads a different config file. if used at the same time as `--project` the project flag takes precedence. +Alias `--cf`. Loads a different config file. If it is used at the same time as the `--project` flag, the project flag takes precedence. ## project @@ -71,7 +71,7 @@ Alias `--cf`. loads a different config file. if used at the same time as `--proj npx scully --project someName ``` -Alias `--pr`. This enables you to select a different project. Scully by default uses the project that is the default project of the Angular CLI. When you want to run for another project, you can use this option, or use the Angular CLI to set another default project. +Alias `--pr`. It is used to select a different project. Scully uses the default project from generated by the the Angular CLI. ## baseFilter @@ -79,11 +79,15 @@ Alias `--pr`. This enables you to select a different project. Scully by default npx scully --baseFilter /someRoute ``` -Alias `--bf`. This enable to Scully to start to render an specific route. +Alias `--bf`. Enables Scully to start rendering a specific route. ## proxyConfig -Alias `--proxy` takes a relative filename filename for a proxy config file. for details look at [this](https://github.com/chimurai/http-proxy-middleware/blob/master/README.md). We use the same config format as [webpackDevServer](https://webpack.js.org/configuration/dev-server/#devserverproxy) +Alias `--proxy`. Takes a relative filename for a proxy config file. + +For more details look at [this](https://github.com/chimurai/http-proxy-middleware/blob/master/README.md). + +Scully uses the same config format as [webpackDevServer](https://webpack.js.org/configuration/dev-server/#devserverproxy). ## removeStaticDist @@ -91,7 +95,7 @@ Alias `--proxy` takes a relative filename filename for a proxy config file. for npx scully --removeStaticDist ``` -Alias `--RSD`. Remove the static folder generated by Scully in previous renders. +Alias `--RSD`. Removes the static folder generated by Scully from previous renders. ## open @@ -99,12 +103,11 @@ Alias `--RSD`. Remove the static folder generated by Scully in previous renders. npx scully serve/watch --open ``` -Alias `--o`. Open the default browser and show the scully dist. +Alias `--o`. Opens the default browser and renders the dist folder generated by Scully. ## scanRoutes -Alias `--sr` or `--scan` -Scan the application again to find unhandled routes. This normally only done once. When you add/change routes in the app, you need this parameter to discover the new routes. +Alias `--sr` or `--scan`. Scans the application again to find unhandled routes. This is normally done just once. When routes in the application are added or changed, use this flag to discover all the new routes. ## ssl @@ -112,7 +115,7 @@ Scan the application again to find unhandled routes. This normally only done onc npx scully serve/watch --ssl ``` -Run the scully server with ssl. +Runs the Scully server with ssl. ## ssl-cert @@ -120,7 +123,7 @@ Run the scully server with ssl. npx scully serve/watch --ssl --ssl-cert=./url/to/file ``` -Add url to ssl cert file for SSL server +Adds a url to the ssl certificate file for a server with SSL. ## ssl-key @@ -128,7 +131,7 @@ Add url to ssl cert file for SSL server npx scully serve/watch --ssl --ssl-key=./url/to/file ``` -Add url to ssl key file for SSL server +Adds a url to an ssl key file for a server with SSL. ## tds @@ -136,11 +139,12 @@ Add url to ssl key file for SSL server npx scully --tds ``` -This launches the Test Data Server. This is only helpful for demos. Currently the following APIs are -supported on the test data server: +Launches the Test Data Server. This is only helpful for demos. + +The following APIs are supported on the test data server: -- `/users` - returns a list of users -- `/users/:id` - returns just one user by id -- `/posts` - returns a list of posts -- `/posts/:id` - returns a post by id -- `/slow/:delay` - returns a 200 after the delay has gone by. (eg: `/slow/2000` takes 2 seconds) +- `/users` - Returns a list of users +- `/users/:id` - Returns just one user by id +- `/posts` - Returns a list of posts +- `/posts/:id` - Returns a post by id +- `/slow/:delay` - Returns 200 code after a delay has gone by. Eg: `/slow/2000` takes 2 seconds. diff --git a/docs/scully-configuration.md b/docs/scully-configuration.md index d82e9ea72..6bfb779de 100644 --- a/docs/scully-configuration.md +++ b/docs/scully-configuration.md @@ -5,12 +5,13 @@ order: 300 # Scully Configuration -The center of every Scully project is the file `scully.config.js`. This config file must export the configuration for your -scully build. +The central part of a Scully project is the `scully.config.js` file. This file exports the Scully build configuration for an application. -If you are starting to use Scully we highly recommend read the [Getting Started](getting-started.md) section, -also if you want to enhance your project made with Scully, visit the [Utils](utils.md) section and see -or teach to the community how to combine Scully with others tools. +If you are new to Scully, it is recommended to read the [Getting Started](getting-started.md) documentation. + +If you want to enhance a Scully project, read the [Utils](utils.md) documentation. + +The `scully.config.js` file's structure is shown below: - [Scully Configuration](#scully-configuration) - [`ScullyConfig` Interface](#scullyconfig-interface) @@ -19,7 +20,6 @@ or teach to the community how to combine Scully with others tools. - [homeFolder](#homefolder) - [outDir](#outdir) - [distFolder](#distfolder) - - [proxyConfig](proxyConfig) - [routes](#routes) - [handled Routes](#handled-routes) - [unhandled Routes](#unhandled-routes) @@ -51,27 +51,29 @@ export interface ScullyConfig { } ``` -`ScullyConfig` interface provide the parameters to configure how Scully works in your project. +The `ScullyConfig` interface provides parameters for configuring how Scully works in a project. -## scullyConfig properties explained +## scullyConfig File's Properties ### projectRoot -`projectRoot` is reference to the path to the project where Scully will intervene. +`projectRoot` - The project's from which Scully generates the static content. + +This property is **_mandatory_**, and Scully automatically sets this property to the default Angular project. -This property is **_mandatory_**, Scully fills automatically post installation, +### IMPORTANT: -**_IMPORTANT_** this property won't be **_mandatory_** anymore in future releases. +_this property won't be \*\*\_mandatory_\*\* anymore in future releases.\_ ### homeFolder -`homeFolder` is reference to your project root folder. -This property is for internal use mostly, it defaults to the location where angular.json is. +`homeFolder` - A reference to the Angular project's root folder. This property is for internal use, and it defaults to the angular.json file's location. ### outDir -`outDir` is reference to the path folder which Scully will take to put the statics files. -By default the path is: +`outDir` - The folder's path where Scully leaves the statics files. + +The default path is: ``` ./dist/static @@ -79,86 +81,89 @@ By default the path is: ### distFolder -`distFolder` option provide to Scully the path to the compiled Angular application. By default Scully take the path -reading the `angular.json`. You can set it up follow your needs. +`distFolder` - Path to the Angular application's dist folder. Scully takes the `angular.json` file's default path. This option can be modify according to the needs. ### routes -Scully sort routes in 2 types: +Scully has the two following types of routes: -- handled -- unhandled +#### Handled Routes -#### handled Routes +Routes with static params. -handled routes reference to routes with static params. +Eg. ``` /foo/1 ``` -#### unhandled Routes +#### Unhandled Routes + +Routes with dynamic data. -handled routes reference to routes with dynamic data. +Eg. ``` /foo/:id ``` -## proxyConfig - -Takes a relative filename filename for a proxy config file. For details look at [this](https://github.com/chimurai/http-proxy-middleware/blob/master/README.md). We use the same config format as [webpackDevServer](https://webpack.js.org/configuration/dev-server/#devserverproxy). - -`routes` is a reference to all unhandled routes which Scully will transform to handled, using plugins. -If you want to know more about plugins go to [Plugins](plugins.md) section. +All unhandled need to be handle through plugins. For more information about router plugins read the [Plugins](plugins.md) documentation. ### extraRoutes -The `extraRoutes` property allow to the developer add an array of unhandled routes to discover by Scully. -These can be routes that exist in AngularJS, or in React, or in whatever Framework's router. +`extraRoutes` - Allows developers to add an array of unhandled routes. These routes can exist in an AngularJS, React, or any other framework. It can be handle `:string`, `Promise` or `Promise>` +The **extra routes** array requires parameters of type: `:string`, `Promise` or `Promise>` + +Eg. + ```typescript extraRoutes: ['/foo/id', new Promise('/bar/barId'), new Promise(['/foo/fooId', '/bar/id'])]; ``` ### appPort -Scully provides you a server to check how your Angular app works. -`appPort` is the property to configure the port which your Angular app will run. +Scully provides a server to to render the Angular application. + +`appPort` - Configure the port where the Angular application runs. + +The default port is: `1864` + +### staticPort -The port by default is: `1864` +Similar to _appPort_, `staticport` provides a server to to render the static files compiled by Scully. -### staticport +The default port is: `1668` -Similarly as _appPort_, the property `staticport` allows the developer to set up a port to execute a server, -which will serve static files compiled by Scully. +## proxyConfig + +Takes a relative filename for a proxy config file. -The port by default is: `1668` +For more details look at [this](https://github.com/chimurai/http-proxy-middleware/blob/master/README.md). -### proxyConfig +Scully uses the same config format as [webpackDevServer](https://webpack.js.org/configuration/dev-server/#devserverproxy). -Optional, when you need a proxy, we can read the proxy config file that is also used by the [Angular CLI](https://angular.io/guide/build#proxying-to-a-backend-server) +This is an optional property, and it is also used by the [Angular CLI](https://angular.io/guide/build#proxying-to-a-backend-server) ### puppeteerLaunchOptions -When in a restricted environment there is a change the default options for puppeteer won't work. In such a case -this option can override the puppeteerLaunchOptions with settings that match this environment. -Word of warning, some settings might interfer with the way Scully is working, creating errornous results. -Follow [this link](https://pptr.dev/#?product=Puppeteer&version=v2.0.0&show=api-puppeteerlaunchoptions) for more information +If the application is in a restricted environment, puppeteer's default options may not work. In that case, +this option can be overwrite with settings that match a specific environment. + +Word of warning, some settings might interfere with the way Scully is working, creating inaccurate results. +Follow [this link](https://pptr.dev/#?product=Puppeteer&version=v2.0.0&show=api-puppeteerlaunchoptions) for more information. ### hostName -Use a different name as `localhost` for the local server. Needed if doe to environmental restrictions localhost isn't usable +Allows to set a different name for the `localhost`. ### hostUrl -Connect to another server. If your app has special demands to host it, you might need to use your own server. When that is needed you can provide this setting to let Scully knows where to look for your running app. Make sure the server is up and running, and hosting the correct application. +Connects your application to a different host. This is useful when using your own server. ### guessParserOptions -These are the `guessParserOptions` that get passed to the `guess-parser` library. Currently the only property supported -`excludedFiles`, which allows you to exclude files from the `guess-parser` route discovery process. - -[Full Documentation ➡️](scully.md) +The`guessParserOptions` that get passed to the `guess-parser` library. Currently, the only supported property is +`excludedFiles`, and it excludes files from the `guess-parser` route discovery process. diff --git a/docs/scully-lib-core.md b/docs/scully-lib-core.md index 15ce9dbce..2b22ca977 100644 --- a/docs/scully-lib-core.md +++ b/docs/scully-lib-core.md @@ -5,20 +5,24 @@ order: 500 # Scully Core -## Idle Monitor +Scully has several core features, and they will be covered in his section. -Scully implements the `IdleMonitorService` to hook into Zonejs. When Angular goes idle (**more precise, when all outgoing HTTP-requests are settled**) -Scully triggers Puppeteer, and knows when it's ready to render. +## Idle Monitor Service -Without this process, we have to resort to a (25 seconds) timeout. this is both slower and unprecise, some pages need even more time. +The `IdleMonitorService` hooks into Zonejs. When Angular goes idle (**more precisely, when all outgoing HTTP requests are settled**) +Scully triggers Puppeteer in order to know when it is ready to render. -`IdleMonitorService` is available in `ScullyLibModule`. +Without this process it would have to resort to a (25 seconds), which is both slower and inaccurate. Some pages could need even more time. + +`IdleMonitorService` is in the `ScullyLibModule`. ## Router Service -`ScullyRoutesService` is an service to provide to the user access to certains methods and observables to know +The `ScullyRoutesService` provides access to certain methods and observables in order to know the routes rendered by Scully. +The observables and methods are listed blow: + - available\$ - unPublished\$ - topLevel\$ @@ -40,42 +44,39 @@ export interface ScullyRoute { #### available\$: _Observable_ -`available$` returns routes with the property `published` with value true. +`available$` - Returns routes with the property `published` with a value of true. #### unPublished\$: _Observable_ -`unPublished$` returns routes with the property `published` with value false. +`unPublished$` - Returns routes with the property `published` with a value of false. #### topLevel\$: _Observable_ -`topLevel$` returns top level routes. +`topLevel$` - Returns the top level routes. #### getCurrent(): _Observable_ -`getCurrent()` method returns the current location. +`getCurrent()` - A method that returns the current location. #### reload(): _void_ -`reload` method checks if new routes were added in the `scully-routes.json`. - -## Scully Content +`reload` - A method that checks if new routes were added to the `scully-routes.json` file. -Scully uses the `scully-content` to insert the result of the render process into the HTML document. +## Scully Content Component -The `scully-content` component won't work inside a `*ngIf` directive. +The `scully-content` component inserts the render process' result into the HTML document. -## Transfer State +**NOTE:** The `scully-content` component does not work inside an `*ngIf` directive. -The `TransferStateService` allows transfer the state of the Angular application to the static site rendered by Scully. +## Transfer State Service -To set or get the state of the application you can use 2 methods: +The `TransferStateService` allows to transfer an Angular application's state into the static site rendered by Scully. -- getState -- setState +To get or set the application's state; use the two methods below: #### getState -`getState` will return an observable that fires once and completes. It does so right after the navigation for the page has finished. +`getState` - This method returns an observable that fires once and then completes, and it does so right after the page's navigation has finished. ```typescript getState(name: string): Observable @@ -83,25 +84,20 @@ getState(name: string): Observable #### setState -`setState` will set values to the property key. +`setState` - This method sets values to the property key. ```typescript -setState(name: string, val: T): void +setState(name: string, val: T): void; ``` -## Utils +## Utility Methods: -#### Is Scully - -- isScullyRunning() -- isScullyGenerated() +These methods provide useful information about Scully processes. ##### isScullyRunning(): _boolean_ -`isScullyRunning` returns `true` or `false` if Scully build is happening. +`isScullyRunning` - This method returns `true` or `false` if the Scully build is currently running. ##### isScullyGenerated(): _boolean_ -`isScullyGenerated` returns `true` if Scully build has run. - -[Full Documentation ➡️](scully.md) +`isScullyGenerated` - This method returns `true` if the Scully build has run. diff --git a/docs/scully.md b/docs/scully.md index bd6263b4a..2351d1103 100644 --- a/docs/scully.md +++ b/docs/scully.md @@ -24,4 +24,14 @@ Visit one of the following topics: - [Issues](issues.md) - [Contribution Guideline](../CONTRIBUTING.md) +--- + Join to Scully community in [Gitter](https://gitter.im/scullyio/community) + +--- + +### Do you want to collaborate to scully? + +We would love your feedback and how you are using Scully with other tools. + +If you want to share your experience with the community please check our [CONTRIBUTING](../CONTRIBUTING.md) guidelines. diff --git a/docs/showcase.md b/docs/showcase.md index 14cd20f8e..fd82c9596 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -1,3 +1,3 @@ # Scully Showcase -[Full Documentation ➡️](scully.md) +Coming Soon! diff --git a/docs/utils.md b/docs/utils.md index 63d6bef52..0bc54e181 100644 --- a/docs/utils.md +++ b/docs/utils.md @@ -1,19 +1,20 @@ # Utilities +Prism is a lightweight, extensible syntax highlighter that can be used when working with code blocks in markdown files in blog posts. + Scully works well in combination with other tools and utilities. 1. [Syntax Highlighting using prismjs](#add-syntax-highlighting) ## Syntax Highlighting Using Prismjs -When you are using code blocks in your markdown files for your blog posts, you'll may define a language for the used code like this: +It is possible to define a language for the code to be used in the Scully code like this: 
```ts
 const foo = 'bar';
 ```
-Scully will parse the markdown using [_marked_](https://www.npmjs.com/package/marked). -In the end the parsed result will look like this: +Scully parses the markdown using [_marked_](https://www.npmjs.com/package/marked), and the parsed result looks like this: ```html @@ -23,18 +24,16 @@ In the end the parsed result will look like this: ``` -As you can see _marked_ will use the CSS class prefix `language-` for tagging the code block with the appropriate language. +_marked_ uses the CSS class prefix `language-` to tag the code block with an appropriate language. -To highlight your code blocks, you can use [_prismjs_](https://prismjs.com) as it matches with the resulting class names. You can install prismjs using NPM and creating a service to highlight your code blocks: +To highlight the code blocks use [_prismjs_](https://prismjs.com) and create a service like this: ```bash npm i --save prismjs ng g s highlight ``` -The service will include all languages you need and probably the clipboard library to simply copy the code etc. - -It could look like this: +The service will include all languages needed. The code looks like this: ```ts import {Injectable, Inject} from '@angular/core'; @@ -68,7 +67,7 @@ export class HighlightService { } ``` -After this, you need the service to be injected in your `BlogComponent` that was generated by scully: +Now, it needs to inject the service in the `BlogComponent` that was generated by scully: ```ts import {/* ... */, AfterViewChecked} from '@angular/core'; @@ -86,7 +85,7 @@ export class BlogComponent implements OnInit, AfterViewChecked { } ``` -The last step is to include a theme from prism: +Finally, include a Prism's theme like this: ```css /* include CSS for prism toolbar */ @@ -95,17 +94,4 @@ The last step is to include a theme from prism: @import '~prismjs/themes/prism-tomorrow'; ``` -That's it, all code languages you have been imported in your `HighlightService` should be highlighted now. -Check out also the official [docs of prismjs](https://prismjs.com/) - ---- - -### Do you want to colaborate with scully? - -We would really love to know how you are combining Scully with other tools. -If you want to share your experience with the community please check our [CONTRIBUTING](../CONTRIBUTING.md) file, -and don't forget to sign the [CLA](https://cla-assistant.io/scullyio/scully). - ---- - -[Full Documentation ➡️](scully.md) +Check out also the official [docs of prismjs](https://prismjs.com/) for more information. diff --git a/projects/scullyDocs/src/styles.css.rej b/projects/scullyDocs/src/styles.css.rej new file mode 100644 index 000000000..3a7bff285 --- /dev/null +++ b/projects/scullyDocs/src/styles.css.rej @@ -0,0 +1,9 @@ +diff a/projects/scullyDocs/src/styles.css b/projects/scullyDocs/src/styles.css (rejected hunks) +@@ -252,6 +252,7 @@ + + app-card > div > .icon-container { + width: 100%; ++ display: flex; + justify-content: center; + align-items: center; + height: 116px;