first working version :-)

Author: JohannesHoppe

README.md

@@ -1,6 +1,7 @@
 # angular-cli-ghpages
 [![NPM version][npm-image]][npm-url]
 [![CircleCI](https://circleci.com/gh/angular-schule/angular-cli-ghpages.svg?style=svg)](https://circleci.com/gh/angular-schule/angular-cli-ghpages)
+[![The MIT License](https://img.shields.io/badge/license-MIT-orange.svg?color=blue&style=flat-square)](http://opensource.org/licenses/MIT)
 
 <!--
 TODO: cool screenshot with animated gif
@@ -18,20 +19,23 @@ Deploy your Angular app to GitHub pages directly from the Angular CLI! 🚀
 A detailed changelog is available in the [releases](https://github.com/angular-schule/angular-cli-ghpages/releases) section.
 
 In the past this project was a standalone program.
-This is still possible.
-See the documentation at (https://github.com/angular-schule/angular-cli-ghpages/blob/master/README_standalone.md)[README_standalone].
+This is still possible.  
+See the documentation at [README_standalone](README_standalone).
 
 
 ## ⚠️ Prerequisites <a name="prerequisites"></a>
 
-This action has the following prerequisites:
+This command has the following prerequisites:
 
 - Git 1.9 or higher (execute `git --version` to check your version)
 - Angular project created via [Angular CLI](https://github.com/angular/angular-cli)
 
 
 ## 🚀 Quick-start <a name="quickstart"></a>
 
+This quickstart assumes that you are starting from scratch.
+If you alreay have an existing Angular project on GitHub, skip step 1 and 2.
+
 1. Install the next version of the Angular CLI (v8.3.0-next.0 or greater)
    and create a new Angular project.
 
@@ -41,38 +45,65 @@ This action has the following prerequisites:
    cd hello-world
    ```
 
-2. Add `angular-cli-ghpages` to your project.
+2. By default the Angular CLI initializes a git repository for you.  
+   To add a new remote for GitHub, use the `git remote add` command:
+
+   ```sh
+   git remote add origin https://github.com/<username>/<repositoryname>.git
+   ```
+
+   Hints:  
+   * Create a new empty GithHub repository first.
+   * Replace `<username>` and `<repositoryname>` with your username from GitHub and the name of your new repository. 
+   * Please enter the URL `https://github.com/<username>/<repositoryname>.git` into your browser – you should see your existing repository on GitHub. 
+   * Please double-check that you have the necessary rights to make changes to the given project!  
+
+3. Add `angular-cli-ghpages` to your project.
 
    ```sh
    ng add angular-cli-ghpages
    ```
 
-3. Deploy your project to Github pages with all default settings.
+4. Deploy your project to Github pages with all default settings.
    Your project will be automatically build in production mode.
 
    ```sh
    ng run hello-world:deploy
    ```
 
+5. Your project should be available at `http(s)://<username>.github.io/<projectname>`.
+   Learn more about GitHub pages on the [official website](https://pages.github.com/).
+
+
+## Options
+
+- `--base-href` - specifies the base url for the application being built. Same as `ng build --base-href=XXX`.
+- `--configuration`
+- TODO: document all the other options! 
+
+
 ## 🏁 Next milestones <a name="milestones"></a>
 
 We are glad that we have an integration into the CLI again.
 But we are looking forward to the following features:
 
-* an interactive command-line prompt that guides you through the available options and outputs a `angular-cli-ghpages.json` file 
+* an interactive command-line prompt that guides you through the available options 
+* a configuration file (`angular-cli-ghpages.json`) to avoid all these command-line cmd options
 
-We look forward to any help. PRs are welcome!
+We look forward to any help. PRs are welcome! 😃
 
 ## ⁉️ FAQ <a name="faq"></a>
 
 Before posting any issue, [please read the FAQ first](https://github.com/angular-schule/angular-cli-ghpages/wiki/FAQ).
+See the contributors documentation at [README_contributors](README_contributors) if you want to debug and test this project.
+
 
 ## License
 Code released under the [MIT license](LICENSE).
 
 <hr>
 
-<img src="http://assets.angular.schule/logo-angular-schule.png" height="60">  
+<img src="https://assets.angular.schule/logo-angular-schule.png" height="60">  
 
 ### &copy; 2019 https://angular.schule
 

README_contributors.md

@@ -1,9 +1,110 @@
 # angular-cli-ghpages
 
-## How to start
+## How to start <a name="start"></a>
+
+tl;dr – execute this:
 
 ```
 npm i
 npm run build
 npm test
-```
+```
+
+
+## Local development <a name="local-dev"></a>
+
+If you want to try the latest package locally without installing it from npm, use the following instructions.
+This may be useful when you want to try the latest non published version of this library or you want to make a contribution.
+
+Follow the instructions for [checking and updating the Angular CLI version](#angular-cli) and then link the package.
+
+
+### 1. Angular CLI <a name="angular-cli"></a>
+
+1. Install the next version of the Angular CLI.
+
+   ```sh
+   npm install -g @angular/cli@next
+   ```
+
+2. Run `ng --version`, make sure you have angular CLI version v8.3.0-next.0 or greater.
+
+3. Update your existing project using the command:
+
+   ```sh
+   ng update @angular/cli @angular/core --next=true
+   ```
+
+
+### 2. npm link
+
+Use the following instructions to make `angular-cli-ghpages` available locally via `npm link`.
+
+1. Clone the project
+
+   ```sh
+   git clone https://github.com/angular-schule/angular-cli-ghpages.git
+   cd angular-cli-ghpages
+   ```
+
+2. Install the dependencies
+
+   ```sh
+   npm install
+   ```
+
+3. Build the project:
+
+   ```sh
+   npm run build
+   ```
+
+4. Create a local npm link:
+
+   ```sh
+   cd dist
+   npm link
+   ```
+
+
+### 3. Adding to an Angular project - ng add <a name="local-dev-add"></a>
+
+Once you have completed the previous steps to npm link the local copy of `angular-cli-ghpages`,
+follow these steps to use it in a local angular project.
+
+1. Enter the project's directory
+
+   ```sh
+   cd your-angular-project
+   ```
+
+2. Add the local version of `angular-cli-ghpages`.
+
+   ```sh
+   npm link angular-cli-ghpages
+   ```
+
+3. Now execute the schematic.
+
+   ```sh
+   ng add angular-cli-ghpages
+   ```
+
+4. Now you can deploy your angular app to Github pages.
+
+   ```sh
+   ng run your-angular-project:deploy
+   ```
+
+5. You can remove the link later by running `npm unlink`
+
+
+### 4. Testing <a name="testing"></a>
+
+Testing is done with [Jest](https://jestjs.io/).
+To run the tests:
+
+```sh
+cd angular-cli-ghpages
+npm test
+```

deploy/actions.ts

@@ -15,13 +15,17 @@ export default async function deploy(
     throw new Error('Cannot execute the build target');
   }
 
-  context.logger.info(`📦 Building "${context.target.project}"`);
+  const configuration = options.configuration ? options.configuration : 'production'
+
+  context.logger.info(`📦 Building "${ context.target.project }". Configuration: "${ configuration }".${ options.baseHref ? ' Your base-href: "' + options.baseHref + '"' : '' }`);
 
   const build = await context.scheduleTarget({
     target: 'build',
     project: context.target.project,
-    configuration: 'production'
-  }, options);
+    configuration
+  }, {
+    baseHref: options.baseHref ? options.baseHref : null
+  });
   await build.result;
 
   await engine.run(

deploy/builder.ts

@@ -48,7 +48,8 @@ export default createBuilder<any>(
         options
       );
     } catch (e) {
-      context.logger.error('Error when trying to deploy: ', e.message);
+      context.logger.error('Error when trying to deploy:', e);
+      console.error(e);
       return { success: false };
     }
 

engine/engine.ts

@@ -15,7 +15,7 @@ export async function run(dir: string, options: RealDeployOptions, logger: loggi
   // always clean the cache directory.
   // avoids "Error: Remote url mismatch."
   if (options.dryRun) {
-    logger.info('*** Dry-run / SKIPPED: cleaning of the cache directory');
+    logger.info('Dry-run / SKIPPED: cleaning of the cache directory');
   } else {
     ghpages.clean();
   }
@@ -26,10 +26,10 @@ export async function run(dir: string, options: RealDeployOptions, logger: loggi
     await createCnameFile(dir, options, logger);
     await publishViaGhPages(ghpages, dir, options, logger);
 
-    logger.info('*** 🚀 Successfully published! Have a nice day!');
+    logger.info('🚀 Successfully published via angular-cli-ghpages! Have a nice day!');
   }
   catch (error) {
-    logger.error('*** An error occurred!', error);
+    logger.error('❌ An error occurred!');
     throw error;
   }
 };
@@ -51,7 +51,7 @@ function prepareOptions(origOptions: RealDeployOptions, logger: logging.LoggerAp
   }
 
   if (options.dryRun) {
-    logger.info('*** Dry-run: No changes are applied at all.');
+    logger.info('Dry-run: No changes are applied at all.');
   }
 
   if (options.name && options.email) {
@@ -86,14 +86,14 @@ function prepareOptions(origOptions: RealDeployOptions, logger: logging.LoggerAp
 
 async function checkIfDistFolderExists(dir: string) {
   if (await !fse.pathExists(dir)) {
-    throw new Error('*** Dist folder does not exist. Check the dir --dir parameter or build the project first!');
+    throw new Error('Dist folder does not exist. Check the dir --dir parameter or build the project first!');
   }
 }
 
 async function createNotFoundPage(dir: string, options: RealDeployOptions, logger: logging.LoggerApi) {
 
   if (options.dryRun) {
-    logger.info('*** Dry-run / SKIPPED: copying of index.html to 404.html');
+    logger.info('Dry-run / SKIPPED: copying of index.html to 404.html');
     return;
   }
 
@@ -108,7 +108,7 @@ async function createNotFoundPage(dir: string, options: RealDeployOptions, logge
     return await fse.copy(indexHtml, notFoundPage);
   }
   catch (err) {
-    logger.info('index.html could not be copied to 404.html. This does not look like an angular project?!');
+    logger.info('index.html could not be copied to 404.html. This does not look like an angular-cli project?!');
     logger.info('(Hint: are you sure that you have setup the directory correctly?)');
     logger.debug('Diagnostic info', err);
     return;
@@ -123,23 +123,23 @@ async function createCnameFile(dir: string, options: RealDeployOptions, logger:
 
   const cnameFile = path.join(dir, 'CNAME');
   if (options.dryRun) {
-    logger.info('*** Dry-run / SKIPPED: creating of CNAME file with content: ' + options.cname);
+    logger.info('Dry-run / SKIPPED: creating of CNAME file with content: ' + options.cname);
     return;
   }
 
   try {
     await fse.writeFile(cnameFile, options.cname);
-    logger.info('*** CNAME file created');
+    logger.info('CNAME file created');
   }
   catch (err) {
-    logger.error('*** CNAME file could not be created. Stopping execution.');
+    logger.error('CNAME file could not be created. Stopping execution.');
     throw err;
   }
 }
 
 async function publishViaGhPages(ghPages: GHPages, dir: string, options: RealDeployOptions, logger: logging.LoggerApi) {
   if (options.dryRun) {
-    logger.info('*** Dry-run / SKIPPED: publishing folder "' + dir + '" with the following options:', {
+    logger.info(`Dry-run / SKIPPED: publishing folder "${ dir }" with the following options: ` + JSON.stringify({
       dir: dir,
       repo: options.repo || 'falsy: current working directory (which must be a git repo in this case) will be used to commit & push',
       message: options.message,
@@ -148,7 +148,7 @@ async function publishViaGhPages(ghPages: GHPages, dir: string, options: RealDep
       silent: options.silent || 'falsy: logging is in silent mode by default',
       dotfiles: options.dotfiles || 'falsy: dotfiles are included by default',
       cname: options.cname || 'falsy: no CNAME file will be created',
-    } as any);
+    }) as any);
     return;
   }