docs: update docs for parser

Author: skovy

README.md

@@ -72,6 +72,10 @@ export const transform: Transform = (fileInfo, api) => {
   // Implement the transform.
   // See below for more details on the API.
 };
+
+// Optionally defined a named `parser` export to configure the PostCSS parser.
+//   Docs: https://postcss.org/api/#parser
+// export const parser = ...;
 ```
 
 ## API
@@ -107,6 +111,7 @@ It's an object with helpers provided by `css-codemod` to perform transformations
 // transform.ts
 
 import { Transform } from 'css-codemod';
+import { parse, stringify } from 'postcss-scss';
 
 export const transform: Transform = (fileInfo, api) => {
   // Convert the file source into an AST using the provided helper.
@@ -129,8 +134,16 @@ export const transform: Transform = (fileInfo, api) => {
 
   // Convert the mutated AST back into a string.
   // Since a string is returned this will be written back to the file.
-  return root.toString();
+  // Note: in this example the `postcss-scss` package is used to add
+  // SCSS syntax support. The stringifier is passed when we call `toString` to
+  // re-output valid SCSS syntax.
+  return root.toString(stringify);
 };
+
+// Note: in this example the `postcss-scss` package is used to add SCSS syntax support.
+// This configures PostCSS to correctly parse SCSS syntax.
+//   Docs: https://postcss.org/api/#parser
+export const parser = parse;
 ```
 
 ### PostCSS

recipes/rename-scss-variable/input/a.scss

@@ -17,4 +17,4 @@
 
 ul {
   @include horizontal-list;
-}
+}

recipes/rename-scss-variable/output/a.scss

@@ -17,4 +17,4 @@
 
 ul {
   @include horizontal-list;
-}
+}

src/api.ts

@@ -13,7 +13,7 @@ const createAPIParse = ({
 }): TransformAPI['parse'] => {
   const parse: TransformAPI['parse'] = source => {
     const result = postcss().process(source, {
-      // Silence a warning about sourcemaps. Not relevant to this use case.
+      // Silence warning about sourcemaps. Not relevant to this use case.
       from: undefined,
       parser,
     });
@@ -22,7 +22,7 @@ const createAPIParse = ({
     // if one occurs. The error field can then be checked.
     const { root } = result;
 
-    // Re-surface an PostCSS parsing errors.
+    // Re-surface any PostCSS parsing errors.
     // https://github.com/postcss/postcss/issues/1708
     if ((result as any).error) {
       throw (result as any).error;