diff --git a/.github/workflows/vale-check.yml b/.github/workflows/vale-check.yml new file mode 100644 index 0000000..f9725cf --- /dev/null +++ b/.github/workflows/vale-check.yml @@ -0,0 +1,33 @@ +name: Vale Linter Check + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + vale-quality-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Vale + run: | + wget https://github.com/errata-ai/vale/releases/download/v3.9.0/vale_3.9.0_Linux_64-bit.tar.gz + tar -xvzf vale_3.9.0_Linux_64-bit.tar.gz + sudo mv vale /usr/local/bin/ + + - name: Run Vale Smoke Test + run: | + cd docs-linter + vale sync + vale smoke-test.md --no-exit + + - name: Install Markdownlint + run: sudo npm install -g markdownlint-cli + + - name: Run Markdownlint (Format Check) + run: | + cd docs-linter + markdownlint --config .markdownlint.json smoke-test.md || true diff --git a/docs-linter/.markdownlint.json b/docs-linter/.markdownlint.json new file mode 100644 index 0000000..9711d76 --- /dev/null +++ b/docs-linter/.markdownlint.json @@ -0,0 +1,8 @@ +{ + "default": true, + "MD013": false, + "MD024": false, + "MD033": false, + "MD034": false, + "MD041": false +} diff --git a/docs-linter/.vale.ini b/docs-linter/.vale.ini new file mode 100644 index 0000000..e0da6c4 --- /dev/null +++ b/docs-linter/.vale.ini @@ -0,0 +1,9 @@ +StylesPath = styles +MinAlertLevel = suggestion +Vocab = terms +Packages = Microsoft + +[*.{md,mdx}] +BasedOnStyles = Vale, Microsoft, custom-rules +TokenIgnores = (https?://[^\s\)]+), (`.+?`), (\*\*.+?\*\*) +BlockIgnores = (?s)(^---\n.*?\n---) diff --git a/docs-linter/smoke-test.md b/docs-linter/smoke-test.md new file mode 100644 index 0000000..523f713 --- /dev/null +++ b/docs-linter/smoke-test.md @@ -0,0 +1,16 @@ +# Smoke Test File + +This is a paragraph with trailing spaces at the end. +(That line has spaces, triggering MD009). + +# A Second H1 Header (Violation: MD025) + +#### Skipped Header Level (Violation: MD001 - H1 to H4) + +Here is a list of Vale violations: + +1. **Branding:** We use netfoundry and github in our daily work. +2. **Passive Voice:** The file was opened by the admin. +3. **Wordiness:** In order to login, you must utilize the key. +4. **First Person:** I decided to push the code myself. +5. **Spelling:** This is a testtoken for moret esting. \ No newline at end of file diff --git a/docs-linter/styles/Microsoft/Auto.yml b/docs-linter/styles/Microsoft/Auto.yml new file mode 100644 index 0000000..4da4393 --- /dev/null +++ b/docs-linter/styles/Microsoft/Auto.yml @@ -0,0 +1,11 @@ +extends: existence +message: "In general, don't hyphenate '%s'." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/auto +ignorecase: true +level: error +action: + name: convert + params: + - simple +tokens: + - 'auto-\w+' diff --git a/docs-linter/styles/Microsoft/ComplexWords.yml b/docs-linter/styles/Microsoft/ComplexWords.yml new file mode 100644 index 0000000..5be92d5 --- /dev/null +++ b/docs-linter/styles/Microsoft/ComplexWords.yml @@ -0,0 +1,14 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'" +level: warning +ignorecase: true +# This rule swaps complex words for simpler ones (e.g. utilize -> use) +swap: + utilize: use + utilization: use + facilitate: help + leverage: use + commence: start + terminate: end + subsequently: later + \ No newline at end of file diff --git a/docs-linter/styles/Microsoft/Contractions.yml b/docs-linter/styles/Microsoft/Contractions.yml new file mode 100644 index 0000000..8c81dcb --- /dev/null +++ b/docs-linter/styles/Microsoft/Contractions.yml @@ -0,0 +1,50 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions +level: error +ignorecase: true +action: + name: replace +swap: + are not: aren't + cannot: can't + could not: couldn't + did not: didn't + do not: don't + does not: doesn't + has not: hasn't + have not: haven't + how is: how's + is not: isn't + + 'it is(?!\.)': it's + 'it''s(?=\.)': it is + + should not: shouldn't + + "that is(?![.,])": that's + 'that''s(?=\.)': that is + + 'they are(?!\.)': they're + 'they''re(?=\.)': they are + + was not: wasn't + + 'we are(?!\.)': we're + 'we''re(?=\.)': we are + + 'we have(?!\.)': we've + 'we''ve(?=\.)': we have + + were not: weren't + + 'what is(?!\.)': what's + 'what''s(?=\.)': what is + + 'when is(?!\.)': when's + 'when''s(?=\.)': when is + + 'where is(?!\.)': where's + 'where''s(?=\.)': where is + + will not: won't diff --git a/docs-linter/styles/Microsoft/Dashes.yml b/docs-linter/styles/Microsoft/Dashes.yml new file mode 100644 index 0000000..72b05ba --- /dev/null +++ b/docs-linter/styles/Microsoft/Dashes.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Remove the spaces around '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes +ignorecase: true +nonword: true +level: error +action: + name: edit + params: + - trim + - " " +tokens: + - '\s[—–]\s|\s[—–]|[—–]\s' diff --git a/docs-linter/styles/Microsoft/DateFormat.yml b/docs-linter/styles/Microsoft/DateFormat.yml new file mode 100644 index 0000000..1965313 --- /dev/null +++ b/docs-linter/styles/Microsoft/DateFormat.yml @@ -0,0 +1,8 @@ +extends: existence +message: Use 'July 31, 2016' format, not '%s'. +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}' diff --git a/docs-linter/styles/Microsoft/DateNumbers.yml b/docs-linter/styles/Microsoft/DateNumbers.yml new file mode 100644 index 0000000..14d4674 --- /dev/null +++ b/docs-linter/styles/Microsoft/DateNumbers.yml @@ -0,0 +1,40 @@ +extends: existence +message: "Don't use ordinal numbers for dates." +link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates +level: error +nonword: true +ignorecase: true +raw: + - \b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?)\b\s* +tokens: + - first + - second + - third + - fourth + - fifth + - sixth + - seventh + - eighth + - ninth + - tenth + - eleventh + - twelfth + - thirteenth + - fourteenth + - fifteenth + - sixteenth + - seventeenth + - eighteenth + - nineteenth + - twentieth + - twenty-first + - twenty-second + - twenty-third + - twenty-fourth + - twenty-fifth + - twenty-sixth + - twenty-seventh + - twenty-eighth + - twenty-ninth + - thirtieth + - thirty-first diff --git a/docs-linter/styles/Microsoft/DateOrder.yml b/docs-linter/styles/Microsoft/DateOrder.yml new file mode 100644 index 0000000..12d69ba --- /dev/null +++ b/docs-linter/styles/Microsoft/DateOrder.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Always spell out the name of the month." +link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates +ignorecase: true +level: error +nonword: true +tokens: + - '\b\d{1,2}/\d{1,2}/(?:\d{4}|\d{2})\b' diff --git a/docs-linter/styles/Microsoft/Ellipses.yml b/docs-linter/styles/Microsoft/Ellipses.yml new file mode 100644 index 0000000..320457a --- /dev/null +++ b/docs-linter/styles/Microsoft/Ellipses.yml @@ -0,0 +1,9 @@ +extends: existence +message: "In general, don't use an ellipsis." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/ellipses +nonword: true +level: warning +action: + name: remove +tokens: + - '\.\.\.' diff --git a/docs-linter/styles/Microsoft/FirstPerson.yml b/docs-linter/styles/Microsoft/FirstPerson.yml new file mode 100644 index 0000000..f58dea3 --- /dev/null +++ b/docs-linter/styles/Microsoft/FirstPerson.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Use first person (such as '%s') sparingly." +link: https://docs.microsoft.com/en-us/style-guide/grammar/person +ignorecase: true +level: warning +nonword: true +tokens: + - (?:^|\s)I(?=\s) + - (?:^|\s)I(?=,\s) + - \bI'd\b + - \bI'll\b + - \bI'm\b + - \bI've\b + - \bme\b + - \bmy\b + - \bmine\b diff --git a/docs-linter/styles/Microsoft/Gender.yml b/docs-linter/styles/Microsoft/Gender.yml new file mode 100644 index 0000000..47c0802 --- /dev/null +++ b/docs-linter/styles/Microsoft/Gender.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't use '%s'." +link: https://github.com/MicrosoftDocs/microsoft-style-guide/blob/master/styleguide/grammar/nouns-pronouns.md#pronouns-and-gender +level: error +ignorecase: true +tokens: + - he/she + - s/he diff --git a/docs-linter/styles/Microsoft/HeadingColons.yml b/docs-linter/styles/Microsoft/HeadingColons.yml new file mode 100644 index 0000000..7013c39 --- /dev/null +++ b/docs-linter/styles/Microsoft/HeadingColons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Capitalize '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/colons +nonword: true +level: error +scope: heading +tokens: + - ':\s[a-z]' diff --git a/docs-linter/styles/Microsoft/HeadingPunctuation.yml b/docs-linter/styles/Microsoft/HeadingPunctuation.yml new file mode 100644 index 0000000..4954cb1 --- /dev/null +++ b/docs-linter/styles/Microsoft/HeadingPunctuation.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't use end punctuation in headings." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +nonword: true +level: warning +scope: heading +action: + name: edit + params: + - trim_right + - ".?!" +tokens: + - "[a-z][.?!]$" diff --git a/docs-linter/styles/Microsoft/Headings.yml b/docs-linter/styles/Microsoft/Headings.yml new file mode 100644 index 0000000..63624ed --- /dev/null +++ b/docs-linter/styles/Microsoft/Headings.yml @@ -0,0 +1,28 @@ +extends: capitalization +message: "'%s' should use sentence-style capitalization." +link: https://docs.microsoft.com/en-us/style-guide/capitalization +level: suggestion +scope: heading +match: $sentence +indicators: + - ':' +exceptions: + - Azure + - CLI + - Code + - Cosmos + - Docker + - Emmet + - I + - Kubernetes + - Linux + - macOS + - Marketplace + - MongoDB + - REPL + - Studio + - TypeScript + - URLs + - Visual + - VS + - Windows diff --git a/docs-linter/styles/Microsoft/Hyphens.yml b/docs-linter/styles/Microsoft/Hyphens.yml new file mode 100644 index 0000000..7e5731c --- /dev/null +++ b/docs-linter/styles/Microsoft/Hyphens.yml @@ -0,0 +1,14 @@ +extends: existence +message: "'%s' doesn't need a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens +level: warning +ignorecase: false +nonword: true +action: + name: edit + params: + - regex + - "-" + - " " +tokens: + - '\b[^\s-]+ly-\w+\b' diff --git a/docs-linter/styles/Microsoft/Negative.yml b/docs-linter/styles/Microsoft/Negative.yml new file mode 100644 index 0000000..d73221f --- /dev/null +++ b/docs-linter/styles/Microsoft/Negative.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Form a negative number with an en dash, not a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +action: + name: edit + params: + - regex + - "-" + - "–" +tokens: + - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/docs-linter/styles/Microsoft/Ordinal.yml b/docs-linter/styles/Microsoft/Ordinal.yml new file mode 100644 index 0000000..e3483e3 --- /dev/null +++ b/docs-linter/styles/Microsoft/Ordinal.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't add -ly to an ordinal number." +link: https://docs.microsoft.com/en-us/style-guide/numbers +level: error +action: + name: edit + params: + - trim + - ly +tokens: + - firstly + - secondly + - thirdly diff --git a/docs-linter/styles/Microsoft/OxfordComma.yml b/docs-linter/styles/Microsoft/OxfordComma.yml new file mode 100644 index 0000000..493b55c --- /dev/null +++ b/docs-linter/styles/Microsoft/OxfordComma.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas +scope: sentence +level: suggestion +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/docs-linter/styles/Microsoft/Percentages.yml b/docs-linter/styles/Microsoft/Percentages.yml new file mode 100644 index 0000000..b68a736 --- /dev/null +++ b/docs-linter/styles/Microsoft/Percentages.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use a numeral plus the units." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +tokens: + - '\b[a-zA-z]+\spercent\b' diff --git a/docs-linter/styles/Microsoft/Plurals.yml b/docs-linter/styles/Microsoft/Plurals.yml new file mode 100644 index 0000000..1bb6660 --- /dev/null +++ b/docs-linter/styles/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/docs-linter/styles/Microsoft/Spacing.yml b/docs-linter/styles/Microsoft/Spacing.yml new file mode 100644 index 0000000..bbd10e5 --- /dev/null +++ b/docs-linter/styles/Microsoft/Spacing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should have one space." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +level: error +nonword: true +tokens: + - '[a-z][.?!] {2,}[A-Z]' + - '[a-z][.?!][A-Z]' diff --git a/docs-linter/styles/Microsoft/Wordiness.yml b/docs-linter/styles/Microsoft/Wordiness.yml new file mode 100644 index 0000000..8a4fea7 --- /dev/null +++ b/docs-linter/styles/Microsoft/Wordiness.yml @@ -0,0 +1,127 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences +ignorecase: true +level: suggestion +action: + name: replace +swap: + "sufficient number(?: of)?": enough + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell + (?:previous|prior) to: before + (?:utilize|make use of): use + a (?:large)? majority of: most + a (?:large)? number of: many + a myriad of: myriad + adversely impact: hurt + all across: across + all of a sudden: suddenly + all of these: these + all of(?! a sudden| these): all + all-time record: record + almost all: most + almost never: seldom + along the lines of: similar to + an adequate number of: enough + an appreciable number of: many + an estimated: about + any and all: all + are in agreement: agree + as a matter of fact: in fact + as a means of: to + as a result of: because of + as of yet: yet + as per: per + at a later date: later + at all times: always + at the present time: now + at this point in time: at this point + based in large part on: based on + based on the fact that: because + basic necessity: necessity + because of the fact that: because + came to a realization: realized + came to an abrupt end: ended abruptly + carry out an evaluation of: evaluate + close down: close + closed down: closed + complete stranger: stranger + completely separate: separate + concerning the matter of: regarding + conduct a review of: review + conduct an investigation: investigate + conduct experiments: experiment + continue on: continue + despite the fact that: although + disappear from sight: disappear + doomed to fail: doomed + drag and drop: drag + drag-and-drop: drag + due to the fact that: because + during the period of: during + during the time that: while + emergency situation: emergency + establish connectivity: connect + except when: unless + excessive number: too many + extend an invitation: invite + fall down: fall + fell down: fell + for the duration of: during + gather together: gather + has the ability to: can + has the capacity to: can + has the opportunity to: could + hold a meeting: meet + if this is not the case: if not + in a careful manner: carefully + in a thoughtful manner: thoughtfully + in a timely manner: timely + in addition: also + in an effort to: to + in between: between + in lieu of: instead of + in many cases: often + in most cases: usually + in order to: to + in some cases: sometimes + in spite of the fact that: although + in spite of: despite + in the (?:very)? near future: soon + in the event that: if + in the neighborhood of: roughly + in the vicinity of: close to + it would appear that: apparently + lift up: lift + made reference to: referred to + make reference to: refer to + mix together: mix + none at all: none + not in a position to: unable + not possible: impossible + of major importance: important + perform an assessment of: assess + pertaining to: about + place an order: order + plays a key role in: is essential to + present time: now + readily apparent: apparent + some of the: some + span across: span + subsequent to: after + successfully complete: complete + take action: act + take into account: consider + the question as to whether: whether + there is no doubt but that: doubtless + this day and age: this age + this is a subject that: this subject + time (?:frame|period): time + under the provisions of: under + until such time as: until + used for fuel purposes: used for fuel + whether or not: whether + with regard to: regarding + with the exception of: except for diff --git a/docs-linter/styles/config/vocabularies/terms/accept.txt b/docs-linter/styles/config/vocabularies/terms/accept.txt new file mode 100644 index 0000000..254ebec --- /dev/null +++ b/docs-linter/styles/config/vocabularies/terms/accept.txt @@ -0,0 +1,53 @@ +performant +hostname +repo +linter +egress +egressed +ingress +ingressed +sidebar_position +sidebar_label +config +microsegmentation +plaintext +ciphertext +untrusted +failover +failovers +antivirus +datacenter +datacenters +reachability +signin +NetFoundry +OpenZiti +Ziti +zrok +zLAN +Frontdoor +Docusaurus +GitHub +Bitbucket +Kubernetes +Okta +JavaScript +TypeScript +Semver +Keycloak +API +AMI +AMIs +CLI +JWT +JWTs +CA +CAs +VM +VMs +TLDs +FQDN +FQDNs +MFA +IdP +IdPs diff --git a/docs-linter/styles/config/vocabularies/terms/reject.txt b/docs-linter/styles/config/vocabularies/terms/reject.txt new file mode 100644 index 0000000..e69de29 diff --git a/docs-linter/styles/custom-rules/Branding.yml b/docs-linter/styles/custom-rules/Branding.yml new file mode 100644 index 0000000..0ef3d44 --- /dev/null +++ b/docs-linter/styles/custom-rules/Branding.yml @@ -0,0 +1,10 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://netfoundry.io +level: error +ignorecase: true +swap: + # KEEP: Substitutions that change structure (spaces, punctuation). For just capitalization, add to accept.txt + vscode: VS Code + open ziti: OpenZiti + front door: Frontdoor