diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md index c8682b1a7d..c61811dad0 100644 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md +++ b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md @@ -32,6 +32,11 @@ After you add an existing organization to your enterprise, the organization's re - The organization's members will become members of the enterprise, and {% data variables.product.company_short %} will bill the enterprise account for the organization's usage. You must ensure that the enterprise account has enough licenses to accommodate any new members. For more information, see "[AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise)." - Enterprise owners can manage their role within the organization. For more information, see "[AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise)." - Any policies applied to the enterprise will apply to the organization. For more information, see "[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies)." + {% note %} + + **Note:** {% data reusables.actions.org-to-enterprise-actions-permissions %} + + {% endnote %} - If SAML SSO is configured for the enterprise account, the enterprise's SAML configuration will apply to the organization. If the organization used SAML SSO, the enterprise account's configuration will replace the organization's configuration. SCIM is not available for enterprise accounts, so SCIM will be disabled for the organization. For more information, see "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)" and "[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account)." - If SAML SSO was configured for the organization, members' existing {% data variables.product.pat_generic %} or SSH keys that were authorized to access the organization's resources will be authorized to access the same resources. To access additional organizations owned by the enterprise, members must authorize the {% data variables.product.pat_generic %} or key. For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)" and "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on)." - If the organization was connected to {% data variables.product.prodname_ghe_server %} or {% data variables.product.prodname_ghe_managed %} using {% data variables.product.prodname_github_connect %}, adding the organization to an enterprise will not update the connection. {% data variables.product.prodname_github_connect %} features will no longer function for the organization. To continue using {% data variables.product.prodname_github_connect %}, you must disable and re-enable the feature. For more information, see the following articles. diff --git a/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md b/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md index 0e06c384b0..b52293bfbb 100644 --- a/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md +++ b/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md @@ -66,6 +66,12 @@ Upgrading an organization does not affect your personal account or repositories {% data reusables.dotcom_billing.org-billing-perms %} +{% note %} + +**Note:** {% data reusables.actions.org-to-enterprise-actions-permissions %} + +{% endnote %} + {% data reusables.organizations.billing-settings %} {% data reusables.dotcom_billing.upgrade_org %} {% data reusables.dotcom_billing.choose_org_plan %} diff --git a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md b/content/contributing/collaborating-on-github-docs/using-the-content-linter.md index 69421cd00b..480644c655 100644 --- a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md +++ b/content/contributing/collaborating-on-github-docs/using-the-content-linter.md @@ -48,8 +48,9 @@ npm run lint-content -- --errors Use the following command to run the linter locally on specific files or directories. Separate multiple paths with a space. You can include both files and directories in the same command. -```shell -npm run lint-content -- --paths content/FILENAME.md content/DIRECTORY +```shell copy +npm run lint-content -- \ + --paths content/FILENAME.md content/DIRECTORY ``` #### Automatically fix errors that can be fixed @@ -65,7 +66,8 @@ npm run lint-content -- --fix Run this command to fix specific files or directories: ```shell -npm run lint-content -- --fix --paths content/FILENAME.md content/DIRECTORY +npm run lint-content -- \ + --fix --paths content/FILENAME.md content/DIRECTORY ``` #### Run a specific set of linter rules @@ -75,13 +77,16 @@ Use the following command to run one or more specific linter rules. These exampl Run the specified linter rules on all staged and changed files: ```shell -npm run lint-content -- --rules heading-increment code-fence-line-length +npm run lint-content -- \ + --rules heading-increment code-fence-line-length ``` Run the specified linter rules on specific files or directories: ```shell -npm run lint-content -- --rules heading-increment code-fence-line-length --path content/FILENAME.md content/DIRECTORY +npm run lint-content -- \ + --rules heading-increment code-fence-line-length \ + --path content/FILENAME.md content/DIRECTORY ``` #### Bypass the commit hook @@ -104,47 +109,26 @@ Each rule is configured in a file in [`src/content-linter/style`](https://github Errors must be addressed before merging your changes to the `main` branch. Warnings should be addressed but do not prevent a change from being merged into the `main` branch. Most rules will eventually be promoted to errors, once the content no longer has warning violations. -| **Rule ID** | **Description** | **Severity** | -|---|---|---| -| [MD004](https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md) | Unordered list style must be a dash. | Error | -| [MD011](https://github.com/DavidAnson/markdownlint/blob/main/doc/md011.md) | Make sure that link syntax is not reversed. | Error | -| [MD012](https://github.com/DavidAnson/markdownlint/blob/main/doc/md012.md) | No unnecessary blank lines. | Error | -| [MD014](https://github.com/DavidAnson/markdownlint/blob/main/doc/md014.md) | Dollar signs should not be used before commands without showing output. | Error | -| [MD018](https://github.com/DavidAnson/markdownlint/blob/main/doc/md018.md) | Must have one space after a hash style heading. | Error | -| [MD019](https://github.com/DavidAnson/markdownlint/blob/main/doc/md019.md) | Must not have spaces after a hash style heading. | Error | -| [MD022](https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md) | Headings must be surrounded by a blank line. | Error | -| [MD023](https://github.com/DavidAnson/markdownlint/blob/main/doc/md023.md) | Headings must start at the beginning of the line. | Error | -| [MD027](https://github.com/DavidAnson/markdownlint/blob/main/doc/md027.md) | Catches multiple spaces after blockquote symbol. | Error | -| [MD029](https://github.com/DavidAnson/markdownlint/blob/main/doc/md029.md) | All ordered lists should be prefixed with `1.`. | Error | -| [MD030](https://github.com/DavidAnson/markdownlint/blob/main/doc/md030.md) | Only allow one space after list markers. | Error | -| [MD037](https://github.com/DavidAnson/markdownlint/blob/main/doc/md037.md) | Remove extra spacing inside emphasis markers. | Error | -| [MD039](https://github.com/DavidAnson/markdownlint/blob/main/doc/md039.md) | Remove spacing around image text. | Error | -| [MD042](https://github.com/DavidAnson/markdownlint/blob/main/doc/md042.md) | Do not allow empty links. | Error | -| [MD050](https://github.com/DavidAnson/markdownlint/blob/main/doc/md050.md) | All strong styling should use asterisks. | Error | -| [GHD002](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-alt-text-end-punctuation.js) | Images alternate text should end with a punctuation. | Error | -| [GHD005](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/internal-links-lang.js) | Internal links must not have a hardcoded language code. | Error | -| [GHD006](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-file-kebab.js) | Image file names should be lowercase kebab case. | Error | -| [MD001](https://github.com/DavidAnson/markdownlint/blob/main/doc/md001.md) | Header levels can only increments by one level at a time. | Warning | -| [MD002](https://github.com/DavidAnson/markdownlint/blob/main/doc/md002.md) | Ensure that headings start with an H2 heading. | Warning | -| [MD009](https://github.com/DavidAnson/markdownlint/blob/main/doc/md009.md) | No unnecessary whitespace from the end of the line. | Warning | -| [MD031](https://github.com/DavidAnson/markdownlint/blob/main/doc/md031.md) | Fenced code blocks must be surrounded by blank lines. | Warning | -| [MD040](https://github.com/DavidAnson/markdownlint/blob/main/doc/md040.md) | Code fences must have a language specified. | Warning | -| [MD047](https://github.com/DavidAnson/markdownlint/blob/main/doc/md047.md) | All files should end with a new line character. | Warning | -| [MD049](https://github.com/DavidAnson/markdownlint/blob/main/doc/md049.md) | All emphasis styling should use underscores. | Warning | -| [GHD001](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/code-fence-line-length.js) | Code fence content should be 60 lines or less in length. | Warning | -| [GHD003](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/image-alt-text-length.js) | Images alternate text should be between 40-150 characters. | Warning | -| [GHD004](https://github.com/github/docs/blob/main/src/content-linter/lib/linting-rules/internal-links-slash.js) | Internal links must start with a `/`. | Warning | +{% data reusables.contributing.content-linter-rules %} ## Suppressing linter rules -Rarely, you may need to document something that violates one or more linter rules. In these cases, you can suppress rules by adding a comment to the Markdown file. You can disable all rules or specific rules. Always try to limit as few rules as possible. +Rarely, you may need to document something that violates one or more linter rules. In these cases, you can suppress rules by adding a comment to the Markdown file. You can disable all rules or specific rules. Always try to limit as few rules as possible. You can disable a rule for an entire file, for a section of a Markdown file, a specific line, or the next line. -For example, if you are writing an article that includes a regular expression such as (^|/)[Cc]+odespace/, you can suppress the `MD011` rule that checks for reversed link syntax by adding the following comment. +For example, if you are writing an article that includes the regular expression `(^|/)[Cc]+odespace/` that checks for reversed link syntax, it will trigger the `MD011` rule that checks for reversed links. You can disable the rule `MD011` on that specific line by adding the following comment. + +
+(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->
+
+ +If the line you're trying to ignore is in a code block, you can ignore the code block by surrounding it with the following comments. 
 <!-- markdownlint-disable MD011 -->
+```
 (^|/)[Cc]+odespace/
+```
 <!-- markdownlint-enable MD011 -->
diff --git a/data/reusables/actions/org-to-enterprise-actions-permissions.md b/data/reusables/actions/org-to-enterprise-actions-permissions.md new file mode 100644 index 0000000000..8b5d08ffb1 --- /dev/null +++ b/data/reusables/actions/org-to-enterprise-actions-permissions.md @@ -0,0 +1 @@ +If the organization has write permissions for {% data variables.product.prodname_actions %}, you must manually set write permissions for the enterprise. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository)." For more information about managing organization-level permissions for {% data variables.product.prodname_actions %}, see "[AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization)." diff --git a/data/reusables/contributing/content-linter-rules.md b/data/reusables/contributing/content-linter-rules.md new file mode 100644 index 0000000000..e2f0251be3 --- /dev/null +++ b/data/reusables/contributing/content-linter-rules.md @@ -0,0 +1,61 @@ + + +| Rule ID | Rule Name(s) | Description | Severity | Tags | +| ------- | ------------ | ----------- | -------- | ---- | +| [MD001](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md001.md) | heading-increment, header-increment | Heading levels should only increment by one level at a time | error | headings, headers | +| [MD002](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md002.md) | first-heading-h1, first-header-h1 | First heading should be a top-level heading | error | headings, headers | +| [MD004](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md004.md) | ul-style | Unordered list style | error | bullet, ul | +| [MD009](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md009.md) | no-trailing-spaces | Trailing spaces | error | whitespace | +| [MD011](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md011.md) | no-reversed-links | Reversed link syntax | error | links | +| [MD012](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md012.md) | no-multiple-blanks | Multiple consecutive blank lines | error | whitespace, blank_lines | +| [MD014](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md014.md) | commands-show-output | Dollar signs used before commands without showing output | error | code | +| [MD018](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md018.md) | no-missing-space-atx | No space after hash on atx style heading | error | headings, headers, atx, spaces | +| [MD019](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md019.md) | no-multiple-space-atx | Multiple spaces after hash on atx style heading | error | headings, headers, atx, spaces | +| [MD022](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md022.md) | blanks-around-headings, blanks-around-headers | Headings should be surrounded by blank lines | error | headings, headers, blank_lines | +| [MD023](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md023.md) | heading-start-left, header-start-left | Headings must start at the beginning of the line | error | headings, headers, spaces | +| [MD027](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md027.md) | no-multiple-space-blockquote | Multiple spaces after blockquote symbol | error | blockquote, whitespace, indentation | +| [MD029](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md029.md) | ol-prefix | Ordered list item prefix | error | ol | +| [MD030](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md030.md) | list-marker-space | Spaces after list markers | error | ol, ul, whitespace | +| [MD031](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md031.md) | blanks-around-fences | Fenced code blocks should be surrounded by blank lines | error | code, blank_lines | +| [MD037](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md037.md) | no-space-in-emphasis | Spaces inside emphasis markers | error | whitespace, emphasis | +| [MD039](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md039.md) | no-space-in-links | Spaces inside link text | error | whitespace, links | +| [MD040](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md040.md) | fenced-code-language | Fenced code blocks should have a language specified | error | code, language | +| [MD042](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md042.md) | no-empty-links | No empty links | error | links | +| [MD047](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md047.md) | single-trailing-newline | Files should end with a single newline character | error | blank_lines | +| [MD049](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md049.md) | emphasis-style | Emphasis style should be consistent | error | emphasis | +| [MD050](https://github.com/DavidAnson/markdownlint/blob/v0.28.2/doc/md050.md) | strong-style | Strong style should be consistent | error | emphasis | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | todocs-placeholder | Catch occurrences of TODOCS placeholder. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | docs-domain | Catch occurrences of docs.gitub.com domain. | warning | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | help-domain | Catch occurrences of help.github.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | preview-domain | Catch occurrences of preview.ghdocs.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | developer-domain | Catch occurrences of developer.github.com domain. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: site.data | Catch occurrences of deprecated liquid data syntax. | error | | +| [search-replace](https://github.com/OnkarRuikar/markdownlint-rule-search-replace) | deprecated liquid syntax: octicon- | The octicon liquid syntax used is deprecated. Use this format instead `octicon "" aria-label=""` | error | | +| [GH001](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH001-no-default-alt-text.md) | no-default-alt-text | Images should have meaningful alternative text (alt text) | error | accessibility, images | +| [GH002](https://github.com/github/markdownlint-github/blob/main/docs/rules/GH002-no-generic-link-text.md) | no-generic-link-text | Avoid using generic link text like `Learn more` or `Click here` | error | accessibility, links | +| GHD030 | code-fence-line-length | Code fence lines should not exceed a maximum length | warning | code | +| GHD032 | image-alt-text-end-punctuation | Alternate text for images should end with a punctuation. | error | accessibility, images | +| GHD004 | image-file-kebab | Image file names should always be lowercase kebab case | error | images | +| GHD033 | incorrect-alt-text-length | Images alternate text should be between 40-150 characters | warning | accessibility, images | +| GHD002 | internal-links-lang | Internal links must not have a hardcoded language code | error | links, url | +| GHD003 | internal-links-slash | Internal links must start with a / | error | links, url | +| GHD031 | image-alt-text-exclude-words | Alternate text for images should not begin with words like "image" or "graphic". | error | accessibility, images | +| GHD034 | list-first-word-capitalization | First word of list item should be capitalized. | warning | ul, ol | +| GHD001 | link-punctuation | Internal link titles must not contain punctuation | error | links, url | +| GHD008 | early-access-references | Files that are not early access should not reference early-access or early-access files. | error | feature, early-access | +| GHD021 | yaml-scheduled-jobs | YAML snippets that include scheduled workflows must not run on the hour and must be unique | error | feature, actions | +| GHD006 | internal-links-old-version | Internal links must not have a hardcoded version using old versioning patterns | error | links, url | +| GHD005 | hardcoded-data-variable | Strings that have a data reusable should use the reusable instead of the hardcoded string. | error | single-source | +| GHD013 | github-owned-action-references | Strings that have a data reusable should use the reusable instead of the hardcoded string. | error | feature, actions | +| GHD016 | liquid-quoted-conditional-arg | Liquid conditional tags should not quote the conditional argument. | error | liquid, format | +| GHD014 | liquid-data-references-defined | Liquid data or indented data references were found in content but do not exist in the data directory or have no value. | error | liquid | +| GHD015 | liquid-data-tag-format | Liquid data or indented data references tags must have the correct number of arguments and spacing. | error | liquid | +| GHD010 | frontmatter-hidden-docs | An article with the hidden frontmatter property can only be located in specific products. | error | frontmatter, feature, early-access | +| GHD009 | frontmatter-early-access-references | Files that are not early access should not have frontmatter that references early-access. | error | frontmatter, feature, early-access | +| GH011 | frontmatter-video-transcripts | Video transcripts must be configured correctly. This rule checks the filepaths and metadata for files that are related to video transcripts. | error | frontmatter | +| GHD012 | frontmatter-schema | Frontmatter must conform to the schema | error | frontmatter, schema | +| GHD007 | annotate-frontmatter | Annotations defined in Markdown must contain a specific layout frontmatter property. | error | code, feature, annotate | +| GHD017 | frontmatter-liquid-syntax | Frontmatter properties that contain Markdown (e.g., translatable strings) must use valid liquid. | error | liquid, frontmatter | +| GHD018 | liquid-syntax | Markdown content must have valid liquid. | error | liquid | +| GHD019 | liquid-if-tags | Liquid `if` conditional tags should not be used when the argument is a version. Use `ifversion` instead. | error | liquid, versioning | +| GHD020 | liquid-ifversion-tags | Liquid `ifversion` conditional tags should contain valid version names as arguments. | error | liquid, versioning | \ No newline at end of file diff --git a/src/content-linter/lib/linting-rules/annotate-frontmatter.js b/src/content-linter/lib/linting-rules/annotate-frontmatter.js index d4f5a89e3f..78955b47a5 100644 --- a/src/content-linter/lib/linting-rules/annotate-frontmatter.js +++ b/src/content-linter/lib/linting-rules/annotate-frontmatter.js @@ -5,7 +5,7 @@ export const annotateFrontmatter = { names: ['GHD007', 'annotate-frontmatter'], description: 'Annotations defined in Markdown must contain a specific layout frontmatter property.', - tags: ['code', 'annotate'], + tags: ['code', 'feature', 'annotate'], function: function GHD007(params, onError) { filterTokens(params, 'fence', (token) => { if (!token.info.includes('annotate')) return diff --git a/src/content-linter/lib/linting-rules/early-access-references.js b/src/content-linter/lib/linting-rules/early-access-references.js index ffbde2017d..4fe5416de2 100644 --- a/src/content-linter/lib/linting-rules/early-access-references.js +++ b/src/content-linter/lib/linting-rules/early-access-references.js @@ -21,7 +21,7 @@ export const earlyAccessReferences = { names: ['GHD008', 'early-access-references'], description: 'Files that are not early access should not reference early-access or early-access files.', - tags: ['early-access'], + tags: ['feature', 'early-access'], severity: 'error', function: function GHD008(params, onError) { @@ -49,7 +49,7 @@ export const frontmatterEarlyAccessReferences = { names: ['GHD009', 'frontmatter-early-access-references'], description: 'Files that are not early access should not have frontmatter that references early-access.', - tags: ['early-access', 'frontmatter'], + tags: ['frontmatter', 'feature', 'early-access'], function: function GHD009(params, onError) { const filepath = params.name if (isEarlyAccessFilepath(filepath)) return diff --git a/src/content-linter/lib/linting-rules/frontmatter-hidden-docs.js b/src/content-linter/lib/linting-rules/frontmatter-hidden-docs.js index e9ce69318e..300307291c 100644 --- a/src/content-linter/lib/linting-rules/frontmatter-hidden-docs.js +++ b/src/content-linter/lib/linting-rules/frontmatter-hidden-docs.js @@ -6,7 +6,7 @@ export const frontmatterHiddenDocs = { names: ['GHD010', 'frontmatter-hidden-docs'], description: 'An article with the hidden frontmatter property can only be located in specific products.', - tags: ['early-access', 'frontmatter'], + tags: ['frontmatter', 'feature', 'early-access'], function: function GHD010(params, onError) { const fm = getFrontmatter(params.lines) if (!fm || !fm.hidden) return diff --git a/src/content-linter/lib/linting-rules/frontmatter-format.js b/src/content-linter/lib/linting-rules/frontmatter-schema.js similarity index 95% rename from src/content-linter/lib/linting-rules/frontmatter-format.js rename to src/content-linter/lib/linting-rules/frontmatter-schema.js index ce649f26ad..4ec20e7251 100644 --- a/src/content-linter/lib/linting-rules/frontmatter-format.js +++ b/src/content-linter/lib/linting-rules/frontmatter-schema.js @@ -6,10 +6,10 @@ import { formatAjvErrors } from '../helpers/schema-utils.js' import { frontmatter, deprecatedProperties } from '../../../../lib/frontmatter.js' import readFrontmatter from '../../../../lib/read-frontmatter.js' -export const frontmatterFormat = { - names: ['GHD012', 'frontmatter-format'], +export const frontmatterSchema = { + names: ['GHD012', 'frontmatter-schema'], description: 'Frontmatter must conform to the schema', - tags: ['frontmatter', 'format'], + tags: ['frontmatter', 'schema'], function: function GHD012(params, onError) { const fm = getFrontmatter(params.lines) if (!fm) return diff --git a/src/content-linter/lib/linting-rules/github-owned-action-references.js b/src/content-linter/lib/linting-rules/github-owned-action-references.js index bc3f06b1fd..74e7c64736 100644 --- a/src/content-linter/lib/linting-rules/github-owned-action-references.js +++ b/src/content-linter/lib/linting-rules/github-owned-action-references.js @@ -10,7 +10,7 @@ export const githubOwnedActionReferences = { names: ['GHD013', 'github-owned-action-references'], description: 'Strings that have a data reusable should use the reusable instead of the hardcoded string.', - tags: ['actions'], + tags: ['feature', 'actions'], function: function GHD013(params, onError) { const filepath = params.name if (filepath.startsWith('data/reusables/actions/action-')) return diff --git a/src/content-linter/lib/linting-rules/index.js b/src/content-linter/lib/linting-rules/index.js index e51fc87e2d..124a0a5cb4 100644 --- a/src/content-linter/lib/linting-rules/index.js +++ b/src/content-linter/lib/linting-rules/index.js @@ -22,7 +22,7 @@ import { hardcodedDataVariable } from './hardcoded-data-variable.js' import { githubOwnedActionReferences } from './github-owned-action-references.js' import { liquidQuotedConditionalArg } from './liquid-quoted-conditional-arg.js' import { liquidDataReferencesDefined, liquidDataTagFormat } from './liquid-data-tags.js' -import { frontmatterFormat } from './frontmatter-format.js' +import { frontmatterSchema } from './frontmatter-schema.js' import { annotateFrontmatter } from './annotate-frontmatter.js' import { frontmatterLiquidSyntax, liquidSyntax } from './liquid-syntax.js' import { liquidIfTags, liquidIfVersionTags } from './liquid-versioning.js' @@ -59,7 +59,7 @@ export const gitHubDocsMarkdownlint = { frontmatterHiddenDocs, frontmatterEarlyAccessReferences, frontmatterVideoTranscripts, - frontmatterFormat, + frontmatterSchema, annotateFrontmatter, frontmatterLiquidSyntax, liquidSyntax, diff --git a/src/content-linter/lib/linting-rules/liquid-quoted-conditional-arg.js b/src/content-linter/lib/linting-rules/liquid-quoted-conditional-arg.js index 8a4a177486..4386dfe822 100644 --- a/src/content-linter/lib/linting-rules/liquid-quoted-conditional-arg.js +++ b/src/content-linter/lib/linting-rules/liquid-quoted-conditional-arg.js @@ -15,7 +15,7 @@ import { isStringQuoted } from '../helpers/utils.js' export const liquidQuotedConditionalArg = { names: ['GHD016', 'liquid-quoted-conditional-arg'], description: 'Liquid conditional tags should not quote the conditional argument.', - tags: ['liquid', 'formatting'], + tags: ['liquid', 'format'], function: function GHD016(params, onError) { const content = params.lines.join('\n') const tokens = getLiquidTokens(content) @@ -41,7 +41,7 @@ export const liquidQuotedConditionalArg = { addError( onError, lineNumber, - "A conditional Liquid tag's argument is quoted, meaning it will always evaluate to true. Remove the quotes to allow Liquid to evaluate variable.", + "A conditional Liquid tag's argument is quoted, meaning it will always evaluate to true. Remove the quotes to allow Liquid to evaluate the variable.", token.content, [column, length], { diff --git a/src/content-linter/lib/linting-rules/yaml-scheduled-jobs.js b/src/content-linter/lib/linting-rules/yaml-scheduled-jobs.js index 94f05d73d1..01c4a6459e 100644 --- a/src/content-linter/lib/linting-rules/yaml-scheduled-jobs.js +++ b/src/content-linter/lib/linting-rules/yaml-scheduled-jobs.js @@ -10,7 +10,7 @@ export const yamlScheduledJobs = { names: ['GHD021', 'yaml-scheduled-jobs'], description: 'YAML snippets that include scheduled workflows must not run on the hour and must be unique', - tags: ['actions'], + tags: ['feature', 'actions'], asynchronous: true, function: function GHD021(params, onError) { filterTokens(params, 'fence', async (token) => { diff --git a/src/content-linter/scripts/generate-docs.js b/src/content-linter/scripts/generate-docs.js new file mode 100755 index 0000000000..f63bc61bce --- /dev/null +++ b/src/content-linter/scripts/generate-docs.js @@ -0,0 +1,50 @@ +#!/usr/bin/env node +import { writeFileSync } from 'fs' +import { allRules, allConfig } from '../lib/helpers/get-rules.js' + +main() + +function main() { + const markdown = [] + // Some rule messages contain text that will trigger markdownlint errors + markdown.push('') + markdown.push( + '', + ) + markdown.push('| Rule ID | Rule Name(s) | Description | Severity | Tags |') + markdown.push('| ------- | ------------ | ----------- | -------- | ---- |') + for (const rule of allRules) { + const ruleName = rule.names.find((name) => allConfig[name] !== undefined) + if (allConfig[ruleName] === undefined) continue + if (rule.names.includes('search-replace')) { + markdown.push(...getSearchRepolaceRules(rule, allConfig[ruleName])) + continue + } + const row = [] + const ruleId = rule.information ? `[${rule.names[0]}](${rule.information})` : rule.names[0] + row.push(ruleId) + row.push(rule.names.slice(1).join(', ')) + row.push(rule.description) + row.push(allConfig[ruleName].severity) + row.push(rule.tags.join(', ')) + markdown.push(`| ${row.join(' | ')} |`) + } + writeFileSync('data/reusables/contributing/content-linter-rules.md', markdown.join('\n')) +} + +// The search-replace rule configures multiple psuedo-rules +// under the rules key. +function getSearchRepolaceRules(srRule, ruleConfig) { + const name = srRule.information ? `[search-replace](${srRule.information})` : 'search-replace' + const markdown = [] + for (const rule of ruleConfig.rules) { + const row = [] + row.push(name) + row.push(rule.name) + row.push(rule.message) + row.push(rule.severity) + row.push('') + markdown.push(`| ${row.join(' | ')} |`) + } + return markdown +} diff --git a/src/content-linter/style/github-docs.js b/src/content-linter/style/github-docs.js index d8c9cc65dc..43a3ddc1d2 100644 --- a/src/content-linter/style/github-docs.js +++ b/src/content-linter/style/github-docs.js @@ -122,7 +122,7 @@ export const githubDocsFrontmatterConfig = { severity: 'error', 'partial-markdown-files': false, }, - 'frontmatter-format': { + 'frontmatter-schema': { // GHD012 severity: 'error', 'partial-markdown-files': false, @@ -214,7 +214,7 @@ export const searchReplaceConfig = { // - {{ octicon-plus An example label }} name: 'deprecated liquid syntax: octicon-', message: - 'The octicon liquid syntax used is deprecated. Use this format instead {% octicon "" aria-label="" %}', + 'The octicon liquid syntax used is deprecated. Use this format instead `octicon "" aria-label=""`', searchPattern: '/{{\\s*?octicon-([a-z-]+)(\\s[\\w\\s\\d-]+)?\\s*?}}/g', severity: 'error', 'partial-markdown-files': true, diff --git a/src/content-linter/tests/unit/frontmatter-format.js b/src/content-linter/tests/unit/frontmatter-schema.js similarity index 80% rename from src/content-linter/tests/unit/frontmatter-format.js rename to src/content-linter/tests/unit/frontmatter-schema.js index df853dcccf..9e5dd0eba8 100644 --- a/src/content-linter/tests/unit/frontmatter-format.js +++ b/src/content-linter/tests/unit/frontmatter-schema.js @@ -1,10 +1,10 @@ import { runRule } from '../../lib/init-test.js' -import { frontmatterFormat } from '../../lib/linting-rules/frontmatter-format.js' +import { frontmatterSchema } from '../../lib/linting-rules/frontmatter-schema.js' // Configure the test figure to not split frontmatter and content const fmOptions = { markdownlintOptions: { frontMatter: null } } -describe(frontmatterFormat.names.join(' - '), () => { +describe(frontmatterSchema.names.join(' - '), () => { test('Deprecated properties in frontmatter fails', async () => { const markdown = [ '---', @@ -14,7 +14,7 @@ describe(frontmatterFormat.names.join(' - '), () => { 'miniTocMaxHeadingLevel: 2', '---', ].join('\n') - const result = await runRule(frontmatterFormat, { strings: { markdown }, ...fmOptions }) + const result = await runRule(frontmatterSchema, { strings: { markdown }, ...fmOptions }) const errors = result.markdown expect(errors.length).toBe(1) expect(errors[0].lineNumber).toBe(5) @@ -22,7 +22,7 @@ describe(frontmatterFormat.names.join(' - '), () => { }) test('Minimum required prpoperties pass', async () => { const markdown = ['---', 'title: Title', 'versions:', " fpt: '*'", '---'].join('\n') - const result = await runRule(frontmatterFormat, { strings: { markdown }, ...fmOptions }) + const result = await runRule(frontmatterSchema, { strings: { markdown }, ...fmOptions }) const errors = result.markdown expect(errors.length).toBe(0) }) @@ -30,7 +30,7 @@ describe(frontmatterFormat.names.join(' - '), () => { const markdown = ['---', 'title: Title', 'versions:', " ft: '*'", 'mona: lisa', '---'].join( '\n', ) - const result = await runRule(frontmatterFormat, { strings: { markdown }, ...fmOptions }) + const result = await runRule(frontmatterSchema, { strings: { markdown }, ...fmOptions }) const errors = result.markdown expect(errors.length).toBe(2) expect(errors[0].lineNumber).toBe(4) @@ -40,7 +40,7 @@ describe(frontmatterFormat.names.join(' - '), () => { }) test('Missing required property fails', async () => { const markdown = ['---', 'title: Title', '---'].join('\n') - const result = await runRule(frontmatterFormat, { strings: { markdown }, ...fmOptions }) + const result = await runRule(frontmatterSchema, { strings: { markdown }, ...fmOptions }) const errors = result.markdown expect(errors.length).toBe(1) expect(errors[0].lineNumber).toBe(1)