Update guide and remove docs/ instructions

Author: mb21

data/guide/client-side-vs-server-side-javascript-static-vs-ondemand-spa-vs-mpa.md

@@ -34,7 +34,7 @@ We'll only be using server-side JavaScript in the next couple of chapters of thi
 
 ## Static site generation vs running a server
 
-In the first half of this guide, we'll be using Mastro as a _static site generator_ – i.e. running the JavaScript ahead of time, to pregenerate all pages of the website. This means the website will be very fast, and doesn't require you to run a server, which you might have to harden against load spikes or attacks.
+In the first half of this guide, we'll be using Mastro as a _static site generator_ – i.e. running the JavaScript ahead of time, to pregenerate all pages of the website. This means the website will be very fast, and doesn't require you to run a server, which you might have to harden against load spikes or attacks. Unless you have specific requirements, this is the best way to run a modern website.
 
 In later chapters of this guide, we'll use Mastro as a _web server_, which will run the JavaScript to generate a page each time a user visits the page. (Some people call this _server-side rendering_ or _SSR_.) While more complex to operate, running a server gives you the ability to return a potentially different page each time it is visited.
 

data/guide/css.md

@@ -16,9 +16,11 @@ Add the following line to link a CSS file to your page:
   ...
 ```
 
-And create the corresponding CSS style sheet file in the `routes` folder. (You could choose another name, but `styles.css` is fairly common.)
+If it doesn't exist yet, create the file `routes/styles.css`. (You could choose another name, but `styles.css` is fairly common.)
 
-Since `/styles.css` starts with a slash, it is an absolute path. Because your `index.html` is in the same folder, the relative path `href="styles.css"` or `href="./styles.css"` would have worked here as well.
+Since the path in `href="/styles.css"` starts with a slash, it is an absolute path. Because your `index.html` is in the same folder, the relative path `href="styles.css"` or `href="./styles.css"` would have worked here as well.
+
+Replace whatever is currently in `routes/styles.css` with the following CSS:
 
 ```css title=routes/styles.css
 body {
@@ -31,11 +33,12 @@ body {
 
 The above is a minimalistic style sheet, which applies four CSS properties to the HTML `body` element.
 
+`font-family: Helvetica, Arial, sans-serif` instructs the browser to use the Helvetica font if availlable, otherwise look for the Arial font, and in the worst case, to fall back to its default sans-serif font.
 Font-related properties (like `font-family`, `font-size`, `color`, etc.) are [inherited](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Inheritance) by default, meaning that they will affect all descendants of `body` in the HTML document tree. However, this is the exception. Most properties are not inherited.
 
 For example, the `max-width` property is not inherited. It constrains the width of the `body` to not be wider than `30em`. An `em` is a relative unit and is equal to the font-size. Since the font-size of that element is `18px` (pixels), `30em` equals `30 * 18px`, which equals `540px`. Unless you work with a print designer who is used to absolute units like inches, centimeters and pixels, it's best to quickly forget again that the element is 540 pixels wide, as it doesn't really matter. Quite the contrary: it's good practice to use the `em` unit to specify things that should change if the font-size also changes – like the width of the text in this case.
 
-The final declaration in the above example is `margin: 0 auto;`. This sets `margin-top` and `margin-bottom` to `0`, and `margin-left` and `margin-right` to `auto`, which has the effect of centering the element horizontally. If you don't see that happening, try making the preview pane wider.
+The final declaration in the above example is `margin: 0 auto;`. This sets `margin-top` and `margin-bottom` to `0`, and `margin-left` and `margin-right` to `auto`, which has the effect of centering the element horizontally (if it's not taking the whole width already). If you don't see that happening, try making the preview pane wider.
 
 
 ## Header and Footer

data/guide/html.md

@@ -9,7 +9,9 @@ In this chapter, you build your very first page.
 
 The simplest website is a single HTML file. In Mastro, each file in the `routes/` folder results in one or more files publicly accessible on your website.
 
-1. If you've started from the template repository, delete all files in the `components` and `routes` folders by right-clicking each file individually, then select "Delete Permanently". Don't worry, we'll add them again in later chapters of this guide. If you want, you can also edit the `README.md` file.
+If you've started from the template repository, you'll have a few more folders besides the `routes/` folder. You can ignore them for now.
+
+1. Open the `routes/` folder. You'll see that it already contains two files (`index.server.js` and `styles.css`). You can either delete them or just ignore them.
 
 2. Create a new file `routes/index.html`: with the `routes` folder selected, click the leftmost of the four small icons at the top (a sheet of paper with a plus icon in it), type `index.html`, and hit enter.
 
@@ -35,7 +37,9 @@ Hit `Ctrl-Shift-P` (Windows or Linux) or `Command-Shift-P` (Mac), type `mastro`,
   In Firefox, this keyboard shortcut unfortunately opens a new incognito window. Instead, you need to hit `Ctrl-P` (Windows or Linux) or `Command-P` (Mac) and type `>mastro` (note the `>`).
 </details>
 
-This opens the _Mastro preview pane_ in a new tab to the right, displaying your `index.html` file, just like it would show in a web browser tab. Note how the text in the `<title>` is shown as the tab name, just like it would be in a browser's tab. The `body` is the part of the HTML file that is visible as the page itself.
+This opens the _Mastro preview pane_ in a new tab to the right. Try to remember how to open the preview pane, as you might sometimes close it.
+
+The pane will now preview your `index.html` file, just like it would show in a web browser tab. Note how the text in the `<title>` is shown as the tab name, just like it would be in a browser's tab. The `body` is the part of the HTML file that is visible as the page itself.
 
 
 ## Content first

data/guide/publish-website.md

@@ -4,44 +4,20 @@ title: Publish your website
 
 You can publish your website to the internet directly from within _VS Code_ – without leaving your browser.
 
-:::tip
-## Alternative option: CI/CD pipeline
-If you are comfortable with the command line and/or GitHub Actions, you can set up a CI/CD pipeline instead of commiting the output folder. To do that, see [Deploy static site with CI/CD](/guide/deploy/#deploy-static-site-with-ci%2Fcd).
-
-Once you've done that, you can jump to the [next chapter](/guide/css/).
-:::
-
-To publish your website, we need to:
-
-1. Enable _GitHub Pages_ on your GitHub repository (this only needs to be done once)
-2. Generate the static site (this creates a new `docs/` folder with all the public files)
-3. Save changes to GitHub
-
 
 ## One-time setup
 
-Configure [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) to make the `docs/` folder of your repository accessible as a website:
+Configure [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow):
 
 ![](https://docs.github.com/assets/cb-28260/mw-1440/images/help/repository/repo-actions-settings.webp)
 
 1. On GitHub, navigate to the **page of the repository** you created in the previous chapter: `https://github.com/your-user-name/your-repository-name/`
-2. Click the **Settings** tab on the top right (possibly hiding in a `...` menu).
+2. Click the **Settings** tab. It's the rightmost tab, but might be hiding in a `...` menu.
 3. In the **Code and automation** section of the left sidebar, click **Pages**.
-4. Under **Source**, make sure that **Deploy from a branch** is selected.
-5. Under **Branch**,
-    - switch the branch from `None` to `main`,
-    - switch the folder from `/ (root)` to `/docs`, and
-    - click **Save**.
-
-## Generate the static site
-
-In the Mastro preview pane on the right (which previews your website), click the **Generate** button in the top-right corner.
-
-After a slight delay, the _Output_ panel should fade in from the bottom and inform you that mastro built the entire static website (or if anything went wrong). Feel free to close that panel again – it will reappear every time you click the _Generate_ button.
+4. Under **Source**, make sure that **GitHub Actions** is selected.
 
-The HTML files are generated in the `docs/` folder, which you should now see in the _Explorer_ view on the left, just above your `routes/` folder. You can look at the generated files in the `docs/` folder, but don't edit them, as they'll be overwriteen the next time you click _Generate_.
+If you've started with Mastro's [basic template repository](https://github.com/mastrojs/template-basic), you should already have a `.github/workflows/deploy.yml` file containing a workflow to deploy your website.
 
-We're using the `docs/` folder, because that's the only folder name GitHub Pages allows. (If you know GitHub Pages, you may be wondering why we're not automatically pushing to the `gh-pages` branch. That's because at the moment, it's [not possible](https://github.com/microsoft/vscode-remote-repositories-github/issues/101) for a _VS Code for the Web_ extension to directly interact with git.)
 
 ## Save changes and publish to the web
 
@@ -53,7 +29,7 @@ The first time, a blue box might be there with the text:
 
 > Your changes will be committed and immediately pushed to the 'main' branch on GitHub.
 
-You can click **Don't show again**. Below, you should see a list of changed files (e.g. `docs/index.html` and `routes/index.html`).
+You can click **Don't show again**. Below, you should see a list of changed files (e.g. `routes/index.html`).
 
 To save these changes to your repository on GitHub:
 
@@ -62,12 +38,25 @@ To save these changes to your repository on GitHub:
 
 In your browser, go to your repository's page on GitHub and verify that the changes are there: `https://github.com/your-user-name/your-repository-name/`
 
-On that same GitHub page, in the horizontal grey bar above your files and folders, you should see the message you just entered. And just on the right of your message, there should be a green tickmark, indicating that the `docs/` folder was successfully deployed as a website. If it's still a yellow dot, you need to wait a few more seconds.
+On that same GitHub page, in the horizontal grey bar above your files and folders, you should see the message you just entered. And just on the right of your message, there should be a green tickmark, indicating that the website was successfully deployed. If it's still a yellow dot, you need to wait a few more seconds.
 
 To visit your website, open a new tab in your browser and go to:
 
     https://your-user-name.github.io/your-repository-name/
 
-If you're unsure about the link to your website, you can find it where you previously set up Github Pages: Click the _Settings_ tab in the top right -> _Pages_ -> _Visit site_.
+If you're unsure about the link to your website, you can find it where you previously set up Github Pages. If you still have that page open, reload it and look for the _Visit site_ button. If not, to find it again, click the _Settings_ tab in the top right -> _Pages_ -> _Visit site_.
 
 Congratulations on publishing your website!
+
+
+## Generating all pages inside VS Code
+
+If you make a mistake in your server-side JavaScript, it's possible that the site will fail to build and deploy. On your GitHub repo page, instead of a green tick, there will be a red cross besides your last commit message. You can click through and should eventually find an error message that might explain what went wrong. However, it can be faster to generate the whole site with the Mastro VS Code extension and see whether any pages fail to build.
+
+To do so, click the **Generate** button in the top-right corner of the Mastro preview pane (the one that previews your website).
+
+After a slight delay, the _Output_ panel should fade in from the bottom and inform you that Mastro built the entire static website and/or if anything went wrong. Feel free to close that panel again – it will reappear every time you click the _Generate_ button.
+
+The HTML files are generated in the `generated/` folder, which you should now see in the _Explorer_ view on the left, just above your `routes/` folder. You can look at the generated files in the `generated/` folder, but don't edit them, as they'll be overwriteen the next time you click _Generate_.
+
+After you've fixed your code, and generating the site doesn't produce any errors anymore, you can click _Commit & Push_ again in the _Source Control_ view. This time, after a minute or so, the green tick should appear again on your GitHub repo page.

data/guide/setup.md

@@ -2,7 +2,7 @@
 title: "Setup: GitHub, VS Code and Mastro"
 ---
 
-There are various ways to run Mastro, which is a general-purpose web framework and static site generator. The by far easiest way is with the Mastro _Visual Studio Code for the Web_ extension, which lets you run Mastro as a static site generator right in your browser. No need to install anything or learn how to use the command line.
+There are various ways to run Mastro, which is a general-purpose web framework and static site generator. By far the easiest way is with the Mastro _Visual Studio Code for the Web_ extension, which lets you run Mastro as a static site generator right in your browser. No need to install anything or learn how to use the command line.
 
 :::tip
 ## Alternative option: command line
@@ -12,7 +12,7 @@ If you're already comfortable with the command line and prefer a local installat
 Once you've done that, you can jump to the [next chapter](/guide/html/).
 :::
 
-Either way, since all the processing happens upfront, and the generated files are served from a CDN close to your users, a static site is extremely fast and secure.
+Since all the processing happens upfront, and the generated files are served from a CDN close to your users, a static site is extremely fast and secure.
 We'll be using GitHub Pages, which hosts your static site for free.
 
 
@@ -28,7 +28,7 @@ If you want, you can buy and [configure a custom domain](https://docs.github.com
 
     - Open Mastro's [basic template repository](https://github.com/mastrojs/template-basic).
     - In the upper right, click the green button **Use this template**, and from the dropdown select **Create a new repository**.
-    - Choose a repository name (something short and descriptive like `blog`, or `cooking-website`, or even the domain name of your future website), and click **Create repository**.
+    - Choose a repository name (something short and descriptive like `blog`, or `cooking-website`, or even the domain name of your future website), and click **Create repository**. (On the free tier, it needs to be public.)
 
 
 ## Open _Visual Studio Code for the Web_
@@ -55,4 +55,4 @@ See also [VS Code for the Web's browser support](https://code.visualstudio.com
 
 ![](/assets/vscode-extensions.png)
 
-Done? Congrats, you're all set up now! You can switch back to the _Explorer_ view (the topmost icon in the activity bar on the left) to finally write some HTML.
+Done? Congrats, you're all set up now! You can switch back to the _Explorer_ view by clicking the topmost icon ⧉ in the activity bar on the left. Now you should see your files and folders again. Next up, finally write some HTML!