Added config documentation. Refactored 'Getting Started' section of R…

…EADME.md

README.md

@@ -4,28 +4,46 @@
 [![Build Status](https://travis-ci.org/rakutentech/docpub.svg?branch=master)](https://travis-ci.org/rakutentech/docpub)
 [![Coverage Status](https://coveralls.io/repos/github/rakutentech/docpub/badge.svg)](https://coveralls.io/github/rakutentech/docpub)
 
-DocPub is a command line utility for converting a folder structure of markdown files to HTML and uploading the result to Zendesk.
+**DocPub** is a command line utility for converting a folder structure of markdown files to HTML and uploading the result to Zendesk.
 
 ## Getting Started
 
-1. Install the utility globally with `npm install -g docpub`
-2. Set environment variables for your Zendesk username, token, and url by running the following commands:
+### Installing
 
-    - `ZENDESK_API_USERNAME="{Your username}"`
-    - `ZENDESK_API_TOKEN="{Your API token}"`
-    - `ZENDESK_URL="{Your fully qualified Zendesk URL}"`
-
-You can alternative create an enviroment profile in your home directory. Using bash, add the variables to your `.bash_profile`, if there is no file, create it.
+To install the utility, use [npm](https://www.npmjs.org/) `install` command:
 
+```sh
+npm install -g docpub
 ```
-export ZENDESK_API_USERNAME="{Your username}"
-export ZENDESK_API_TOKEN="{Your API token}"
-export ZENDESK_URL="{Your fully qualified Zendesk URL}"
+
+Global installation is used for launching commands.
+
+### Configuring
+
+**DocPub** is configured using a config file. The only supported config file format is `JSON`.
+By default, **DocPub** looks for the config in the root of documentation folder by `docpub.conf` name.
+If needed, specific config location may be set with `--config-path` CLI option. Please note, that
+this option accepts path to the file, not to the folder, where config is located
+
+The minimal config must include following required options:
+
+- `username` - name of ZenDesk user with documentation publish access rights
+- `token` - access token of the user above
+- `url` - fully qualified URL of your `ZenDesk` space
+
+Example:
+```javascript
+{
+    "username": "user@example.com"
+    "token": "abc123def456ghi789"
+    "url": "example.zendesk.com"
+}
 ```
+Please see more about other configuration options and options overriding in [config](doc/config.md) section.
 
-Then check that the variables are included with `env`.
+### Running
 
-3. Run the command `docpub` from the directory that you wish to convert and upload.
+Run the command `docpub` from the directory that you wish to convert and upload.
 
 This will do the following:
 - Convert the contained markdown files to HTML
@@ -55,6 +73,5 @@ Tests are divided into unit tests and functional tests, and utilize [SinonJS](ht
 
 ### Precommit and Preversion Hooks
 
-[husky](https://github.com/typicode/husky) is used to provide hooks prior to committing and versioning. This will run the unit and functional tests as well as [ESLint](http://eslint.org/) to make sure that the code style is correct and has no syntax errors.
-
+[husky](https://github.com/typicode/husky) is used to provide hooks prior to committing and versioning. This will run linter for commits and linter + all tests for releases.
 If any of the tests fail to pass or any file doesn't meet the ESLint specifications, you will not be allowed to commit or version.

docs/config.md

@@ -0,0 +1,81 @@
+# DocPub configuration
+
+**DocPub** is configured using `docpub.conf` file at the root of the project.
+
+Complete example with all available settings looks like this, but you'll need
+to specify only a few settings specific for your project:
+
+```javascript
+{
+    "username": "user@example.com"
+    "token": "abc123def456ghi789"
+    "url": "example.zendesk.com"
+    "rendering": {
+        "highlight": true
+    }
+}
+```
+
+## Available settings
+
+### Generic settings:
+
+* `username` (required) — name of ZenDesk user with documentation publish access rights.
+  On ZenDesk, this user would be displayed as documentation publisher.
+
+* `token` (required) — access token of the user above.
+
+* `url` (required) — fully qualified URL of your `ZenDesk` space. Please note, that this should
+  be only base URL, path shall not be included. Example: `example.zendesk.com`
+
+### Rendering settings
+
+Rendering settings are controlling Markdown to HTML conversion process. Mostly control appearance,
+but may add impact on resulting HTML structure too.
+
+Settings list:
+
+* `highlight` - should highlighting be applied to code block in markdown or not.
+  If enabled, will add HTML markup and CSS classes provided by [highlight.js](https://highlightjs.org).
+  Please note, that stylesheets themselves will be neither linked nor inlined into
+  the resulting HTML because, by default, such content considered as unsafe and
+  stripped out by ZenDesk. Stylesheets shall be added separately to the ZenDesk template.
+  Default option value: `true`.
+
+## Overriding settings
+
+All options can also be overridden via command-line flags or environment
+variables. Priorities are the following:
+
+* command-line option has the highest priority. It overrides environment
+  variable and config file value.
+
+* environment variable has second priority. It overrides config file value.
+
+* config file value has the lowest priority.
+
+* if no command-line option, environment variable or config file option
+  specified, default is used.
+
+To override config setting with CLI option, convert full option path to
+`--kebab-case`. For example, if you want publish documents to different ZenDesk
+space, call:
+
+```sh
+docpub --url http://example.com
+```
+
+To disable code highlighting in resulting HTML, you may do following:
+
+```sh
+docpub --rendering-highlight=false
+```
+
+To override setting with environment variable, convert its full path to
+`snake_case` and add `docpub_` prefix. Above examples can be rewritten to use
+environment variables instead of CLI options:
+
+```
+docpub_url=http://example.com docpub
+docpub_rendering_highlight=false docpub
+```