From 063ee689df986369e573a73ea5a7daff0a7ad5db Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Mon, 16 Nov 2015 11:23:53 +0000 Subject: [PATCH] docs --- README.md | 45 +++++++++++++++++++++++++++++++++------------ jsdoc2md/README.hbs | 45 +++++++++++++++++++++++++++++++++------------ 2 files changed, 66 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 17644fb..ff4b2de 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A simple web-server for productive front-end development. **Requires node v4.0.0 or higher**. ## Synopsis -Some typical use cases. For these examples, assume we're in a site directory looking like this: +For the examples below, assume we're in a project directory looking like this: ```sh . @@ -35,7 +35,9 @@ You're building a web app with client-side routing, so mark `index.html` as the $ ws --spa index.html ``` -By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found`. By marking `index.html` as the SPA you create this rule: *if a file with that url exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then pass it to the SPA*. +By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found` as there is no file at that location on disk. By marking `index.html` as the SPA you create this rule: + +*if a file with that url exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then pass it to the SPA.* ### Access Control @@ -60,6 +62,7 @@ $ ws --rewrite "/api => http://api.example.com/api" \ ``` ### Mock Responses +*Coming soon*. ### Stored config @@ -75,10 +78,26 @@ Always use this port and blacklist? Persist it to the config: } ``` +### Logging +By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`: + +```sh +$ ws --log-format combined +serving at http://localhost:8000 +::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36" +``` + ### Other features Compression, caching, simple statistics view, log, override mime types. +## Tips + +### Use with Google DevTools Workspaces + +### Log Visualisation +Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation). + ## Install Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`. @@ -86,16 +105,21 @@ Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need $ npm install -g local-web-server ``` +This will install the `ws` tool globally. To see the available options, run: +```sh +$ ws --help +``` + ## Distribute with your project The standard convention with client-server applications is to add an `npm start` command to launch the server component. -1. Install the server as a dev dependency +1\. Install the server as a dev dependency ```sh $ npm install local-web-server --save-dev ``` -2. Add a `start` command to your `package.json`: +2\. Add a `start` command to your `package.json`: ```json { @@ -111,11 +135,12 @@ $ npm install local-web-server --save-dev } ``` -3. Document how to build and launch your site +3\. Document how to build and launch your site ```sh $ npm install $ npm start +serving at http://localhost:8100 ``` ## Storing default options @@ -165,12 +190,6 @@ You can set additional mime-type/extension mappings, or override the defaults by } ``` -## Use with Google DevTools Workspaces - - -## Log Visualisation -Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation). - ## API Reference @@ -191,6 +210,8 @@ Returns a Koa application const localWebServer = require('local-web-server') ``` +## Composition + * * * -© 2015 Lloyd Brookes <75pound@gmail.com> +© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown). diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs index f376a0d..8daa6d3 100644 --- a/jsdoc2md/README.hbs +++ b/jsdoc2md/README.hbs @@ -10,7 +10,7 @@ A simple web-server for productive front-end development. **Requires node v4.0.0 or higher**. ## Synopsis -Some typical use cases. For these examples, assume we're in a site directory looking like this: +For the examples below, assume we're in a project directory looking like this: ```sh . @@ -35,7 +35,9 @@ You're building a web app with client-side routing, so mark `index.html` as the $ ws --spa index.html ``` -By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found`. By marking `index.html` as the SPA you create this rule: *if a file with that url exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then pass it to the SPA*. +By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found` as there is no file at that location on disk. By marking `index.html` as the SPA you create this rule: + +*if a file with that url exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then pass it to the SPA.* ### Access Control @@ -60,6 +62,7 @@ $ ws --rewrite "/api => http://api.example.com/api" \ ``` ### Mock Responses +*Coming soon*. ### Stored config @@ -75,10 +78,26 @@ Always use this port and blacklist? Persist it to the config: } ``` +### Logging +By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`: + +```sh +$ ws --log-format combined +serving at http://localhost:8000 +::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36" +``` + ### Other features Compression, caching, simple statistics view, log, override mime types. +## Tips + +### Use with Google DevTools Workspaces + +### Log Visualisation +Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation). + ## Install Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`. @@ -86,16 +105,21 @@ Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need $ npm install -g local-web-server ``` +This will install the `ws` tool globally. To see the available options, run: +```sh +$ ws --help +``` + ## Distribute with your project The standard convention with client-server applications is to add an `npm start` command to launch the server component. -1. Install the server as a dev dependency +1\. Install the server as a dev dependency ```sh $ npm install local-web-server --save-dev ``` -2. Add a `start` command to your `package.json`: +2\. Add a `start` command to your `package.json`: ```json { @@ -111,11 +135,12 @@ $ npm install local-web-server --save-dev } ``` -3. Document how to build and launch your site +3\. Document how to build and launch your site ```sh $ npm install $ npm start +serving at http://localhost:8100 ``` ## Storing default options @@ -165,16 +190,12 @@ You can set additional mime-type/extension mappings, or override the defaults by } ``` -## Use with Google DevTools Workspaces - - -## Log Visualisation -Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation). - ## API Reference {{>main}} +## Composition + * * * -© 2015 Lloyd Brookes <75pound@gmail.com> +© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).