diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 1f1dbe24a..fc4bf856c 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -5,6 +5,4 @@ order: 900 # Code of Conduct -This will be prepared before we end the alpha phase of our development. - -[Full Documentation ➡️](scully.md) +This will be ready before alpha phase of Scully's development. diff --git a/docs/blog.md b/docs/blog.md index 4423cb3e8..c1ab29f95 100644 --- a/docs/blog.md +++ b/docs/blog.md @@ -1,9 +1,13 @@ -# Scully with Blogs +--- +title: Adding Blog Support +order: 600 +--- + +# Blogs in Scully -Scully is your best friend when you want to move your blog to Angular! +Scully is the best option for moving a blog to Angular! -We have a schematic that will add the necessary pieces to your project to enable blogging with markdown files in your -Angular app. +It has a schematic that enables Angular applications to use markdown files for blog's content. 1. [Adding Blog Support](#adding-blog-support) 2. [Generating New Blog Posts](#generating-new-blog-posts) @@ -13,54 +17,51 @@ Angular app. To add blog support to your app, run the following command: ```bash -ng g @scullyio/init:blog +ng generate @scullyio/init:blog ``` -This will add the blog components/modules/routes to your Angular app, as well as a folder for your blog markdown files. -If you don't want the folder to be called 'blog', you can run a longer command to provide your own custom names/folders. +This command adds the blog modules's roues to the Angular application. In addition, it creates a `./blog` folder for the blog's markdown files. -To name your blog folders and components another name, run the following command with your own name: +To create a folder with a different name, run the following command: ```bash -ng g @scullyio/init:markdown --name=my-test --slug=my-slug-id +ng generate @scullyio/init:markdown --name=my-markdown --slug=my-slug-id ``` or ```bash -ng g @scullyio/init:markdown --name="my text" --slug="my slug id" +ng generate @scullyio/init:markdown --name="my markdown" --slug="my slug id" ``` -the following table shows all available options: +**NOTE:** Slug is . + +The following table shows all available options: + +| Option | Description | Default | +| -------------- | --------------------------------------------------------- | ------------------------ | +| `name` | Defines the name for the created module | 'blog' | +| `slug` | Define the name for the `:slug` | 'id' | +| `routingScope` | Sets a routing scope (`Root` or `Child`) | Child | +| `sourceDir` | Defines a source directory name (default: `name`) | value from `name` option | +| `route` | Defines a route path before the `:slug` (default: `name`) | value from `name` option | -| option | description | default | -| -------------- | ------------------------------------------------------------------------------ | ------------------------ | -| `name` | define the name for the created module | 'blog' | -| `slug` | define the name for the `:slug` | 'id' | -| `routingScope` | set a routing scope (`Root` or `Child`) | Child | -| `sourceDir` | define a source dir name (when not used, `name` is used instead) | value from `name` option | -| `route` | define a route path before the `:slug` (when not used, `name` is used instead) | value from `name` option | +Scully works well in combination with other tools and [utilities](utils.md). -> If your markdown content will include code blocks, you may want the [code to be highlighted](utils.md). +For instance, if the markdown content includes code blocks, and you want to highlight it us the use a utility. ## Generating New Blog Posts -To add a new blog post, run the following command: +To create a new blog post, run the following command: ```bash -ng g @scullyio/init:post --name="This is my post" +ng generate @scullyio/init:post --name="This is my post" ``` -the following table shows all available options: +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 | - -[Check how to integrate Scully with other tools.](utils.md) - ---- - -[Full Documentation ➡️](scully.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index 30927d039..b5d09a65b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,48 +3,29 @@ title: Getting Started order: 200 --- -# Scully - Getting Started +# Getting Started with Scully -[Español](getting-started_es.md) +Welcome to Scully! -## Prerequisites +Before getting started, please read the [Prerequisites](pre-requisites.md). -The first thing you need to get started with Scully is a working Angular app using **Angular 8.x.x** or **9.x.x** and **Node 12.x.x** - -You can create a new Angular 9 app using the following command: - -```bash -npx -p @angular/cli ng new my-scully-app -``` - -If that fails, you can install the Angular CLI globally and create a new app with that version. - -``` -npm install -g @angular/cli -ng new my-scully-app -``` - -Find more info here [👉 angular.io/cli](https://angular.io/cli) - -**NOTE:** Scully will use Chromium. Make sure your Operating System (and its restrictions by your administrator) allow installing and executing Chromium. - -This getting started doc covers the three steps to adding Scully into your project. +This getting started guide covers three topics: 1. [Installation](#installation) -2. [Build](#build) -3. [Test](#test) +2. [Building](#build) +3. [Testing](#test) ## Installation -To install Scully, execute the following command from the root directory of your Angular project (in a terminal window): +First, open your Angular application. Inside the project's root directory run the following command: ```bash ng add @scullyio/init ``` -The command above installs dependencies and configures the files needed to start building with Scully (_we will further elaborate on this in upcoming releases_). +This command installs dependencies and configures the files needed by Scully. -If the installation was successful a message similar to this one will be displayed: +Once the installation finishes the following message will be displayed: ```bash Installed packages for tooling via yarn. @@ -59,31 +40,25 @@ CREATE scully.config.js (65 bytes) UPDATE package.json (1507 bytes) ``` -#### IMPORTANT: _Scully requires the router to be present in your application, don't forget to add it._ - -#### IMPORTANT: _Scully requires the distribution files to be in a subfolder of `./dist`_ - -If you have an angular app, that outputs the distribution files directly into the root of `./dist` Scully can't copy all of the dist files. This is an OS file-system issue. We can't copy recursively into a subfolder of dist. The solution is to set the option `architect->build->options->outputPath` to a subfolder. +## ng generate @scullyio/init:blog -## ng g @scullyio/init:blog +This command will generate a blog module. [more info here](blog.md) -This command will generate a blog module. [more info here](https://github.com/scullyio/scully/blob/master/docs/blog.md) - -Once it's generated you can open the default `app.component.html` created by angular-cli and remove the whole placeholder leaving only the router outlet tag `` +Once it is generated remove all the content in the `app.component.html` file, and add only the router outlet tag ``. ### Home page -Since the default template from angular-cli doesn't ship an entry point for route, it might be confusing to get Scully working on the very first shot. +It is necessary to create a _route entry point_ because the Angular CLI does not create one by default. + +Create a _Home Module_ with a _Home Component_ and its routes already configured with the following command: ```ts -ng g m home --route=home --module=app-routing +ng generate module home --route=home --module=app-routing ``` -This command will generate the new home page module plus a new component with a route configured. +### Configuring the home module as root -### Configure home as root - -Open `app-routing.module.ts` and let the path attribute empty for the home route. +Open the `app-routing.module.ts` file and set an empty path attribute for the home route as shown below: ```ts const routes: Routes = [ @@ -95,9 +70,9 @@ const routes: Routes = [ ]; ``` -### Inject route service +### Inject the route service -Scully provides a service to easy get access on generated routes. To list these in your template open `home.component.ts` by adding the following code: +Scully provides a service for accessing generated routes with ease. To use it, open the `home.component.ts` file and add the following code: ```ts import {ScullyRoutesService} from '@scullyio/ng-lib'; @@ -119,7 +94,7 @@ export class HomeComponent implements OnInit { } ``` -and then loop inside `home.component.html` +Now, it is possible to loop through the links inside the template by opening the `home.component.html` file and adding the following code: ```html

