Title: "docs: Fix MDX formatting and improve readability"

fern/products/docs/pages/getting-started/how-it-works.mdx

@@ -8,77 +8,77 @@ Fern combines your API specifications, static Markdown files (like how-to guides
 This process is built around two major workflows: **editing** and **deploying** your documentation.
 
 <Accordion title="System architecture">
-
-This diagram shows the technical infrastructure that powers the documentation generation process.
-
-```mermaid
-flowchart TD
-    %% Input sources at the top
-    subgraph inputs ["Input Sources"]
-        API["API Specs"]
-        DOCS["Docs.yml"]
-        MDX["MDX files"]
-        MEDIA["Media content"]
-    end
-
-    %% Generation process
-    GENERATE[["fern generate<br/>--docs"]]
-
-    %% AWS VPC section
-    subgraph vpc ["Fern AWS VPC"]
-        direction LR
-        MICROSERVICE["Fern Docs<br/>microservice"]
-        DATABASE[("Database")]
-        S3[("S3")]
-    end
-
-    %% External services
-    SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]
-
-    %% Vercel hosting
-    subgraph vercel ["Vercel"]
-        direction LR
-        STATIC["Static site"]
-        EXPLORER["API explorer"]
-        EDGE["Vercel Edge<br/>(Middleware)"]
-    end
-
-    %% External connections as hexagons
-    CLOUDFLARE{{"Cloudflare (CORS)"}}
-    WORKOS{{"WorkOS"}}
-    CUSTOMER{{"Customer API"}}
-
-    USER(("User"))
-
-    %% Vertical flow connections
-    API --> GENERATE
-    DOCS --> GENERATE
-    MDX --> GENERATE
-    MEDIA --> GENERATE
-
-    GENERATE --> MICROSERVICE
-    MICROSERVICE --> SERVICES
-    SERVICES <--> STATIC
-
-    STATIC --> CLOUDFLARE
-    EXPLORER <--> CLOUDFLARE
-    EDGE <--> WORKOS
-
-    CLOUDFLARE --> CUSTOMER
-    EDGE <--> USER
-
-    %% Internal connections
-    MICROSERVICE -.-> DATABASE
-    MICROSERVICE -.-> S3
-```
+  This diagram shows the technical infrastructure that powers the documentation generation process.
+
+  ```mermaid
+  flowchart TD
+      %% Input sources at the top
+      subgraph inputs ["Input Sources"]
+          API["API Specs"]
+          DOCS["Docs.yml"]
+          MDX["MDX files"]
+          MEDIA["Media content"]
+      end
+
+      %% Generation process
+      GENERATE[["fern generate<br/>--docs"]]
+
+      %% AWS VPC section
+      subgraph vpc ["Fern AWS VPC"]
+          direction LR
+          MICROSERVICE["Fern Docs<br/>microservice"]
+          DATABASE[("Database")]
+          S3[("S3")]
+      end
+
+      %% External services
+      SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]
+
+      %% Vercel hosting
+      subgraph vercel ["Vercel"]
+          direction LR
+          STATIC["Static site"]
+          EXPLORER["API explorer"]
+          EDGE["Vercel Edge<br/>(Middleware)"]
+      end
+
+      %% External connections as hexagons
+      CLOUDFLARE{{"Cloudflare (CORS)"}}
+      WORKOS{{"WorkOS"}}
+      CUSTOMER{{"Customer API"}}
+
+      USER(("User"))
+
+      %% Vertical flow connections
+      API --> GENERATE
+      DOCS --> GENERATE
+      MDX --> GENERATE
+      MEDIA --> GENERATE
+
+      GENERATE --> MICROSERVICE
+      MICROSERVICE --> SERVICES
+      SERVICES <--> STATIC
+
+      STATIC --> CLOUDFLARE
+      EXPLORER <--> CLOUDFLARE
+      EDGE <--> WORKOS
+
+      CLOUDFLARE --> CUSTOMER
+      EDGE <--> USER
+
+      %% Internal connections
+      MICROSERVICE -.-> DATABASE
+      MICROSERVICE -.-> S3
+  ```
 </Accordion>
 
+
 ## Content workflows
 
 You can update your documentation in two ways:
 
-- **Direct editing**: Open a pull request directly in the [GitHub repository that contains your docs](/learn/docs/getting-started/project-structure) (including your `docs.yml` configuration and Markdown files). 
-- **Fern Editor**: Use the [Fern Editor](/learn/docs/writing-content/fern-editor) to modify your docs without touching code. The Fern GitHub App fetches the current state from your docs repository and passes it to the Fern Editor. When you submit changes, the Fern GitHub App automatically opens a pull request for review. 
+- **Direct editing**: Open a pull request directly in the [GitHub repository that contains your docs](/learn/docs/getting-started/project-structure) (including your `docs.yml` configuration and Markdown files).
+- **Fern Editor**: Use the [Fern Editor](/learn/docs/writing-content/fern-editor) to modify your docs without touching code. The Fern GitHub App fetches the current state from your docs repository and passes it to the Fern Editor. When you submit changes, the Fern GitHub App automatically opens a pull request for review.
 
 After the update goes through your review process, an approver can merge it. 
 
@@ -111,29 +111,29 @@ The deployed documentation site integrates with external systems like Cloudflare
 </Steps>
 
 <Accordion title="Editing and deployment workflows">
-
-This diagram shows how content flows from editing to deployment.
-
-```mermaid
-flowchart TD
-    FE[Fern Editor]
-    U[User]
-    DR[Docs Repo]
-    CLI[Fern CLI]
-    Decision{Make a PR or edit in Fern Editor?}
-    Spec((API Spec Repo))
-    GA[GitHub Actions]
-
-    U ==> Decision
-    Decision == Make edit ==> FE
-    Decision == Open and Merge PR ==> DR
-
-    FE <== Fetches state and opens PR ==> DR
-    DR == ① Merged PR triggers deployment flow ==> GA
-
-    Spec <-. ② Fetches and merges API spec .-> GA
-
-    GA == ③ Triggers doc regeneration ==> CLI
-    CLI == ④ Deploys updated docs ==> Server[Fern Docs Server]
-```
+  This diagram shows how content flows from editing to deployment.
+
+  ```mermaid
+  flowchart TD
+      FE[Fern Editor]
+      U[User]
+      DR[Docs Repo]
+      CLI[Fern CLI]
+      Decision{Make a PR or edit in Fern Editor?}
+      Spec((API Spec Repo))
+      GA[GitHub Actions]
+
+      U ==> Decision
+      Decision == Make edit ==> FE
+      Decision == Open and Merge PR ==> DR
+
+      FE <== Fetches state and opens PR ==> DR
+      DR == ① Merged PR triggers deployment flow ==> GA
+
+      Spec <-. ② Fetches and merges API spec .-> GA
+
+      GA == ③ Triggers doc regeneration ==> CLI
+      CLI == ④ Deploys updated docs ==> Server[Fern Docs Server]
+  ```
 </Accordion>
+

fern/products/docs/pages/getting-started/project-structure.mdx

@@ -166,11 +166,11 @@ title: Fern's Documentation
 </AccordionGroup>
 
 <Note>
-  If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation.  
+  If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation.
 
   If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec:
 
-  ```yaml title="generators.yml"
+  ```yaml
   api:
     specs:
       - openapi: ../openapi/openapi.json
@@ -189,6 +189,4 @@ The `fern.config.json` file specifies your organization name and the version of
   "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
 }
 ```
-</CodeBlock> 
-
-
+</CodeBlock>