-
Notifications
You must be signed in to change notification settings - Fork 256
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d999119
commit a36d7f0
Showing
11 changed files
with
168 additions
and
128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Code of Conduct | ||
|
||
This will be prepared before we end the alpha phase of our development. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
# Scully w/ Blogs | ||
|
||
Scully is your best friend when you want to move you 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. | ||
|
||
1. [Adding Blog Support](#adding-blog-support) | ||
2. [Generating New Blog Posts](#generating-new-blog-posts) | ||
|
||
## Adding Blog Support | ||
|
||
To add blog support to your app, run the following command: | ||
|
||
```bash | ||
ng g @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. | ||
|
||
To name your blog folders and components another name, run the following command with your own name: | ||
|
||
```bash | ||
ng g @scullyio/init:markdown --name=cooking | ||
``` | ||
|
||
## Generating New Blog Posts | ||
|
||
To add a new blog post, run the following command. T | ||
|
||
``` | ||
ng g @scullyio/init:post --title | ||
``` | ||
|
||
--- | ||
Next: [Full Documentation ➡️](scully.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,136 +1,63 @@ | ||
# Scully - Getting Started | ||
|
||
After created your Angular application go to your command line using Angular-CLI, you need to add Scully to your project: | ||
The first thing you need to get started with Scully is a working Angular app using Angular 8.* or 9.*. | ||
|
||
```bash | ||
ng add @scullyio/init | ||
``` | ||
This getting started doc covers the three steps to adding Scully into your project. | ||
|
||
The command above set up the necessary to start to work with Scully (_we go to get more deep about this in next releases._). | ||
1. [Installation](#installation) | ||
2. [Build](#build) | ||
3. [Test](#test) | ||
|
||
If the installation was success you can read a message similar to this one. | ||
|
||
## Installation | ||
To install Scully, do the following: From the root directory of your Angular project (in a terminal window), run the following command: | ||
```bash | ||
Installed packages for tooling via yarn. | ||
✔ Added dependency | ||
✔ Import HttpClientModule into root module | ||
UPDATE package.json (1447 bytes) | ||
UPDATE src/app/app.module.ts (472 bytes) | ||
UPDATE src/polyfills.ts (3035 bytes) | ||
UPDATE src/app/app.component.ts (325 bytes) | ||
✔ Packages installed successfully. | ||
✔ Update package.json | ||
CREATE scully.config.js (65 bytes) | ||
UPDATE package.json (1507 bytes) | ||
``` | ||
|
||
## @scullyio/init:blog | ||
|
||
Scully have built-in schematics to use, `@scullyio/init:blog` allows you to create a full Lazy Loaded feature module to start your basic | ||
static site. | ||
|
||
You just need write in your command line: | ||
|
||
```bash | ||
ng g @scullyio/init:blog | ||
``` | ||
|
||
After the execution, you should read: | ||
``` | ||
CREATE src/app/blog/blog-routing.module.ts (336 bytes) | ||
CREATE src/app/blog/blog.module.ts (335 bytes) | ||
CREATE src/app/blog/blog.component.css (0 bytes) | ||
CREATE src/app/blog/blog.component.html (19 bytes) | ||
CREATE src/app/blog/blog.component.spec.ts (614 bytes) | ||
CREATE src/app/blog/blog.component.ts (261 bytes) | ||
UPDATE src/app/app-routing.module.ts (336 bytes) | ||
✔ Blog 12-13-2019-blog-X file created | ||
✔ Update scully.config.js | ||
CREATE blog/12-13-2019-blog-X.md (101 bytes) | ||
UPDATE scully.config.js (121 bytes) | ||
``` | ||
|
||
As you can see above `ng g @scullyio/init:blog` creates the following files for you: | ||
|
||
- blog-routing.module.ts | ||
- blog.module.ts | ||
- blog.component.css | ||
- blog.component.html | ||
- blog.component.spec.ts | ||
- blog.component.ts | ||
|
||
Also, it updated the `app-routing.module.ts` with the new module added. Last but not least we added `scully.config.js` and create a | ||
folder named `/blog` wich inside have a markdown file. | ||
|
||
###### `scully.config.js` | ||
|
||
Inside this file, we can find all the routes of your app generated automatically from Scully. | ||
|
||
```js | ||
exports.config = { | ||
projectRoot: "./src/app", | ||
routes: { | ||
'/blog/:slug': { | ||
type: 'contentFolder' | ||
}, | ||
} | ||
}; | ||
ng add @scullyio/init | ||
``` | ||
|
||
##### What if I don't want a module called "blog"? | ||
At this point, Scully has been added to your project. The most important part of the installation is the addition of the | ||
Scully configuration file: `scully.config.js` (_soon this will be `scully.config.ts`_). To learn more about this file, | ||
read [Scully Configuration](scully-configuration.md) docs. | ||
|
||
If for any reason you want to customize the name of your module we have a specific command for that. | ||
## Build | ||
|
||
## @scullyio/init:markdown --name | ||
|
||
With `@scullyio/init:markdown` you can customize the name of your modules easy, just adding the flag `--name` | ||
So you have your Angular app AND you have installed Scully. So let's run a scully build to turn your site into a | ||
pre-rendered Angular app. Because scully runs based on a build of your app, the first step is to build your Angular | ||
project. Then you can run the scully build. | ||
|
||
```bash | ||
ng g @scullyio/init:markdown --name=categories | ||
ng build | ||
npm run scully | ||
``` | ||
|
||
The example above allows you to create a new Lazy Loaded Module named "categories". | ||
|
||
That's it. You're done! In your project directory, you now have a `/dist/static` folder that contains the built version | ||
of your app. | ||
|
||
## ng g @scullyio/init:post --title | ||
__NOTE:__ If you had any errors or warning during the build phase, please follow the instructions in the errors/warnings | ||
(if applicable) or [submit an issue](issues). | ||
|
||
PENDING | ||
## Test | ||
|
||
``` | ||
ng g @scullyio/init:post --title | ||
``` | ||
Now that you're project has been pre-rendered, you can validate the build in one of a few ways. | ||
|
||
### Time to build! | ||
1. Serve the contents of your `dist/static` directory | ||
2. Browse the contents of `dist/static` directory and read the HTML | ||
|
||
At this moment we know how to create our static site using Scully, but now it's time to build and see the magic. | ||
#### Serve the contents | ||
|
||
#### Step one, build our angular app | ||
Using something like [http-server](https://www.npmjs.com/package/http-server) you can serve the contents of your | ||
`dist/static` folder. All routes that work in your non-pre-rendered Angular app should still work. Not all apps are | ||
capable of running without | ||
|
||
We need to build our Angular app using the command: | ||
__Extra Credit__: While serving your app, [disable javasript](https://developers.google.com/web/tools/chrome-devtools/javascript/disable) | ||
and make sure that you app still works. This is the goal for your app, to run with JavaScript disabled. Most of the | ||
parts of your app should work without JS enabled. | ||
|
||
```bash | ||
ng build | ||
``` | ||
|
||
After finished this process the Angular-CLI should create the dist folder with all our fully compiled app. | ||
|
||
#### Step two, build using Scully | ||
|
||
```bash | ||
npm run scully | ||
``` | ||
|
||
As a result of command line above inside the `dist` folder we should found another 2 folder: | ||
|
||
``` | ||
|-- dist/ | ||
| |-- my-project-name/ | ||
| |-- static/ | ||
#### Browse the contents | ||
|
||
``` | ||
Browse the contents of your `dist/static` directory and make sure that all of your pages were pre-rendered and saved to | ||
HTML correctly. | ||
|
||
`static` folder contains all our static site ready for deploy to your favorite server. | ||
|
||
--- | ||
Prev: [Pre-requisites ⬅️️](pre-requisites.md) | Next: [Working with Plugins ➡️](working-with-plugins.md) | ||
Next: [Full Documentation ➡️](scully.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Scully Issues | ||
|
||
Better documentation will be added for creating issues. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
# Plugins | ||
|
||
Scully uses a plugin system to allow users to define new ways for Scully to build your app. There are two main types of | ||
plugins: | ||
|
||
1. [Route Plugins](#route-plugins) | ||
2. [Data Transform Plugins](#transform-plugins) | ||
|
||
See our [Recommended Plugins](recommended-plugins.md) page to find a list of available plugins. | ||
|
||
## <a name="route-plugins"></a> Route Plugins | ||
|
||
Scully needs __Route 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 plugin that teaches Scully how to get the data needed for those route | ||
parameters. | ||
|
||
Let's look at an example. 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: | ||
``` | ||
/user/10 | ||
/user/11 | ||
/user/12 | ||
/user/13 | ||
/user/14 | ||
``` | ||
|
||
To provide this list of User IDs to Scully, you'll use a __Route Plugins__. | ||
|
||
The following is an example that uses the [jsonplaceholder](https://jsonplaceholder.typicode.com/) to fetch a list of | ||
User IDs for my app. | ||
|
||
```javascript | ||
// scully.config.js | ||
exports.config = { | ||
// Add the following to your file | ||
routes: { | ||
"/user/:userId": { | ||
"type": "json", | ||
"userId": { | ||
"url": "https://jsonplaceholder.typicode.com/users", | ||
"property": "id" | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
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. | ||
|
||
|
||
## <a name="transform-plugins"></a> Data Transform Plugins | ||
|
||
Describe data transform plugins |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
# Community Plugins | ||
|
||
The following is a list of our recommended Scully plugins. | ||
|
||
_If you would like to add a plugin to this list, please submit a PR to the `docs/recommended-plugins.md`._ | ||
|
||
## Official Plugins | ||
|
||
- `json` plugin | ||
- `content` plugin (_we will be renaming this_) | ||
|
||
## Community Plugins | ||
|
||
- (_be the first to submit a plugin_) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Scully Configuration | ||
|
||
The center of every scully project is the `scully.config.js`. This config file must export the configuration for your | ||
scully build. Whether you need to add a |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.