Create "newbie track" documentation by anantone · Pull Request #1077 · bridgetownrb/bridgetown

anantone · 2026-02-04T05:50:35Z

First two files of proposed "newbie track" (basics of using Bridgetown for a user without previous experience of a Ruby web framework).

"First steps for newbies" continues where "Getting started" left off.
"The initial files scaffold" describes the content of initiales files and folders of a standard Bridgetown installation.

Added a guide for beginners on setting up and using Bridgetown.

Added documentation for the initial files scaffold in Bridgetown, detailing the structure and purpose of various components and folders.

anantone · 2026-02-04T05:54:12Z

@jaredcwhite @fpsvogel I tentatively included front matter in order to integrate with the existing docs, but where exactly this should go is a matter for discussion.

fpsvogel

Thanks for writing these and filling a gap in the docs!

Two of my comments suggest describing an example or common scenarios. I wonder if there's a way to supply those in a unified way, by making the first steps doc into more of a how-to on making a specific example site (one that involves adding some custom metadata, and a specific custom collection).

I'm not 100% sure that format would be better, so it's up to you and what you feel would have been most helpful to you in the beginning.

In any case, once we work through some of the details, this will be a nice next step after the Getting Started guide.

fpsvogel · 2026-02-06T16:01:22Z

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

+
+`posts.md` contains an example of how to access the items in a collection.
+
+![getting posts](/images/posts-each.png)


Looks like this image needs to be added to the PR. (If it's an image of code or text, it would be better as a code block.)

Same for the other images paths below.

Replaced with code blocks.

fpsvogel · 2026-02-06T16:03:41Z

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

+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.


An example of adding custom metadata (and why someone might want to do that) might be helpful, because some of the concepts mentioned here might not be obvious to beginners, like "front matter" and "the top of your directory tree".

Example added

fpsvogel · 2026-02-06T16:05:12Z

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

+
+## 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].)


It could be helpful to explain why a custom collection might be useful / one or two common scenarios where someone would want to make a custom collection.

Without going into too much detail, added a relevant example of custom collection.

fpsvogel · 2026-02-06T16:15:37Z

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

+
+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].


"Deploy to production" is another phrase that might not be familiar to beginners. Also, it might be helpful to suggest a few bundled configurations that are useful for a blog or other beginner site.

Something like this, perhaps?

To make your site more accessible on the Web, consider adding the [SEO](/docs/bundled-configurations#seo) and [Feed](https://www.bridgetownrb.com/docs/bundled-configurations#feed) bundled configurations (instructions in the links). When you're ready to publish your site, head over to our [deployment guide](/docs/deployment).

fpsvogel · 2026-02-06T16:17:17Z

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

+<!--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


For consistency with the rest of Bridgetown docs, could you move these links to be inline rather than at the bottom as references?

fpsvogel · 2026-02-06T16:31:12Z

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

+
+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.


I think for a brand-new beginner, it's not worthwhile to touch on wider concepts of web apps, as the preceding paragraphs do.

IMO the start of this doc should narrow its focus to the immediate concerns of that brand-new beginner who has just run bridgetown new, who may be thinking something like: "Wow, this is a lot of files. What do they all mean? Do I need to know what they all mean? Maybe this isn't for me after all…"

Maybe it would also be worth mentioning that it's OK to not know all of this, and building a site with Bridgetown doesn't require an intimate knowledge of everything listed here, and that this is more for reference (if you can find a succinct way to say that).

fpsvogel · 2026-02-06T16:32:13Z

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

+
+## What next?
+
+You now have a basic Bridgetown site set up, and you can focus on what matters most: your content.


I really like how you put this!

fpsvogel · 2026-02-06T16:45:11Z

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

+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])


This is not a blocker, but once Jared publishes the Willamette theme for Bridgetown, we can come back and update this section to make it more Bridgetown/Willamette-specific.

Looking forward to it!

Updated instructions for creating custom collections and added code examples for configuration and navigation.

Move links inline for consistency with existing docs.

Added YAML front matter example and improved clarity on custom metadata usage.

Added information about custom metadata in front matter.

Add example of creating a custom collection and clarify why

Added final recommendations for SEO and Feed configurations, and deployment.

Revised the introduction to clarify the purpose of initial files in Bridgetown and reduce confusion for beginners.

anantone · 2026-02-07T05:11:09Z

Thank you for the excellent suggestions, @fpsvogel ! I added more specific examples, not changing completely into a "how-to", but keeping a general "tutorial" approach, with some explanation and reference in there as well (just like, I think, the existing Bridgetown docs).

fpsvogel

Thanks for the changes! Just a few small issues that I pointed out in comments, as well as one more significant suggestion that is totally my fault for not bringing up earlier:

