Added linting rules (#458)

* Added linting rules

* fixed gitignore

* Typos, spelling, etc.

* remove workflow

.github/workflows/codeql.yml

@@ -1,4 +1,4 @@
-# For most projects, this workflow file will not need changing; you simply need
+# For most projects, this workflow file won't need changing; you simply need
 # to commit it to your repository.
 #
 # You may wish to alter this file to override the set of languages analyzed,

.gitignore

@@ -52,3 +52,16 @@ docs/dev-portal/zudoku/
 # Sentry Config File
 .env.sentry-build-plugin
 
+
+
+# We want to ignore our StylesPath *except* for our local
+# `vocabularies/Base` directory.
+
+.styles/*
+!.styles/config/
+!.styles/Zuplo/
+
+!.styles/config/
+
+.styles/config/vocabularies/*
+!.styles/config/vocabularies/Base

.hyperlint/config.yaml

@@ -0,0 +1 @@
+content_dir: /docs

.styles/Zuplo/Acronyms.yml

@@ -0,0 +1,15 @@
+extends: conditional
+message: "'%s' has no definition."
+link: https://docs.microsoft.com/en-us/style-guide/acronyms
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - CDN
+  - TLS
+  - WAF
+  - API
+  - VPC

.styles/Zuplo/Terms.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: "Prefer '%s' over '%s'."
+# term preference should be based on microsoft style guide, such as
+link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  zup: Zuplo Project
+  zups: Zuplo projects

.styles/config/filters/errors.expr

@@ -0,0 +1 @@
+.Level in ["error"]

.styles/config/vocabularies/Base/accept.txt

@@ -0,0 +1,60 @@
+[Zz]uplo
+[Zz]udoku
+backend
+failover
+onboarding
+asdf
+VMWare
+Datadog
+Dynatrace
+URLPattern
+APIs
+WAFs
+liveness
+@zuplo.com
+AWS
+(?i)JSON
+MDN
+Lamdba
+routes.oas.json
+Dev
+Vite
+we have
+Inkeep
+VPCs
+GCP
+URL
+chai
+SLA
+SLAs
+OAuth
+Supabase
+Okta
+Cognito
+Fastly
+[Hh]ostname
+Crypto
+Equinix
+VMs
+serverless
+Astra
+[Bb]ackend
+[Mm]ockbin
+Grafana
+Xata
+monorepo
+subfolder
+[Tt]odos
+[Ss]ubrequests
+DataDog
+Checkly
+Keycloak
+[Mm]isconfigured
+[Mm]iddleware
+enqueued
+severities
+[Pp]olyfill
+Blockdaemon
+Docusaurus
+frontmatter
+Fastify

.vale.ini

@@ -0,0 +1,11 @@
+StylesPath = .styles
+
+MinAlertLevel = suggestion
+
+Vocab = Base
+Packages = Microsoft, MDX
+
+[*.{md,mdx}]
+BasedOnStyles = Vale, Microsoft, Zuplo
+Microsoft.Accessibility = NO
+Microsoft.Units = NO

Makefile

@@ -0,0 +1,2 @@
+lint:
+	vale --filter=errors.expr docs/

STYLEGUIDE.md

@@ -0,0 +1,11 @@
+# Style guide
+
+- Use American English.
+- The documentation uses
+  [Microsoft's Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)
+  as a reference for writing style.
+- Try to avoid using passive voice or first-person pronouns.
+- Use the present tense.
+- Writing should be clear, concise, and easy to understand.
+- Use Vale to check for style and grammar issues. The vale configuration file is
+  located at `.vale.ini`.

cspell.json

@@ -10,7 +10,9 @@
     "proxying",
     "Quickstart",
     "quickstarts",
-    "Zuplo"
+    "Zuplo",
+    "vercel",
+    "zudoku"
   ],
   // flagWords - list of words to be always considered incorrect
   // This is useful for offensive words and common spelling errors.

docs/articles/accounts/billing.md

@@ -19,7 +19,7 @@ checkout page where you can update your payment method.
 
 :::note{title="Enterprise Plans"}
 
-Enterprise plans are setup with custom billing and cannot be managed through the
+Enterprise plans are setup with custom billing and can't be managed through the
 portal. Contact your account representative for questions or assistance.
 
 :::

docs/articles/accounts/managing-account-members.md

@@ -9,7 +9,7 @@ manage users in your account.
 ## Add Account Member
 
 To start, navigate to the account settings page by clicking your user icon in
-the top right corner of the screen and selecting "Settings" from the dropdown
+the top right corner of the screen and selecting **Settings** from the dropdown
 menu.
 
 The view will display the users that are currently members of the account and
@@ -19,8 +19,8 @@ their roles.
 
 On the top of the page, you can enter an email address of the user you want to
 invite. For accounts with the enterprise role feature, users are added to the
-account with the role of "Member", for all other accounts users are added with
-the role of "Admin".
+account with the role of **Member**, for all other accounts users are added with
+the role of **Admin**.
 
 ![Invite User](/media/managing-account-members/image-1.png)
 

docs/articles/accounts/managing-project-members.md

@@ -9,9 +9,9 @@ project level roles in order to grant them access to specific project resources.
 
 ## Add Project Member
 
-To manage project members, navigate to the project settings page and click 
-the **Members** tab, which shows a list of all members in the project and
-their roles.
+To manage project members, navigate to the project settings page and click the
+**Members** tab, which shows a list of all members in the project and their
+roles.
 
 ![Project Members](/media/managing-project-members/image-1.png)
 
@@ -24,9 +24,9 @@ the project.
 
 Account admins will always have access to all projects. If you try to change the
 role of an account admin, you will see a warning message that this user is an
-account admin and cannot be changed.
+account admin and can't be changed.
 
-For users who are not account admins, you can change their role by selecting the
+For users who aren't account admins, you can change their role by selecting the
 desired role from the dropdown.
 
 ![Member Role](/media/managing-project-members/image-2.png)

docs/articles/accounts/roles-and-permissions.md

@@ -23,7 +23,7 @@ The following roles are available at the account level:
   the account. They also have wide access to resources such as tunnels, custom
   domains, API key buckets, etc. Developers can edit preview and development
   resources, but not production resources.
-- **Member**: Members of an account do not have any account level or project
+- **Member**: Members of an account don't have any account level or project
   level permissions. Members can be granted project level permissions by an
   admin.
 
@@ -36,8 +36,8 @@ The following roles are available at the project level:
 - **Admin**: Admins have full access to the project and can manage all aspects
   of the project, including environment variables, secrets, and members.
 - **Developer**: Developers have access to all preview and development resources
-  in a project. They cannot modify production resources.
-- **Member**: Members of a project can view resources in the project but cannot
+  in a project. They can't modify production resources.
+- **Member**: Members of a project can view resources in the project but can't
   modify them.
 
 ## Account Role Permissions
@@ -106,7 +106,7 @@ The following table outlines the permissions available to each project role.
 |                       | Preview     | Edit   | ✅    | ✅        | ❌     |
 |                       |             | View   | ✅    | ✅        | ✅     |
 |                       | Development | Edit   | ✅    | ❌        | ❌     |
-|                       |             | View   | ✅    | ✅       | ✅     |
+|                       |             | View   | ✅    | ✅        | ✅     |
 | Monetization Buckets  | Production  | Edit   | ✅    | ❌        | ❌     |
 |                       |             | View   | ✅    | ✅        | ✅     |
 |                       | Preview     | Edit   | ✅    | ✅        | ❌     |

docs/articles/accounts/zuplo-api-keys.md

@@ -6,8 +6,8 @@ sidebar_label: API Keys
 The [Zuplo Developer API](https://dev.zuplo.com) allows you to programmatically
 interact with Zuplo. To access the API, you need to create an API key.
 
-API keys are used to authenticate requests to the Zuplo API. They are unique to
-your account and should be kept secret. Do not share your API key in publicly
+API keys are used to authenticate requests to the Zuplo API. They're unique to
+your account and should be kept secret. Don't share your API key in publicly
 accessible areas such as GitHub repositories.
 
 ## Creating an API Key
@@ -22,7 +22,7 @@ have access to.
 :::note{title="Required Role"}
 
 Account admins can view and manage all API keys in the account. Developers can
-only view their own API keys. Members do not have access to API keys.
+only view their own API keys. Members don't have access to API keys.
 
 :::
 
@@ -91,4 +91,4 @@ When selecting permissions for API Key Buckets or Monetization Buckets, the
 environment type scope is also applied. For example, if your key has access to
 preview environments and has Read and Write access to API Key buckets, that key
 can only read and write to API Key buckets in the preview environments - it
-cannot modify buckets used in production environments.
+can't modify buckets used in production environments.

docs/articles/add-api-to-backstage.md

@@ -9,8 +9,8 @@ In this guide, we'll walk you through the steps to add a your Zuplo API to
 
 Backstage allows you to document
 [API entities](https://backstage.io/docs/features/software-catalog/descriptor-format/#kind-api)
-using an OpenAPI file. Although Zuplo is OpenAPI based, you cannot directly use
-your `routes.oas.json` file, as it is missing details about your API. Instead,
+using an OpenAPI file. Although Zuplo is OpenAPI based, you can't directly use
+your `routes.oas.json` file, as it's missing details about your API. Instead,
 you will need to use the public-ready version of your spec, by adding an
 [OpenAPI Spec Handler](../handlers/openapi.md).
 
@@ -83,8 +83,8 @@ spec:
 ```
 
 You should now be able to see your API under the APIs tab in Backstage. If you
-navigate to your API and click the **DEFINITION** tab - you can even preview your
-OpenAPI spec.
+navigate to your API and click the **DEFINITION** tab - you can even preview
+your OpenAPI spec.
 
 ![OpenAPI spec](/media/add-api-to-backstage/image-6.png)
 
@@ -93,9 +93,9 @@ repeat the steps above for all of your OpenAPI files.
 
 ## Optional: Reusing your API across Backstage catalogs
 
-If you do not wish to directly add your Zuplo API to your backstage
+If you don't wish to directly add your Zuplo API to your backstage
 `entities.yaml`, you can instead add the entity definition to your Zuplo
-repository directly, and sync it with backstage using their github integration.
+repository directly, and sync it with backstage using their GitHub integration.
 You will still need to follow steps 1 & 2 from the guide above.
 
 ### 1/ Add `catalog-info.yaml` to your Zuplo Repository
@@ -130,14 +130,14 @@ to the APIs tab, and click **REGISTER EXISTING API**.
 
 ![APIs list](/media/add-api-to-backstage/image-5.png)
 
-When prompted for the component URL, enter the github URL of your
+When prompted for the component URL, enter the GitHub URL of your
 `catalog-info.yaml` file (ex.
 https://github.com/AdrianMachado/adrian-api/blob/main/catalog-info.yaml).
 
-![Adding the github URL](/media/add-api-to-backstage/image-4.png)
+![Adding the GitHub URL](/media/add-api-to-backstage/image-4.png)
 
 Complete registration of your API. If you run into issues connecting your
-repository, see our [troubleshooting guide](#troubleshooting).
+repository, see the [troubleshooting guide](#troubleshooting).
 
 ### 3/ Link the API to a component
 
@@ -167,11 +167,11 @@ spec:
 
 ## Troubleshooting
 
-### I can't connect to Github
+### Can't connect to GitHub
 
-If your repository is not public and you haven't already configured Github
+If your repository isn't public and you haven't already configured GitHub
 authentication -
-[follow the Github auth guide](https://backstage.io/docs/getting-started/config/authentication).
+[follow the GitHub auth guide](https://backstage.io/docs/getting-started/config/authentication).
 You will likely want to add sign-in support as a part of your Backstage setup,
 to authenticate your users. In your `app-config.yaml` add:
 
@@ -197,12 +197,12 @@ Additionally, in your `index.ts` file, add the following line before calling
 backend.add(import("@backstage/plugin-auth-backend-module-github-provider"));
 ```
 
-This is not well documented by Backstage - any issues should be directed
+This isn't well documented by Backstage - any issues should be directed
 [to them](https://github.com/backstage/backstage/issues).
 
 ### Backstage hosted on Roadie.io
 
 If you are using a managed version of Backstage from services like Roadie.io -
 you will need to follow their
 [official docs](https://roadie.io/docs/details/openapi-specs/) for OpenAPI. We
-do not guarantee support for these platforms.
+don't guarantee support for these platforms.

docs/articles/advanced-path-matching.md

@@ -22,8 +22,8 @@ browser.
 
 ## Trailing Slashes
 
-In URLPattern, trailing slashes are not accepted unless explicitly specified.
-For example:
+In URLPattern, trailing slashes aren't accepted unless explicitly specified. For
+example:
 
 - `/cars/:manufacturer`
 
@@ -41,7 +41,7 @@ parts of the URL. For example:
 
 Path: `/products/:productId/sizes/:size` will match the following paths
 
-`/products/pizza/size/small` and set the params object on `request` to:
+`/products/pizza/size/small` and set the `params` object on `request` to:
 
 ```json
 {
@@ -52,7 +52,7 @@ Path: `/products/:productId/sizes/:size` will match the following paths
 
 :::tip
 
-Query-strings (or search parameters) will not affect path matching.
+Query-strings (or search parameters) won't affect path matching.
 
 :::