home works!

@@ -129,46 +104,37 @@ and then loop inside `home.component.html` ``` -## Build - -By now you should have your Angular project with Scully successfully installed, so let us run a Scully build and turn your site into a -pre-rendered Angular app. - -Since Scully runs based on a build of your app, the first step is to build your Angular project (with added routes), subsequently running the Scully build. +**NOTE:** If you don't add any route, scully will pre-render 0 pages. -```bash -ng build -npm run scully -``` +## Build -That's it, you're done! In your project directory, you should now have a `/dist/static` folder containing the built version -of your app. +At this point, you have your Angular project with Scully successfully installed. -**NOTE:** If you had any errors or warnings during the build phase, please follow the instructions in the errors/warnings -(if applicable) or [submit an issue](https://github.com/scullyio/scully/issues/new/choose). +#### IMPORTANT: _Scully requires the distribution files in the `./dist/my-scully-app` folder._ -**NOTE:** If you don't add any route, scully will pre-render 0 pages. +**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. -## Test +Build the application in order to generate the distribution files: -Now that your project has been pre-rendered, you can validate the build by either: +``` +ng build +``` -#### Serving the contents +Now, lets build Scully and turn your Angular app into a pre-rendered static site. -By utilizing something like [http-server](https://www.npmjs.com/package/http-server) you can serve the contents of your -`dist/static` folder. All of the routes in your non-pre-rendered Angular app should still work. Not all apps are -capable of running without. +```bash +npm run scully +``` -[//]: # 'Missing text for the line above' +Congratulations! You have turned your Angular application into a wicked fast pre-rendered one thanks to Scully. -**Extra Credit**: While serving your app, [disable JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript/disable) -and make sure that it still works. This is the goal for your app, to run with JavaScript disabled. Most parts of your app should still work without JS enabled. +The built version is in the `./dist/static` folder. This folder contains ol the pages in the site. -#### Browsing the contents +**NOTE:** In case of any errors or warnings during the build process, please follow the instructions in the errors/warnings section (_Coming soon_) or [submit an issue](https://github.com/scullyio/scully/issues/new/choose). -Browse the contents of your `dist/static` directory and make sure that all of your pages were pre-rendered and saved to -HTML correctly. +#### Serving the content ---- +Use [http-server](https://www.npmjs.com/package/http-server) to serve the `dist/static` folder's content. -[Full Documentation ➡️](scully.md) +**Extra Credit**: While serving the static app, [disable JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript/disable) +and make sure that the site's navigation still works and most parts of it should still work without JS enabled. diff --git a/docs/getting-started_es.md b/docs/getting-started_es.md index 1e73c070d..cf26ff6a1 100644 --- a/docs/getting-started_es.md +++ b/docs/getting-started_es.md @@ -1,6 +1,11 @@ -# Scully - Empezando +--- +title: Primeros pasos +order: 200 +--- + +# Scully - Primeros pasos -## Requerimientos previos +## Requisitos previos Lo primero que se necesita para comenzar con Scully es una aplicación Angular que utilice **Angular 8.x.x** o **9.x.x** y **Node 12.x.x** diff --git a/docs/issues.md b/docs/issues.md index f5cf3551a..0e3f14b03 100644 --- a/docs/issues.md +++ b/docs/issues.md @@ -1,9 +1,12 @@ -# Scully Issues +--- +title: Issues +order: 1000 +--- + +# Issues To create a bug report go to [Scully Bug template](https://github.com/scullyio/scully/issues/new?assignees=&labels=bug&template=---bug-report.md&title=). To propose a new feature go to [Scully Feature request](https://github.com/scullyio/scully/issues/new?assignees=&labels=enhancement&template=---feature-request.md&title=) -We are working on better documentation for creating issues. - -[Full Documentation ➡️](scully.md) +The Scully team is working on better documentation for creating issues. diff --git a/docs/plugins.md b/docs/plugins.md index 4c06dae67..ade84b8de 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -1,3 +1,8 @@ +--- +title: Plugins +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 diff --git a/docs/polyfills.md b/docs/polyfills.md index e4db430da..af4ba1f78 100644 --- a/docs/polyfills.md +++ b/docs/polyfills.md @@ -1,14 +1,19 @@ +--- +title: Polyfills +order: 800 +--- + # Polyfills -Depending on the browsers and environments your app targets, polyfills may be -required. This page lists some recommended polyfills. +Depending on the browser and environment that your application targets, some polyfills may be +required. This page lists the recommended polyfills. ## `Event()` constructor -We use [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event) -inside Scully to be aware of different points in the lifecycle of the application. +Scully uses [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event) +to be aware of different points in the application's lifecycle. -To make this work in **Internet Explorer 10+**, include the following polyfill. +To make **Internet Explorer 10+** work, install the following polyfill: `npm install events-polyfill` diff --git a/docs/pre-requisites.md b/docs/pre-requisites.md index 7b6284ce5..919c914cb 100644 --- a/docs/pre-requisites.md +++ b/docs/pre-requisites.md @@ -1,21 +1,40 @@ --- -subtitle: Prerequisites +title: Prerequisites order: 100 --- -# Scully - Pre-Requisites +# Prerequisites -Before you start building awesome sites with **Scully**, you will need to understand how some web technologies work. +In order to use start using Scully, you need an existing Angular application with **v8.x.x** or **v9.x.x** or You can create a new Angular 9 application by running the following command: -- Command Line Interface (CLI) -- GIT -- Node.js +```bash +npx -p @angular/cli ng new my-scully-app +``` -Those 3 topics are very important to successfully start using Scully. +If the above command fails, install the Angular CLI globally with the following command: -### Software tools needed to work with Scully are: +``` +npm install -g @angular/cli +``` -- Node.js 10 or higher. -- Angular CLI version 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_ + +Add a router module with the following command: + +``` +ng generate module app-routing --flat --module=app +``` -[Full Documentation ➡️](scully.md) +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._ + +### Node version: + +- Node.js 10 or higher. diff --git a/docs/scully-cmd-line.md b/docs/scully-cmd-line.md index c9aa5a793..3fd1182fa 100644 --- a/docs/scully-cmd-line.md +++ b/docs/scully-cmd-line.md @@ -1,3 +1,8 @@ +--- +title: Command Line Options +order: 400 +--- + # Scully command line options Scully CLI has the following options available: diff --git a/docs/scully-configuration.md b/docs/scully-configuration.md index 09d61fe1b..d82e9ea72 100644 --- a/docs/scully-configuration.md +++ b/docs/scully-configuration.md @@ -1,3 +1,8 @@ +--- +title: Configuration +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 diff --git a/docs/scully-lib-core.md b/docs/scully-lib-core.md index 0a8db5ab6..15ce9dbce 100644 --- a/docs/scully-lib-core.md +++ b/docs/scully-lib-core.md @@ -1,3 +1,8 @@ +--- +title: Core +order: 500 +--- + # Scully Core ## Idle Monitor diff --git a/docs/scully.md b/docs/scully.md index c73cc765e..bd6263b4a 100644 --- a/docs/scully.md +++ b/docs/scully.md @@ -2,13 +2,11 @@ ## What is Scully? -**Scully** is freaking awesome. Why? Because it can create static sites using Angular. -In other words, **Scully** is a SSG (static site generator) for Angular. +**Scully** is the best static site generator for Angular projects looking to embrace the JAMStack. ### How does it work? -Under the hood, Scully analyzes your project and generates a static version of your website. Scully provides you with -a few node commands and several Angular schematics to make this all **AS EASY AS POSSIBLE!** +Under the hood, Scully analyzes your Angular application and generates a static version of it. It provides several Angular schematics to make its usage **AS EASY AS POSSIBLE!** Scully works on Windows, Linux and macOS. @@ -26,4 +24,4 @@ Visit one of the following topics: - [Issues](issues.md) - [Contribution Guideline](../CONTRIBUTING.md) -Join to Scully room in [Gitter](https://gitter.im/scullyio/community) +Join to Scully community in [Gitter](https://gitter.im/scullyio/community) diff --git a/docs/utils.md b/docs/utils.md index 06645e6d9..63d6bef52 100644 --- a/docs/utils.md +++ b/docs/utils.md @@ -1,6 +1,6 @@ -# Utils +# Utilities -Scully works well in combination with other tools and utils. +Scully works well in combination with other tools and utilities. 1. [Syntax Highlighting using prismjs](#add-syntax-highlighting) diff --git a/projects/scullyDocs/src/assets/scully-routes.json b/projects/scullyDocs/src/assets/scully-routes.json index 64c7d4c1b..9f61a9d86 100644 --- a/projects/scullyDocs/src/assets/scully-routes.json +++ b/projects/scullyDocs/src/assets/scully-routes.json @@ -1,6 +1,6 @@ [ {"route": "/"}, - {"route": "/docs/blog", "sourceFile": "blog.md"}, + {"route": "/docs/blog", "title": "Adding Blog Support", "order": 600, "sourceFile": "blog.md"}, { "route": "/docs/CODE_OF_CONDUCT", "title": "Code of Conduct", @@ -13,22 +13,37 @@ "order": 200, "sourceFile": "getting-started.md" }, - {"route": "/docs/getting-started_es", "sourceFile": "getting-started_es.md"}, - {"route": "/docs/issues", "sourceFile": "issues.md"}, + { + "route": "/docs/getting-started_es", + "title": "Primeros pasos", + "order": 200, + "sourceFile": "getting-started_es.md" + }, + {"route": "/docs/issues", "title": "Issues", "order": 1000, "sourceFile": "issues.md"}, {"route": "/docs/learn", "sourceFile": "learn.md"}, - {"route": "/docs/plugins", "sourceFile": "plugins.md"}, - {"route": "/docs/polyfills", "sourceFile": "polyfills.md"}, + {"route": "/docs/plugins", "title": "Plugins", "order": 700, "sourceFile": "plugins.md"}, + {"route": "/docs/polyfills", "title": "Polyfills", "order": 800, "sourceFile": "polyfills.md"}, { "route": "/docs/pre-requisites", - "subtitle": "Prerequisites", + "title": "Prerequisites", "order": 100, "sourceFile": "pre-requisites.md" }, {"route": "/docs/recommended-plugins", "sourceFile": "recommended-plugins.md"}, {"route": "/docs/release-for-v8", "author": "Sander Elias", "sourceFile": "release-for-v8.md"}, - {"route": "/docs/scully-cmd-line", "sourceFile": "scully-cmd-line.md"}, - {"route": "/docs/scully-configuration", "sourceFile": "scully-configuration.md"}, - {"route": "/docs/scully-lib-core", "sourceFile": "scully-lib-core.md"}, + { + "route": "/docs/scully-cmd-line", + "title": "Command Line Options", + "order": 400, + "sourceFile": "scully-cmd-line.md" + }, + { + "route": "/docs/scully-configuration", + "title": "Configuration", + "order": 300, + "sourceFile": "scully-configuration.md" + }, + {"route": "/docs/scully-lib-core", "title": "Core", "order": 500, "sourceFile": "scully-lib-core.md"}, {"route": "/docs/scully", "sourceFile": "scully.md"}, {"route": "/docs/showcase", "sourceFile": "showcase.md"}, {"route": "/docs/utils", "sourceFile": "utils.md"},