Automatically create JS versions of our TS code in the docs

web/README.md

@@ -23,6 +23,97 @@ $ npm start
 This command starts a local development server and opens up a browser window.
 Most changes are reflected live without having to restart the server.
 
+### Writing docs
+
+To write docs, you can use Markdown or MDX. The docs are located in the `docs` directory.
+Remember to refer to the [Writing Guide](https://wasp.sh/docs/writingguide) for an explanation
+of how we like to write docs. You can check
+[Docusaurus' documentation](https://docusaurus.io/docs/2.x/markdown-features) to see which special
+Markdown features available (e.g. line highlighting).
+
+#### Polyglot code blocks
+
+For examples that have a JavaScript and TypeScript version, add a `auto-js` meta attribute
+to the code block, like so:
+
+~~~mdx
+```ts title="src/apis.ts" auto-js
+export const validatePassword = (password: string) => password.length > 8;
+```
+~~~
+
+And it will automatically generate a JS and TS version with a selector to switch between them:
+
+~~~mdx
+<Tabs groupId="js-ts">
+<TabItem value="js" label="JavaScript">
+
+```js title="src/apis.js"
+export const validatePassword = (password) => password.length > 8;
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+```ts title="src/apis.ts"
+export const validatePassword = (password: string) => password.length > 8;
+```
+
+</TabItem>
+</Tabs>
+~~~
+
+> [!NOTE]
+> You can create a language switcher manually as described in
+> [Docusaurus docs](https://docusaurus.io/docs/2.x/markdown-features/code-blocks#multi-language-support-code-blocks).
+
+If you need to omit some part of the code in a code example, you can use the `with-hole` meta attribute
+which will add an ellipsis wherever you write the identifier `hole` in the code block, so you can keep
+it syntactically valid. You can combine it with the `auto-js` tag.
+
+For example, the following input:
+
+~~~mdx
+```ts title="src/apis.ts" auto-js with-hole
+export const validatePassword = (password: string) => password.length > 8 && hole;
+```
+~~~
+
+Will be transformed to:
+
+~~~mdx
+<Tabs groupId="js-ts">
+<TabItem value="js" label="JavaScript">
+
+```js title="src/apis.js"
+export const validatePassword = (password) => password.length > 8 && ...;
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+```ts title="src/apis.ts"
+export const validatePassword = (password: string) => password.length > 8 && /* ... */;
+```
+
+</TabItem>
+</Tabs>
+
+##### Caveats
+
+The `auto-js` and `with-hole` meta attributes are custom Docusaurus plugins that we wrote, implemented at
+[./src/remark/auto-js-code.ts](./src/remark/auto-js-code.ts) and [./src/remark/code-with-hole.ts](./src/remark/code-with-hole.ts).
+
+`auto-js` specifically is backed by [ts-blank-space](https://github.com/bloomberg/ts-blank-space), which will _only_ remove the
+type annotations and not process anything else. Thus, some edge-cases can arise, so we recommend to run `npm run start` and
+check the output JS in the browser to see if everything looks good.
+
+Known caveats are:
+- Run `prettier` on the code before pasting it in the document, as `auto-js` will enforce it.
+- Remember to add a `type` specifier to `import`s we don't want to appear in the JS
+- `// highlight-next-line` comment before a TS-only line will hang around and highlight the wrong line. Use `// highlight-start` and `// highlight-end` instead.
+- It doesn't replace file names' extensions in clarification comments (this is mostly unique to the tutorial pages).
+
 ### Build
 
 ```
@@ -56,14 +147,14 @@ We deploy the website to Cloudflare Pages. When you want to deploy changes from
    git checkout release
    ```
 
-The website should be live within a few minutes at https://wasp.sh. 
+The website should be live within a few minutes at https://wasp.sh.
 
 You can track the deployment progress on Cloudflare Pages (https://dash.cloudflare.com/). Credentials are in the 1Password vault.
 
 ### Preview docs from the `main` branch
 
 We set up automatic deployment of docs from the `main` branch on Cloudflare Pages. This means that every time you push to the `main` branch, the docs will be built and deployed to https://wasp-docs-on-main.pages.dev.
- 
+
 ### Multiple documentation versions
 
 We maintain docs for multiple versions of Wasp.

web/docs/advanced/apis.md

@@ -128,47 +128,23 @@ For example, if your app is running at `https://example.com` then from the above
 
 To use the API from your client, including with auth support, you can import the Axios wrapper from `wasp/client/api` and invoke a call. For example:
 
-<Tabs groupId="js-ts">
-  <TabItem value="js" label="JavaScript">
-    ```jsx title="src/pages/SomePage.jsx"
-    import React, { useEffect } from "react";
-    import { api } from "wasp/client/api";
-
-    async function fetchCustomRoute() {
-      const res = await api.get("/foo/bar");
-      console.log(res.data);
-    }
-
-    export const Foo = () => {
-      useEffect(() => {
-        fetchCustomRoute();
-      }, []);
-
-      return <>// ...</>;
-    };
-    ```
-  </TabItem>
-
-  <TabItem value="ts" label="TypeScript">
-    ```tsx title="src/pages/SomePage.tsx"
-    import React, { useEffect } from "react";
-    import { api } from "wasp/client/api";
-
-    async function fetchCustomRoute() {
-      const res = await api.get("/foo/bar");
-      console.log(res.data);
-    }
-
-    export const Foo = () => {
-      useEffect(() => {
-        fetchCustomRoute();
-      }, []);
-
-      return <>// ...</>;
-    };
-    ```
-  </TabItem>
-</Tabs>
+```tsx title="src/pages/SomePage.tsx" auto-js with-hole
+import React, { useEffect } from "react";
+import { api } from "wasp/client/api";
+
+async function fetchCustomRoute() {
+  const res = await api.get("/foo/bar");
+  console.log(res.data);
+}
+
+export const Foo = () => {
+  useEffect(() => {
+    fetchCustomRoute();
+  }, []);
+
+  return <>{hole}</>;
+};
+```
 
 #### Making Sure CORS Works
 

web/docs/auth/social-auth/google.md

@@ -2,6 +2,7 @@
 title: Google
 ---
 
+import { ShowForTs } from '@site/src/components/TsJsHelpers'
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DefaultBehaviour from './\_default-behaviour.md';
 import OverrideIntro from './\_override-intro.md';
@@ -379,103 +380,53 @@ The fields you receive depend on the scopes you request. The default scope is se
 
 <OverrideExampleIntro />
 
-<Tabs groupId="js-ts">
-  <TabItem value="js" label="JavaScript">
-    ```wasp title="main.wasp"
-    app myApp {
-      wasp: {
-        version: "{latestWaspVersion}"
-      },
-      title: "My App",
-      auth: {
-        userEntity: User,
-        methods: {
-          google: {
-            // highlight-next-line
-            configFn: import { getConfig } from "@src/auth/google.js",
-            // highlight-next-line
-            userSignupFields: import { userSignupFields } from "@src/auth/google.js"
-          }
-        },
-        onAuthFailedRedirectTo: "/login"
-      },
-    }
-    ```
-
-    ```prisma title="schema.prisma"
-    model User {
-      id          Int    @id @default(autoincrement())
-      username    String @unique
-      displayName String
-    }
-
-    // ...
-    ```
-
-    ```js title=src/auth/google.js
-    export const userSignupFields = {
-      username: () => 'hardcoded-username',
-      displayName: (data) => data.profile.name,
-    }
-
-    export function getConfig() {
-      return {
-        scopes: ['profile', 'email'],
+```wasp title="main.wasp"
+app myApp {
+  wasp: {
+    version: "{latestWaspVersion}"
+  },
+  title: "My App",
+  auth: {
+    userEntity: User,
+    methods: {
+      google: {
+        // highlight-next-line
+        configFn: import { getConfig } from "@src/auth/google.js",
+        // highlight-next-line
+        userSignupFields: import { userSignupFields } from "@src/auth/google.js"
       }
-    }
-    ```
-  </TabItem>
-
-  <TabItem value="ts" label="TypeScript">
-    ```wasp title="main.wasp"
-    app myApp {
-      wasp: {
-        version: "{latestWaspVersion}"
-      },
-      title: "My App",
-      auth: {
-        userEntity: User,
-        methods: {
-          google: {
-            // highlight-next-line
-            configFn: import { getConfig } from "@src/auth/google.js",
-            // highlight-next-line
-            userSignupFields: import { userSignupFields } from "@src/auth/google.js"
-          }
-        },
-        onAuthFailedRedirectTo: "/login"
-      },
-    }
-    ```
+    },
+    onAuthFailedRedirectTo: "/login"
+  },
+}
+```
 
-    ```prisma title="schema.prisma"
-    model User {
-      id          Int    @id @default(autoincrement())
-      username    String @unique
-      displayName String
-    }
+```prisma title="schema.prisma"
+model User {
+  id          Int    @id @default(autoincrement())
+  username    String @unique
+  displayName String
+}
 
-    // ...
-    ```
+// ...
+```
 
-    ```ts title=src/auth/google.ts
-    import { defineUserSignupFields } from 'wasp/server/auth'
+```ts title=src/auth/google.ts auto-js
+import { defineUserSignupFields } from 'wasp/server/auth'
 
-    export const userSignupFields = defineUserSignupFields({
-      username: () => 'hardcoded-username',
-      displayName: (data: any) => data.profile.name,
-    })
+export const userSignupFields = defineUserSignupFields({
+  username: () => 'hardcoded-username',
+  displayName: (data: any) => data.profile.name,
+})
 
-    export function getConfig() {
-      return {
-        scopes: ['profile', 'email'],
-      }
-    }
-    ```
+export function getConfig() {
+  return {
+    scopes: ['profile', 'email'],
+  }
+}
+```
 
-    <GetUserFieldsType />
-  </TabItem>
-</Tabs>
+<ShowForTs><GetUserFieldsType /></ShowForTs>
 
 ## Using Auth
 

web/docusaurus.config.ts

@@ -2,6 +2,8 @@ import type * as Preset from '@docusaurus/preset-classic'
 import type { Config, DocusaurusConfig } from '@docusaurus/types'
 import { themes } from 'prism-react-renderer'
 import autoImportTabs from './src/remark/auto-import-tabs'
+import autoJSCode from './src/remark/auto-js-code'
+import codeWithHole from './src/remark/code-with-hole'
 import fileExtSwitcher from './src/remark/file-ext-switcher'
 import searchAndReplace from './src/remark/search-and-replace'
 
@@ -157,7 +159,13 @@ const config: Config = {
           sidebarPath: './sidebars.ts',
           sidebarCollapsible: true,
           editUrl: 'https://github.com/wasp-lang/wasp/edit/release/web',
-          remarkPlugins: [autoImportTabs, fileExtSwitcher, searchAndReplace],
+          remarkPlugins: [
+            autoJSCode,
+            autoImportTabs,
+            fileExtSwitcher,
+            searchAndReplace,
+            codeWithHole,
+          ],
 
           // ------ Configuration for multiple docs versions ------ //