Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore(docs) Prescribe more detailed docs style lints (#46895)

Miranda Limonczenkodcf02db5c703
diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md
index 825c9e22150..6450a90c812 100644
--- a/apps/docs/CONTRIBUTING.md
+++ b/apps/docs/CONTRIBUTING.md
@@ -345,7 +345,7 @@ Here are some exceptions and Supabase-specific guidelines.
### General word usage
-- **Filler words**: You can often make your writing more concise by removing these words. (Some of these words can also sound patronizing.)
+- **Filler words**: You can often make your writing more concise by removing these words. (Some of these words can also sound patronizing.) Most filler, marketing, and vague-verb phrases are flagged by `supa-mdx-lint` as warnings, with suggested alternatives where a direct replacement exists. Run `pnpm lint:mdx` in `apps/docs` to check your changes.
- Actually
- Easy, easily
- Just
@@ -360,8 +360,8 @@ Here are some exceptions and Supabase-specific guidelines.
### Word list
-- `Backend` isn't hyphenated (not `back-end`).
- `Frontend` isn't hyphenated (not `front-end`).
+- `Backend` isn't hyphenated (not `back-end`).
- `Login` is a noun. `Log in` is a verb.
- `Postgres` is capitalized, except in code, and used instead of `PostgreSQL`.
- `Setup` is a noun. `Set up` is a verb.
@@ -370,6 +370,6 @@ Here are some exceptions and Supabase-specific guidelines.
## Search
-Search is handled using a Supabase instance. During CI, [a script](https://github.com/supabase/supabase/blob/master/apps/docs/scripts/search/generate-embeddings.ts) aggregates all content sources (eg. guides, reference docs, etc), indexes them using OpenAI embeddings, and stores them in a Supabase database.
+Search is handled using a Supabase instance. During CI, [a script](https://github.com/supabase/supabase/blob/master/apps/docs/scripts/search/generate-embeddings.ts) aggregates all content sources (for example, guides, reference docs, etc), indexes them using OpenAI embeddings, and stores them in a Supabase database.
Search uses a hybrid of native Postgres FTS and embedding similarity search based on [`pgvector`](https://github.com/pgvector/pgvector). At runtime, a PostgREST call triggers the RPC that runs the weighted FTS search, and an [Edge Function](https://github.com/supabase/supabase/tree/master/supabase/functions) is executed to perform the embedding search.
diff --git a/supa-mdx-lint.config.toml b/supa-mdx-lint.config.toml
index 2dbe93502ce..2c5def8a005 100644
--- a/supa-mdx-lint.config.toml
+++ b/supa-mdx-lint.config.toml
@@ -13,10 +13,16 @@ admonition_types = ["note", "tip", "caution", "deprecation", "danger"]
[Rule004ExcludeWords]
rules.filler = "include('supa-mdx-lint/Rule004ExcludeWords/filler.toml')"
+rules.marketing = "include('supa-mdx-lint/Rule004ExcludeWords/marketing.toml')"
+rules.vague_verbs = "include('supa-mdx-lint/Rule004ExcludeWords/vague_verbs.toml')"
+rules.generic_phrases_apology = "include('supa-mdx-lint/Rule004ExcludeWords/generic_phrases_apology.toml')"
rules.first_person = "include('supa-mdx-lint/Rule004ExcludeWords/first_person.toml')"
rules.gender_neutral = "include('supa-mdx-lint/Rule004ExcludeWords/gender_neutral.toml')"
rules.inclusive_wording = "include('supa-mdx-lint/Rule004ExcludeWords/inclusive_wording.toml')"
+rules.human_language = "include('supa-mdx-lint/Rule004ExcludeWords/human_language.toml')"
+rules.latin_phrases = "include('supa-mdx-lint/Rule004ExcludeWords/latin_phrases.toml')"
rules.preferred_usage = "include('supa-mdx-lint/Rule004ExcludeWords/preferred_usage.toml')"
+rules.formal_corporate = "include('supa-mdx-lint/Rule004ExcludeWords/formal_corporate.toml')"
rules.slang = "include('supa-mdx-lint/Rule004ExcludeWords/slang.toml')"
[Rule006NoAbsoluteUrls]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/filler.toml b/supa-mdx-lint/Rule004ExcludeWords/filler.toml
index 2b15dda8ce3..b4c186d48dd 100644
--- a/supa-mdx-lint/Rule004ExcludeWords/filler.toml
+++ b/supa-mdx-lint/Rule004ExcludeWords/filler.toml
@@ -1,3 +1,16 @@
-description = "Don't use '%s'. The sentence is more concise and/or the tone is more neutral without it."
+description = "Remove '%s' for a more concise, direct sentence."
level = "WARNING"
-words = ["easily", "please", "simply", "that's it"]
+words = [
+ "actually",
+ "easily",
+ "easy",
+ "just",
+ "let's",
+ "obviously",
+ "of course",
+ "please",
+ "quickly",
+ "simple",
+ "simply",
+ "that's it",
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/formal_corporate.toml b/supa-mdx-lint/Rule004ExcludeWords/formal_corporate.toml
new file mode 100644
index 00000000000..9fde727a044
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/formal_corporate.toml
@@ -0,0 +1,45 @@
+description = "Use a direct, simpler phrase instead of '%s'."
+level = "WARNING"
+words = [
+ [
+ "in order to",
+ "to",
+ ],
+ [
+ "prior to",
+ "before",
+ ],
+ [
+ "subsequent to",
+ "after",
+ ],
+ [
+ "for the purpose of",
+ "to",
+ ],
+ [
+ "leverage",
+ "use",
+ ],
+ [
+ "whilst",
+ "while",
+ ],
+ [
+ "amongst",
+ "among",
+ ],
+ [
+ "facilitate",
+ "help",
+ ],
+ [
+ "endeavor",
+ "try",
+ ],
+ [
+ "endeavour",
+ "try",
+ ],
+ "aforementioned",
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/generic_phrases_apology.toml b/supa-mdx-lint/Rule004ExcludeWords/generic_phrases_apology.toml
new file mode 100644
index 00000000000..456f3fcb4a0
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/generic_phrases_apology.toml
@@ -0,0 +1,6 @@
+description = "Remove '%s' and state what happened directly. For example: 'Unable to connect to database' instead of 'Sorry, we couldn't connect'."
+level = "WARNING"
+words = [
+ "oops",
+ "sorry",
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/human_language.toml b/supa-mdx-lint/Rule004ExcludeWords/human_language.toml
new file mode 100644
index 00000000000..d236d100097
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/human_language.toml
@@ -0,0 +1,24 @@
+description = "Prefer '%r' to '%s'."
+level = "WARNING"
+words = [
+ [
+ "eg.",
+ "e.g.",
+ ],
+ [
+ "eg",
+ "e.g.",
+ ],
+ [
+ "i.e.",
+ "that is",
+ ],
+ [
+ "ie.",
+ "that is",
+ ],
+ [
+ "ie",
+ "that is",
+ ],
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/latin_phrases.toml b/supa-mdx-lint/Rule004ExcludeWords/latin_phrases.toml
new file mode 100644
index 00000000000..32ef3f97016
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/latin_phrases.toml
@@ -0,0 +1,5 @@
+description = "Prefer 'with', 'by', or 'through' instead of '%s', depending on context."
+level = "WARNING"
+words = [
+ "powered by"
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/marketing.toml b/supa-mdx-lint/Rule004ExcludeWords/marketing.toml
new file mode 100644
index 00000000000..15003e72807
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/marketing.toml
@@ -0,0 +1,15 @@
+description = "Remove '%s' to avoid marketing language and describe what the feature does specifically."
+level = "WARNING"
+words = [
+ "best in class",
+ "best-in-class",
+ "cutting edge",
+ "cutting-edge",
+ "effortlessly",
+ "game changer",
+ "game-changer",
+ "hassle free",
+ "hassle-free",
+ "powerful",
+ "seamlessly",
+]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/preferred_usage.toml b/supa-mdx-lint/Rule004ExcludeWords/preferred_usage.toml
index 41fc225568b..675e7357546 100644
--- a/supa-mdx-lint/Rule004ExcludeWords/preferred_usage.toml
+++ b/supa-mdx-lint/Rule004ExcludeWords/preferred_usage.toml
@@ -1,28 +1,36 @@
description = "Prefer '%r' to '%s'."
-level = "ERROR"
+level = "WARNING"
words = [
[
- "eg.",
- "e.g.",
+ "PostgreSQL",
+ "Postgres",
],
[
- "eg",
- "e.g.",
+ "concurrent clients",
+ "concurrent connections",
],
[
- "ie.",
- "i.e.",
+ "utilize",
+ "use",
],
[
- "ie",
- "i.e.",
+ "utilise",
+ "use",
],
[
- "PostgreSQL",
- "Postgres",
+ "utilizes",
+ "uses",
],
[
- "concurrent clients",
- "concurrent connections",
+ "utilises",
+ "uses",
+ ],
+ [
+ "utilizing",
+ "using",
+ ],
+ [
+ "utilising",
+ "using",
],
]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/slang.toml b/supa-mdx-lint/Rule004ExcludeWords/slang.toml
index d60da9d81d9..10bcccab2e9 100644
--- a/supa-mdx-lint/Rule004ExcludeWords/slang.toml
+++ b/supa-mdx-lint/Rule004ExcludeWords/slang.toml
@@ -1,3 +1,3 @@
description = "Don't use Internet slang abbreviations"
-level = "ERROR"
+level = "WARNING"
words = ["tl;dr", "ymmv", "rtfm", "imo", "fwiw"]
diff --git a/supa-mdx-lint/Rule004ExcludeWords/vague_verbs.toml b/supa-mdx-lint/Rule004ExcludeWords/vague_verbs.toml
new file mode 100644
index 00000000000..43f69d602a0
--- /dev/null
+++ b/supa-mdx-lint/Rule004ExcludeWords/vague_verbs.toml
@@ -0,0 +1,7 @@
+description = "Use '%r' instead of '%s'."
+level = "WARNING"
+words = [
+ ["handle errors", "view and resolve errors"],
+ ["manage tables", "create, edit, or delete tables"],
+ ["work with data", "query and update data"],
+]