website(docs): More website tweaks (#3707)

website/astro.config.ts

@@ -143,10 +143,10 @@ function inlineIntegration(): AstroIntegration {
 }
 
 function remarkDefaultLayoutPlugin() {
-  return function (tree, file) {
-		const {frontmatter} = file.data.astro;
-    frontmatter.layout = frontmatter.layout ?? "/Layout.astro";
-  };
+	return function (tree, file) {
+		const { frontmatter } = file.data.astro;
+		frontmatter.layout = frontmatter.layout ?? "/Layout.astro";
+	};
 }
 
 // https://astro.build/config

website/src/Layout.astro

@@ -6,7 +6,10 @@ import {buildGetPages, buildTOC} from "./navigation-utils";
 const {props} = Astro;
 const {frontmatter = {}} = props;
 
-const getPages = buildGetPages(await Astro.glob("./**/*.mdx"));
+const getPages = buildGetPages([
+  ...(await Astro.glob("./**/*.mdx")),
+  ...(await Astro.glob("./**/*.md")),
+]);
 let sidebarEnabled = false;
 let toc = "";
 
@@ -18,13 +21,30 @@ for (const page of allPages) {
     break;
   }
 }
+
+let parentPage;
+if (frontmatter.parent) {
+  for (const page of allPages) {
+    if (page.file.includes(frontmatter.parent)) {
+      parentPage = page;
+      break;
+    }
+  }
+  if (parentPage === undefined) {
+    throw new Error(`Could not find parent page ${frontmatter.parent}`);
+  }
+}
 ---
 
 <BaseLayout sidebarEnabled={sidebarEnabled} {...Astro.props}>
   <div class="docs-main">
     <NavigationSidebar />
 
     <main class={`main content ${frontmatter.mainClass ?? ""}`}>
+      {parentPage && <p class="parent-back"><a href={parentPage.url}>
+        <span aria-hidden="true" class="symbol">⏎</span>
+        <span class="text">{parentPage.frontmatter.title}</span>
+      </a></p>}
       <slot />
     </main>
 

website/src/navigation-utils.ts

@@ -1,14 +1,20 @@
 import type Astro from "astro";
 
