Skip to content

Commit

Permalink
docs(grammar): improve grammar for the docs (#579)
Browse files Browse the repository at this point in the history 
In addition, address issue #538
  • Loading branch information
@GuzmanPI
GuzmanPI authored May 26, 2020
1 parent 0009e04 commit a73558d
Show file tree
Hide file tree
Showing 19 changed files with 293 additions and 331 deletions.
46 changes: 20 additions & 26 deletions docs/blog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,32 @@ order: 600
lang: en
---

# Create a blog
# Creating a Blog

Scully is the best option for moving a blog to Angular!
Scully is the best option for moving a blog to Angular! It provides a schematic that enables Angular applications to use markdown files for blog's content.

It has a schematic that enables Angular applications to use markdown files for blog's content.
This guide covers the following topics:

1. [Adding Blog Support](#adding-blog-support)
2. [Generating New Blog Posts](#generating-new-blog-posts)

_IMPORTANT:_ You only need a Angular app with scully, if you don't have, please check first the [getting started](/docs/getting-started) docs.
_IMPORTANT:_ If you do not have an Angular app with Scully, please check the [getting started](/docs/getting-started) guide first.

## Adding Blog Support

To add blog support to your app, run the following command:
Add blog support by running the following command:

```bash
ng generate @scullyio/init:blog
```

This command adds the blog modules's routes to the Angular application. In addition, it creates a `./blog` folder for the blog's markdown files.

To create a folder with a different name, run the following command:
The above command adds the blog modules' routes to the Angular application. In addition, it creates a `./blog` folder for the blog's markdown files. In case you want to use a different folder name, run the following command:

```bash
ng generate @scullyio/init:markdown
```

and you need response some options
You will be prompted with the following questions;

```bash
? What name do you want to use for the module? blog
Expand All @@ -40,13 +38,7 @@ and you need response some options
? Under which route do you want your files to be requested? blog
```

or

```bash
ng generate @scullyio/init:markdown --name="blog" --slug="title" --source-dir="mdblog" --route="blog"
```

And the result is:
After adding the blog support, you should see the following message:

```bash
✅️ Update scully.{{yourApp}}.config.js
Expand All @@ -62,22 +54,25 @@ UPDATE src/app/blog/blog.module.ts (391 bytes)
CREATE mdblog/2020-03-24-blog.md (95 bytes)
```

**NOTE:** Slug is the name of the url matcher for search the file.
Alternatively, it is possible to run the `@scullyio/init:markdown` command with flags to avoid the prompts as follows:

```bash
ng generate @scullyio/init:markdown --name="blog" --slug="title" --source-dir="mdblog" --route="blog"
```

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' |
| `slug` | Defines the name for the url matcher file. `: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 |

Scully works well in combination with other tools and [utilities](utils.md).

For instance, if the markdown content includes code blocks, and you want to highlight it use the
[prismjs utility](/docs/utils.md#syntax-highlighting-using-prismjs).
For instance, if the markdown content includes code blocks, and you want to highlight them; use a utility.

## Generating New Blog Posts

Expand All @@ -89,9 +84,8 @@ ng generate @scullyio/init:post --name="This is my post"

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 |
| `extension` | define the file extension for the target file.<br>Out of the box Scully supports `adoc` and `md`.<br>You can handle other files by setting up your own [_File Handle Plugin_](plugins.md#file-plugin). | 'md' |
| 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 |
6 changes: 3 additions & 3 deletions docs/features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ lang: en

# Scully's Features

Under the hood, Scully analyzes your Angular application and generates a static
Under the hood, Scully analyzes an Angular application and generates a static
version of it. It provides several Angular schematics to make
its usage AS EASY AS POSSIBLE!

Expand All @@ -29,7 +29,7 @@ its usage AS EASY AS POSSIBLE!
[Schematics](/docs/schematics):

- Install and create files for Scully (ng-add).
- Creating a blog config for scully & Angular.
- Generate a plugin skeleton.
- Creating a blog config for Scully & Angular.
- Generate a plugin's skeleton.
- Run the router discovery.
- Create markdown files and skeleton.
139 changes: 58 additions & 81 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,20 @@ Before getting started, please read the [Prerequisites](pre-requisites.md).

**_All about Scully in one video_** : [Building the Fastest Angular Apps Possible](https://thinkster.io/tutorials/scully-webinar-building-the-fastest-angular-apps-possible)

This getting started guide covers topics:
This getting started guide covers the following topics:

1. [Installation](#installation)
2. [Building](#build)

## Installation

First, open in your terminal in the path of your Angular application and run the following command:
First, open an Angular application's path in your terminal and run the following command:

```bash
ng add @scullyio/init
```

This scheme installs and generates everything you need to start using Scully.
Once the installation finishes the following message will be displayed:
After a successful installation the following message will be displayed:

```bash
Installing packages for tooling via npm.
Expand All @@ -43,27 +42,31 @@ CREATE scully.{{yourApp}}.config.js (109 bytes)
UPDATE package.json (1438 bytes)
```

## Generate blog
## Generating a Blog

Run the following command to generate a blog module.

[more info here](blog.md)

```bash
ng generate @scullyio/init:blog
generate @scullyio/init:blog
```

This command will generate a blog module. [more info here](blog.md)

Once it is generated remove all the content in the `app.component.html` file, and add only the router outlet tag `<router-outlet></router-outlet>`.
Now, remove the `app.component.html` file's content just leave the `<router-outlet></router-outlet>` tag.

### Home page
[more info here](blog.md)

**It is necessary to create a _route entry point_ because the Angular CLI does not create one by default.**
### Creating the Application's Entry Point (Home Page)

Create a _Home Module_ with a _Home Component_ and its routes already configured with the following command:
Create a _Home Module_ with routes configured and with a _Home Component_ with the following command:

```bash
```ts
ng generate module home --route=home --module=app-routing
```
### Configuring the home module as root
**Scully depends on the _route entry point_.**
### Configuring the Home Module as the Project's Root
Open the `app-routing.module.ts` file and set an empty path attribute for the home route as shown below:
Expand All @@ -72,23 +75,25 @@ const routes: Routes = [
// ...
{
path: '',
loadChildren: () => import('./home/home.module').then(m => m.HomeModule),
},
loadChildren: () => import('./home/home.module').then(m => m.HomeModule)
}
];
```

### Inject the route service
### Injecting Scully's Route Service

Scully provides a service for accessing generated routes with ease.

Scully provides a service for accessing generated routes with ease. To use it, open the `home.component.ts` file and add the following code:
Open the `home.component.ts` file and add the following code:

```ts
import {ScullyRoutesService, ScullyRoute} from '@scullyio/ng-lib';
import {Observable} from 'rxjs';
import { ScullyRoutesService } from '@scullyio/ng-lib';
import { Observable } from 'rxjs';

@Component()
//...
export class HomeComponent implements OnInit {
links$: Observable<ScullyRoute[]> = this.scully.available$;
links$: Observable<any> = this.scully.available$;

constructor(private scully: ScullyRoutesService) {}

Expand All @@ -101,22 +106,7 @@ export class HomeComponent implements OnInit {
}
```

We can see `ScullyRoutesService.available$` returns an Observable of an array of `ScullyRoute`s, the interface of which looks like this:

```ts
export interface ScullyRoute {
route: string;
title?: string;
slugs?: string[];
published?: boolean;
slug?: string;
sourceFile?: string;
[prop: string]: any;
}
```

To extract data from the available `links$` Scully has rendered, we can loop through them inside the template by opening the `home.component.html` file and adding the following code:

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
<p>home works!</p>
Expand All @@ -126,70 +116,57 @@ To extract data from the available `links$` Scully has rendered, we can loop thr
</ul>
```

**NOTE:** If you don't add any route, scully will pre-render 0 pages.
**NOTE:** If Scully's route service is not added, it does not pre-render pages.

### Adding metadata to `ScullyRoutes`
## Building the Scully Application

At the very top of each `.md` blog post file, between the opening and closing `---` indicators, each line of text corresponds to a property we can pull out of `ScullyRoutesService.available$`.
At this point, the Angular project with Scully is ready.

For example, a `.md` file beginning with:
```
---
title: blog title
description: blog description
published: true
arbitraryValue: single value
arbitraryArray: [first item, second item]
---
```
Fist, build the Angular application by running the following command:

... lets us use these values in our template like this:
```html
<ul>
<li *ngFor="let page of links$ | async">
{{ page.route }}
{{ page.arbitraryValue }}
<span *ngFor="let arrayItem of page.arbitraryArray">
{{ arrayItem }}
</span>
</li>
</ul>
```bash
ng build
```

## Build
Now, build Scully and turn the Angular app into a pre-rendered static site.

```bash
npm run scully
```

At this point, you have your Angular project with Scully successfully installed.
Congratulations! You have turned your Angular application into a wicked fast pre-rendered one thanks to Scully.

#### IMPORTANT:
The built version of the static site is located in the `./dist/static` folder. It contains all the static pages.

_Scully requires the distribution files in the `./dist/my-scully-app` folder._
**NOTE:** In case of any errors or warnings during the build process, please follow the instructions in the errors/warnings section or [submit an issue](https://github.com/scullyio/scully/issues/new/choose).

**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.
## Serving the Static Site

Build the application in order to generate the distribution files:
Serve the content of the static site by running:

```bash
ng build
npm run scully serve
```

Now, lets build Scully and turn your Angular app into a pre-rendered static site.
The above command creates two web servers, one for the Angular app and one for the Scully app.

```bash
npm run scully
```
### Disabling JS

Congratulations! You have turned your Angular application into a wicked fast pre-rendered one thanks to Scully.
**Extra**: While serving the Scully app, [disable JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript/disable)
and the site's navigation still works. More importantly, most parts of the site still work even though JS has been disabled.

The built version is in the `./dist/static` folder. This folder contains all the pages in the site.
### Debungging the Scully App

**NOTE:** In case of any errors or warnings during the build process, please follow the instructions in the errors/warnings section or [submit an issue](https://github.com/scullyio/scully/issues/new/choose).
**Extra**: In order to debug the Scully application with ngServe, make sure to run:

#### Serving the content
```bash
npm run scully
```

Use `npm run scully:serve` to serve your content.
Scully serve is an option to create two web servers, one for your angular app and the other for the scully build.
Then, start the server:

**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.
```bash
npm run scully:serve
```

**Extra credits**: If you want to debug your blog page using ngServe, make sure you do a full run off `npm run scully` and then start `npm run scully:serve`. Then scully will use the generated HTML to fill in the content in your `ng serve` session.
Scully will use the generated HTML to fill in the `ng serve`'s session content.
4 changes: 2 additions & 2 deletions docs/issues.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ lang: en

# 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 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=)
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=)

The Scully team is working on better documentation for creating issues.
Loading

0 comments on commit a73558d

Please sign in to comment.