Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(grammar): improve grammar for the docs #579

Merged
merged 2 commits into from
May 26, 2020
Merged

docs(grammar): improve grammar for the docs #579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
25b5129
docs(grammar): improve grammar for the docs
GuzmanPI May 25, 2020
3c040db
Merge branch 'master' of https://github.com/scullyio/scully into docs…
GuzmanPI May 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 20 additions & 26 deletions docs/blog.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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