Create "newbie track" documentation

bridgetown-website/src/_docs/first-steps-for-newbies.md

@@ -0,0 +1,63 @@
+---
+order: 45
+title: First Steps for Newbies
+top_section: Setup
+description: If Bridgetown is your first web framework
+category: first-steps
+---
+
+You have just installed Bridgetown by following the [Getting Started][getting-started] guide. Great! Now what?
+
+If you are not familiar with other web frameworks, your brand new site may seem confusing. Head to our [explanation][initial-files] to discover what all these files and folders are about!
+
+## First posts and pages
+
+If you want a "typical", simple blog, open the `src` folder and identify:
+- the `_posts` folder, which will result in the `posts` collection when you add files in the format `YYY-MM-DD-title.md`. These will follow the layout `post.erb` contained in the `_layouts` folder.
+- the `index.md`, `about.md` and `posts.md` pages, which will follow the layout `page.erb` contained in the `_layouts` folder.
+
+For now, `index.md` and `about.md` are static pages, respectively a home page and an about page. You can edit their content to suit your blog.
+
+`posts.md` contains an example of how to access the items in a collection.
+
+![getting posts](/images/posts-each.png)
+
+In this case, it will list the titles of all your posts, with links to the corresponding posts. You can also access other properties of your posts. For instance, `post.data.date` will give you the date. Any custom metadata that you specify in the front matter can be accessed in the same way.
+
+> [!NOTE]:
+> If you create custom metadata for one post, you will need to include the same data for all other posts, in order to access it with an `each` method. The best strategy, if not all posts need this specific data, is to add it in a `_defaults.yml` file at the top of your directory tree, and leave it empty there.
+
+## A custom collection
+
+If you want to create a custom collection, you will need to initialize it in the `config/initializers.rb` file. (See [detailed instructions here][custom-collections].)
+
+Then, create a `_your-collection` folder under the `src` folder, and add your files in it. You can use an existing layout, or create a custom layout in the `layouts` folder.
+
+Add a `your-collection.md` file under the `src` folder to create a collection page similar to the `posts.md` page.
+
+Edit the `components/shared/navbar.erb` file to add your new collection to the navigation bar (you can follow the format used for pages and posts).
+
+![navbar](/images/navbar.png)
+
+Now, you can add your content, either as a page, a post, or an item in a custom collection. But how will it look?
+
+## Looking good
+
+Bridgetown comes with a decent default theme. You can edit the CSS directly in `frontend/styles/index.css`.
+
+You can also search the web for CSS themes, and either place the contents of the theme's CSS file in index.css, or follow the theme's installation instructions (for instance [pico][pico-theme])
+
+## What next?
+
+You now have a basic Bridgetown site set up, and you can focus on what matters most: your content.
+
+When you are ready for more complex stuff, we recommend taking a look at Bridgetown's [bundled configurations][bundled-configurations] and [how to deploy to production][deploy].
+
+<!--LINKS-->
+
+[getting-started]: https://www.bridgetownrb.com/docs
+[initial-files]: /docs/initial_files
+[custom-collections]: https://www.bridgetownrb.com/docs/collections#custom-collections
+[pico-theme]: https://picocss.com/docs#install-manually
+[bundled-configurations]: https://www.bridgetownrb.com/docs/bundled-configurations
+[deploy]: https://www.bridgetownrb.com/docs/deployment

bridgetown-website/src/_docs/initial-files.md