-export function buildGetPages(pages: Astro.MDXInstance<any>[]) {
-	return (category?: string): Astro.MDXInstance<any>[] => {
+type GlobInstance = Astro.MarkdownInstance<any> | Astro.MDXInstance<any>;
+
+function getTitle(page: GlobInstance): string {
+	return page.frontmatter.title ?? "";
+}
+
+export function buildGetPages(pages: GlobInstance[]) {
+	return (category?: string): GlobInstance[] => {
 		return pages
 			.filter(
 				(page) =>
 					category === undefined || page.frontmatter.category === category,
 			)
 			.sort((a, b) => {
-				return a.frontmatter.title.localeCompare(b.frontmatter.title);
+				return getTitle(a).localeCompare(getTitle(b));
 			});
 	};
 }

website/src/pages/configuration.mdx

@@ -6,6 +6,7 @@ description: How to customize and configure Rome with rome.json.
 ---
 
 import LintGroups from "/components/reference/Groups.astro";
+import CodeBlockHeader from "/components/CodeBlockHeader.astro";
 
 {/** Make sure to update the redirect in `static/_redirects` when changing the configuration title --> **/}
 
@@ -19,6 +20,8 @@ directory is usually the directory containing your project's `package.json`.
 
 Here's an example:
 
+<CodeBlockHeader filename="rome.json" />
+
 ```json
 {
   "formatter": {
@@ -34,29 +37,29 @@ Here's an example:
 
 This configuration file enables the formatter and sets the preferred indent style and width. The linter is disabled.
 
-## `rome.json`
-
-#### Files
+## `files`
 
-##### `files.maxSize`
+### `files.maxSize`
 
 The maximum allowed size for source code files in bytes. Files above
 this limit will be ignored for performance reason.
 
 > Default: 1024*1024 (1MB)
 
-### Linter
+## `linter`
 
-#### `linter.enabled`
+### `linter.enabled`
 
 Enables Rome's linter
 
 > Default: `true`
 
-#### `linter.ignore`
+### `linter.ignore`
 
 An array of Unix shell style patterns.
 
+<CodeBlockHeader filename="rome.json" />
+
 ```json
 {
   "linter": {
@@ -65,24 +68,26 @@ An array of Unix shell style patterns.
 }
 ```
 
-#### `linter.rules.recommended`
+### `linter.rules.recommended`
 
 Enables the [recommended rules](/lint/rules) for all categories.
 
 > Default: `true`
 
-#### `linter.rules.[category]`
+### `linter.rules.[category]`
 
 Options that influence the rules of a single category. Rome supports the following categories:
 
 <LintGroups />
 
-#### `linter.rules.[category].recommended`
+### `linter.rules.[category].recommended`
 
 Enables the recommended rules for a single category.
 
 Example:
 
+<CodeBlockHeader filename="rome.json" />
+
 ```json
 {
   "linter": {
@@ -96,18 +101,20 @@ Example:
 }
 ```
 
-### Formatter
+## `formatter`
 
-#### `formatter.enabled`
+### `formatter.enabled`
 
 Enables Rome's formatter
 
 > Default: `true`
 
-#### `formatter.ignore`
+### `formatter.ignore`
 
 An array of Unix shell style patterns.
 
+<CodeBlockHeader filename="rome.json" />
+
 ```json
 {
   "formatter": {
@@ -116,39 +123,39 @@ An array of Unix shell style patterns.
 }
 ```
 
-#### `formatter.indentStyle`
+### `formatter.indentStyle`
 
 The style of the indentation. It can be `"tab"` or `"space"`.
 
 > Default: `tab`
 
 Rome's default is `"tab"`.
 
-#### `formatter.indentSize`
+### `formatter.indentSize`
 
 How big the indentation should be.
 
-#### `formatter.lineWidth`
+### `formatter.lineWidth`
 
 How many characters can be written on a single line.
 
 > Default: `80`
 
-### JavaScript
+## `javascript`
 
-#### `javascript.formatter.quoteStyle`
+### `javascript.formatter.quoteStyle`
 
 The type of quote used when representing string literals. It can be `single` or `double`.
 
 > Default: `double`
 
-#### `javascript.formatter.quoteProperties`
+### `javascript.formatter.quoteProperties`
 
 When properties inside objects should be quoted. It can be `asNeeded` or `preserve`.
 
 > Default: `asNeeded`
 
-#### `javascript.formatter.trailingComma`
+### `javascript.formatter.trailingComma`
 
 Print trailing commas wherever possible in multi-line comma-separated syntactic structures. Possible values:
 - `all`, the trailing comma is always added

website/src/pages/formatter/index.mdx

@@ -39,7 +39,7 @@ USAGE:
 OPTIONS:
     --write                                  Edit the files in place (beware!) instead of printing the diff to the console
     --skip-errors                            Skip over files containing syntax errors instead of emitting an error diagnostic.
-    --indent-style <tab|space>              Change the indention character (default: tab)
+    --indent-style <tab|space>               Change the indention character (default: tab)
     --indent-size <number>                   If the indentation style is set to spaces, determine how many spaces should be used for indentation (default: 2)
     --line-width <number>                    Change how many characters the formatter is allowed to print in a single line (default: 80)
     --quote-style <single|double>            Changes the quotation character for strings (default: ")
@@ -50,69 +50,13 @@ OPTIONS:
 
 ## Ignoring Code
 
-There are times when a developer wants to keep a specific formatting.
-
-You can achieve this by adding a suppression comment right before the syntax node (expressions, statements, etc.).
-
-Suppression comments have the following format:
+There are times when the way we format code might not be ideal. For these cases you can use a format suppression comment:
 
 ```js
 // rome-ignore format: <explanation>
 ```
 
-Where
-
-- `rome-ignore` is the start of a suppression comment;
-- `format:` suppresses the formatting;
-- `<explanation>` is an explanation why the formatting is disabled;
-
-Here's an example of how a code will look like before and after the formatter does its job:
-
-Before running the formatter
-
-```js
-const expr =
-  // rome-ignore format: the array should not be formatted
-  [
-    (2 * n) / (r - l),
-    0,
-    (r + l) / (r - l),
-    0,
-    0,
-    (2 * n) / (t - b),
-    (t + b) / (t - b),
-    0,
-    0,
-    0,
-    -(f + n) / (f - n),
-    -(2 * f * n) / (f - n),
-    0,
-    0,
-    -1,
-    0,
-  ];
-
-const expr = [
-  (2 * n) / (r - l),
-  0,
-  (r + l) / (r - l),
-  0,
-  0,
-  (2 * n) / (t - b),
-  (t + b) / (t - b),
-  0,
-  0,
-  0,
-  -(f + n) / (f - n),
-  -(2 * f * n) / (f - n),
-  0,
-  0,
-  -1,
-  0,
-];
-```
-
-After running the formatter
+Example:
 
 ```js
 const expr =
@@ -135,25 +79,4 @@ const expr =
     -1,
     0,
   ];
-
-const expr = [
-  (2 * n) / (r - l),
-  0,
-  (r + l) / (r - l),
-  0,
-  0,
-  (2 * n) / (t - b),
-  (t + b) / (t - b),
-  0,
-  0,
-  0,
-  -(f + n) / (f - n),
-  -(2 * f * n) / (f - n),
-  0,
-  0,
-  -1,
-  0,
-];
 ```
-
-As you can see the first array, which has a suppression comment, is left untouched!

website/src/pages/lint/rules/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Lint Rules
+parent: linter/index
 emoji: 📏
 description: List of available lint rules.
 category: reference

website/src/pages/lint/rules/noArguments.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noArguments
+parent: lint/rules/index
 ---
 
 # noArguments (since v0.7.0)

website/src/pages/lint/rules/noArrayIndexKey.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noArrayIndexKey
+parent: lint/rules/index
 ---
 
 # noArrayIndexKey (since v0.10.0)

website/src/pages/lint/rules/noAsyncPromiseExecutor.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noAsyncPromiseExecutor
+parent: lint/rules/index
 ---
 
 # noAsyncPromiseExecutor (since v0.7.0)

website/src/pages/lint/rules/noAutofocus.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noAutofocus
+parent: lint/rules/index
 ---
 
 # noAutofocus (since v10.0.0)

website/src/pages/lint/rules/noBannedTypes.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noBannedTypes
+parent: lint/rules/index
 ---
 
 # noBannedTypes (since v10.0.0)

website/src/pages/lint/rules/noCatchAssign.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noCatchAssign
+parent: lint/rules/index
 ---
 
 # noCatchAssign (since v0.7.0)

website/src/pages/lint/rules/noChildrenProp.md

@@ -1,5 +1,6 @@
 ---
 title: Lint Rule noChildrenProp
+parent: lint/rules/index
 ---
 
 # noChildrenProp (since v0.10.0)