Merge pull request #215 from cloudflare/markdown-lint

Markdown linter

.travis.yml

@@ -2,6 +2,16 @@ go_import_path: github.com/cloudflare/unsee
 
 jobs:
   include:
+    - stage: Lint docs
+      language: node_js
+      node_js: "8"
+      cache:
+        directories:
+          - node_modules
+      # install defaults to "npm install", which is done via make
+      install: []
+      script: make lint-docs
+
     - stage: Test Go code
       language: go
       go:  "1.9.2"

Makefile

@@ -113,8 +113,12 @@ lint-go: .build/deps-lint-go.ok
 lint-js: .build/deps-build-node.ok
 	$(CURDIR)/node_modules/.bin/eslint --quiet assets/static/*.js
 
+.PHONY: lint-docs
+lint-docs: .build/deps-build-node.ok
+	$(CURDIR)/node_modules/.bin/markdownlint *.md docs
+
 .PHONY: lint
-lint: lint-go lint-js
+lint: lint-go lint-js lint-docs
 
 # Creates mock bindata_assetfs.go with source assets rather than webpack generated ones
 .PHONY: mock-assets

README.md

@@ -1,27 +1,28 @@
 # unsee
 
-Alert dashboard for [Prometheus Alertmanager](https://prometheus.io/docs/alerting/alertmanager/).
+Alert dashboard for
+[Prometheus Alertmanager](https://prometheus.io/docs/alerting/alertmanager/).
 
 Alertmanager UI is useful for browsing alerts and managing silences, but it's
 lacking as a dashboard tool - unsee aims to fill this gap.
 Starting with `0.7.0` release it can also aggregate alerts from multiple
 Alertmanager instances, running either in HA mode or separate. Duplicated alerts
 are deduplicated so only unique alerts are displayed. Each alert is tagged with
-names of all  Alertmanager instances it was found at and can be filtered based
+names of all Alertmanager instances it was found at and can be filtered based
 on those tags.
 
 ![Screenshot](/screenshot.png)
 
 To get notifications about new unsee releases you can subscribe to the RSS feed
-that GitHub provides - https://github.com/cloudflare/unsee/releases.atom
+that [GitHub provides](https://github.com/cloudflare/unsee/releases.atom)
 To get email notifications please use one of the free services providing
 _RSS to email_ notifications, like [Blogtrottr](https://blogtrottr.com/).
 
 ## Supported Alertmanager versions
 
-Alertmanager's API isn't stable yet and can change between releases,
-see `VERSIONS` in [internal/mock/Makefile](/internal/mock/Makefile) for list of all Alertmanager
-releases that are tested and supported by unsee.
+Alertmanager's API isn't stable yet and can change between releases, see
+`VERSIONS` in [internal/mock/Makefile](/internal/mock/Makefile) for list of all
+Alertmanager releases that are tested and supported by unsee.
 Due to API differences between those releases some features will work
 differently or be missing, it's recommended to use the latest supported
 Alertmanager version.
@@ -33,9 +34,9 @@ modify alerts or silence state, but it does provide a web interface that allows
 a user to send such requests directly to the Alertmanager API.
 If you wish to deploy unsee as a read-only tool please ensure that:
 
-  * the unsee process is able to connect to the Alertmanager API
-  * read-only users are able to connect to the unsee web interface
-  * read-only users are NOT able to connect to the Alertmanager API
+* the unsee process is able to connect to the Alertmanager API
+* read-only users are able to connect to the unsee web interface
+* read-only users are NOT able to connect to the Alertmanager API
 
 ## Metrics
 
@@ -91,21 +92,21 @@ Official docker images are built and hosted on
 
 Images are built automatically for:
 
-  * release tags in git - `cloudflare/unsee:vX.Y.Z`
-  * master branch commits - `cloudflare/unsee:latest`
+* release tags in git - `cloudflare/unsee:vX.Y.Z`
+* master branch commits - `cloudflare/unsee:latest`
 
 #### Examples
 
 To start a release image run:
 
-  docker run -e ALERTMANAGER_URI=https://alertmanager.example.com cloudflare/unsee:vX.Y.Z
+    docker run -e ALERTMANAGER_URI=https://alertmanager.example.com cloudflare/unsee:vX.Y.Z
 
 Latest release details can be found on
 [GitHub](https://github.com/cloudflare/unsee/releases).
 
 To start docker image build from lastet master branch run:
 
-  docker run -e ALERTMANAGER_URI=https://alertmanager.example.com cloudflare/unsee:latest
+    docker run -e ALERTMANAGER_URI=https://alertmanager.example.com cloudflare/unsee:latest
 
 Note that latest master branch might have bugs or breaking changes. Using
 release images is strongly recommended for any production use.
@@ -127,7 +128,7 @@ apply as with `make run`. Example:
 
 ## Configuration
 
-Please see [CONFIGURATION](/docs/CONFIGURATION.md) for full list of avaiable
+Please see [CONFIGURATION](/docs/CONFIGURATION.md) for full list of available
 configuration options and [example.yaml](/docs/example.yaml) for a config file
 example.
 

docs/CONFIGURATION.md

@@ -15,21 +15,15 @@ environment variables:
 
 Example with flags:
 
-```
-$ unsee --config.file example --config.dir ./docs/
-```
+    unsee --config.file example --config.dir ./docs/
 
 Example with environment variables:
 
-```
-$ CONFIG_FILE="example" CONFIG_DIR="./docs/" unsee
-```
+    CONFIG_FILE="example" CONFIG_DIR="./docs/" unsee
 
 Example using both:
 
-```
-$ CONFIG_FILE="example" unsee --config.dir ./docs/
-```
+    CONFIG_FILE="example" unsee --config.dir ./docs/
 
 ### Alertmanagers
 
@@ -288,7 +282,7 @@ listen:
   location other than `/`. This option is mostly useful when using unsee behind
   reverse proxy with other services on the same IP but different URL root.
 
-Example where unsee would listen for HTTP requests on http://1.2.3.4:80/unsee/
+Example where unsee would listen for HTTP requests on `http://1.2.3.4:80/unsee/`
 
 ```yaml
 listen:
@@ -347,7 +341,7 @@ jira:
   (where `FOO-1` is example issue ID).
 
 Example where a string `DEVOPS-123` inside a comment would be rendered as a link
-to https://jira.example.com/browse/DEVOPS-123.
+to `https://jira.example.com/browse/DEVOPS-123`.
 
 ```yaml
 jira:
@@ -463,42 +457,34 @@ section using only flags or environment variables.
 
 To set the `uri` key from `alertmanager.servers` map `ALERTMANAGER_URI` env or
 `--alertmanager.uri` flag can be used.
-Example:
+Examples:
 
-```
-$ ALERTMANAGER_URI=https://alertmanager.example.com unsee
-$ unsee --alertmanager.uri https://alertmanager.example.com
-```
+    ALERTMANAGER_URI=https://alertmanager.example.com unsee
+    unsee --alertmanager.uri https://alertmanager.example.com
 
 ### Alertmanager name
 
 To set the `name` key from `alertmanager.servers` map `ALERTMANAGER_NAME` env or
 `--alertmanager.name` flag can be used.
-Example:
+Examples:
 
-```
-$ ALERTMANAGER_NAME=single unsee
-$ unsee --alertmanager.name single
-```
+    ALERTMANAGER_NAME=single unsee
+    unsee --alertmanager.name single
 
 ### Alertmanager timeout
 
 To set the `timeout` key from `alertmanager.servers` map `ALERTMANAGER_TIMEOUT`
 env or `--alertmanager.timeout` flag can be used.
-Example:
+Examples:
 
-```
-$ ALERTMANAGER_TIMEOUT=10s unsee
-$ unsee --alertmanager.timeout 10s
-```
+    ALERTMANAGER_TIMEOUT=10s unsee
+    unsee --alertmanager.timeout 10s
 
 ### Alertmanager request proxy
 
 To set the `proxy` key from `alertmanager.servers` map `ALERTMANAGER_PROXY`
 env or `--alertmanager.proxy` flag can be used.
-Example:
+Examples:
 
-```
-$ ALERTMANAGER_PROXY=true unsee
-$ unsee --alertmanager.proxy
-```
+    ALERTMANAGER_PROXY=true unsee
+    unsee --alertmanager.proxy