@@ -0,0 +1,100 @@
+---
+order: 47
+title: The initial files scaffold
+top_section: Setup
+description: Explanation of initial files scaffold
+category: files-scaffold
+---
+
+You can start a web application with one file (like `config.ru` for Roda or other Rack-based apps) and build from there.
+
+If instead you use a framework like Bridgetown (or Sinatra, Rails, etc.), you will be provided with a "scaffold" of initial files and folders, setting up a standard organization for your project.
+
+This is very useful, but can also confuse beginning developers, as it presents a number of building blocks in a manner that is conventional and convenient _if you know what each part is for_.
+
+![view of the Bridgetown scaffold](/images/bridgetown-scaffold.png)
+
+Some of this know-how comes from general programming knowledge (about Ruby, JavaScript, etc.), something that everyone possesses in different amounts at different times. Other Bridgetown specific information can be found in the official documentation. Yet when first starting with Bridgetown, it can be useful to have a quick summary of the building blocks and scaffold that you are beginning to work with.
+
+This is an attempt at making such a summary, followed by additional details about the main files and folders that you will use when starting with Bridgetown.
+
+## The building blocks (a.k.a. "the stack")
+
+**Backend / Core:**
+
+- **Ruby** — The primary programming language that powers Bridgetown's core functionality, plugins, and templating.
+- **Roda** — A lightweight Ruby web framework used for the server-side routing and API endpoints. Handles dynamic server-side rendering (SSR) when needed.
+
+**Templating:**
+
+- **Liquid** — A templating language.
+- **ERB** — Ruby's built-in templating system, available as an alternative to Liquid.
+- **Serbea** — Bridgetown's own templating syntax that combines ERB with Liquid-like filters.
+
+**Frontend Bundling:**
+
+- **esbuild** — A JavaScript bundler that compiles and bundles CSS and JavaScript files for the browser.
+- **PostCSS** — A CSS processor that enables modern/upcoming CSS features and runs plugins like autoprefixer.
+- **Sass** — An optional CSS preprocessor available as an alternative to PostCSS.
+
+**Package Management:**
+
+- **Bundler** — Manages Ruby gem dependencies (via Gemfile).
+- **npm** — Manages JavaScript package dependencies (via package.json).
+
+**Content:**
+
+- **Markdown** — The primary format for writing content (processed by Kramdown by default).
+- **YAML** — Used for front matter, data files, and configuration.
+
+## The scaffold
+
+When you create a new project with the `bridgetown new` command, this initial scaffold of files and folders is provided. Here is a short description of what each does or contains.
+
+**Folders:**
+
+- **bin** — Contains executable scripts for running Bridgetown commands (like `bin/bridgetown build`, `bin/bridgetown start`, etc.). Using these binstubs ensures you're using the correct version of Bridgetown as specified in your Gemfile.
+- **config** — Stores frontend and server default configurations, including `initializers.rb` for Ruby-based site configuration.
+- **frontend** — Contains your CSS and JavaScript source files for esbuild to process. Includes subdirectories for `javascript/` and `styles/`.
+- **node_modules** — Contains all installed npm packages and their dependencies.
+- **plugins** — Where you can write custom Ruby plugins to extend Bridgetown's functionality.
+- **server** — Where you can optionally add API routes using Roda for server-side functionality.
+- **src** — The main source directory containing your resources and design templates, including `_components`, `_data`, `_layouts`, `_posts`, and other content. Read more about it below.
+
+**Files:**
+
+- **.gitignore** — A list of files to be ignored by git.
+- **.ruby-version** — The version of Ruby used for this project.
+- **config.ru** — Configuration for a Rack-based (in this case, Roda) web server interface. Puma uses this to boot up the web server.
+- **esbuild.config.js** — Configuration file for esbuild, the frontend JavaScript bundler that processes your CSS and JS files.
+- **Gemfile** — A list of all Ruby dependencies.
+- **Gemfile.lock** — A locked list of all Ruby dependencies and their exact versions, as installed.
+- **jsconfig.json** — Configures JavaScript language features for code editors (like VS Code), specifying the project root and compiler options for better IntelliSense.
+- **package-lock.json** — A locked list of all npm dependencies and their exact versions, as installed.
+- **package.json** — A list of all npm (JavaScript) dependencies and build scripts.
+- **postcss.config.js** — Configuration file for PostCSS, which processes CSS with plugins for features like autoprefixing and modern CSS syntax.
+- **Rakefile** — Defines Rake tasks for automating common operations like building and deploying the site.
+- **README.md** — A helpful starter document.
+
+## The src folder
+
+![src folder in scaffold](/images/scaffold-src.png)
+
+When starting a new site or blog with Bridgetown, you will spend most of your time within the `src` folder, where the content lives. Yet opening this folder can also be disconcerting, initially. Here is a quick description:
+
+**Folders:**
+
+- **_components** — Reusable view components that can include Ruby classes, templates (ERB, Liquid, Serbea), and sidecar CSS/JS files. Components encapsulate markup, styling, and behavior. Accessed via `render ComponentName.new`.
+- **_data** — Data files (YAML, JSON, CSV, TSV, or Ruby `.rb` files) that provide centralized, reusable data accessible across your site via `site.data`. Includes `site_metadata.yml` for site-wide settings.
+- **_layouts** — Page layout templates that wrap your content. Typically includes a `default` layout and specialized layouts (like `post`) that can inherit from others. Accessed via the `layout` front matter key.
+- **_partials** — Reusable template fragments (like headers, footers, navigation) that can be included in layouts and other templates via `render "partial_name"`. Similar to Rails partials.
+- **_posts** — Blog posts, typically Markdown files with a date-prefixed filename format (`YYYY-MM-DD-title.md`). Part of the built-in `posts` collection.
+- **images** — Static image files (SVGs, PNGs, JPGs, etc.) that get copied to the output folder. Referenced via relative URLs like `/images/logo.svg`.
+
+**Files:**
+
+- **index.md** — The homepage of your site.
+- **404.html** — Custom "page not found" error page.
+- **500.html** — Custom "internal server error" error page.
+- **Other pages** (e.g., `about.md`, `posts.md`) — Standalone pages that become part of the built-in `pages` collection. Their URL typically matches their file path.
+- **favicon.ico** — Custom favicon (a small icon file that represents your website).