Apply suggestions from code review

Co-authored-by: Cole Peters <[email protected]>

app/docs/md/patterns/rendering-markdown.md

@@ -4,11 +4,11 @@ links:
   - "Arcdown": https://github.com/architect/arcdown/blob/main/readme.md
 ---
 
-A frequent question is, *“Can I render Markdown files with Enhance?”* and the answer is, *“of course!”*  [This site](https://enhance.dev/docs/) is an Enhance app which renders markdown on demand. You can always dig into the [source code](https://github.com/enhance-dev/enhance.dev) to see exactly how we've set it up, but I thought I'd review some of the high points.
+Enhance can be used to render Markdown with minimal effort — in fact, this very site is itself an Enhance app that renders Markdown to HTML on demand. You can dig into the [source code](https://github.com/enhance-dev/enhance.dev) to see exactly how we've set it up, or follow along below.
 
 ## Arcdown
 
-Enhance does not natively support rendering markdown into HTML, which is out of scope for the project. Instead, we rely on [markdown-it](https://markdown-it.github.io/), an excellent JavaScript markdown parser that is endlessly configurable with plugins. As we use markdown in many different projects, we've created a node module called, [Arcdown](https://github.com/architect/arcdown), which packages together our preferred conventions for parsing markdown files.
+When rendering Markdown to HTML in Enhance projects, we rely on [Arcdown](https://github.com/architect/arcdown), which packages together our preferred conventions for parsing Markdown files. Under the hood, Arcdown makes use of [markdown-it](https://markdown-it.github.io/), an excellent JavaScript Markdown parser that is highly configurable via a wealth of plugins.
 
 Here's a quick example of parsing a markdown string with Arcdown:
 
@@ -36,19 +36,19 @@ The result of the render returns an object with the following properties:
 
 Property | Description
 -: | :-
-`html` | The Markdown document contents as HTML
-`tocHtml` | The document's table of contents as HTML (nested unordered lists).
+`html` | The Markdown document content, converted to HTML
+`tocHtml` | The document's table of contents, converted to HTML
 `title` | The document title, lifted from the document's frontmatter.
-`slug` | A URL-friendly slug of the title. (possibly empty) Synonymous with links in the table of contents.
-`frontmatter` | An object containing all remaining frontmatter. (possibly empty)
+`slug` | A URL-friendly slug of the title (possibly empty). Synonymous with links in the table of contents.
+`frontmatter` | An object containing all remaining frontmatter (possibly empty)
 
-Arcdown follows along the convention of markdown-it as being infinitely configurable. For example, you can always disable functionality if you don't need things like a table of contents or syntax highlighting.
+Arcdown follows the convention of markdown-it as being highly configurable. For example, you can always disable functionality if you don't need things like a table of contents or syntax highlighting.
 
 > For more information on configuring Arcdown see [Configuration](https://github.com/architect/arcdown#configuration)
 
-## Parsing markdown in an API route
+## Parsing Markdown in an API route
 
-When parsing markdown, we'll want to do it in an API route and then pass the result to our page route as part of the store. Let's assume you have a new Enhance project like this:
+In Enhance apps, Markdown parsing is optimally performed as part an API route. After parsing, we can then pass the result to our page route as part of [the store](/docs/elements/state/store). Let's assume you have a new Enhance project, structured like this:
 
 ```
 app
@@ -58,7 +58,7 @@ app
     └── index.html
 ```
 
-Now we want to be able to parse the `app/markdown/example.md` file. In order to do that we'll need an API route so you can manually create a new folder called `app/api/markdown` and add a catch-all API route named `app/api/markdown/$$.mjs`, or you can run the Enhance CLI command:
+Now we want to be able to parse the `app/markdown/example.md` file. In order to do that, we'll first need an API route. Create a new folder called `app/api/markdown` and add a catch-all API route named `app/api/markdown/$$.mjs`. Alternatively, you can run the Enhance CLI command:
 
 ```bash
 enhance gen api --path 'markdown/$$'
@@ -88,7 +88,7 @@ import { Arcdown } from 'arcdown'
 const arcdown = new Arcdown()
 ```
 
-Then in our `get` function we'll need to figure out which file the user has requested. To do that we'll determine the document path from the incoming request.
+Next, in our API route's `get` function, we'll need to figure out which file the user has requested. To do that, we'll determine the document path from the incoming request:
 
 ```javascript
  const { path: activePath } = req
@@ -98,14 +98,14 @@ Then in our `get` function we'll need to figure out which file the user has requ
  }
 ```
 
-Next we'll use the `docPath` to read our markdown file from the `app/markdown` folder.
+Next, we'll use the `docPath` to read our Markdown file from the `app/markdown` folder:
 
 ```javascript
  const docURL = new URL(`../../${docPath}.md`, import.meta.url)
  const docMarkdown = readFileSync(docURL.pathname, 'utf-8')
 ```
 
-Once we have the markdown string, we can transform it into HTML using Arcdown and add it to the `store`.
+Once we have the Markdown string, we can transform it into HTML using Arcdown and add it to the `store`:
 
 ```javascript
  const doc = await arcdown.render(docMarkdown)
@@ -146,11 +146,11 @@ export async function get (req) {
 
 </doc-code>
 
-> **Note:** I'm omitting a lot of error checking for the sake of brevity but check out this [hardened example](https://github.com/enhance-dev/enhance.dev/blob/main/app/api/docs/%24%24.mjs) for more details on how to handle 404's.
+> **Note:** We’re omitting a lot of error checking for the sake of brevity, but check out this [hardened example](https://github.com/enhance-dev/enhance.dev/blob/main/app/api/docs/%24%24.mjs) for more details on how to handle 404s.
 
-## Displaying markdown
+## Displaying Markdown
 
-Now that we have successfully transformed our markdown into HTML let's go about displaying it in a page. First, we'll create a new catch-all page under `app/pages/markdown/$$.html` and a new web component to display the markdown at `app/elements/doc-content.mjs` which you can do manually or by running the Begin CLI commands:
+Now that we've successfully transformed our Markdown into HTML, let's go about displaying it in a page. First, we'll create a new catch-all page under `app/pages/markdown/$$.html`, and a new web component to display the Markdown at `app/elements/doc-content.mjs`. You can create these files manually, or by running the Enhance CLI commands:
 
 ```bash
 enhance gen page --path 'markdown/$$'
@@ -174,7 +174,7 @@ app
     └── index.html
 ```
 
-Our `app/pages/markdown/$$.html` file will look really simple as we will just hand everything over to our web component to handle. Feel free to make this page more advanced by adding headers, footers, etc. as required by your design.
+For the purposes of this example, we'll keep our `app/pages/markdown/$$.html` simple by including only the web component we just created:
 
 <doc-code filename="app/pages/markdown/$$.html">
 
@@ -184,7 +184,7 @@ Our `app/pages/markdown/$$.html` file will look really simple as we will just ha
 
 </doc-code>
 
-Over in `app/elements/doc-content.mjs` we will read the result of the transformation off the `store`. Then we'll return the rendered content to be displayed on our page:
+In the web component we just created, we'll read the result of the transformation off the `store`. Then we'll return the rendered content to be displayed on our page:
 
 <doc-code filename="app/elements/doc-content.mjs">