chore: Add static frontmatter to docs (#15782)

* chore: Add static frontmatter to docs * cleanup architecture docs location * Update rule ID check for docs * Update lint check * Update Makefile.js Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> * Cleanup based on feedback * Fix Makefile.js gensite * Revert "Fix Makefile.js gensite" This reverts commit 822dc55. * Update docs/src/pages/index.md Co-authored-by: Brandon Mills <btmills@users.noreply.github.com> * Remove extra file and resources sections Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com> Co-authored-by: Brandon Mills <btmills@users.noreply.github.com>
eslint · Apr 22, 2022 · db28f2c · db28f2c
1 parent c2407e8
commit db28f2c
Show file tree

Hide file tree

Showing 357 changed files with 2,995 additions and 924 deletions.
diff --git a/Makefile.js b/Makefile.js
@@ -660,9 +660,7 @@ target.gensite = function(prereleaseVersion) {
                 sourcePath = path.join("lib/rules", sourceBaseName),
                 ruleName = path.basename(filename, ".md"),
                 filePath = path.posix.join("docs", path.relative("tmp", filename));
-            let text = cat(filename),
-                ruleType = "",
-                title;
+            let text = cat(filename);
 
             process.stdout.write(`> Updating files (Steps 4-9): ${i}/${length} - ${filePath + " ".repeat(30)}\r`);
 
@@ -675,40 +673,12 @@ target.gensite = function(prereleaseVersion) {
                 const isFixable = rule && rule.meta.fixable;
                 const hasSuggestions = rule && rule.meta.hasSuggestions;
 
-                // Incorporate the special portion into the documentation content
-                const textSplit = text.split("\n");
-                const ruleHeading = textSplit[0];
-                const ruleDocsContent = textSplit.slice(1).join("\n");
+                text = text.replace("<!--FIXABLE-->", isFixable ? FIXABLE_TEXT : "")
+                    .replace("<!--SUGGESTIONS-->", hasSuggestions ? HAS_SUGGESTIONS_TEXT : "")
+                    .replace("<!--RECOMMENDED-->", isRecommended ? RECOMMENDED_TEXT : "");
 
-                text = `${ruleHeading}${isRecommended ? RECOMMENDED_TEXT : ""}${isFixable ? FIXABLE_TEXT : ""}${hasSuggestions ? HAS_SUGGESTIONS_TEXT : ""}\n${ruleDocsContent}`;
-                title = `${ruleName} - Rules`;
-
-                if (rule && rule.meta) {
-                    ruleType = `rule_type: ${rule.meta.type}`;
-                }
-            } else {
-
-                // extract the title from the file itself
-                title = text.match(/#([^#].+)\n/u);
-                if (title) {
-                    title = title[1].trim();
-                } else {
-                    title = "Documentation";
-                }
             }
 
-            text = [
-                "---",
-                `title: ${title}`,
-                "layout: doc",
-                `edit_link: https://github.com/eslint/eslint/edit/main/${filePath.replace("docs/", "docs/src/")}`,
-                ruleType,
-                "---",
-                "<!-- Note: No pull requests accepted for this file. See README.md in the root directory for details. -->",
-                "",
-                text
-            ].join("\n");
-
             // 6. Remove .md extension for relative links and change README to empty string
             text = text.replace(/\((?!https?:\/\/)([^)]*?)\.md(.*?)\)/gu, "($1$2)").replace("README.html", "");
 
@@ -816,7 +786,7 @@ target.checkRuleFiles = function() {
          * @todo Will remove this check when the main heading is automatically generated from rule metadata.
          */
         function hasIdInTitle(id) {
-            return new RegExp(`^# ${id}`, "u").test(docText);
+            return new RegExp(`title: ${id}`, "u").test(docText);
         }
 
         /**

diff --git a/docs/src/about/index.md b/docs/src/about/index.md
@@ -1,4 +1,9 @@
-# About
+---
+title: About
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/about/index.md
+
+---
 
 ESLint is an open source JavaScript linting utility originally created by Nicholas C. Zakas in June 2013. Code [linting][] is a type of static analysis that is frequently used to find problematic patterns or code that doesn't adhere to certain style guidelines. There are code linters for most programming languages, and compilers sometimes incorporate linting into the compilation process.
 

diff --git a/docs/src/developer-guide/README.md b/docs/src/developer-guide/README.md
@@ -1,4 +1,9 @@
-# Developer Guide
+---
+title: Developer Guide
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/README.md
+
+---
 
 This guide is intended for those who wish to:
 
@@ -14,31 +19,31 @@ In order to work with ESLint as a developer, it's recommended that:
 
 If that sounds like you, then continue reading to get started.
 
-## Section 1: Get the [Source Code](source-code.md)
+## Section 1: Get the [Source Code](source-code)
 
 Before you can get started, you'll need to get a copy of the ESLint source code. This section explains how to do that and a little about the source code structure.
 
-## Section 2: Set up a [Development Environment](development-environment.md)
+## Section 2: Set up a [Development Environment](development-environment)
 
 Developing for ESLint is a bit different than running it on the command line. This section shows you how to set up a development environment and get you ready to write code.
 
-## Section 3: Run the [Unit Tests](unit-tests.md)
+## Section 3: Run the [Unit Tests](unit-tests)
 
 There are a lot of unit tests included with ESLint to make sure that we're keeping on top of code quality. This section explains how to run the unit tests.
 
-## Section 4: [Working with Rules](working-with-rules.md)
+## Section 4: [Working with Rules](working-with-rules)
 
 You're finally ready to start working with rules. You may want to fix an existing rule or create a new one. This section explains how to do all of that.
 
-## Section 5: [Working with Plugins](working-with-plugins.md)
+## Section 5: [Working with Plugins](working-with-plugins)
 
 You've developed library-specific rules for ESLint and you want to share them with the community. You can publish an ESLint plugin on npm.
 
-## Section 6: [Working with Custom Parsers](working-with-custom-parsers.md)
+## Section 6: [Working with Custom Parsers](working-with-custom-parsers)
 
 If you aren't going to use the default parser of ESLint, this section explains about using custom parsers.
 
-## Section 7: [Node.js API](nodejs-api.md)
+## Section 7: [Node.js API](nodejs-api)
 
 If you're interested in writing a tool that uses ESLint, then you can use the Node.js API to get programmatic access to functionality.
 

diff --git a/docs/src/developer-guide/architecture.md → ...src/developer-guide/architecture/index.md b/docs/src/developer-guide/architecture.md → ...src/developer-guide/architecture/index.md
@@ -1,6 +1,11 @@
-# Architecture
+---
+title: Architecture
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/architecture/index.md
 
-<center><img alt="dependency graph" src="./architecture/dependency.svg"></center>
+---
+
+<center><img alt="dependency graph" src="dependency.svg"></center>
 
 At a high level, there are a few key parts to ESLint:
 

diff --git a/docs/src/developer-guide/code-conventions.md b/docs/src/developer-guide/code-conventions.md
@@ -1,4 +1,9 @@
-# Code Conventions
+---
+title: Code Conventions
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/code-conventions.md
+
+---
 
 Code conventions for ESLint are determined by
 [eslint-config-eslint](https://www.npmjs.com/package/eslint-config-eslint).

diff --git a/docs/src/developer-guide/code-path-analysis.md b/docs/src/developer-guide/code-path-analysis.md
@@ -1,4 +1,9 @@
-# Code Path Analysis Details
+---
+title: Code Path Analysis Details
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/code-path-analysis.md
+
+---
 
 ESLint's rules can use code paths.
 The code path is execution routes of programs.

diff --git a/docs/src/developer-guide/code-path-analysis/README.md b/docs/src/developer-guide/code-path-analysis/README.md
@@ -1 +1,8 @@
-[Code Path Analysis Details](../code-path-analysis.md)
+---
+title: Code Path Analysis Details
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/code-path-analysis/README.md
+
+---
+
+[Code Path Analysis Details](../code-path-analysis)
diff --git a/docs/src/developer-guide/contributing/README.md b/docs/src/developer-guide/contributing/README.md
@@ -1,4 +1,9 @@
-# Contributing
+---
+title: Contributing
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/README.md
+
+---
 
 One of the great things about open source projects is that anyone can contribute in any number of meaningful ways. ESLint couldn't exist without the help of the many contributors it's had since the project began, and we want you to feel like you can contribute and make a difference as well.
 
@@ -12,27 +17,27 @@ ESLint welcomes contributions from everyone and adheres to the [OpenJS Foundatio
 
 Think you found a problem? We'd love to hear about it. This section explains how to submit a bug, the type of information we need to properly verify it, and the overall process.
 
-## Proposing a [New Rule](new-rules.md)
+## Proposing a [New Rule](new-rules)
 
 We get a lot of proposals for new rules in ESLint. This section explains how we determine which rules are accepted and what information you should provide to help us evaluate your proposal.
 
-## Proposing a [Rule Change](rule-changes.md)
+## Proposing a [Rule Change](rule-changes)
 
 Want to make a change to an existing rule? This section explains the process and how we evaluate such proposals.
 
-## Requesting a [Change](changes.md)
+## Requesting a [Change](changes)
 
 If you'd like to request a change other than a bug fix or new rule, this section explains that process.
 
 ## Reporting a security vulnerability
 
 To report a security vulnerability in ESLint, please use our [HackerOne program](https://hackerone.com/eslint).
 
-## [Working on Issues](working-on-issues.md)
+## [Working on Issues](working-on-issues)
 
 Have some extra time and want to contribute? This section talks about the process of working on issues.
 
-## Submitting a [Pull Request](pull-requests.md)
+## Submitting a [Pull Request](pull-requests)
 
 We're always looking for contributions from the community. This section explains the requirements for pull requests and the process of contributing code.
 

diff --git a/docs/src/developer-guide/contributing/changes.md b/docs/src/developer-guide/contributing/changes.md
@@ -1,4 +1,9 @@
-# Change Requests
+---
+title: Change Requests
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/changes.md
+
+---
 
 If you'd like to request a change to ESLint, please [create a new issue](https://github.com/eslint/eslint/issues/new/choose) on GitHub. Be sure to include the following information:
 

diff --git a/docs/src/developer-guide/contributing/new-rules.md b/docs/src/developer-guide/contributing/new-rules.md
@@ -1,4 +1,9 @@
-# New Rules
+---
+title: New Rules
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/new-rules.md
+
+---
 
 ESLint is all about rules. For most of the project's lifetime, we've had over 200 rules, and that list continues to grow. However, we can't just accept any proposed rule because all rules need to work cohesively together. As such, we have some guidelines around which rules can be part of the ESLint core and which are better off as custom rules and plugins.
 
@@ -39,4 +44,4 @@ The ESLint team doesn't implement new rules that are suggested by users because
 
 ## Alternative: Creating Your Own Rules
 
-Remember that ESLint is completely pluggable, which means you can create your own rules and distribute them using plugins. We did this on purpose because we don't want to be the gatekeepers for all possible rules. Even if we don't accept a rule into the core, that doesn't mean you can't have the exact rule that you want. See the [working with rules](../working-with-rules.md) and [working with plugins](../working-with-plugins.md) documentation for more information.
+Remember that ESLint is completely pluggable, which means you can create your own rules and distribute them using plugins. We did this on purpose because we don't want to be the gatekeepers for all possible rules. Even if we don't accept a rule into the core, that doesn't mean you can't have the exact rule that you want. See the [working with rules](../working-with-rules) and [working with plugins](../working-with-plugins) documentation for more information.
diff --git a/docs/src/developer-guide/contributing/pull-requests.md b/docs/src/developer-guide/contributing/pull-requests.md
@@ -1,13 +1,18 @@
-# Pull Requests
+---
+title: Pull Requests
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/pull-requests.md
+
+---
 
 If you want to contribute to an ESLint repo, please use a GitHub pull request. This is the fastest way for us to evaluate your code and to merge it into the code base. Please don't file an issue with snippets of code. Doing so means that we need to manually merge the changes in and update any appropriate tests. That decreases the likelihood that your code is going to get included in a timely manner. Please use pull requests.
 
 ## Getting Started
 
 If you'd like to work on a pull request and you've never submitted code before, follow these steps:
 
-1. Set up a [development environment](../development-environment.md).
-1. If you want to implement a breaking change or a change to the core, ensure there's an issue that describes what you're doing and the issue has been accepted. You can create a new issue or just indicate you're [working on an existing issue](working-on-issues.md). Bug fixes, documentation changes, and other pull requests do not require an issue.
+1. Set up a [development environment](../development-environment).
+1. If you want to implement a breaking change or a change to the core, ensure there's an issue that describes what you're doing and the issue has been accepted. You can create a new issue or just indicate you're [working on an existing issue](working-on-issues). Bug fixes, documentation changes, and other pull requests do not require an issue.
 
 After that, you're ready to start working on code.
 
@@ -39,7 +44,7 @@ You should do all of your development for the issue in this branch.
 
 ### Step 2: Make your changes<a name="step2"></a>
 
-Make the changes to the code and tests, following the [code conventions](../code-conventions.md) as you go. Once you have finished, commit the changes to your branch:
+Make the changes to the code and tests, following the [code conventions](../code-conventions) as you go. Once you have finished, commit the changes to your branch:
 
 ```shell
 git add -A
@@ -72,7 +77,7 @@ The `tag` is one of the following:
 * `ci` - changes to our CI configuration files and scripts.
 * `perf` - a code change that improves performance.
 
-Use the [labels of the issue you are working on](working-on-issues.md#issue-labels) to determine the best tag.
+Use the [labels of the issue you are working on](working-on-issues#issue-labels) to determine the best tag.
 
 The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. If the pull request addresses an issue, then the issue number should be mentioned in the body of the commit message in the format `Fixes #1234`. If the commit doesn't completely fix the issue, then use `Refs #1234` instead of `Fixes #1234`.
 
@@ -116,7 +121,7 @@ With your code ready to go, this is a good time to double-check your submission
 * Make separate pull requests for unrelated changes. Large pull requests with multiple unrelated changes may be closed without merging.
 * All changes must be accompanied by tests, even if the feature you're working on previously had no tests.
 * All user-facing changes must be accompanied by appropriate documentation.
-* Follow the [Code Conventions](../code-conventions.md).
+* Follow the [Code Conventions](../code-conventions).
 
 ### Step 6: Push your changes<a name="step6"></a>
 
@@ -176,7 +181,7 @@ The commit messages in subsequent commits do not need to be in any specific form
 
 ### Rebasing
 
-If your code is out-of-date, we might ask you to rebase. That means we want you to apply your changes on top of the latest upstream code. Make sure you have set up a [development environment](../development-environment.md) and then you can rebase using these commands:
+If your code is out-of-date, we might ask you to rebase. That means we want you to apply your changes on top of the latest upstream code. Make sure you have set up a [development environment](../development-environment) and then you can rebase using these commands:
 
 ```shell
 git fetch upstream

diff --git a/docs/src/developer-guide/contributing/reporting-bugs.md b/docs/src/developer-guide/contributing/reporting-bugs.md
@@ -1,6 +1,11 @@
-# Reporting Bugs
+---
+title: Reporting Bugs
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/reporting-bugs.md
 
-If you think you've found a bug in ESLint, please [create a new issue](https://github.com/eslint/eslint/issues/new/choose) or a [pull request](/docs/developer-guide/contributing/pull-requests.md) on GitHub.
+---
+
+If you think you've found a bug in ESLint, please [create a new issue](https://github.com/eslint/eslint/issues/new/choose) or a [pull request](/docs/developer-guide/contributing/pull-requests) on GitHub.
 
 Please include as much detail as possible to help us properly address your issue. If we need to triage issues and constantly ask people for more detail, that's time taken away from actually fixing issues. Help us be as efficient as possible by including a lot of detail in your issues.
 

diff --git a/docs/src/developer-guide/contributing/rule-changes.md b/docs/src/developer-guide/contributing/rule-changes.md
@@ -1,18 +1,23 @@
-# Rule Changes
+---
+title: Rule Changes
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/rule-changes.md
+
+---
 
 Occasionally, a core ESLint rule needs to be changed. This is not necessarily a bug, but rather, an enhancement that makes a rule more configurable. In those situations, we will consider making changes to rules.
 
 ## Proposing a Rule Change
 
-To propose a change to an existing rule, [create a pull request](/docs/developer-guide/contributing/pull-requests.md) or [new issue](https://github.com/eslint/eslint/issues/new/choose) and fill out the template.
+To propose a change to an existing rule, [create a pull request](/docs/developer-guide/contributing/pull-requests) or [new issue](https://github.com/eslint/eslint/issues/new/choose) and fill out the template.
 
 We need all of this information in order to determine whether or not the change is a good candidate for inclusion.
 
 ## Accepting a Rule Change
 
 In order for a rule change to be accepted into ESLint, it must:
 
-1. Adhere to the [Core Rule Guidelines](new-rules.md#core-rule-guidelines)
+1. Adhere to the [Core Rule Guidelines](new-rules#core-rule-guidelines)
 1. Have an ESLint team member champion the change
 1. Be important enough that rule is deemed incomplete without this change
 

diff --git a/docs/src/developer-guide/contributing/working-on-issues.md b/docs/src/developer-guide/contributing/working-on-issues.md
@@ -1,4 +1,9 @@
-# Working on Issues
+---
+title: Working on Issues
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/contributing/working-on-issues.md
+
+---
 
 Our public [issues tracker](https://github.com/eslint/eslint/issues) lists all of the things we plan on doing as well as suggestions from the community. Before starting to work on an issue, be sure you read through the rest of this page.
 

diff --git a/docs/src/developer-guide/development-environment.md b/docs/src/developer-guide/development-environment.md
@@ -1,4 +1,9 @@
-# Development Environment
+---
+title: Development Environment
+layout: doc
+edit_link: https://github.com/eslint/eslint/edit/main/docs/src/developer-guide/development-environment.md
+
+---
 
 ESLint has a very lightweight development environment that makes updating code fast and easy. This is a step-by-step guide to setting up a local development environment that will let you contribute back to the project.
 
@@ -59,7 +64,7 @@ The testing takes a few minutes to complete. If any tests fail, that likely mean
 
 ### Workflow
 
-Once you have your development environment installed, you can make and submit changes to the ESLint source files. Doing this successfully requires careful adherence to our [pull-request submission workflow](contributing/pull-requests.md).
+Once you have your development environment installed, you can make and submit changes to the ESLint source files. Doing this successfully requires careful adherence to our [pull-request submission workflow](contributing/pull-requests).
 
 ### Build Scripts