fix: add ability to lint markdown

.github/workflows/style.yml

@@ -0,0 +1,30 @@
+# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: WebsiteCI
+
+on:
+  push:
+    branches: [ master ]
+    paths: 
+       - "docs/**"
+  pull_request:
+    branches: [ master ]
+    paths: 
+       - "docs/**"
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install && npm run lint

.gitignore

@@ -1 +1,3 @@
 **/.DS_Store
+node_modules
+yarn.lock

CONTRIBUTING.md

@@ -4,3 +4,13 @@ Contributions are welcome through pull requests, however, the reference architec
 is intended to reflect the opinion of Red Hat and IBM based on the key tenants
 outlined in the README.md. Therefore only PR's which are aligned with that
 opinion will be accepted.
+
+# Checking formatting and style
+
+Before pushing changes contributors need to ensure that their markdown spec is valid
+by executing
+
+```
+npm install
+npm run lint
+```

README.md

@@ -14,28 +14,29 @@ looking to the `team` for an opinion of where to start.
 The components in this architecture are what we recommend to help internal
 and external customers get started based on our experience. Other components may be equally
 good, but these are the ones we know best and have the most experience with.
-* Where possible the opinion is based on what we've used internally and in our customer engagements.
-* The components specified will be our first priority for our contributions to open source projects in the JavaScript ecosystem.
-* Due to the above these are the components the `team` is best positioned when working with internal and external customers.
+
+- Where possible the opinion is based on what we've used internally and in our customer engagements.
+- The components specified will be our first priority for our contributions to open source projects in the JavaScript ecosystem.
+- Due to the above these are the components the `team` is best positioned when working with internal and external customers.
   However, we do not include formal support for these components in any of our support offerings unless specifically identified
   in those offerings.
-* The recommended components may change over time as technologies and approaches change.
+- The recommended components may change over time as technologies and approaches change.
 
 ### The team
 
 The `team` consists of engineers from across groups within IBM and Red Hat who:
 
-* are actively engaged in the JavaScript/Node.js community
-* have large Javascript/Node.js deployments
-* provide consulting advice and/or development related to JavaScript/Node.js for customers
-* develop/deliver JavaScript or Node.js components
+- are actively engaged in the JavaScript/Node.js community
+- have large Javascript/Node.js deployments
+- provide consulting advice and/or development related to JavaScript/Node.js for customers
+- develop/deliver JavaScript or Node.js components
 
 ### Key tenets
 
-* Whenever possible components should have been validated at scale within the `team's`
+- Whenever possible components should have been validated at scale within the `team's`
   JavaScript/Node.js deployments or in engagements with our customers.
-* We need to consider licensing and other due diligence when selecting components.
-* We are going to start with a focus on the back-end, a similar effort for front-end
+- We need to consider licensing and other due diligence when selecting components.
+- We are going to start with a focus on the back-end, a similar effort for front-end
   components will make sense as a follow on.
 
 ## Components

docs/development/code-consistency.md

@@ -1,14 +1,14 @@
 # Code Consistency
 
-It is important to the efficiency of teams working 
+It is important to the efficiency of teams working
 on JavaScript (and other languages) to have consistency
 in formatting within the projects managed by their team.
 
 Not having a consistent coding style documented or enforcing
 consistency manually as part of code reviews or
 other manual techniques is error prone, potentially
-harmful to relationships between team members, 
-is a barrier to attracting external contributions and can 
+harmful to relationships between team members,
+is a barrier to attracting external contributions and can
 result in bugs because the is harder to understand and spot
 repeating patterns.
 
@@ -24,69 +24,71 @@ needs of the team.
 
 ## Recommended Components
 
-* ESLint - https://eslint.org/
+- ESLint - https://eslint.org/
 
 ESLint is broadly used with the `teams` organizations and has broad usage
 across the JavaScript ecosystem with > 11 million weekly downlaods.
 It can be configured to reflect the coding style followed by most
-if not all teams. 
+if not all teams.
 
 # Guidance
 
-* Use one of the pre-existing ESLint shareable configurations. There are a number
+- Use one of the pre-existing ESLint shareable configurations. There are a number
   of pre-existing configurations and re-using one of these has a number
   of benefits:
-  
-  * minimizing what can be potentially divisive discussions to agree
+
+  - minimizing what can be potentially divisive discussions to agree
     on the style to be followed.
-  * leveraging the experience of what has worked for other teams.
-  * increasing the likelyhood of familiarity for new team members.
+  - leveraging the experience of what has worked for other teams.
+  - increasing the likelyhood of familiarity for new team members.
 
   Examples include:
-  * eslint-config-airbnb-standard - https://www.npmjs.com/package/eslint-config-airbnb-standard
-  * eslint-config-semistandard - https://www.npmjs.com/package/eslint-config-semistandard
-  * eslint-config-standard - https://www.npmjs.com/package/eslint-config-standard
-  * eslint-config-prettier - https://github.com/prettier/prettier-eslint
+
+  - eslint-config-airbnb-standard - https://www.npmjs.com/package/eslint-config-airbnb-standard
+  - eslint-config-semistandard - https://www.npmjs.com/package/eslint-config-semistandard
+  - eslint-config-standard - https://www.npmjs.com/package/eslint-config-standard
+  - eslint-config-prettier - https://github.com/prettier/prettier-eslint
 
   with a complete list available through this query: https://www.npmjs.com/search?q=eslint-config-&ranking=popularity
 
-* Integrate eslint into your package.json so that it runs before scripts. For example:
+- Integrate eslint into your package.json so that it runs before scripts. For example:
 
   ```json
     "scripts": {
         "pretest": "eslint --ignore-path .gitignore ."
     }
   ```
 
-* set your project to extend your chosen eslint-config-X by populating an eslintrc.json file:
+- set your project to extend your chosen eslint-config-X by populating an eslintrc.json file:
 
   ```
     echo '{"extends": "X"}' > .eslintrc.json
   ```
 
-  substituting X with your chosen config.  You can also get started by running `npx eslint --init` which 
+  substituting X with your chosen config. You can also get started by running `npx eslint --init` which
   will ask you a number of interactive questions and then create your `.eslintrc.json` file and add
   the required depenencies into your package.json.
 
-* Ensure you have a gitignore file so derived files do not get linted.  A minimal one can be
+- Ensure you have a gitignore file so derived files do not get linted. A minimal one can be
   created with:
 
   ```shell
   echo node_modules/ >> .gitignore
   ```
 
   Some additional useful suggestions are available in this
