Better text

Author: mb21

README.md

@@ -1,5 +1,7 @@
 # The Mastro Guide 👨‍🍳
 
+Repo for https://mastrojs.github.io
+
 Because of the syntax highlighting and other niceties that are already built in, we're currently using [Starlight](https://starlight.astro.build) for this website.
 
 Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.

src/content/docs/guides/javascript.md

@@ -8,12 +8,16 @@ Now that you got a taste of HTML and CSS, let's talk about JavaScript. It's the
 
 ## Client-side and server-side JavaScript
 
-Inside the browser, JavaScript is best used sparingly to add interactivy to a page. Although unfortunately, some websites load millions of lines of JavaScript into the browser. Since a browser is also known as a _client_, this is known as client-side JavaScript. In fact, client-side JavaScript frameworks like React compute the whole page in the browser of your user every time they load the page. This may be required for an app like Google Docs or Visual Studio Code. But for most websites, it just makes everything slow for no good reason – especially on mobile phones, with their limited computing power and slow networks.
+Inside the browser, JavaScript is best used sparingly to add interactivy to a page. Although unfortunately, some websites load millions of lines of JavaScript into the browser. Since a browser is also known as a _client_, this is known as client-side JavaScript. In fact, client-side JavaScript frameworks like React compute the whole page in the browser of your user every time they load the page. This may be required for an app like Google Docs or Visual Studio Code. But for most websites, it just makes everything slow for little reason – especially on mobile phones, with their limited computing power and slow networks.
+
+A lot of these "websites" even go so far as to take control of loading the next page away from the browser, and reimplement the functionality in JavaScript. This approach is called a Single-Page-App (SPA), and just recently [peaked in popularity](https://nolanlawson.com/2022/05/21/the-balance-has-shifted-away-from-spas/). Nowadays, you can get equally smooth page transitions by adding [two lines of CSS](https://webkit.org/blog/16967/two-lines-of-cross-document-view-transitions-code-you-can-use-on-every-website-today/) to your MPA (Multi-Page-App).
 
 However, JavaScript is a general-purpose programming language like any other. Nowadays, you can run JavaScript also on your server or laptop, generate the HTML there, and only send that to your user's browser – just like people have done with PHP or Ruby for ages. This is known as server-side JavaScript and it's what we'll be doing primarily in this guide.
 
 
-## Introducing JavaScript
+## Getting your feet wet with JavaScript
+
+However, one of the easiest way to mess around with JavaScript is still your browser.
 
 On your published website, open your [browser's developer tools](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools#how_to_open_the_devtools_in_your_browser) again. But this time, switch to the tab named **Console**.
 

src/content/docs/guides/multiple-pages-with-shared-components.md

@@ -58,6 +58,8 @@ Now, to `import` the two functions we just created, you first need to convert th
 
 ### JavaScript page handlers
 
+All files in the `routes/` folder are sent out unmodified to your website's visitors – except for JavaScript files ending in `.server.js` or `.server.ts`. The code in these files is run and the result is sent to your website's visitors.
+
 Rename the `routes/index.html` file to `routes/index.server.js` and change its contents to:
 
 ```js title=routes/index.server.js ins={1-8,15,22,25}

src/content/docs/guides/rest.md

@@ -3,9 +3,6 @@ title: Rest
 template: splash
 ---
 
-All files in the `routes/` folder are sent out unmodified to your website's visitors – except for JavaScript files ending in `.server.js` or `.server.ts`. The code in these files is run and the result is sent to your website's visitors.
-
-
 ## Images
 
 Now that you have your basic blog up and running on a live website, let's add some images.

src/content/docs/guides/static-blog-from-markdown-files.md

@@ -79,9 +79,11 @@ export const GET = async () => {
 };
 ```
 
-Note the use of the `readMarkdownFiles` function that we imported from mastro. Because it requests the files from the computer's harddisk (which is potentially something we need to wait for), we need to `await` it. This in turn forces us to mark up our `GET` function as `async`.
+Note the `../../` when importing the `Layout` component, while previously it was just `../`. That's because this file is in the `news/` folder, so you need to go one level further up than before to get to the `components/` folder.
 
-The `.slice(11, -3)` cuts off the first eleven and the last three character from the string: in our case it removes the leading `/data/posts` and the trailing `.md` from the filename.
+The code imports the `readMarkdownFiles` function from mastro. Because that function requests the files from the computer's harddisk (which might take some time), we need to `await` it. This in turn forces us to mark up our `GET` function as `async` (short for [asynchronous](https://eloquentjavascript.net/11_async.html)).
+
+The `.slice(11, -3)` [slices](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) off the first eleven and the last three character from the string: in our case it removes the leading `/data/posts` and the trailing `.md` from the filename.
 
 Have a look at `/news` in the Mastro preview pane. Clicking one of the links will lead you to a page saying "404, page not found". That's because those pages don't exist yet.
 
@@ -116,8 +118,31 @@ To read the markdown file from disk and convert the markdown to HTML, we use the
 
 Test following the links in the Mastro preview pane now. Congratulations, you have a working blog!
 
+## Debugging with `console.log`
+
+Usually when programming, thinks go wrong at some point. It's fairly uncommon for a programmer to write out a program and get exactly what they wanted the first time they run it. Perhaps you get a syntax error and the program doesn't even start running. Or perhaps the JavaScript syntax was correct, but the program crashes later on, or at least doesn't do what you wanted it to. In this second case, it can be useful to add `console.log` statements in various places of your code and see what it prints into your browser's JavaScript console (what you used in a [previous chapter](/guides/javascript/#getting-your-feet-wet-with-javascript)). Give it a try:
+
+```js title=routes/news/[slug].server.js ins={6}
+import { getParams, htmlToResponse, readMarkdownFile } from "mastro";
+import { Layout } from "../../components/Layout.js";
+
+export const GET = async (req) => {
+  const { slug } = getParams(req.url);
+  console.log('the slug variable holds the value', slug)
+  const post = await readMarkdownFile(`data/posts/${slug}.md`);
+  return htmlToResponse(
+    Layout({
+      title: post.meta.title,
+      children: post.content,
+    })
+  );
+}
+```
+
+After opening your browser's JavaScript console and clearing what's already printed out there with the button labelled `🚫`, open the page in the Mastro preview pane.
+
 
-## Generating the route parameters
+## Generating pages with route parameters
 
 Try generating all your HTML files: click the **Generate** button in the top-right corner of the Mastro preview pane.