docs(oxfmt): update how embeddedLanguageFormatting option works (#27362)

Refine docs about `embeddedLanguageFormatting`.

apps/oxfmt/src-js/config.generated.ts

@@ -77,9 +77,16 @@ export interface Oxfmtrc {
    */
   bracketSpacing?: boolean;
   /**
-   * Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.
+   * Control whether to format embedded parts in the file.
+   * For example:
+   * - CSS-in-JS: template literal
+   * - JS-in-Vue: `<script>` block
+   * - JS-in-Markdown: code fence
+   * - YAML-in-CSS/Markdown: front matter
    *
-   * - Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
+   * With `"off"`, these parts are kept as-is.
+   *
+   * - Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
    * - Default: `"auto"`
    */
   embeddedLanguageFormatting?: EmbeddedLanguageFormattingConfig;
@@ -414,9 +421,16 @@ export interface FormatConfig {
    */
   bracketSpacing?: boolean;
   /**
-   * Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.
+   * Control whether to format embedded parts in the file.
+   * For example:
+   * - CSS-in-JS: template literal
+   * - JS-in-Vue: `<script>` block
+   * - JS-in-Markdown: code fence
+   * - YAML-in-CSS/Markdown: front matter
    *
-   * - Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
+   * With `"off"`, these parts are kept as-is.
+   *
+   * - Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
    * - Default: `"auto"`
    */
   embeddedLanguageFormatting?: EmbeddedLanguageFormattingConfig;

apps/oxfmt/src/core/oxfmtrc.rs

@@ -177,16 +177,20 @@ pub struct FormatConfig {
     #[schemars(skip)]
     pub experimental_ternaries: Option<bool>,
 
-    /// Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.
+    /// Control whether to format embedded parts in the file.
+    /// For example:
+    /// - CSS-in-JS: template literal
+    /// - JS-in-Vue: `<script>` block
+    /// - JS-in-Markdown: code fence
+    /// - YAML-in-CSS/Markdown: front matter
     ///
-    /// - Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
+    /// With `"off"`, these parts are kept as-is.
+    ///
+    /// - Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
     /// - Default: `"auto"`
     #[serde(skip_serializing_if = "Option::is_none")]
     pub embedded_language_formatting: Option<EmbeddedLanguageFormattingConfig>,
 
-    // ============================================================================================
-    // Prettier compatible options and only used by Prettier
-    // ============================================================================================
     /// How to wrap prose.
     ///
     /// By default, formatter will not change wrapping in markdown text since some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket.
@@ -197,6 +201,10 @@ pub struct FormatConfig {
     /// - Default: `"preserve"`
     #[serde(skip_serializing_if = "Option::is_none")]
     pub prose_wrap: Option<ProseWrapConfig>,
+
+    // ============================================================================================
+    // Prettier compatible options and only used by Prettier
+    // ============================================================================================
     /// Specify the global whitespace sensitivity for HTML, Vue, Angular, and Handlebars.
     ///
     /// - Languages: HTML, Angular, Vue, Handlebars, Svelte

npm/oxfmt/configuration_schema.json

@@ -24,13 +24,13 @@
       "markdownDescription": "Print spaces between brackets in object literals.\n\n- Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML\n- Default: `true`"
     },
     "embeddedLanguageFormatting": {
-      "description": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\n- Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`",
+      "description": "Control whether to format embedded parts in the file.\nFor example:\n- CSS-in-JS: template literal\n- JS-in-Vue: `<script>` block\n- JS-in-Markdown: code fence\n- YAML-in-CSS/Markdown: front matter\n\nWith `\"off\"`, these parts are kept as-is.\n\n- Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`",
       "allOf": [
         {
           "$ref": "#/definitions/EmbeddedLanguageFormattingConfig"
         }
       ],
-      "markdownDescription": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\n- Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`"
+      "markdownDescription": "Control whether to format embedded parts in the file.\nFor example:\n- CSS-in-JS: template literal\n- JS-in-Vue: `<script>` block\n- JS-in-Markdown: code fence\n- YAML-in-CSS/Markdown: front matter\n\nWith `\"off\"`, these parts are kept as-is.\n\n- Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`"
     },
     "endOfLine": {
       "description": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Languages: All\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`",
@@ -299,13 +299,13 @@
           "markdownDescription": "Print spaces between brackets in object literals.\n\n- Languages: JS, JSX, TS, TSX, JSON, JSONC, JSON5, GraphQL, YAML\n- Default: `true`"
         },
         "embeddedLanguageFormatting": {
-          "description": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\n- Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`",
+          "description": "Control whether to format embedded parts in the file.\nFor example:\n- CSS-in-JS: template literal\n- JS-in-Vue: `<script>` block\n- JS-in-Markdown: code fence\n- YAML-in-CSS/Markdown: front matter\n\nWith `\"off\"`, these parts are kept as-is.\n\n- Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`",
           "allOf": [
             {
               "$ref": "#/definitions/EmbeddedLanguageFormattingConfig"
             }
           ],
-          "markdownDescription": "Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.\n\n- Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`"
+          "markdownDescription": "Control whether to format embedded parts in the file.\nFor example:\n- CSS-in-JS: template literal\n- JS-in-Vue: `<script>` block\n- JS-in-Markdown: code fence\n- YAML-in-CSS/Markdown: front matter\n\nWith `\"off\"`, these parts are kept as-is.\n\n- Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)\n- Default: `\"auto\"`"
         },
         "endOfLine": {
           "description": "Which end of line characters to apply.\n\nNOTE: `\"auto\"` is not supported.\n\n- Languages: All\n- Default: `\"lf\"`\n- Overrides `.editorconfig.end_of_line`",

tasks/website_formatter/src/snapshots/schema_markdown.snap

@@ -51,9 +51,16 @@ Print spaces between brackets in object literals.
 type: `"auto" | "off"`
 
 
-Control whether to format embedded parts (For example, CSS-in-JS, or JS-in-Vue, etc.) in the file.
+Control whether to format embedded parts in the file.
+For example:
+- CSS-in-JS: template literal
+- JS-in-Vue: `<script>` block
+- JS-in-Markdown: code fence
+- YAML-in-CSS/Markdown: front matter
 
-- Languages: JS, JSX, TS, TSX, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
+With `"off"`, these parts are kept as-is.
+
+- Languages: JS, JSX, TS, TSX, CSS, SCSS, Less, HTML, Vue, Angular, Svelte, Markdown, MDX (languages with embedded code)
 - Default: `"auto"`