- [article](https://medium.com/the-node-js-collection/why-and-how-to-use-eslint-in-your-project-742d0bc61ed7).
+  [article](https://medium.com/the-node-js-collection/why-and-how-to-use-eslint-in-your-project-742d0bc61ed7).
 
-* When adopting a pre-existing shareable config it is important to understand that these
+- When adopting a pre-existing shareable config it is important to understand that these
   configs can change over time. Include time in your regular workflow to review these changes
   and update your code base appropriately.
 
-* Configure hooks to run eslint before committing code, but ensure that this pre-commit check does not take too long to execute which may cause complaints from developers.
-  * Use [husky](https://github.com/typicode/husky) to configure scripts to run before git commits and git pushes.
-    * These checks can be skipped by a developer when needed via `git commit --no-verify`
-  * Use [lint-staged](https://github.com/okonet/lint-staged) to reduce amount of code to be linted. This speeds up linting step before commit/push.
-These can be integrated into package.json as follows:
+- Configure hooks to run eslint before committing code, but ensure that this pre-commit check does not take too long to execute which may cause complaints from developers.
+
+  - Use [husky](https://github.com/typicode/husky) to configure scripts to run before git commits and git pushes.
+    - These checks can be skipped by a developer when needed via `git commit --no-verify`
+  - Use [lint-staged](https://github.com/okonet/lint-staged) to reduce amount of code to be linted. This speeds up linting step before commit/push.
+    These can be integrated into package.json as follows:
 
   ```json
   "lint-staged": {
@@ -99,5 +101,4 @@ These can be integrated into package.json as follows:
   }
   ```
 
-* Always ensure CI/CD is running linting regardless of hooks.
-
+- Always ensure CI/CD is running linting regardless of hooks.

docs/functional-components/auth.md

@@ -2,53 +2,53 @@
 
 ## Recommended Components
 
-* Passport - http://www.passportjs.org/
+- Passport - http://www.passportjs.org/
   Passport is authentication middleware for Node.js. Extremely flexible and modular, Passport can be unobtrusively dropped in to any Express-based web application. Is based on strategies which allows for a large number of integrations.
 
-* HelmetJS - https://helmetjs.github.io/
+- HelmetJS - https://helmetjs.github.io/
   Helmet helps you secure your Express apps by setting various HTTP headers. It’s not a silver bullet, but it can help!
 
-* IBM Cloud AppID https://cloud.ibm.com/docs/services/appid
+- IBM Cloud AppID https://cloud.ibm.com/docs/services/appid
   App ID helps developers to easily add authentication to their web and mobile apps with few lines of code, and secure their Cloud-native applications and services on IBM Cloud.
 
-* Istio - https://istio.io/
+- Istio - https://istio.io/
   Istio provides a service mesh, includes security features https://istio.io/docs/tasks/security/
   IBM provides an Istio Adapter for App Identity and Access https://istio.io/docs/reference/config/policy-and-telemetry/adapters/app-identity-access-adapter/
 
 ## Guidance
 
-* Use Helmet to configure http headers to address security attacks.
+- Use Helmet to configure http headers to address security attacks.
 
-* Use Passport to handle your web strategy
+- Use Passport to handle your web strategy
 
-* Use a web strategy based on AppID whenever possible.
+- Use a web strategy based on AppID whenever possible.
 
-* There is a difference between a WebApp/BFF(Backend for Frontend) and a pure Backend API that never deals with a Frontend like a Web Browser. Knowing this difference will help you understand the requirements in terms of security.
+- There is a difference between a WebApp/BFF(Backend for Frontend) and a pure Backend API that never deals with a Frontend like a Web Browser. Knowning this difference will help you understand the requirements in terms of security.
 
-* A Frontend WebApp should never handle end user credentials such as username/password, it should always delegate to an Authorization Server for example AppID service. https://github.com/ibm-cloud-security/appid-video-tutorials/blob/master/02a-simple-node-web-app/app.js
+- A Frontend WebApp should never handle end user credentials such as username/password, it should always delegate to an Authorization Server for example AppID service. https://github.com/ibm-cloud-security/appid-video-tutorials/blob/master/02a-simple-node-web-app/app.js
 
-* A pure Backend API that never deals with a fronted should never be concern of redirecting or dealing with end users, they would require an access/API token or assume the proxy/gateway in front is already handling this and not require token at all. https://github.com/ibm-cloud-security/appid-video-tutorials/blob/master/02b-simple-node-backend-app/app.js
+- A pure Backend API that never deals with a fronted should never be concern of redirecting or dealing with end users, they would require an access/AOI token or assume the proxy/gateway in front is already handling this and not require token at all. https://github.com/ibm-cloud-security/appid-video-tutorials/blob/master/02b-simple-node-backend-app/app.js
 
-* The browser/client should never have access to access token.
+- The browser/client should never have access to access token.
 
-* The Authorization Server will interact with the user and once is authenticated it will return to the browser with a grant code, which in turn can be used by the Web App request an access token. With this access token the WebApp can access a Backend API for a resource.
+- The Authorization Server will interact with the user and once is authenticated it will return to the browser with a grant code, which in turn can be used by the Web App request an access token. With this access token the WebApp can access a Backend API for a resource.
 
-* Use the refresh token whenever possible, this avoids re-authentication.
+- Use the refresh token whenever possible, this avoids re-authentication.
 
-* Do not use OAUTH2 implicit grant, instead the Authorization code workflow is preferred.
+- Do not use OAUTH2 implicit grant, is preferred to use Authorization code workflow.
 
-* Use OIDC ID token for authentication, they are represented as JSON Web Token (JWT) and it contains the requested claims.
+- Use OIDC ID token for authentication, they are represented as JSON Web Token (JWT) and it contains the requested claims.
 
-* When using Istio:
-  * Istio Adapter for AppID can handle the authentication and authorization of the client, this leaves the nodejs service without the responsibilities of handling authentication or authorization. https://github.com/ibm-cloud-security/app-identity-and-access-adapter
+- When using Istio:
 
-  * Using Istio you can handle authorization based on roles for the Node.js service, for example all authenticated users can read data via http method GET, but only users with `role=admin` are allowed to write data via http method POST.
+  - Istio Adapter for AppID can handle the authentication and authorization of the client, this leaves the nodejs service without the responsibilities of handling authentication or authorization. https://github.com/ibm-cloud-security/app-identity-and-access-adapter
 
-## Learning Resources
+  - Using Istio you can handle authorization based on roles for the nodejs service, for example all authenticated users can read data via http method GET, but only users with `role=admin` are allowed to write data via http method POST.
 
-* [Technologies Under the Hood (OAuth2, OIDC, JWT, Bearer Token)](https://www.youtube.com/watch?v=ndlk-ZhKGXM&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=2)
+## Learning Resources
 
-* [Protecting Node.js Web Applications with IBM Cloud App ID](https://www.youtube.com/watch?v=6roa1ZOvwtw&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=3)
+- [Technologies Under the Hood (OAuth2, OIDC, JWT, Bearer Token)](https://www.youtube.com/watch?v=ndlk-ZhKGXM&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=2)
 
-* [Protecting Node.js Backend Application with IBM Cloud App ID](https://www.youtube.com/watch?v=jJLSgkHpZwA&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=4)
+- [Protecting Node.js Web Applications with IBM Cloud App ID](https://www.youtube.com/watch?v=6roa1ZOvwtw&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=3)
 
+- [Protecting Node.js Backend Application with IBM Cloud App ID](https://www.youtube.com/watch?v=jJLSgkHpZwA&list=PLbAYXkuqwrX2WLQqR0LUtjT77d4hisvfK&index=4)