While reviewing your changes, I came across a Bridgetown docs page that is similar to your scaffold doc: Folder Structure (source).

I apologize for not remembering this existing doc earlier!

Are there changes you could make to the existing doc so that it could serve as a reference for beginners?

If so, you could link to it from your doc, in place of your lists of folders and files.

I know we're talking about making a separate beginner's guide here, but at the same time, if we could find a way to make the existing doc work better for beginners, that would be a win because the specifics of the scaffold tend to change over time Bridgetown evolves, and it would be less of a maintenance burden if we had just one doc that lists everything out specifically.

fpsvogel · 2026-02-09T14:30:31Z

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

 `posts.md` contains an example of how to access the items in a collection.

-![getting posts](/images/posts-each.png)
+```ruby


Use erb as the language, here and in other ERB code blocks.

Done, thank you.

fpsvogel · 2026-02-09T14:47:17Z

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

+Below is a quick summary of the building blocks and scaffold, followed by additional details about the main files and folders that you will use when starting with Bridgetown.

-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.
+![view of the Bridgetown scaffold](/images/bridgetown-scaffold.png)


Missing image. Or if possible, change it to a code block showing a directory tree (tree output), as in this Bridgetown docs page.

Though see my comment above about the existing docs.

fpsvogel · 2026-02-09T14:50:31Z

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

+Like other frameworks (Sinatra, Rails, etc.), Bridgetown provides 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_.
+But do you need to know what all those files and folders are for? _Not really!_


This could come across as "there's no value in learning about the scaffold", so I think it's best omitted or softened to communicate that the beginner doesn't need to remember/memorize all of this.

Updated code snippets from Ruby to ERB for consistency in documentation.

Delete new document in favor of existing "Folder Structure" (to be edited in a separate commit)

anantone · 2026-02-09T16:42:01Z

Nice catch! We clearly shouldn't duplicate the "Folder Structure" document. So, for now, I've deleted the "Initial Files", small parts of which can be reused later.

I suggest that we limit the scope of this PR to adding the new "First Steps for Newbies" file. Further changes, aiming to create a more newbie friendly track within the existing docs, can come as a later batch.

fpsvogel

LGTM!

I'll leave it to @jaredcwhite to give further feedback or merge.

jaredcwhite · 2026-02-20T00:36:47Z

Excited to review this, hopefully over the weekend!

anantone added 2 commits February 4, 2026 11:13

Create first-steps-for-newbies.md documentation

de363d9

Added a guide for beginners on setting up and using Bridgetown.

Document initial files scaffold for Bridgetown

e34b530

Added documentation for the initial files scaffold in Bridgetown, detailing the structure and purpose of various components and folders.

fpsvogel reviewed Feb 6, 2026

View reviewed changes

anantone added 7 commits February 7, 2026 09:33

Enhance documentation for custom collections setup

7140e34

Updated instructions for creating custom collections and added code examples for configuration and navigation.

Update links in first-steps-for-newbies.md

b88cc3e

Move links inline for consistency with existing docs.

Improve custom metadata section

d236481

Added YAML front matter example and improved clarity on custom metadata usage.

Enhance first steps guide with metadata details

0b05a5b

Added information about custom metadata in front matter.

Update instructions for custom collections

872f6ca

Add example of creating a custom collection and clarify why

Add SEO and Feed tips as possible next steps

a80f6ed

Added final recommendations for SEO and Feed configurations, and deployment.

Clarify initial files explanation for beginners

95e8b82

Revised the introduction to clarify the purpose of initial files in Bridgetown and reduce confusion for beginners.

fpsvogel reviewed Feb 9, 2026

View reviewed changes

anantone and others added 2 commits February 9, 2026 21:29

Change code examples from Ruby to ERB format

1b212f5

Updated code snippets from Ruby to ERB for consistency in documentation.

Delete 'Initial Files' document

9906f68

Delete new document in favor of existing "Folder Structure" (to be edited in a separate commit)

fpsvogel approved these changes Feb 9, 2026

View reviewed changes


		`posts.md` contains an example of how to access the items in a collection.

		![getting posts](/images/posts-each.png)


		## 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].)


		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].


		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.


		## What next?

		You now have a basic Bridgetown site set up, and you can focus on what matters most: your content.

		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])

Uh oh!

Conversation

anantone commented Feb 4, 2026

Uh oh!

anantone commented Feb 4, 2026

Uh oh!

fpsvogel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anantone commented Feb 7, 2026

Uh oh!

fpsvogel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fpsvogel Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anantone commented Feb 9, 2026

Uh oh!

fpsvogel left a comment

Choose a reason for hiding this comment

Uh oh!

jaredcwhite commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fpsvogel left a comment •

edited

Loading

fpsvogel Feb 9, 2026 •

edited

Loading