+ 
+
+
flags (specified on the command-line) that control them.
Default: liquid
template_engine: ENGINE (erb, slim, haml, etc.)
Content Engine
-Change the content engine Bridgetown uses for its data pipeline. The resource-based engine will become standard for v1.0.
-Default: legacy
content_engine: ENGINE (legacy, resource)
template_engine: ENGINE (erb, serbea, slim, haml, etc.)
Permalink
-Change the default permalink style or template used by pages & blog posts. Documentation here—and if you're using the Resource-based content engine, read this additional information.
+Change the default permalink style or template used by pages & blog posts. Documentation here and read this additional information.
permalink: STYLE or TEMPLATE
Encoding
- Set the encoding of files by name (only available for Ruby
- 1.9 or later).
- The default value is utf-8 starting in 2.0.0,
- and nil before 2.0.0, which will yield the Ruby
- default of ASCII-8BIT.
+ Set the encoding of files by name. The default value is utf-8.
Available encodings can be shown by the
command ruby -e 'puts Encoding::list.join("\n")'.
Ruby Front Matter
-Process Ruby front matter (default true)
+Process Ruby front matter (default true)
ruby_in_front_matter: BOOL
LSI
-Produce an index for related posts. Requires the - classifier-reborn plugin.
-lsi: BOOL
--lsi
Limit Posts
-Limit the number of posts to parse and publish.
-limit_posts: NUM
--limit_posts NUM
Force polling
@@ -352,7 +320,11 @@ a staging area and copy files from there to your web server. -### Serve Command Options +### Webrick Options + +{%@ Note type: :warning do %} +The Webrick server is deprecated and will be removed in a future version of Bridgetown. +{% end %} In addition to the options below, the `serve` sub-command can accept any of the options for the `build` sub-command, which are then applied to the site build which occurs right @@ -425,10 +397,12 @@ before your site is served. -{% rendercontent "docs/note", title: "Do not use tabs in configuration files", type: "warning" %} +{%@ Note type: :warning do %} + #### Do not use tabs in configuration files + This will either lead to parsing errors, or Bridgetown will revert to the default settings. Use spaces instead. -{% endrendercontent %} +{% end %} ### Additional Configuration File Settings diff --git a/bridgetown-website/src/_docs/configuration/front-matter-defaults.md b/bridgetown-website/src/_docs/content/front-matter-defaults.md similarity index 77% rename from bridgetown-website/src/_docs/configuration/front-matter-defaults.md rename to bridgetown-website/src/_docs/content/front-matter-defaults.md index e2e95f29d..73c67ec32 100644 --- a/bridgetown-website/src/_docs/configuration/front-matter-defaults.md +++ b/bridgetown-website/src/_docs/content/front-matter-defaults.md @@ -1,8 +1,8 @@ --- title: Front Matter Defaults -hide_in_toc: true order: 0 -category: configuration +top_section: Writing Content +category: resources --- Using [front matter](/docs/front-matter) is the way you specify metadata for the file-based resources for your site, setting things like a default layout, or customizing the title, or providing taxonomy terms. @@ -11,7 +11,7 @@ Sometimes you will find you're repeating a few configuration options over and ov There are two ways to accomplish this: the data cascade, and via your site's configuration file. -# The Data Cascade +## The Data Cascade You can add `_defaults.yml` (also `.yaml` or `.json`) files anywhere in your source tree, which will then cause a "data cascade". In other words, any resources in that folder or in a subfolder will use the front matter data contained in the defaults file. Defaults files in subfolders can also potentially overwrite values contained in parent folders (hence the term "cascade"). @@ -31,13 +31,17 @@ Now all the `fancy_posts` posts will use the `fancy_post` layout. If you had oth Also, keep in mind these are "default" values, so if you were to add `layout: some_other_layout` to a post, it would overwrite either `layout: post` or `layout: fancy_post`. This is what makes front matter defaults so powerful! -{% rendercontent "docs/note" %} -Defaults files work well for custom collections! Just add a `_defaults.yml` to the collection root folder to set layouts and other variables for your entire collection. -{% endrendercontent %} +{%@ Note do %} + #### Trick out your collections -{% rendercontent "docs/note" %} -You can also add a defaults file to `src` itself! For example, if you wanted every resource on your site to start off with a default thumbnail image, you could simply add `image: /images/thumbnail_image.jpg` to a defaults file in `src` and it would apply globally. -{% endrendercontent %} + Defaults files work well for custom collections! Just add a `_defaults.yml` to the collection root folder to set layouts and other variables for your entire collection. +{% end %} + +{%@ Note do %} + #### Think globally + + You can also add a defaults file to `src` itself! For example, if you wanted every resource on your site to start off with a default thumbnail image, you could simply add `image: /images/thumbnail_image.jpg` to a defaults file in `src` and it would apply globally. +{% end %} ## Configuration-based Front Matter Defaults @@ -51,11 +55,13 @@ defaults: layout: "default" ``` -{% rendercontent "docs/note", title: "Stop and rerunbridgetown serve command." %}
-The bridgetown.config.yml master configuration file contains global configurations and variable definitions that are read once at execution time. Changes made to bridgetown.config.yml will not trigger an automatic regeneration.
-
-Use [Data Files](/docs/datafiles) to set up metadata variables and other structured content you can be sure will get reloaded during automatic regeneration.
-{% endrendercontent %}
+{%@ Note type: :warning do %}
+ #### Stop and rerun bridgetown start
+
+ The bridgetown.config.yml master configuration file contains global configurations and variable definitions that are read once at execution time. Changes made to bridgetown.config.yml will not trigger an automatic regeneration.
+
+ Use [Data Files](/docs/datafiles) to set up metadata variables and other structured content you can be sure will get reloaded during automatic regeneration.
+{% end %}
You probably don't want to set a layout on every file in your project, so you can also specify a `collection` value under the `scope` key.
@@ -117,9 +123,11 @@ defaults:
layout: "specific-layout"
```
-{% rendercontent "docs/note", title:"Globbing and Performance", type: "warning" %}
-Please note that globbing a path is known to have a negative effect on performance. Globbing a path will increase your build times in proportion to the size of the associated collection directory.
-{% endrendercontent %}
+{%@ Note type: "warning" do %}
+ #### Globbing and Performance
+
+ Please note that globbing a path is known to have a negative effect on performance. Globbing a path will increase your build times in proportion to the size of the associated collection directory.
+{% end %}
### Precedence
diff --git a/bridgetown-website/src/_docs/content/pagination.md b/bridgetown-website/src/_docs/content/pagination.md
index 7653b12e9..78796c9e1 100644
--- a/bridgetown-website/src/_docs/content/pagination.md
+++ b/bridgetown-website/src/_docs/content/pagination.md
@@ -1,11 +1,11 @@
---
title: Pagination
-hide_in_toc: true
order: 0
-category: posts
+top_section: Writing Content
+category: resources
---
-{% render "docs/help_needed", page: page %}
+{%@ "docs/help_needed", resource: resource %}
Pagination support is built-in to Bridgetown, but it is not enabled by default. To enable it on your site, simply add:
@@ -90,4 +90,4 @@ To display pagination links, simply use the `paginator` Liquid object as follows
The `paginator` Liquid object provides the following attributes:
-{% render "docs/variables_table", scope: site.data.bridgetown_variables.paginator %}
+{%@ Documentation::VariablesTable data: site.data, scope: :paginator, description_size: :bigger %}
diff --git a/bridgetown-website/src/_docs/content/permalinks.md b/bridgetown-website/src/_docs/content/permalinks.md
new file mode 100644
index 000000000..5025a84d9
--- /dev/null
+++ b/bridgetown-website/src/_docs/content/permalinks.md
@@ -0,0 +1,59 @@
+---
+title: Permalinks
+order: 0
+top_section: Writing Content
+category: resources
+---
+
+A permalink is simply the determination of what the output URL of your [resource](/docs/resources) will be. Every resource uses a _permalink processer_ to figure out where to save your transformed resource in the output folder tree.
+
+Resources in the **pages** collection are the most straightforward. The filenames and folder structure of your pages will result in matching output URLs. For example, a file saved at `src/_pages/this/is/great.md` would be output to `/this/is/great/`.
+
+For resources in the **posts** collection, Bridgetown ships with few permalink "styles". The posts permalink style is configured by using the `permalink` key in the config file. If the key isn't present, the default is `pretty`.
+
+The available styles are:
+
+* `pretty`: `/[locale]/:categories/:year/:month/:day/:slug/`
+* `pretty_ext`: `/[locale]/:categories/:year/:month/:day/:slug.*`
+* `simple`: `/[locale]/:categories/:slug/`
+* `simple_ext`: `[locale]/:categories/:slug.*`
+
+(Including `.*` at the end simply means it will output the resource with its own slug and extension. Alternatively, `/` at the end will put the resource in a folder of that slug with `index.html` inside.)
+
+To set a permalink style or template for a **custom collection**, add it to your collection metadata in `bridgetown.config.yml`. For example:
+
+```yaml
+collections:
+ articles:
+ permalink: pretty
+```
+
+would make your articles collection behave the same as posts. Or you can create your own template:
+
+```yaml
+collections:
+ articles:
+ permalink: /lots-of/:collection/:year/:title/
+```
+
+This would result in URLs such as `/lots-of/articles/2021/super-neato/`.
+
+### Placeholders
+
+All of the segments you see above starting with a colon, such as `:year` or `:slug`, are called **placeholders**. Bridgetown ships with a number of placeholders, but you can also create your own! Simply use the `register_placeholder` in a plugin, perhaps at the bottom of your `plugins/site_builder.rb` file. For example, if you wanted a placeholder to resolve a resource data, you could add:
+
+```ruby
+Bridgetown::Resource::PermalinkProcessor.register_placeholder :ymd, ->(resource) do
+ "#{resource.date.strftime("%Y")}#{resource.date.strftime("%m")}#{resource.date.strftime("%d")}"
+end
+
+Bridgetown::Resource::PermalinkProcessor.register_placeholder :y_m_d, ->(resource) do
+ "#{resource.date.strftime("%Y")}-#{resource.date.strftime("%m")}-#{resource.date.strftime("%d")}"
+end
+```
+
+Thus with a permalink key of `/blog/:ymd/:slug/`, you'd get `/blog/20211020/my-post/`, or for `/blog/:y_m_d/:slug/` you'd get `/blog/2021-10-20/my-post/`.
+
+Here's the full list of built-in placeholders available:
+
+{%@ Documentation::VariablesTable data: site.data, scope: :permalinks %}
diff --git a/bridgetown-website/src/_docs/core-concepts.md b/bridgetown-website/src/_docs/core-concepts.md
index 53883f94b..edd1ef7f3 100644
--- a/bridgetown-website/src/_docs/core-concepts.md
+++ b/bridgetown-website/src/_docs/core-concepts.md
@@ -1,12 +1,11 @@
---
-order: 4
-next_page_order: 4.2
+order: 20
title: Core Concepts
-top_section: Setup
+top_section: Introduction
category: core_concepts
---
-It's easy to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed, and only optionally provide dynamic routes via a server process. Frameworks like this are sometimes referred to as [Jamstack](/docs/jamstack/) style. This means the website your visitors will ultimately engage with is primarily a "snapshot in time"—the product of a build process. How does that process work? Let's find out!
+It's easy to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed as atomic artifacts, but they can optionally provide dynamic routes via a secondary server process. Frameworks like this are sometimes referred to as Jamstack frameworks. This means the website your visitors will ultimately engage with was largely produced as a "snapshot in time"—the product of Bridgetown's build process. How does that process work? Let's find out!
## The Build Process
@@ -20,10 +19,10 @@ There's a relatively linear process which occurs every time you run a [build com
* [Layouts](/docs/layouts)
* [Components](/docs/components)
* [Data files](/docs/datafiles)
- * [Static files](/docs/static_files)
+ * [Static files](/docs/static-files)
* [Resources](/docs/resources)
* Any gem-based plugins which supply their own layouts, components, and content via [Source Manifests](/docs/plugins/source-manifests).
-1. Once all of the data structures for the entire website are in place, Bridgetown __renders__ all relevant content objects to prepare them for final output. This is when [Front Matter](/docs/front-matter) variables are made available to templates, any [Liquid](/docs/liquid) or [Ruby](/docs/erb-and-beyond) templates are processed, formats like [Markdown](https://kramdown.gettalong.org/quickref.html) are converted to HTML, resources are placed within layout templates, and generally everything is finalized in its proper output format (HTML, JSON, images, PDFs, etc.).
+1. Once all of the data structures for the entire website are in place, Bridgetown __renders__ all relevant content objects to prepare them for final output. This is when [Front Matter](/docs/front-matter) variables are made available to templates, any [Liquid](/docs/template-engines/liquid) or [Ruby](/docs/template-engines/erb-and-beyond) templates are processed, formats like [Markdown](https://kramdown.gettalong.org/quickref.html) are converted to HTML, resources are placed within layout templates, and generally everything is finalized in its proper output format (HTML, JSON, images, PDFs, etc.).
1. The final step is to write everything to the destination folder (typically `output`). If all has gone well, that folder will contain a complete, fully-functioning website [which can be deployed](/docs/deployment) to any basic HTTP web server.
Normally during development, you will be running a local dev server, which means
@@ -38,19 +37,18 @@ substantially. There are technical solutions to many of these slowdowns, which c
range from caching API data between builds to limiting the number of files built in development.
Improving build time is a major goal of the Bridgetown core team as we look to the future.
-## The Webpack Build Process
+## The Frontend Build Process
There's one aspect of the build process overlooked above: the compiling,
compressing, and bundling of [frontend assets](/docs/frontend-assets) like
JavaScript, CSS, web fonts, and so forth.
When using Bridgetown's built-in `start` or `deploy` commands,
-essentially _two_ build processes are kicked off: the Webpack build process and the
-Bridgetown build process. The two align when something magical happens.
+essentially _two_ build processes are kicked off: the frontend build process (either esbuild or Webpack) and the Bridgetown build process. The two align when something magical happens.
-1. Webpack will conclude its build process by exporting a `manifest.json` file to the hidden `.bridgetown-webpack` folder. This manifest lists the exact, fingerprinted filenames of the compiled and bundled JS and CSS output files.
-1. Bridgetown, using the `webpack_path` Liquid tag, monitors that manifest, and whenever it detects a change it will regenerate the site to point to those bundled output files.
-1. This way, your website frontend and the HTML of your generated static site are always kept in sync (as long as you use the provided Yarn scripts!).
+1. esbuild/Webpack will conclude its build process by exporting a `manifest.json` file to the hidden `.bridgetown-cache` folder. This manifest lists the exact, fingerprinted filenames of the compiled and bundled JS and CSS output files.
+1. Bridgetown, using the `asset_path` Liquid tag/Ruby helper, monitors that manifest, and whenever it detects a change it will regenerate the site to point to those bundled output files.
+1. This way, your website frontend and the HTML of your generated static site are always kept in sync.
## Adding Extra Features to Your Site
@@ -60,15 +58,21 @@ applying automations. These may provide new features, themes, or software
configurations in useful ways. Some examples:
* Add instant search to your site with the [bridgetown-quick-search](https://github.com/bridgetownrb/bridgetown-quick-search) plugin
-* Include inline SVG images with the [bridgetown-inline-svg](https://github.com/andrewmcodes/bridgetown-inline-svg) plugin
+* Include inline SVG images with the [bridgetown-svg-inliner](https://github.com/ayushn21/bridgetown-svg-inliner) plugin
* Start your site off with a clean, professional design via the [Bulmatown](https://github.com/whitefusionhq/bulmatown) theme and Bulma CSS framework
You can discover links to these and many more in our [Plugins directory](/plugins/).
+## Server-Side Rendering and Dynamic Routes
+
+For most content-rich websites intended for marketing, educational, or publishing purposes (blogs, etc.), a statically-built and deployed site may be all you need. But there may be times when you need a real backend running for your site, either to provide API endpoints your principal pages can communicate with via JavaScript, or to offer actual routes that are fully SSR'd (Server-Side Rendered).
+
+Bridgetown 1.0 ships with an early look at a [full SSR pipeline powered by the Roda web toolkit](/docs/routes). Roda, like Rails or Sinatra, takes full advantage of Ruby's Rack ecosystem and offers a minimalist yet elegant DSL (Domain-Specific Language) for defining and handling routes via a "routing tree" as well as processing request/response cycles. Accepting form data or JSON payloads is a snap, and there's even a core plugin you can configure to enable dynamic, file-based routing with all of Bridgetown's template engines and component rendering at your disposal.
+
## What to Learn Next
There is detailed documentation available about each and every step mentioned
above, so feel free to poke around and read up on the topics which interest you the
most. And as always, if you get stuck or have follow-up questions, just hop in one
-of our [community channels](/docs/community) and a friendly Bridgetowner will
+of our [community channels](/community) and a friendly Bridgetowner will
endeavor to help you out!
diff --git a/bridgetown-website/src/_docs/datafiles.md b/bridgetown-website/src/_docs/datafiles.md
index 8dbc96831..f6eede6f6 100644
--- a/bridgetown-website/src/_docs/datafiles.md
+++ b/bridgetown-website/src/_docs/datafiles.md
@@ -1,8 +1,8 @@
---
title: Data Files
-order: 14
-top_section: Content
-category: datafiles
+order: 120
+top_section: Writing Content
+category: data-files
---
In addition to [built-in variables](/docs/variables) and [front matter](/docs/front-matter), you can specify custom datasets which are accessible via Liquid and Ruby templates as well as plugins.
@@ -13,7 +13,7 @@ You can also save standard Ruby files (`.rb`) to `_data` which get automatically
This powerful feature allows you to avoid repetition in your templates and set site-specific options without changing `bridgetown.config.yml`—and in the case of Ruby data files, perform powerful processing tasks to populate your site content.
-{% toc %}
+{{ toc }}
## The Data Folder
diff --git a/bridgetown-website/src/_docs/deployment.md b/bridgetown-website/src/_docs/deployment.md
index 40b33af57..afff6b99c 100644
--- a/bridgetown-website/src/_docs/deployment.md
+++ b/bridgetown-website/src/_docs/deployment.md
@@ -1,8 +1,7 @@
---
-order: 4.5
-next_page_order: 4.7
-title: Deploying Your Site
-top_section: Setup
+order: 180
+title: Deploy to Production
+top_section: Publishing Your Site
category: deployment
---
@@ -10,20 +9,23 @@ Bridgetown generates your site and saves it to the `output` directory by default
transfer the contents of this directory to almost any hosting provider to make
your site go live.
-Bridgetown's included site template automatically provides a Yarn script you can run to
+Bridgetown's included site template automatically provides a Rake task you can run to
build both your Webpack bundle and your website. Simply run
```shell
bin/bridgetown deploy
```
-as part of your deployment process, which will kick off both the `webpack` and the `bridgetown build` commands in that order.
+as part of your deployment process, which will kick off both the `frontend:build` Rake task and the `bridgetown build` commands in that order.
-If you wish to utilize additional logic within your site templates or plugins to
-determine what's a "development" build vs. "production" build, set the `BRIDGETOWN_ENV`
+{%@ Note type: :warning do %}
+You must set the `BRIDGETOWN_ENV`
environment variable to `production` on the machine or service that's building the
site for deployment. [Read more about environments here.](/docs/configuration/environments/)
+This will also help you if you wish to utilize additional logic within your site templates or plugins to determine what's a "development" build vs. "production" build.
+{% end %}
+
## Automatic Deployment
We recommend setting up an automatic deployment solution at the earliest opportunity. This way every time you push a commit up to your Git repository on a service such as GitHub, your site is automatically rebuilt and deployed quickly.
diff --git a/bridgetown-website/src/_docs/front-matter.md b/bridgetown-website/src/_docs/front-matter.md
index 22dd36240..3fdf18f52 100644
--- a/bridgetown-website/src/_docs/front-matter.md
+++ b/bridgetown-website/src/_docs/front-matter.md
@@ -1,19 +1,19 @@
---
title: Front Matter
-order: 12
-top_section: Content
+order: 90
+top_section: Writing Content
category: front-matter
---
Front matter is a snippet of [YAML](https://yaml.org/) or Ruby data which sits at the top of a file between special line delimiters. You can think of front matter as a datastore consisting of one or more key-value pairs (aka a `Hash` in Ruby). You use front matter to add metadata, like a title or a description, to files such as pages and documents as well as site layouts. Front matter can be used in various ways to set configuration options on a per-file basis, and if you need more dynamic handling of variable data, you can write Ruby code for processing as front matter.
-{% rendercontent "docs/note", title: "Don't repeat yourself" %}
-If you'd like to avoid repeating your frequently used variables
-over and over, you can define [front matter defaults](/docs/configuration/front-matter-defaults) for them and only override them where necessary (or not at all). This works
-both for predefined and custom variables.
-{% endrendercontent %}
+{%@ Note do %}
+ #### Don't repeat yourself
-{% toc %}
+ If you'd like to avoid repeating your frequently used variables over and over, you can define [front matter defaults](/docs/content/front-matter-defaults) for them and only override them where necessary (or not at all). This works both for predefined and custom variables.
+{% end %}
+
+{{ toc }}
## Using Front Matter
@@ -37,12 +37,13 @@ for a reference) or add custom variables of your own. These variables will
then be available to you to access using Liquid tags both further down in the
file and also in any layouts or components that the file in question relies on.
-{% rendercontent "docs/note", title: "Front matter variables are optional" %}
+{%@ Note do %}
+ #### Front matter variables are optional
If you want to use [Liquid tags and variables](/docs/variables/)
but don’t need anything in your front matter, just leave it empty! The set
of triple-dashed lines with nothing in between will still get Bridgetown to
process your file. (This is useful for things like RSS feeds.)
-{% endrendercontent %}
+{% end %}
## Predefined Global Variables
@@ -73,7 +74,7 @@ front matter of a page or document.
null will produce a file without using a layout
file. This is overridden if the file is a document and has a
- layout defined in the
+ layout defined in the
front matter defaults.
+
+```
+
+will look for `frontend/images/folder/somefile.png`.
+
+## esbuild Setup
+
+The default configuration is defined in `config/esbuild.defaults.js`. However, you should add or override your own config options in the top-level `esbuild.config.js` file.
+
+_More documentation coming soon!_
+
+## Webpack Setup
+
+The default configuration is defined in `config/webpack.defaults.js`. However, you should add or override your own config options in the top-level `webpack.config.js` file.
+
+The default configuration can be updated to the latest version provided by Bridgetown using the `webpack` CLI tool:
+
+```shell
+bin/bridgetown webpack update
+```
+
+All options provided by the `webpack` CLI tool can be viewed by running:
+```shell
+bin/bridgetown webpack
```
-## Multiple Entry Points
+### Multiple Entry Points
If you need to manage more than one Webpack bundle, you can add additional entry points to the `webpack.config.js` file (in Bridgetown 0.20 and above). For example:
@@ -168,9 +149,9 @@ If you need to manage more than one Webpack bundle, you can add additional entry
config.entry.somethingElse = "./frontend/otherscript/something_else.js"
```
-Then simply reference the entry point filename via `webpack_path` wherever you'd like to load it in your HTML:
+Then simply reference the entry point filename via `asset_path` wherever you'd like to load it in your HTML:
```liquid
-
+
```
{% endraw %}
diff --git a/bridgetown-website/src/_docs/index.md b/bridgetown-website/src/_docs/index.md
index 1c9a2afc4..37c85f330 100644
--- a/bridgetown-website/src/_docs/index.md
+++ b/bridgetown-website/src/_docs/index.md
@@ -1,77 +1,79 @@
---
-order: 1
+order: 10
title: Getting Started
top_section: Introduction
category: intro
---
-In a nutshell, Bridgetown is a **static site generator**. You give it text written in an author-friendly markup language like Markdown, and it uses layouts and templates to build a website and save the compiled HTML, CSS, and JavaScript to an output folder. You can tweak how you want the pages to look, what data gets displayed on the site, and more.
+Excited to get started? Woohoo! In case you're wondering, Bridgetown is a **progressive site generator**. You add content written in an author-friendly markup language like Markdown, alongside layouts and components using template syntax such as Liquid or ERB, and Bridgetown will then compile HTML, CSS, and JavaScript to an output website folder. You can tweak exactly how you want the pages to look, what data gets displayed on the site, and more. Bridgetown is powered by the Ruby programming language, as well as Node for JavaScript-based processing of your frontend assets. Bridgetown [started life as a Jekyll fork](/news/time-to-visit-bridgetown/) in early 2020, but it has since grown into so much more.
-Bridgetown works best as part of a version-controlled repository powered by Git. You can centrally store your repository on a service like [GitHub](https://github.com) so that you and everyone else working on the website (plus your hosting provider) all have direct, secure access to the latest website content and design files.
+We'll explain much more about what Bridgetown is and what it can do for you in the sections ahead. Let's go!
-During the development process, you will likely be running Bridgetown from the command line on your local developer machine (or perhaps a remote staging server). Once content is ready to publish, you would commit your website codebase to the Git repository and use an automated build tool to generate and upload the final output to a server or CDN (Content Delivery Network). [Render](https://www.render.com) is a popular service for this, but there are many others. You can also just literally copy the generated files contained in the `output` folder to any HTTP web server and it should Just Work. 😊
-
-For more background on this development approach, [read up on our Jamstack primer](/docs/jamstack/).
-
-For a succinct overview of how the Bridgetown build process works and what goes into creating a site, [read our Core Concepts guide](/docs/core-concepts/).
-
-## Quick Instructions {% if site.data.edge_version %}(EDGE RELEASE){% endif %}
+## Quick Instructions {% if site.data.edge_version %}(EDGE RELEASE){% end %}
{% if site.data.edge_version %}
- {% rendercontent "docs/note", type: "warning" %}
+ {%@ Note type: "warning" do %}
If you don't want to use the latest edge version of Bridgetown, [switch to the stable release documentation](https://www.bridgetownrb.com/docs/).
- {% endrendercontent %}
-{% endif %}
-
-{% rendercontent "docs/note" %}
- Upgrading from v0.x? [Read our 1.0 upgrade notes here.](/release/era-of-bridgetown-v1/#upgrading-from-v02x){:data-no-swup="true"}
-{% endrendercontent %}
-
-Read [requirements]({{ '/docs/installation' | relative_url }}) for more information on what you'll need to have set up in advance.
-
-The basic installation process is as follows:
+ {% end %}
+{% end %}
-1. Install a **Ruby** development environment which is supported by Bridgetown.
+{%@ Note do %}
+ Upgrading from v0.x? [Read our 1.0 upgrade guide here.](/docs/installation/upgrade)
+{% end %}
-2. Install **Node** and **Yarn** to handle frontend assets and spin up a live-reload development server.
+Read the [requirements](/docs/installation) for more information on what you'll need to have set up in advance, primarily **Ruby** and **Node**/**Yarn**. Then:
-3. Install **Bridgetown** and related gems:
-{%- if site.data.edge_version %}
+1. Install **Bridgetown** and related gems:
+{%- if site.data.edge_version -%}
```
-$ gem install bridgetown -N -v {{ bridgetown.version }}
+$ gem install bridgetown -N -v {{ Bridgetown::VERSION }}
```
-{%- else %}
+{%- else -%}
```
$ gem install bridgetown -N
```
-{%- endif %}
+{%- end -%}
-4. Create a new Bridgetown site at `./mysite`.
+2. Create a new Bridgetown site at `./mysite`.
```
$ bridgetown new mysite
```
-5. Change into your new directory.
+3. Change into your new directory.
```
$ cd mysite
```
-6. Build the site and run a live-reload development server:
+4. Build the site and run a live-reload development server:
```
$ bin/bridgetown start
```
-7. Browse to [http://localhost:4000](http://localhost:4000){:target="_blank"}
+5. Browse to [http://localhost:4000](http://localhost:4000){:target="_blank"}
-8. And you're done! (That's the goal at least 😊)
+6. And you're done! (That's the goal at least 😊)
-If you encounter any errors during this process, try revisiting your installation and setup steps, and if all else fails, [reach out to the Bridgetown community for support](/docs/community/). Also, make sure you've installed the development headers and other prerequisites as mentioned in the [Requirements](/docs/installation/#requirements) section.
+{%@ Note do %}
+Detailed installation instructions for macOS, Ubuntu Linux, Fedora Linux and Windows 10 are [available here](/docs/installation).
+{% end %}
-{% rendercontent "docs/note" %}
-More detailed installation instructions for macOS, Ubuntu Linux, Fedora Linux and Windows 10 are [available here](/docs/installation/#guides).
-{% endrendercontent %}
+{%@ Note do %}
+Prefer ERB or Serbea over Liquid? Prefer Webpack over esbuild? Prefer Sass over vanilla CSS? [Read about the available `new` options here](/docs/command-line-usage).
+{% end %}
-Bridgetown comes with the `bridgetown` CLI tool as well as several Yarn scripts,
+{%@ Note type: :warning do %}
+Still stuck? [Please reach out to the Bridgetown community for support](/community). What might take you three hours to eventually figure out could take a mere 10 minutes with the right pointers!
+{% end %}
+
+Bridgetown comes with the `bridgetown` CLI tool as well as a few Rake tasks and Yarn scripts,
so be sure to read up on the [command line usage documentation](/docs/command-line-usage).
-Also read up on [Bridgetown's Core Concepts](/docs/core-concepts/) to gain familiarity with the basic building blocks and workflow of Bridgetown.
+## More About the Tech Specs
+
+Bridgetown is sometimes called a "static site generator" or a "Jamstack" web framework. We think it's simpler to think in terms of _progressive generation_ — the idea that the moment at which your over-the-wire HTML & JSON is generated can vary, depending on the method you choose to use on a route-by-route basis as well as the architecture of your frontend. Bridgetown starts off in SSG (Static Site Generation) mode, and you can opt-into SSR (Server-Side Rendering) mode only if and when you need it. And depending on your choice of frontend tooling, you can leverage CSR (Client-Side Rendering) along with hydration techniques to add highly dynamic and interactive experiences—without compromising on base site speed and efficiency.
+
+Bridgetown works best as part of a version-controlled repository powered by Git. You'll likely want to store your repository on a service like [GitHub](https://github.com) so that you and everyone else working on the website (plus your hosting provider) all have direct, secure access to the latest website content and design files.
+
+During the development process, you'll run Bridgetown from the command line on your local development machine (or perhaps a remote staging server). Once content is ready to publish, you'll want to commit your website codebase to the Git repository and use an automated build tool to generate and upload the final output to a server or CDN (Content Delivery Network). [Render](https://www.render.com) is a popular service for this, but there are many others. You can also just literally copy the generated files contained in the `output` folder to any HTTP web server and it should Just Work. 😊
+
+For more details on how the Bridgetown build process works and what goes into creating a site, continue on to read our **Core Concepts** guide.
diff --git a/bridgetown-website/src/_docs/installation.md b/bridgetown-website/src/_docs/installation.md
index 99f605f1e..0362d9672 100644
--- a/bridgetown-website/src/_docs/installation.md
+++ b/bridgetown-website/src/_docs/installation.md
@@ -1,15 +1,16 @@
---
-order: 3
+order: 40
title: Installation Guides
description: Official guides to install Bridgetown on macOS, GNU/Linux or Windows.
top_section: Setup
-category: installation
+category: installation-guides
---
Bridgetown is software written in Ruby, a friendly programming language that maximizes programmer happiness and makes it easy to build and customize open source projects. You will need to install Bridgetown as a Gem after you set up your Ruby language environment. You will also need to install Node and Yarn to manage your website's frontend assets.
-{:.note}
+{%@ Note do %}
For a quick summary of how to install Bridgetown, read [Getting Started](/docs/). What follows are more in-depth guides to setting up your developer or server environments.
+{% end %}
## Requirements
@@ -18,11 +19,14 @@ Ubuntu Linux, and Ubuntu for Windows will help you install them.
* [GCC](https://gcc.gnu.org/install/) and [Make](https://www.gnu.org/software/make/)
(which you can check by running `gcc -v`,`g++ -v` and `make -v`).
+
* [Ruby](https://www.ruby-lang.org/en/downloads/) version
**{{ site.data.requirements.min_ruby }}** or above (ruby version can be checked by
running `ruby -v`)
+
* [Node](https://nodejs.org) version **{{ site.data.requirements.min_node }}** or
above (which you can check by running `node -v`)
+
* [Yarn](https://yarnpkg.com) (which you can check by running `yarn -v`)
## Guides
@@ -30,7 +34,11 @@ Ubuntu Linux, and Ubuntu for Windows will help you install them.
For detailed installation instructions, take a look at the guide for your operating
system:
-* [macOS](/docs/installation/macos/)
-* [Fedora Linux](/docs/installation/fedora/)
-* [Ubuntu Linux](/docs/installation/ubuntu/)
-* [Windows (via Linux Subsystem + Ubuntu)](/docs/installation/windows/)
+* [macOS](/docs/installation/macos)
+* [Fedora Linux](/docs/installation/fedora)
+* [Ubuntu Linux](/docs/installation/ubuntu)
+* [Windows (via Linux Subsystem + Ubuntu)](/docs/installation/windows)
+
+## Upgrading?
+
+We now have an [official upgrade guide](/docs/installation/upgrade) for migrating your Bridgetown v0.2x website to v1.0.
diff --git a/bridgetown-website/src/_docs/installation/fedora.md b/bridgetown-website/src/_docs/installation/fedora.md
index bca8afed0..e9e90251e 100644
--- a/bridgetown-website/src/_docs/installation/fedora.md
+++ b/bridgetown-website/src/_docs/installation/fedora.md
@@ -1,7 +1,8 @@
---
title: Bridgetown on Fedora
-hide_in_toc: true
-category: installation
+top_section: Setup
+category: installation-guides
+back_to: installation
ruby_version: 3.0.2
order: 0
---
@@ -101,4 +102,4 @@ yarn -v
```
-{% render "docs/install/bridgetown", version: bridgetown.version, edge_version: site.data.edge_version %}
+{%@ "docs/install/bridgetown" %}
diff --git a/bridgetown-website/src/_docs/installation/macos.md b/bridgetown-website/src/_docs/installation/macos.md
index 9d76fbe87..b9ed65cbe 100644
--- a/bridgetown-website/src/_docs/installation/macos.md
+++ b/bridgetown-website/src/_docs/installation/macos.md
@@ -1,7 +1,8 @@
---
title: Bridgetown on macOS
-hide_in_toc: true
-category: installation
+top_section: Setup
+category: installation-guides
+back_to: installation
ruby_version: 3.0.2
order: 0
---
@@ -90,11 +91,11 @@ gem env
And check that `SHELL PATH:` includes to a path to `~/.gem/ruby/X.X.0/bin`
-{% rendercontent "docs/note" %}
+{%@ Note do %}
Every time you update Ruby to a version with a different first two digits, you will need to update your path to match.
You will also need to add `--user-install` to any `gem install` statement you run.
-{% endrendercontent %}
+{% end %}
## Install Node & Yarn {#node}
@@ -117,4 +118,4 @@ node -v
yarn -v
```
-{% render "docs/install/bridgetown", version: bridgetown.version, edge_version: site.data.edge_version %}
+{%@ "docs/install/bridgetown" %}
diff --git a/bridgetown-website/src/_docs/installation/ubuntu.md b/bridgetown-website/src/_docs/installation/ubuntu.md
index b2e335e23..28b0326df 100644
--- a/bridgetown-website/src/_docs/installation/ubuntu.md
+++ b/bridgetown-website/src/_docs/installation/ubuntu.md
@@ -1,7 +1,8 @@
---
title: Bridgetown on Ubuntu
-hide_in_toc: true
-category: installation
+top_section: Setup
+category: installation-guides
+back_to: installation
ruby_version: 3.0.2
order: 0
---
@@ -81,5 +82,5 @@ ruby -v
And that's it! Check out [rbenv command references](https://github.com/rbenv/rbenv#command-reference) to learn how to use different versions of Ruby in your projects.
-{% render "docs/install/node_on_linux" %}
-{% render "docs/install/bridgetown", version: bridgetown.version, edge_version: site.data.edge_version %}
+{%@ "docs/install/node_on_linux" %}
+{%@ "docs/install/bridgetown" %}
diff --git a/bridgetown-website/src/_docs/installation/upgrade.md b/bridgetown-website/src/_docs/installation/upgrade.md
new file mode 100644
index 000000000..c6c667f8b
--- /dev/null
+++ b/bridgetown-website/src/_docs/installation/upgrade.md
@@ -0,0 +1,48 @@
+---
+title: Upgrading from v0.2x
+top_section: Setup
+category: installation-guides
+back_to: installation
+order: 0
+---
+
+To upgrade your existing Bridgetown site to 1.0, you’ll need to specify the new version in your Gemfile:
+
+```ruby
+gem "bridgetown", "~> {{ Bridgetown::VERSION }}"
+```
+
+You’ll also need to add Puma to your Gemfile:
+
+```ruby
+gem "puma", "~> 5.5"
+```
+
+Then run `bundle install`. (You’ll also want to upgrade to the latest version of any extra plugins you may have added, such as the feed and seo plugins.)
+
+Next you should run `bundle binstubs bridgetown-core` so you have access to `bin/bridgetown`, as this is now the canonical way of accessing the Bridgetown CLI within your project.
+
+You will need to add a few additional files to your project, so we suggest using `bridgetown new` to create a separate project, then copy these files over:
+
+* `config.ru`
+* `Rakefile`
+* `config/puma.rb`
+* `server/*`
+
+Finally, you can remove `start.js` and `sync.js` and well as any scripts in `package.json` besides `webpack-build` and `webpack-dev` (and you can also remove the `browser-sync` and `concurrently` dev dependencies in `package.json`).
+
+Going forward, if you need to customize any aspect of Bridgetown’s build scripts or add your own, you can alter your `Rakefile` and utilize Bridgetown’s automatic Rake task support.
+
+{%@ Note type: :warning do %}
+ Your plugins folder will now be loaded via Zeitwerk by default. This means you'll need to namespace your Ruby files using certain conventions or reconfigure the loader settings. [Read the documentation here](/docs/plugins#zeitwerk-and-autoloading).
+{% end %}
+
+The other major change you’ll need to work on in your project is switching your plugins/templates to use resources. There’s a fair degree of [documentation regarding resources here](/docs/resources). In addition, if you used the Document Builder API in the past, you’ll need to upgrade to the [Resource Builder API](/docs/plugins/external-apis).
+
+{%@ Note do %}
+#### Get That Live Reloading Going Again
+
+The live reloading mechanism in v1.0 is no longer injected automatically into your HTML layout, so you'll need to add `{%% live_reload_dev_js %}` (Liquid) or `<%= live_reload_dev_js %>` (ERB) to your HTML head in order to get live reload working. Please make sure you've added `BRIDGETOWN_ENV=production` as an environment variable to your production deployment configuration so live reload requests won't be triggered on your public website.
+{% end %}
+
+We’ve added an **upgrade-help** channel in our [Discord chat](https://discord.gg/4E6hktQGz4) so if you get totally suck, the community can give you a leg up! (Access to the problematic repo in question is almost always a given in order to troubleshoot, so if your code needs to remain private, please create a failing example we can access on GitHub.)
diff --git a/bridgetown-website/src/_docs/installation/windows.md b/bridgetown-website/src/_docs/installation/windows.md
index 55d9e139d..a4c645ab4 100644
--- a/bridgetown-website/src/_docs/installation/windows.md
+++ b/bridgetown-website/src/_docs/installation/windows.md
@@ -1,15 +1,16 @@
---
title: Bridgetown on Windows
-hide_in_toc: true
-category: installation
+top_section: Setup
+category: installation-guides
+back_to: installation
order: 0
---
-{% render "docs/help_needed", page: page %}
+{%@ "docs/help_needed", resource: resource %}
The easiest way to use Bridgetown on Windows is to install the _Windows Subsystem for Linux_. This provides a Linux development environment in which you can install Bash, Ruby, and other tools necessary to run Bridgetown in an optimized fashion.
Try reading [these excellent instructions by GoRails](https://gorails.com/setup/windows/10) to install Ubuntu Linux on Windows, and then once you've reached the "**Installing Rails**" portion, you can come back and continue:
-{% render "docs/install/node_on_linux" %}
-{% render "docs/install/bridgetown", version: bridgetown.version, edge_version: site.data.edge_version %}
+{%@ "docs/install/node_on_linux" %}
+{%@ "docs/install/bridgetown" %}
diff --git a/bridgetown-website/src/_docs/jamstack.md b/bridgetown-website/src/_docs/jamstack.md
deleted file mode 100644
index 7e39cbeb2..000000000
--- a/bridgetown-website/src/_docs/jamstack.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-title: What’s a Jamstack?
-order: 22
-top_section: Philosophy
-category: jamstack
----
-
-According to [Jamstack.org](https://jamstack.org), it's a unique approach to building websites and software for the web:
-
-{:.my-8}
-> **Fast and secure sites and apps delivered by pre-rendering files and serving them directly from a CDN, removing the requirement to manage or run web servers.**
-
-Jamstack sites deliver better performance, higher security, lower cost of scaling, and a superior developer experience.
-
-## Comparison
-
-How does the Jamstack compare with another type of system, such as a monolithic CMS (Content Management System) like WordPress or a bespoke application built in a framework like Ruby on Rails?
-
-* **Single App Stack: Built Upon Each Request.** WordPress, Ruby on Rails, Node, Squarespace, etc. are all designed to run as server software that delivers website content to site visitors at the moment they request it. In other words, when a web browser goes to a specific page, the server software has to generate that page on the spot and send it to the browser.
-
-* **Jamstack: Pre-Built When Content Updates.** A Jamstack website is instead served from a CDN (Content Delivery Network) or standard filesystem rather than a dynamic application server. That means when a visitor opens up a Jamstack site, the essential design and content is _not being generated_ on-the-fly, but rather is coming from a _recent, pre-built_ static snapshot. The speed at which that data transfer can happen and the simplicity of scaling that solution to thousands or even millions of users is an order of magnitude simpler (and cheaper) than the dynamic server approach.
-
-* **Jamstack Interactivity is Added On.** If you do need to add interactivity and fresh real-time information to a Jamstack site, you would need to use JavaScript to load data from an API (Application Programming Interface). You can build an API yourself or employ any number of third-party APIs (including public data services). Using the web development best practice known as _Progressive Enhancement_, you'd build your site for the static snapshot use case **first**, and then add layers of additional interactivity on top **second** (with the goal being any sort of temporary API failure won't terribly degrade the basic website experience).
-
-{:.mt-12}
-## "JAM" (JavaScript, APIs, Markup) Stack
-
-Because **Bridgetown** is a Jamstack framework/site generator, this is how you'd go about developing a website. The process is essentially reversed from the catchy acronym JAM: you start with the markup and work your way up to dynamic frontend functionality.
-
-**Markup.** You start by defining the HTML templates of your website and writing CSS to lay elements out on the page, set typography, and add other graphical enhancements. You author content (blog posts, informational pages, structured data collections, etc.) in simple formats like Markdown, YAML, CSV, JSON, etc., and that content gets automatically converted to final HTML whenever **Bridgetown** is instructed to build the site for deployment.
-
-**APIs.** If you need to pull in data from external sources, or interact with online services via user input, you'll need to find or write one or more APIs. APIs come in many shapes and sizes. Since **Bridgetown** is written in Ruby, one possibility is to use Ruby on Rails to build a custom API, and then use that API either during the website build process (thus "baking" the API's data into the static snapshot for deployment) or on-the-fly via JavaScript (see below). But you can write an API using virtually any language or framework… Node, Python, Go, you name it. Or find a third-party web service which lets you use or adapt existing APIs.
-
-**JavaScript.** The final piece of the puzzle…frontend JavaScript lets you write interactive components and modules that add fresh information to a webpage, capture and process input from users, and otherwise enhance the functionality of your website. Remember, it's best to try as much as possible to provide a working site _without_ JavaScript running, and then use JavaScript to add new features on top of the basic experience. There are many popular JavaScript frameworks available, and by utilizing the Webpack bundler tool, **Bridgetown** lets you easily add one of your choosing—whether it be [Stimulus](https://stimulusjs.org), [Alpine](https://github.com/alpinejs/alpine/), [Vue](https://vuejs.org), [React](https://reactjs.org), [LitElement](https://lit-element.polymer-project.org), or vanilla [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components).
-
-{:.mt-12}
-## How Do You Edit and Publish Content with the Jamstack?
-
-There are typically three different ways to author, manage, save, and publish website content when working with Jamstack sites. Some are easier for programmers, others are easier for visually-focused content creators and editors.
-
-1. **Save Files in the Git Repository.** Because Jamstack sites are typically located in a version-controlled code repository using Git, and saved onto a central repo service such as GitHub, you can clone the site files directly to your device, add Markdown posts and other site content, and _commit_ those changes to the repository. Once you _push_ those changes back up to GitHub (for example), that usually triggers an automated build process to publish the latest changes to the web. Jamstack-focused services such as [Render](https://www.render.com) are a great way to build and publish the website. Unlike hosting services of the past, Render's starting price can't be beat: **it's free** 😁.
-
-1. **Use a CMS-like editing interface.** There is a growing number of tools which provide a familiar visual editing interface on the web, but under the hood modify the same files in the repo (Markdown posts, data collections, etc.) much like the first process above. Examples of these kinds of tools are Forestry, Siteleaf, Netlify CMS, and many others.
-
-1. **Store content inside a "headless" CMS.** This utilizes a process closest to the previous era of dynamic CMS applications. With what's called a "headless" CMS, you author content interactively using the CMS, and content is stored in that CMS' database. When content is ready to get published, a build process is triggered for the Jamstack site generator (aka **Bridgetown**), but at that point the generator uses the headless CMS' API to download all relevant data and produce the final website for deployment. There are many headless CMS tools available, and you can even use WordPress itself as one! (Although that's not typically recommended… 😋)
-
-{:.mt-12}
-## How Do I Get Started Building a Jamstack Website?
-
-We're biased, of course, but our recommendation is simple: install **Bridgetown**, run `bridgetown new` to create a blank site repository, and start customizing your HTML templates, adding a fun CSS framework like Bulma or Tailwind, and authoring some content. Once you have something you like, simply push the repository up to GitHub, connect the repo up to a Jamstack hosting service like Render, and deploy. That might sound like a daunting sequence of steps, but once you get the hang of it the whole process might only take up a breezy afternoon. (Some of us remember spending hours just wrestling with MySQL databases and WordPress theme files! The future is bright, folks! 😃🎉)
-
-{:.has-text-centered.mt-10}
-[Get Started](/docs/){:.button.is-large.is-info}
-
diff --git a/bridgetown-website/src/_docs/layouts.md b/bridgetown-website/src/_docs/layouts.md
index a6efcdb05..d04e66ee4 100644
--- a/bridgetown-website/src/_docs/layouts.md
+++ b/bridgetown-website/src/_docs/layouts.md
@@ -1,7 +1,7 @@
---
title: Layouts
-order: 9
-top_category: Structure
+order: 150
+top_section: Designing Your Site
category: layouts
---
@@ -9,9 +9,9 @@ Layouts are templates that wrap around your [resource's content](/docs/resources
Layouts live in the `_layouts` folder. The convention is to have a base template called `default.html` and have other layouts [inherit](#inheritance) from this as needed.
-{% rendercontent "docs/note" %}
+{%@ Note do %}
While you can configure the folder name in which your layouts can reside by setting the `layouts_dir` key in your config file, the folder itself should be located at the root of your site's `source` folder.
-{% endrendercontent %}
+{% end %}
## Usage
@@ -80,11 +80,11 @@ The rendered output of this resource then is:
```
-You can also use [front matter defaults](/docs/configuration/front-matter-defaults/) to to avoid having to set a layout explicitly for every resource. Note that if you have defaults in place and you _don't_ want a certain resource to render in a layout, you can specify `layout: none` in the resource's front matter.
+You can also use [front matter defaults](/docs/content/front-matter-defaults/) to to avoid having to set a layout explicitly for every resource. Note that if you have defaults in place and you _don't_ want a certain resource to render in a layout, you can specify `layout: none` in the resource's front matter.
-{% rendercontent "docs/note" %}
- If you you're using ERB or another Ruby template language for your layout, try using the more idiomatic `yield` instead of `content`. Refer to the [ERB and Beyond](/docs/erb-and-beyond) docs for further details.
-{% endrendercontent %}
+{%@ Note do %}
+ If you you're using ERB or another Ruby template language for your layout, try using the more idiomatic `yield` instead of `content`. Refer to the [ERB and Beyond](/docs/template-engines/erb-and-beyond) docs for further details.
+{% end %}
## Inheritance
diff --git a/bridgetown-website/src/_docs/liquid.md b/bridgetown-website/src/_docs/liquid.md
deleted file mode 100644
index 78e6cb93c..000000000
--- a/bridgetown-website/src/_docs/liquid.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Liquid
-order: 18.5
-next_page_order: 19
-top_section: Templates
-category: liquid
----
-
-Bridgetown provides comprehensive support for rich presentation of data and design via the **Liquid** template language, available within documents as well as layouts and [components](/docs/components). If you find that Liquid doesn't suit your needs when building your site templates, [Bridgetown also allows for using ERB (Embedded RuBy)](/docs/erb-and-beyond). You can mix and match ERB and Liquid templates freely throughout your site.
-
-Generally in Liquid you output content using two curly braces e.g.
-{% raw %}`{{ variable }}`{% endraw %} and perform logic statements by
-surrounding them in a curly brace percentage sign e.g.
-{% raw %}`{% if statement %}`{% endraw %}. To learn more about Liquid, check
-out the [official Liquid Documentation](https://shopify.github.io/liquid/).
-
-The ability to use Liquid within Markdown in posts and pages allows for truly advanced customization of your content pipeline. For example, you can write custom Liquid [tags](/docs/plugins/tags) and [filters](/docs/plugins/filters) and use them throughout your site.
-
-In addition to Liquid's standard suite of filters and tags, Bridgetown provides a number of useful additions to help you build your site:
-
-|
{{ filter.name }} - {{- filter.description -}} + {{ filter.description | safe }} |
- {%- for example in filter.examples %}
+ {% filter.examples.each do |example| %}
|
{% raw %} and {% endraw %} tags
around your code. If needed, you can add `render_with_liquid: false` in your
front matter to disable Liquid entirely for a particular document.
-{% endrendercontent %}
+{% end %}
-{% rendercontent "docs/note" %}
+{%@ Note do %}
You can also use fenced code blocks in Markdown (starting and ending with three
backticks ```) instead of using the `highlight` tag. However, the
`highlight` tag includes additional features like line numbers (see below).
-{% endrendercontent %}
+{% end %}
### Line numbers
diff --git a/bridgetown-website/src/_docs/pages.md b/bridgetown-website/src/_docs/pages.md
deleted file mode 100644
index 611410aa5..000000000
--- a/bridgetown-website/src/_docs/pages.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Pages
-order: 10.5
-next_page_order: 11
-top_section: Content
-category: pages
-hide_in_toc: true
----
-
-{% rendercontent "docs/note", type: "warning" %}
-The page as a distinct content type has been removed in Bridgetown 1.0. Read about the new [resource content engine](/docs/resources) to learn more about how to create pages and other types of content in v1.0.
-{% endrendercontent %}
diff --git a/bridgetown-website/src/_docs/philosophy.md b/bridgetown-website/src/_docs/philosophy.md
index df95f8eab..227994a30 100644
--- a/bridgetown-website/src/_docs/philosophy.md
+++ b/bridgetown-website/src/_docs/philosophy.md
@@ -1,11 +1,17 @@
---
-title: Project Goals
-order: 21
-top_section: Philosophy
+title: Our Philosophy
+order: 30
+top_section: Introduction
category: philosophy
---
-Every successful open source project has a certain "vibe", those thought patterns and behaviors which ensure meaningful, constant progress forward and the growth of a vibrant developer community. Our project is young, but we feel it's important to start off with a few basic principles and work out way out from here.
+Every successful open source project has a certain "vibe", those thought patterns and behaviors which ensure meaningful, constant progress forward and the growth of a vibrant developer community. Our project may be relatively young, yet we feel it's important to lead with a set of basic principles what will help guide the project long into the future.
+
+(This page is lengthy, so [feel free to skip over to the next section of documentation](/docs/installation)!)
+
+{{ toc }}
+
+## Core Principles
* **Move fast but try really hard not to break things.** Most developer-focsued software projects err on a side…either the side of extreme backwards-compatibility with past versions, or the side of evolving quickly and requiring devs to go through multiple rounds of ["yak shaving"](http://projects.csail.mit.edu/gsb/old-archive/gsb-archive/gsb2000-02-11.html) when upgrading to new versions.
@@ -15,8 +21,59 @@ Every successful open source project has a certain "vibe", those thought pattern
* **Convention over configuration.** Again, to take a cue from that other popular Ruby-based framework (😉), we strongly believe Bridgetown should encourage powerful defaults and best-practice conventions to give website developments an instant leg up as they start new projects. If you have to go fishing for a bunch of extra plugins and add a slew of extra libraries and reconfigure settings just to complete basic setup tasks, we're doing it wrong.
-* **Grow the Ruby ecosystem.** We're unabashed fans of Ruby and consider it our duty to promote and grow the Ruby ecosystem as part of our work on Bridgetown. This includes contributing Ruby code of course, but it also includes developer advocacy and education. Other languages like Go are popular because they're speedy, or JavaScript because it's, well, JavaScript—but Ruby continues to be a strong contender because [it optimizes for programmer happiness](https://basecamp.com/gettingreal/10.2-optimize-for-happiness). We hope that some day when a Ruby beginner wants to get their feet wet, they'll start by reaching for Bridgetown and writing a custom plugin or two for their website.
+* **Grow the Ruby ecosystem.** We're unabashed fans of Ruby and consider it our duty to promote and grow the Ruby ecosystem as part of our work on Bridgetown. This includes contributing Ruby code of course, but it also includes developer advocacy and education. Other languages like Go are popular because they're super speedy, or JavaScript because it's, well, JavaScript—but Ruby continues to be a strong contender because [it optimizes for programmer happiness](https://basecamp.com/gettingreal/10.2-optimize-for-happiness). We hope that some day when a Ruby beginner wants to get their feet wet, they'll start by reaching for Bridgetown and writing a custom plugin or two for their website.
+
+* **Be a leader in Jamstack-style technology** (_without being constrained by it_)**.** Bridgetown's progenitor ([Jekyll](https://jekyllrb.com)) played a significant role in kicking off the modern explosion of the "Jamstack" due to its static generation bona fides. In fact, there might not _be_ a Jamstack today if Jekyll's popularity as the technology powering GitHub Pages hadn't caught fire in the early 2010s. Our sincere wish is that Bridgetown would play a unique and vital role in the continued expansion of this exciting way of building and deploying websites, while also identifying and correcting ways we feel the Jamstack space has strayed too far from its inaugural mission. (For instance, we're _skeptical_ of building complex fullstack applications using serverless functions. It's a solution in search of a problem not everyone has, and it's often promoted by the very hosting companies who benefit from increased usage of serverless functions _because they offer no alternative_. Buyer beware!)
+
+## A Brief History of Bridgetown
+
+Bridgetown started life as a fork of the granddaddy of static site generators, [Jekyll](https://jekyllrb.com). Jekyll came to prominence in the early 2010s due to its slick integration with GitHub, powering thousands of websites for developer tools. In the years since it has grown to provide a popular foundation for a wide variety of sites across the web.
+
+But as the concepts of modern static site generation and the "Jamstack" came to the forefront, a whole new generation of tools rose up, like [Hugo](https://gohugo.io), [Eleventy](https://www.11ty.dev), [Next.js](http://nextjs.org), and many more. In the face of all this new competition, Jekyll chose to focus on maintaining extensive backwards-compatibility and a paired-down feature set—noble goals for an open source project generally speaking, but ones that were at odds with meaningful portions of the web developer community.
+
+So in March 2020, Portland-based web studio [Whitefusion](https://www.whitefusion.studio) started on **Bridgetown**, a fork of Jekyll with a brand new set of project goals and a future roadmap. Whitefusion's multi-year experience producing and deploying numerous Jekyll-based websites furnishes a seasoned take on the unique needs of web agencies and their clients. In the intervening months since, we've seen this strategy pay off in a big way.
+
+Bridgetown has grown considerably since its inception, but in many ways, we're just getting started. We hope you [join our community](/community), build something awesome with Bridgetown, and share it with the world!
+
+## Future Project Roadmap
+
+In late 2021, we crafted a new roadmap for our work on Bridgetown's underlying technologies as well as "marketing" focus heading into 2022. Bear in mind many of the plans outlined below are already present and built into Bridgetown v1.0. But to recap:
+
+We are organizing our work around these three tracks:
+
+* The Platform Track
+* The Content Authoring Track
+* The Experiences Track
+
+### The Platform Track
+
+These are the core architectural features Bridgetown needs to be successful across all site builds and deployments.
+
+Included in this track are:
+
+* Switching the built-in server from WEBrick to Rack + Puma, along with Roda to handle intelligent serving of static assets (more on Roda below).
+* Migrating away from relying on `yarn` as the principal CLI tool and standardizing around the `bin/bridgetown` stub + Rake integration. (We'll still use Yarn for installing and bundling frontend dependencies.)
+* Putting the finishing touches on a huge effort we’ve been calling “The Great Content Re-alignment” — aka replacing the aging Jekyll-derived content engine with the new Resource engine (which among other things supports conceptual consistency, relationship modeling, and taxonomies).
+* Enabling dynamic rendering of specific data and resources within Bridgetown, thus opening the doors to SSR (Server-Side Rendering) and other fascinating use cases.
+* Resolving a number of deprecations, alterations, and needed fixes in order to arrive at API stability for 1.0 and beyond.
+
+### The Content Authoring Track
+
+These are features needed to make Bridgetown the perfect choice for advanced content authoring requirements.
+
+* Implementing robust multilingual and localization features (i18n), continuing under-the-hood work we’ve already undertaken.
+* Creating integration points and even full gems to provide turn-key solutions for headless CMSes like Prismic and Strapi.
+* Adding advanced interactions with file-based content structures and Git state (think `jekyll-compose` on steroids along with WordPress-style status and revision control)…allowing third-parties to build their own Ruby-based “CMS” solutions.
+* Providing publishing lifecycle and webhooks so Bridgetown seamlessly fits into a larger editorial pipeline.
+
+### The Experiences Track
-* **Be a leader in [Jamstack](/docs/jamstack/) technology.** Bridgetown's progenitor ([Jekyll](https://jekyllrb.com)) played a significant role in kicking off the modern explosion of Jamstack technology. In fact, there might not _be_ a Jamstack today if Jekyll's popularity as the technology powering GitHub Pages hadn't caught fire in the early 2010s. Our sincere wish is that Bridgetown would play a unique and vital role in the continued expansion of this exciting way of building and deploying websites and frontend applications.
+These are features _and_ educational resources needed to improve both the DX (Developer Experience) and UX (User Experience) of Bridgetown-based websites and web applications. This is admittedly the most “fuzzy” category, but nevertheless is a vital aspect of our overall mission.
-For more about the future of Bridgetown, read our [project roadmap](/about/#roadmap) and contribute your ideas and feedback!
\ No newline at end of file
+* Launching an entirely new logo/brand and website for Bridgetown to promote the project, showcase real-world usage, provide world-class documentation to developers, and advocate for Ruby as a premier choice for web developers. **_Done…you're looking at it right now!_**
+* Promotion of well-produced themes and theme-like plugins which give teams a huge leg up in starting new Bridgetown sites.
+* Ensuring Bridgetown defaults, recommended best practices, and officially supported ecosystem tooling are aligned with the latest standards and features of the web platform (high-quality semantic HTML, truly modern framework-less CSS, vanilla JavaScript with optional partial hydration) along with examples of effectively using platform-aligned third-party projects (such as Lit for web components, Hotwire/Turbo for SPA-like navigation and inline updates, etc.).
+* Partnering with and supporting other Ruby-based projects which have goals and use-cases that mesh well with Bridgetown and its approach to web development.
+* Moving ahead with architectural advances which would allow Bridgetown to facilitate site interactivity through a bona fide backend (aka write your serverless-less code here folks!), powered by the wicked-fast [Roda framework](http://roda.jeremyevans.net). This is the ultimate culmination of the DREAMstack concept (Delightful Ruby Expressing APIs & Markup).
+ * Much of the work done for the above will also make Bridgetown + Rails monorepos a legit developer story.
+* Along those lines, researching and pioneering new tools and practices around production deployments so we achieve many of the DX and global performance advantages of Jamstack’s “serverless” principles without the many accompanying downsides. Think CDN-like containerization of the backend, static + backend configurations which build and deploy simultaneously, robust connectivity with distributed databases and key-value stores (aka Redis), and other such concerns.
\ No newline at end of file
diff --git a/bridgetown-website/src/_docs/plugins.md b/bridgetown-website/src/_docs/plugins.md
index d8b752af8..bab10cb95 100644
--- a/bridgetown-website/src/_docs/plugins.md
+++ b/bridgetown-website/src/_docs/plugins.md
@@ -1,6 +1,5 @@
---
-order: 6
-next_page_order: 6.5
+order: 210
title: Extend with Plugins
top_section: Configuration
category: plugins
@@ -17,16 +16,18 @@ for ways to jazz up your website.
Whenever you need more information about the plugins installed on your site and what they're doing, you can use the `bridgetown plugins list` command. You can also copy content out of gem-based plugins with the `bridgetown plugins cd` command. [Read the command reference for further details.](/docs/commands/plugins)
-{% rendercontent "docs/note", title: "Turn Your Plugins into Gems", extra_margin: true %}
-If you'd like to maintain plugin separation from your site source code,
-share functionality across multiple projects, and manage dependencies,
-you can create a Ruby gem for private or public distribution. This is also
-how you'd create a [Bridgetown theme](/docs/themes).
+{%@ Note do %}
+ #### Turn Your Plugins into Gems
-[Read further instructions below on how to create and publish a gem.](#creating-a-gem){:data-no-swup="true"}
-{% endrendercontent %}
+ If you'd like to maintain plugin separation from your site source code,
+ share functionality across multiple projects, and manage dependencies,
+ you can create a Ruby gem for private or public distribution. This is also
+ how you'd create a [Bridgetown theme](/docs/themes).
-{% toc %}
+ [Read further instructions below on how to create and publish a gem.](#creating-a-gem)
+{% end %}
+
+{{ toc }}
## Setup
@@ -137,7 +138,7 @@ end
Bridgetown::MyNiftyPlugin::Builder.register
```
-[Read further instructions below on how to create and publish a gem.](#creating-a-gem){:data-no-swup="true"}
+[Read further instructions below on how to create and publish a gem.](#creating-a-gem)
## Internal Ruby API
@@ -156,11 +157,11 @@ Create custom Liquid tags or "shortcodes" which you can add to your content or d
### [Filters](/docs/plugins/filters)
-Create custom Liquid filters to help transform data and content.
+Provide custom Liquid filters to help transform data and content.
### [Helpers](/docs/plugins/helpers)
-For Tilt-based templates such as [ERB, Slim, etc.](/docs/erb-and-beyond), you can provide custom helpers which can be called from your templates.
+For Ruby-based templates such as ERB, Serbea, etc., you can provide custom helpers which can be called from your templates.
### [HTTP Requests and the Resource Builder](/docs/plugins/external-apis)
@@ -182,7 +183,6 @@ Commands extend the `bridgetown` executable using the Thor CLI toolkit.
Converters change a markup language from one format to another.
-{:.mt-8}
#### Priority Flag
You can configure a Legacy API plugin (mainly generators and converters) with a specific `priority` flag. This flag determines what order the plugin is loaded in.
@@ -215,9 +215,10 @@ plugins/my_plugin/woo/zoo.rb -> MyPlugin::Woo::Zoo
You can read more about [Zeitwerk's file conventions here](https://github.com/fxn/zeitwerk#file-structure).
-{% rendercontent "docs/note", title: "Take Me Back" %}
+{%@ Note do %}
+ #### Take Me Back
If you run into any problems with Zeitwerk after upgrading your Bridgetown project from pre-1.0, you can switch to the previous plugin loading method by adding `plugins_use_zeitwerk: false` to your `bridgetown.config.yml`. Or you can try using the `autoloader_collapsed_paths` setting as described below.
-{% endrendercontent %}
+{% end %}
In addition to the `plugins` folder provided by default, **you can add your own folders** with autoloading support! Simply add to the `autoload_paths` setting in your config YAML:
@@ -268,11 +269,7 @@ Bridgetown websites. You'll want to make sure you update the `gemspec`,
plugin to ensure all the necessary metadata and user documentation is present
and accounted for.
-Make sure you [follow these instructions](/docs/plugins/plugins-and-webpack/) to
-integrate your plugin's frontend code with the users' Webpack setup. Also read
-up on [Source Manifests](/docs/plugins/source-manifests/) if you have layouts,
-components, pages, static files, and other content you would like your plugin to
-provide.
+Make sure you [follow these instructions](/docs/plugins/gems-and-frontend/) to integrate your plugin's frontend code with the users' esbuild or Webpack setup. Also read up on [Source Manifests](/docs/plugins/source-manifests/) if you have layouts, components, resources, static files, and other content you would like your plugin to provide.
You can also provide an automation via your plugin's GitHub repository by adding
`bridgetown.automation.rb` to the root of your repo. This is a great way to
@@ -289,34 +286,36 @@ wide. Plus it's a great way to solicit feedback and improvements in the form
of open source code collaboration and discussion.
As always, if you have any questions or need support in creating your plugin,
-[check out our community resources](/docs/community).
+[check out our community resources](/community).
-{% rendercontent "docs/note", title: "Testing Your Plugin" %}
-As you author your plugin, you'll need a way to _use_ the gem within a live
-Bridgetown site. The easiest way to do that is to use a relative local path in
-the test site's `Gemfile`.
+{%@ Note do %}
+ #### Testing Your Plugin
-```ruby
-gem "my-plugin", :path => "../my-plugin", :group => :bridgetown_plugins
-```
+ As you author your plugin, you'll need a way to _use_ the gem within a live
+ Bridgetown site. The easiest way to do that is to use a relative local path in
+ the test site's `Gemfile`.
+
+ ```ruby
+ gem "my-plugin", :path => "../my-plugin", :group => :bridgetown_plugins
+ ```
-You would do something similar in your test site's `package.json` as well (be sure to run [yarn link](https://classic.yarnpkg.com/en/docs/cli/link) so Yarn knows not to install your local path into `node_modules`):
+ You would do something similar in your test site's `package.json` as well (be sure to run [yarn link](https://classic.yarnpkg.com/en/docs/cli/link) so Yarn knows not to install your local path into `node_modules`):
-```json
-"dependencies": {
- "random-js-package": "2.4.6",
- "my-plugin": "../my-plugin"
-}
-```
+ ```json
+ "dependencies": {
+ "random-js-package": "2.4.6",
+ "my-plugin": "../my-plugin"
+ }
+ ```
-You may need to restart your server at times to pick up changes you make
-to your plugin (unfortunately hot-reload doesn't always work with gem-based plugins).
+ You may need to restart your server at times to pick up changes you make
+ to your plugin (unfortunately hot-reload doesn't always work with gem-based plugins).
-Finally, you should try writing some [tests](http://docs.seattlerb.org/minitest/)
-in the `test` folder of your plugin. These tests could ensure your tags, filters,
-and other content are working as expected and won't break in the future as code
-gets updated.
-{% endrendercontent %}
+ Finally, you should try writing some [tests](http://docs.seattlerb.org/minitest/)
+ in the `test` folder of your plugin. These tests could ensure your tags, filters,
+ and other content are working as expected and won't break in the future as code
+ gets updated.
+{% end %}
## Cache API
diff --git a/bridgetown-website/src/_docs/plugins/cache-api.md b/bridgetown-website/src/_docs/plugins/cache-api.md
index 908373b57..f92068378 100644
--- a/bridgetown-website/src/_docs/plugins/cache-api.md
+++ b/bridgetown-website/src/_docs/plugins/cache-api.md
@@ -1,7 +1,7 @@
---
title: Cache API
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
diff --git a/bridgetown-website/src/_docs/plugins/commands.md b/bridgetown-website/src/_docs/plugins/commands.md
index d9e8272ad..5d3b61622 100644
--- a/bridgetown-website/src/_docs/plugins/commands.md
+++ b/bridgetown-website/src/_docs/plugins/commands.md
@@ -1,7 +1,7 @@
---
title: Commands
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
diff --git a/bridgetown-website/src/_docs/plugins/converters.md b/bridgetown-website/src/_docs/plugins/converters.md
index 94c1a2b28..34fd46f62 100644
--- a/bridgetown-website/src/_docs/plugins/converters.md
+++ b/bridgetown-website/src/_docs/plugins/converters.md
@@ -1,7 +1,7 @@
---
title: Converters
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
@@ -9,10 +9,11 @@ If you have a new markup or template language you’d like to use with your site
you can process it by implementing your own converter. The Markdown and ERB
support in Bridgetown is implemented using this very method.
-{% rendercontent "docs/note" title="Remember your Front Matter" %}
-Bridgetown will only convert files that have a YAML header at the top, even for
-converters you add using a plugin.
-{% endrendercontent %}
+{%@ Note do %}
+ #### Remember your Front Matter
+
+ Bridgetown will only convert files that have a YAML or Ruby Front Matter header at the top, even for converters you add using a plugin.
+{% end %}
Below is a converter which will take all posts ending in `.upcase` and process
them using the `UpcaseConverter`:
diff --git a/bridgetown-website/src/_docs/plugins/external-apis.md b/bridgetown-website/src/_docs/plugins/external-apis.md
index cb00bdd67..823d0bf90 100644
--- a/bridgetown-website/src/_docs/plugins/external-apis.md
+++ b/bridgetown-website/src/_docs/plugins/external-apis.md
@@ -1,7 +1,7 @@
---
title: HTTP Requests and the Resource Builder
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
@@ -27,7 +27,7 @@ class LoadPostsFromAPI < SiteBuilder
end
```
-{% toc %}
+{{ toc }}
## Making a Request
@@ -84,9 +84,11 @@ end
Bridgetown comes with the [Faraday Middleware gem](https://github.com/lostisland/faraday_middleware) out-of-the-box and utilizes a few of its options such as following redirects (if necessary). You can `require` additional middleware to add to your Faraday connection if you like. You can also write your own Faraday middleware, but that's an advanced usage and typically not needed.
-{% rendercontent "docs/note", title: "What’s the Deal with HTTP Methods?" %}
-Why is only the HTTP GET method supported? What about POST, PUT, etc.? Well the idea behind making requests as part of the site build process is that it's a one-way data flow: you get data from the API to add to your site, and you don't attempt any remote alterations to that data. If your API requires you to make a request using a method such as POST, please let them know you'd like a GET method as well. As a last resort, you can also use the provided Faraday `connection` object to construct a custom request. See the Faraday documentation for further details.
-{% endrendercontent %}
+{%@ Note do %}
+ #### What’s the Deal with HTTP Methods?
+
+ Why is only the HTTP GET method supported? What about POST, PUT, etc.? Well the idea behind making requests as part of the site build process is that it's a one-way data flow: you get data from the API to add to your site, and you don't attempt any remote alterations to that data. If your API requires you to make a request using a method such as POST, please let them know you'd like a GET method as well. As a last resort, you can also use the provided Faraday `connection` object to construct a custom request. See the Faraday documentation for further details.
+{% end %}
## The Resource Builder
@@ -145,7 +147,7 @@ Another aspect of the Resource Builder to keep in mind is that `content` is a "s
### Customizing Permalinks
-If you'd like to customize the [permalink](/structure/permalinks) of a new resource, you can specifically set the `permalink` front matter variable:
+If you'd like to customize the [permalink](/docs/content/permalinks) of a new resource, you can specifically set the `permalink` front matter variable:
```ruby
add_resource :posts, "blog-post.md" do
diff --git a/bridgetown-website/src/_docs/plugins/filters.md b/bridgetown-website/src/_docs/plugins/filters.md
index 02fa25641..246e847bf 100644
--- a/bridgetown-website/src/_docs/plugins/filters.md
+++ b/bridgetown-website/src/_docs/plugins/filters.md
@@ -1,11 +1,11 @@
---
title: Filters
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
-Filters are simple Ruby methods you can provide to Liquid templates to transform input data in various ways.
+Filters are simple Ruby methods you can provide to [Liquid templates](/docs/template-engines/liquid) to transform input data in various ways.
All methods take at least one argument which represents the input
of the filter, and you can also support multiple method arguments (and even optional ones). The return value will be the output of the filter.
@@ -111,6 +111,6 @@ When using the filters scope, you have access to the Liquid context via `@contex
Filters are great when you want to transform input data from one format to another and potentially allow multiple transformations to be chained together. If instead you simply want to _insert_ a customized piece of content/HTML code into a page, then it's probably better to write a [Tag](/docs/plugins/tags/).
-{% rendercontent "docs/note", extra_margin: true %}
-If you prefer to use the Legacy API (aka `Liquid::Template.register_filter `) to construct Liquid filters, refer to the [Liquid documentation](https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers) here.
-{% endrendercontent %}
+{%@ Note do %}
+ If you prefer to use the Legacy API (aka `Liquid::Template.register_filter `) to construct Liquid filters, refer to the [Liquid documentation](https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers) here.
+{% end %}
diff --git a/bridgetown-website/src/_docs/plugins/gems-and-webpack.md b/bridgetown-website/src/_docs/plugins/gems-and-frontend.md
similarity index 74%
rename from bridgetown-website/src/_docs/plugins/gems-and-webpack.md
rename to bridgetown-website/src/_docs/plugins/gems-and-frontend.md
index 309163fdd..eb5c88292 100644
--- a/bridgetown-website/src/_docs/plugins/gems-and-webpack.md
+++ b/bridgetown-website/src/_docs/plugins/gems-and-frontend.md
@@ -1,14 +1,14 @@
---
-title: Gem-based Plugins and Webpack
-hide_in_toc: true
+title: Gem-based Plugins and the Frontend
order: 0
+top_section: Configuration
category: plugins
---
When authoring a [plugin](/docs/plugins#creating-a-gem){:data-no-swup="true"}
or [theme](/docs/themes) for Bridgetown, you may find
yourself wanting to ensure users of your plugin are able to load in your
-frontend assets through Webpack (such as JavaScript, CSS, etc.) The best way to
+frontend assets through esbuild or Webpack (such as JavaScript, CSS, etc.) The best way to
do this is to set up a `package.json` manifest and [publish your frontend code as a package to the NPM registry](https://docs.npmjs.com/creating-node-js-modules#create-the-file-that-will-be-loaded-when-your-module-is-required-by-another-application).
Let's assume you've been building an awesome plugin called, unsurprisingly,
@@ -29,14 +29,14 @@ includes a `script/release` command you can use to run the test suite, release a
new version of the gem, and release a new version of the NPM package all in one
go. (This will also be present if you set up your plugin using the `bridgetown plugins new` command.)
-{% rendercontent "docs/note", title: "Make sure you update package.json!", type: "warning" %}
-If you bump up your Ruby version number and forget to bump the NPM package version
-at the same time, the packages will get out of sync! So remember always to update
-`version.rb` and `package.json` so they have the same version number.
-{% endrendercontent %}
+{%@ Note type: :warning do %}
+ #### Make sure you update package.json!
+
+ If you bump up your Ruby version number and forget to bump the NPM package version at the same time, the packages will get out of sync! So remember always to update `version.rb` and `package.json` so they have the same version number.
+{% end %}
You will need to instruct your users how to add the plugin's frontend code to their
-Webpack entry points. For example, they might need to update `frontend/javascript/index.js` with:
+esbuild/Webpack entry points. For example, they might need to update `frontend/javascript/index.js` with:
```js
import MyAwesomePlugin from "my-awesome-plugin"
diff --git a/bridgetown-website/src/_docs/plugins/generators.md b/bridgetown-website/src/_docs/plugins/generators.md
index 5ee3a0bf0..0ccf2fb93 100644
--- a/bridgetown-website/src/_docs/plugins/generators.md
+++ b/bridgetown-website/src/_docs/plugins/generators.md
@@ -1,13 +1,13 @@
---
title: Generators
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
-{% rendercontent "docs/note", type: "warning" %}
+{%@ Note type: :warning do %}
Generators are currently deprecated and will be removed in a future version of Bridgetown. If all you're doing is creating new resources, perhaps based on data from an external API, you'll likely want to use [Resource Builder API](/docs/plugins/external-apis) rather than write a generator. Otherwise, take a look at [hooks](/docs/plugins/hooks) for fine-grained access to Bridgetown's build lifecycle.
-{% endrendercontent %}
+{% end %}
You can write a generator when you need Bridgetown to add data to existing content or to programmatically create new pages, posts, and the like. Generators run after Bridgetown has made an inventory of the existing content, but before the site is rendered out.
diff --git a/bridgetown-website/src/_docs/plugins/helpers.md b/bridgetown-website/src/_docs/plugins/helpers.md
index 1712aa4f2..1d23ad3d5 100644
--- a/bridgetown-website/src/_docs/plugins/helpers.md
+++ b/bridgetown-website/src/_docs/plugins/helpers.md
@@ -1,11 +1,11 @@
---
title: Helpers
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
-Helpers are Ruby methods you can provide to Tilt-based templates ([ERB, Slim, etc.](/docs/erb-and-beyond)) to transform data or output new content in various ways.
+Helpers are Ruby methods you can provide to Tilt-based templates ([ERB, Slim, etc.](/docs/template-engines/erb-and-beyond)) to transform data or output new content in various ways.
Example:
@@ -120,4 +120,4 @@ Now just call that helper in your template and use the `label` argument:
## Helpers vs. Filters vs. Tags
-Filters and tags are aspects of the [Liquid](/docs/liquid) template engine which comes installed by default. The behavior of both filters and tags are roughly analogous to helpers in [Tilt-based templates](/docs/erb-and-beyond). Specialized Bridgetown filters are also made available as helpers, as are a few tags such as `webpack_path`.
\ No newline at end of file
+Filters and tags are aspects of the [Liquid](/docs/template-engines/liquid) template engine which comes installed by default. The behavior of both filters and tags are roughly analogous to helpers in [Tilt-based templates](/docs/template-engines/erb-and-beyond). Specialized Bridgetown filters are also made available as helpers, as are a few tags such as `webpack_path`.
\ No newline at end of file
diff --git a/bridgetown-website/src/_docs/plugins/hooks.md b/bridgetown-website/src/_docs/plugins/hooks.md
index ce9902b39..3efa22b8c 100644
--- a/bridgetown-website/src/_docs/plugins/hooks.md
+++ b/bridgetown-website/src/_docs/plugins/hooks.md
@@ -1,7 +1,7 @@
---
title: Hooks
-hide_in_toc: true
order: 0
+top_section: Configuration
category: plugins
---
@@ -81,7 +81,7 @@ end
:resources:[collection_label]
:resources[collection_label]
:post_init
:resources:[collection_label]
:resources[collection_label]
:post_read
:resources:[collection_label]
:resources[collection_label]
:pre_render
:resources:[collection_label]
:resources[collection_label]
:post_render
:resources:[collection_label]
:resources[collection_label]
:post_write
page rendered at: Tue June 22 23:38:47 –0500 2010
``` -{% rendercontent "docs/note" type="warning" %} -In the above example, the tag block and the tag are both registered with -the name `render_time`, but you'll want to avoid registering a tag and a tag block using the same name in the same project as this will lead to conflicts. -{% endrendercontent %} +{%@ Note type: :warning do %} + In the above example, the tag block and the tag are both registered with the name `render_time`, but you'll want to avoid registering a tag and a tag block using the same name in the same project as this will lead to conflicts. +{% end %} ## Using Instance Methods @@ -133,7 +128,7 @@ content/HTML code into a page. If instead you want to _transform_ input data fro one format to another and potentially allow multiple transformations to be chained together, then it's probably better to write a [Filter](/docs/plugins/filters/). -{% rendercontent "docs/note", extra_margin: true %} +{%@ Note do %} If you prefer to use the Legacy API (aka `Liquid::Template.register_tag`) to construct Liquid tags, refer to the [Liquid documentation](https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers) here. -{% endrendercontent %} \ No newline at end of file +{% end %} \ No newline at end of file diff --git a/bridgetown-website/src/_docs/posts.md b/bridgetown-website/src/_docs/posts.md deleted file mode 100644 index 34679eab3..000000000 --- a/bridgetown-website/src/_docs/posts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Posts -order: 11 -top_section: Content -category: posts -hide_in_toc: true ---- - -{% rendercontent "docs/note", type: "warning" %} -The post as a distinct content type has been removed in Bridgetown 1.0. Read about the new [resource content engine](/docs/resources) to learn more about how to create blog posts and other types of content in v1.0. -{% endrendercontent %} diff --git a/bridgetown-website/src/_docs/prototype-pages.md b/bridgetown-website/src/_docs/prototype-pages.md index e1366beaf..492b9646f 100644 --- a/bridgetown-website/src/_docs/prototype-pages.md +++ b/bridgetown-website/src/_docs/prototype-pages.md @@ -1,8 +1,8 @@ --- title: Prototype Pages -order: 15 -top_section: Content -category: prototype_pages +order: 110 +top_section: Writing Content +category: prototype-pages --- This feature builds upon the [Pagination functionality](/docs/content/pagination/) and @@ -12,9 +12,9 @@ own page, every tag has its own page, or virtually any other search term. Note that in order to use [pagination](/docs/content/pagination/), you'll need to enable it your site's `bridgetown.config.yml`. -{% toc %} +{{ toc }} -# Simple Usage +## Simple Usage All you need to do is create a page, say `categories/category.html`, and add a `prototype` config to the Front Matter: @@ -80,7 +80,7 @@ This would produce a generated `tigers/countries/india` page that loops through all the tigers in `India`. -# Pulling in Site Data +## Pulling in Site Data Prototype pages can be configured to load in extra data from [data files](/docs/datafiles/) which get matched with the search term for each item in the collection. This is great for common uses like listing out every post by each of the authors in the site. @@ -133,7 +133,7 @@ As you can image, the possibilities are endless! ## Permalinks -You can also customize the [permalinks](/docs/structure/permalinks/) used in Prototype +You can also customize the [permalinks](/docs/content/permalinks) used in Prototype pages using `:term`. For example, using the Tigers example above, you could change the URLs that get generated like so: diff --git a/bridgetown-website/src/_docs/resources.md b/bridgetown-website/src/_docs/resources.md index c81e98674..3673d4821 100644 --- a/bridgetown-website/src/_docs/resources.md +++ b/bridgetown-website/src/_docs/resources.md @@ -1,8 +1,7 @@ --- title: Resources -order: 10 -next_page_order: 10.5 -top_section: Content +order: 80 +top_section: Writing Content category: resources --- @@ -30,7 +29,7 @@ In this example, the [layout](/docs/layouts) of the resource is specified as `pa You can save resources as files within your source tree, and you can also [generate resources programatically](/docs/plugins/external-apis) via a builder plugin—perhaps based on data from a headless CMS or other third-party APIs. -{% toc %} +{{ toc }} ## Technical Architecture @@ -41,7 +40,7 @@ While certain resources don't actually get written to URLs such as data files (a Resources come with a merry band of objects to help them along the way. These are called Origins, Models, Transformers, and Destinations. Here's a diagram of how it all works.  -{: .my-8} +{:style="margin: 2em 0"} Let's say you add a new blog post by saving `src/_posts/2021-05-10-super-cool-blog-post.md`. To make the transition from a Markdown file with Liquid or ERB template syntax to a final URL on your website, Bridgetown takes your data through several steps: @@ -293,7 +292,7 @@ Bridgetown uses permalink "templates" to determine the default permalink to use * For all other collections, the permalink matches the path of the file along with a collection prefix. So `src/_movies/horror/alien.md` will output to `/movies/horror/alien/` * In addition, if multiple site locales are configured, any content not in the "default" locale will be prefixed by the locale key. So a page offering both English and French variations would be output to `/page-information` and `/fr/page-information`. -Refer to our [permalinks documentation](/docs/structure/permalinks] for further details on how to configure and custom generate permalinks. +Refer to our [permalinks documentation](/docs/content/permalinks) for further details on how to configure and custom generate permalinks. ## Ruby Front Matter and All-Ruby Templates @@ -397,7 +396,7 @@ Prior to Bridgetown 1.0, a different content engine based on Jekyll was used whi * Front matter data is now accessed in Liquid through the `data` variable just like in ERB and skipping `data` is deprecated. Use `{{ post.data.description }}` instead of just `{{ post.description }}`. * In addition, instead of referencing the current "page" through `page` (aka `page.data.title`), you can use `resource` instead: `resource.data.title`. * Resources don't have a `url` variable. Your templates/plugins will need to reference either `relative_url` or `absolute_url`. Also, the site's `base_path` (if configured) is built into both values, so you won't need to prepend it manually. -* Permalink formats have changed somewhat, so please refer to the new [permalink](/docs/structure/permalinks) for how to use the new permalink styles and placeholders. +* Permalink formats have changed somewhat, so please refer to the new [permalink](/docs/content/permalinks) for how to use the new permalink styles and placeholders. * Whereas the `id` of a document is the relative destination URL, the `id` of a resource is its origin id. You can define an id in front matter separately however, which would be available as `resource.data.id`. * The paginator items are now accessed via `paginator.resources` instead of `paginator.documents`. * Instead of `pagination:\n enabled: true` in your front matter for a paginated page, you'll put the collection name instead. Also you can use the term `paginate` instead of `pagination`. So to paginate through posts, just add `paginate:\n collection: posts` to your front matter. diff --git a/bridgetown-website/src/_docs/routes.md b/bridgetown-website/src/_docs/routes.md new file mode 100644 index 000000000..aa442e919 --- /dev/null +++ b/bridgetown-website/src/_docs/routes.md @@ -0,0 +1,145 @@ +--- +title: Dynamic Routes & SSR +order: 250 +top_section: Experimental +category: routes +--- + + +{%@ Note type: "warning" do %} +#### This is just the beginning… + +While Bridgetown's fullstack framework features (aka SSR, file-based routing, and API endpoints) are already being used in production settings, this functionality is still considered "experimental" and subject to further refinement in Bridgetown 1.1 and beyond. Fully-fledged documentation is in the works and ongoing. +{% end %} + +Bridgetown 1.0 comes with a production-ready web server based on the battle-hardened one-two punch of [Rack](https://github.com/rack/rack) + [Puma](https://puma.io). On top of Puma we've layered on [Roda](http://roda.jeremyevans.net), a refreshingly fast & lightweight web routing toolkit created by Jeremy Evans. On a basic level, it handles serving of all statically-built site files you access when you run `bin/bridgetown start`. + +Because Bridgetown uses a Rack-based stack, this means you can potentially add on API endpoints served by a secondary Rails app, or Sinatra, or of course, Roda. In other words, because Rack is fully capable of mounting multiple “apps” within a single server process, you can run Bridgetown alongside your favorite backend/fullstack Ruby app framework. Naturally, we recommend starting out with the framework we've built with Roda as you'll learn more about shortly. + +## Bridgetown SSR via Roda + +Server-Side Rendering, known as SSR, has made its peace with SSG (Static Site Generation), and we are increasingly seeing an SSG/SSR “hybrid” architecture emerge in tooling throughout the web dev industry. + +Bridgetown 1.0 takes advantage of this evolving paradigm by providing a streamlined path for booting a site up in-memory. This means you can write a server-side API to render content whenever it is requested. Here’s an example of what that looks like: + +```ruby +# ./server/routes/preview.rb + +class Routes::Preview < Bridgetown::Rack::Routes + route do |r| + r.on "preview" do + # Our special rendering pathway to preview a page + # route: /preview/:collection/:path + r.get String, String do |collection, path| + item = Bridgetown::Model::Base.find("repo://#{collection}/#{path}") + + unless item.content.present? + next Bridgetown::Model::Base.find("repo://pages/_pages/404.html") + .render_as_resource + .output + end + + item + .render_as_resource + .output + end + end + end +end +``` + +This route handles any `/preview/:collection/:path` URLs which are accessed just like any other statically-generated resource. It will find a content item via a repo origin ID and render that item’s **resource** which is then output as HTML. Needless to say, _this was simply an impossible task_ prior to Bridgetown 1.0. For example: `/preview/posts/_posts%2F2022-01-10-hello-world.md` would SSR the Markdown content located in `src/_posts/2022-01-10-hello-world.md`. + +SSR is great for generating preview content on-the-fly, but you can use it for any number of instances where it’s not feasible to pre-build your content. In addition, you can use SSR to “refresh” stale content…for example, you could pre-build all your product pages statically, but then request a newer version of the page (or better yet, just a component of it) whenever the static page is viewed which would then contain the up-to-date pricing (perhaps coming from a PostgreSQL database or some other external data source). And if you cache _that_ data using Redis in, say, 10-minute increments, you’ve just built yourself an extremely performant e-commerce solution. This is only a single example! + +In order to opt-into SSR support, modify your `server/roda_app.rb` file so it loads the SSR plugin: + +```ruby +class RodaApp < Bridgetown::Rack::Roda + plugin :bridgetown_ssr + + # etc. +end +``` + +## File-based Dynamic Routes + +**But wait, there’s more!** We now ship a new gem you can opt-into (as part of the Bridgetown monorepo) called `bridgetown-routes`. Within minutes of installing it, you gain the ability to write file-based dynamic routes with view templates right inside your source folder! + +Here’s an example of a route saved to `src/_routes/items/index.erb`. It provides the `/items` URL which shows a list of item links: + +```eruby +---<% +# route: /items +r.get do + render_with data: { + layout: :page, + title: "Dynamic Items", + items: [ + { number: 1, slug: "123-abc" }, + { number: 2, slug: "456-def" }, + { number: 3, slug: "789-xyz" }, + ] + } +end +%>--- + +-
+ <% resource.data.items.each do |item| %>
+
- Item #<%= item[:number] %> + <% end %> +
Item ID: <%= resource.data.item_id %>
+ +Item SKU: <%= resource.data.item_sku %>
+ +``` + +This is a contrived example of course, but you can easily imagine loading a specific item from a data source based on the incoming parameter(s) and providing that item data to the view, all within a single file. + +You can even use placeholders in folder names! A route saved to `src/_routes/books/[id]/chapter/[chapter_id].erb` would match to something like `/books/234259/chapter/5` and let you access `r.params[:id]` and `r.params[:chapter_id]`. Pretty nifty. + +Testing is straightforward as well. Simply place `.test.rb` files alongside your routes, and you’ll be able to use Capybara to write **fast** integration tests including interactions requiring Javascript (assuming Cupite is also installed). (_docs coming soon_) + +To opt-into the `bridgetown-routes` gem, make sure it's enabled in your `Gemfile`: + +```ruby +gem "bridgetown-routes", group: :bridgetown_plugins +``` + +and required at the top of your `server/roda_app.rb` file: + +```ruby +require "bridgetown-routes" +``` + +and added in as a Roda plugin below the SSR plugin: + +```ruby +class RodaApp < Bridgetown::Rack::Roda + plugin :bridgetown_ssr + plugin :bridgetown_routes + + # etc. +end +``` diff --git a/bridgetown-website/src/_docs/static_files.md b/bridgetown-website/src/_docs/static-files.md similarity index 79% rename from bridgetown-website/src/_docs/static_files.md rename to bridgetown-website/src/_docs/static-files.md index d869ad6eb..249328106 100644 --- a/bridgetown-website/src/_docs/static_files.md +++ b/bridgetown-website/src/_docs/static-files.md @@ -1,8 +1,8 @@ --- title: Static Files -order: 16 -top_section: Content -category: staticfiles +order: 130 +top_section: Writing Content +category: static-files --- A static file is a file that does not contain any front matter. These @@ -10,9 +10,9 @@ include images, PDFs, and other un-rendered content. You can save static files in any subfolder or directly within the source folder (`src`). A common place to save images specifically is the `src/images` folder. You can reference them from both markup and CSS simply using a relative URL (for example, `/images/logo.svg`). -{% rendercontent "docs/note" %} -Optionally, you can [bundle images through Webpack](/docs/frontend-assets) and reference them with the `webpack_path` helper. Or if you're interested in a full-featured image management solution with the ability to resize and optimize your media sizes, check out [Cloudinary](https://www.cloudinary.com){:rel="noopener"} and the [bridgetown-cloudinary plugin](https://github.com/bridgetownrb/bridgetown-cloudinary){:rel="noopener"}. -{% endrendercontent %} +{%@ Note do %} + Optionally, you can [bundle images through esbuild or Webpack](/docs/frontend-assets) and reference them with the `asset_path` helper. Or if you're interested in a full-featured image management solution with the ability to resize and optimize your media sizes, check out [Cloudinary](https://www.cloudinary.com) and the [bridgetown-cloudinary plugin](https://github.com/bridgetownrb/bridgetown-cloudinary). +{% end %} Static files can be searched and accessed in templates via `site.static_files` and contain the following metadata: @@ -73,7 +73,7 @@ Note that in the above table, `file` representes a variable used in logic such a ## Add front matter to static files -Although you can't directly add front matter values to static files, you can set front matter values through the [defaults property](/docs/configuration/front-matter-defaults/) in your configuration file. When Bridgetown builds the site, it will use the front matter values you set. +Although you can't directly add front matter values to static files, you can set front matter values through the [defaults property](/docs/content/front-matter-defaults/) in your configuration file. When Bridgetown builds the site, it will use the front matter values you set. Here's an example: diff --git a/bridgetown-website/src/_docs/structure.md b/bridgetown-website/src/_docs/structure.md index 12a921eec..29f5a91f2 100644 --- a/bridgetown-website/src/_docs/structure.md +++ b/bridgetown-website/src/_docs/structure.md @@ -1,8 +1,7 @@ --- title: Folder Structure -order: 7 -next_page_order: 7.5 -top_section: Structure +order: 70 +top_section: Writing Content category: structure --- @@ -10,13 +9,15 @@ The typical folder structure for a Bridgetown site usually looks something like ```shell . -├── frontend # this is where you put your CSS and JS for Webpack +├── config # this is where frontend and server defaults are stored +├── frontend # this is where you put your CSS and JS for esbuild/Webpack │ ├── javascript │ │ ├── index.js │ │ └── widget.js │ ├── styles -│ │ ├── index.scss -│ └ └── layout.scss +│ │ ├── index.css +│ └ └── layout.css +├── server # this is where you can (optionally) add API routes using Roda ├── src # this is where you put your resources and design templates │ ├── _components │ │ ├── footer.liquid @@ -25,8 +26,8 @@ The typical folder structure for a Bridgetown site usually looks something like │ │ ├── members.yml │ │ └── site_metadata.yml │ ├── _layouts -│ │ ├── default.html -│ │ └── post.html +│ │ ├── default.erb +│ │ └── post.serb │ ├── _posts │ │ ├── 2019-10-29-why-im-dressing-up-as-thanos-this-year.md │ │ └── 2020-04-12-isolation-is-really-getting-to-me.md @@ -38,14 +39,16 @@ The typical folder structure for a Bridgetown site usually looks something like ├── output # this is the generated site published via bridgetown build/serve ├── plugins # this is where you can write custom plugins ├── bridgetown.config.yml # this is your Bridgetown configuration file +├── config.ru # Puma uses this to boot up the web server +├── esbuild.config.js # frontend bundler config ├── Gemfile -├── package.json -└── webpack.config.js +├── Rakefile +└── package.json ``` {:.minimal-line-height} {:.note} -The location of pages in your source folder structure will by default be mirrored in your output folder, whereas posts are handled in a special way. You can customize these permalinks via front matter and global configuration options. +The location of pages in your source folder structure will by default be mirrored in your output folder, whereas posts are handled in a special way. You can customize these permalinks via front matter and global configuration options. ## Overview of Files & Folders @@ -93,7 +96,7 @@ The location of pages in your source folder structure will by default be mirrore
- This is where you add dynamic blog-style content. The naming convention of these files is important, and must follow the YEAR-MONTH-DAY-post-title.EXT.md, .html, etc.). The permalink can be customized for each post. Posts are a built-in collection, and you can configure other collections in addition to (or even instead of) posts.
+ This is where you add dynamic blog-style content. The naming convention of these files is important, and must follow the YEAR-MONTH-DAY-post-title.EXT.md, .html, etc.). The permalink can be customized for each post. Posts are a built-in collection, and you can configure other collections in addition to (or even instead of) posts.
- Every other directory and file except for those listed above—such as downloadable files, favicon.ico, robots.txt, and so forth—will be copied verbatim to the generated site as Static Files.
+ Every other directory and file except for those listed above—such as downloadable files, favicon.ico, robots.txt, and so forth—will be copied verbatim to the generated site as Static Files.
- Manifest used by Yarn to install frontend assets and set up commands you can run to compile your JavaScript, CSS, etc. via Webpack. + Manifest used by Yarn to install frontend assets and set up commands you can run to compile your JavaScript, CSS, etc. via esbuild/Webpack.
webpack.config.js
esbuild.config.js
- Configuration file used by Webpack to compile frontend assets and save them to the output folder alongside your Bridgetown content. + Configuration file used by esbuild to compile frontend assets and save them to the output folder alongside your Bridgetown content.
| Variable | -Description | -
|---|---|
|
-
|
-
- - Four-digit year based on the resource's date. - - |
-
|
-
|
-
- - Two-digit year based on the resource's date within its century (00..99). - - |
-
|
-
|
-
- - Month based on the resource's date (01..12). - - |
-
|
-
|
-
- - Month based on the resource's date without leading zeros (1..12). - - |
-
|
-
|
-
- - Day of the month based on the resource's date (01..31). - - |
-
|
-
|
-
- - Day of the month based on the resource's date without leading zeros (1..31). - - |
-
|
-
|
-
-
- The specified categories for the resource. If a resource has multiple
- categories, Bridgetown will create a hierarchy (e.g. |
-
|
-
|
-
- - Adds the locale key of the current rendering context, if its not the default site locale. - - |
-
|
-
|
-
- - Title from the resource's front mattter (aka `title: My Resource Title`), slugified (aka any character - except numbers and letters is replaced as hyphen). - - |
-
|
-
|
-
-
- Extracted from the resources’s filename. May be overridden via the resources’s |
-
|
-
|
-
- - Extracted from the resources’s filename and cannot be overridden. - - |
-
|
-
|
-
- - Constructs URL segments out of the relative path of the resource within its collection folder. Used by the **pages** collection as well as custom collections if no specific permalink config is provided. - - |
-
|
-
|
-
- - Outputs the label of the resource's custom collection (will be blank for the built-in pages and posts collections). - - |
-
+
+
+
+
{{ page.title }}
- {% else %} -{{ page.title }}
- {% endif %} - - -{{ resource.data.title }}
+ + {%= yield %} + + {% if url_sections.size > 3 %} + + {% else %} + {% next_order = resource.data.next_page_order %} + {% unless next_order %} + {% next_order = page.data.order + 10 %} + {% end %} + {% alldocs = collections.docs.resources %} + {% next_page = collections.docs.resources.find { _1.data.order == next_order } %} + {% if next_page %} + + {% end %} + {% end %} +Bridgetown
- -News Updates
- - {% for post in collections.posts.resources limit:4 %} - {% render "content/news_item", post: post, authors: site.data.authors %} - {% endfor %} - - -{% endrendercontent %} diff --git a/bridgetown-website/src/_layouts/page.liquid b/bridgetown-website/src/_layouts/page.liquid deleted file mode 100644 index 984a8a39e..000000000 --- a/bridgetown-website/src/_layouts/page.liquid +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default ---- - -{% rendercontent "shared/page_layout" %} - {% rendercontent "shared/box" %} -- {{ page.title }} -
- -{{ resource.data.title }}
+ + {%= yield %} + +{{ page.title }}
- -{{ resource.data.title }}
+ +
+
+ + + +
Latest on the Blog
+ +-
+ {% collections.posts.resources.reject { _1.data.exclude_from_pagination }[0...6].each do |post| %}
+
- {%@ PostCard post: post %} + {% end %} +
Welp, that didn't work!
+ +Check out the rest of the site or use the search box above. Hope you find what you're looking for. 😃
diff --git a/bridgetown-website/src/_pages/_defaults.yml b/bridgetown-website/src/_pages/_defaults.yml new file mode 100644 index 000000000..744e2507f --- /dev/null +++ b/bridgetown-website/src/_pages/_defaults.yml @@ -0,0 +1 @@ +layout: page \ No newline at end of file diff --git a/bridgetown-website/src/_pages/about.md b/bridgetown-website/src/_pages/about.md deleted file mode 100644 index 73e501ac8..000000000 --- a/bridgetown-website/src/_pages/about.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: page -title: The History and Future of Bridgetown ---- - -**September 2021 Update**: We're in the process of revising our website and [just released a brand-new roadmap. Check it out!](/future/roadmap-to-1.0/) - ----- - -### Circa 2020: - -Bridgetown started life as a fork of the granddaddy of static site generators, [Jekyll](https://jekyllrb.com). Jekyll came to prominence in the early 2010s due to its slick integration with GitHub, powering thousands of websites for developer tools. In the years since it has grown to provide a popular foundation for a wide variety of sites across the web. - -But as the concepts of modern static site generation and the [Jamstack](/docs/jamstack/) came to the forefront, a whole new generation of tools rose up, like [Hugo](https://gohugo.io), [Eleventy](https://www.11ty.dev), [Gatsby](http://gatsbyjs.org), and many more. In the face of all this new competition, Jekyll chose to focus on maintaining extensive backwards-compatibility and a paired-down feature set—noble goals for an open source project generally speaking, but ones that were at odds with meaningful portions of the web developer community. - -So in March 2020, Portland-based web studio [Whitefusion](https://www.whitefusion.studio) started on **Bridgetown**, a fork of Jekyll with a brand new set of project goals and a future roadmap. Whitefusion's multi-year experience producing and deploying numerous Jekyll-based websites furnishes a seasoned take on the unique needs of web agencies and their clients. - -It's early days yet, but our goal is to keep adding new features at a steady and predictable pace, grow the open source community around the project, and ensure a lively future for a top-tier Ruby-based static site generator moving forward. - -## Roadmap - -As of spring 2020, here is the vision for where Bridgetown is headed. And this is just a start! If you have [ideas and feature requests (and code!) to contribute](/docs/community/#ways-to-contribute), let's do it! - -([You also might want to take a look at our Project Goals page.](/docs/philosophy/)) - -{:.note} -- ✅ _DONE!_ **Retool the codebase** into a monorepo of multiple gems (like Rails/Spree/etc.) -- ✅ _DONE!_ **Streamline internals** to remove deprecated or legacy code paths and reduce confusing configuration options. -- ✅ _DONE!_ **Improve default site file/folder structure** to bring Bridgetown in line with other popular static site generators. -- ✅ _DONE!_ Add a `bridgetown console` command to **interactively interact with the site data and plugins** (just like the Rails console). -- ✅ _DONE!_ Remove the aging asset pipeline and **regroup around a modern solution: Webpack**. (Similar to how Rails adopted Webpack and distanced itself from Sprockets.) [Check out the preliminary documentation here.](/docs/frontend-assets/) -- ✅ _DONE!_ Integrate **pagination features** directly into the monorepo. [Preliminary docs here.](/docs/content/pagination/) -- ✅ _DONE!_ Add streamlined **taxonomy pages (for categories, tags, and other metadata)** solution (called [Prototype Pages](/docs/prototype-pages/)). -- ✅ _DONE!_ Move most site data vars to a **reloadable file** (aka `_data/site_metadata.yml`) and support [env-specific settings (development vs. production)](/docs/configuration/environments). -- ✳️ _DONE!_ External theme support is nearly here with the arrival of [Source Manifests](/docs/plugins/source-manifests) in Bridgetown 0.13. Stay tuned for an official guide on how to build modern themes for the next release of Bridgetown. -- ✳️ _DONE!_ **Auto-reload plugins** during development. (No more stop-and-restart every 5 seconds!) -- ✳️ _DONE!_ **Liquid Components** — this would build upon the new `render` tag functionality and [add a ton of new features](/docs/components) to make component-based design and authoring a reality, bringing Ruby/Liquid syntax closer to the world of React & Vue. -- ✳️ _DONE!_ Officially-sanctioned **site testing framework** to [verify content and functionality](/docs/testing) after new builds. -- ✳️ _IN PROGRESS…_ Modernize various aspects of the codebase, incrementally **improving - the developer experience (DX)** on a number of different fronts. -- ✳️ _IN PROGRESS…_ Ensure all **documentation, configuration, and deployment recommendations are fully up-to-date** and in line with best practices encouraged by the web development industry. -- Straightforward support for **third-party data APIs** (think GraphQL as a first-class citizen). -- Easy **multilingual setup** right out of the box. -- Support **additional template languages** popular in the Ruby community such as ERB, HAML, and Slim. -- **Simple webhooks** — allow remote webhooks to be pinged after a successful build. - - **“Private” pages** — aka put a website section behind a randomized URL that changes frequently and then allow that to be pinged to a webhook somewhere. -- Investigate potentially huge wins regarding **headless CMS + Bridgetown integrations** as officially recommended plugins. - -And generally speaking, as an [open source](https://en.wikipedia.org/wiki/Open_source) project we want to be good stewards of the codebase and community, which starts with adhering to a predictable release schedule. Based on [SemVer](https://semver.org), our goal is to strive for: - -- **Major** releases every three to six months (1.0, 2.0, 3.0, etc.) -- **Minor** releases twice a month (1.2, 1.3, 1.4, etc.) -- **Patch** releases in between as needed (1.3.2, 1.3.3, etc.) - -We also want to ensure Bridgetown is a **reliable partner** for commercial solution providers by ensuring their frontline work with clients goes well and feedback flows positively into the Bridgetown feature set. What does this mean in a nutshell? It means if you make a living building websites using Bridgetown and run into major workflow hiccups, [we want to know about it](/docs/community/). - -**So, ready to try out Bridgetown for yourself?** - -{:.has-text-centered.mt-10} -[Get Started](/docs/){:.button.is-large.is-info} diff --git a/bridgetown-website/src/_pages/authors/[author].serb b/bridgetown-website/src/_pages/authors/[author].serb new file mode 100644 index 000000000..f6927b275 --- /dev/null +++ b/bridgetown-website/src/_pages/authors/[author].serb @@ -0,0 +1,58 @@ +--- +title: "Articles by :prototype-data-label" +exclude_from_search: true +prototype: + collection: posts + term: author + data: authors + data_label: name +--- + +{% resource.data.breadcrumbs_for_layout = capture do %} ++ Connect with + {{ author.name | split: " " | first }} + on the + Web + or on + {% if author.twitter %} + Twitter + {% elsif author.github %} + GitHub + {% end %} +
+ +-
+ {% paginator.resources.each do |post| %}
+
- {%@ PostCard post: post %} + {% end %} +
+ {% if paginator.previous_page %}
+
{{ page.title }}
- - {% for post in paginator.resources %} - {% render "content/news_item", post: post, authors: site.data.authors %} - {% endfor %} - - {% render "shared/pagination", paginator: paginator %} -{% endrendercontent %} diff --git a/bridgetown-website/src/_pages/blog.serb b/bridgetown-website/src/_pages/blog.serb new file mode 100644 index 000000000..7213abeb2 --- /dev/null +++ b/bridgetown-website/src/_pages/blog.serb @@ -0,0 +1,42 @@ +--- +title: The Bridgetown Blog +exclude_from_search: true +paginate: + collection: posts +--- + +{% if paginator.previous_page %} + {% resource.data.breadcrumbs_for_layout = capture do %} +-
+ {% paginator.resources.each do |post| %}
+
- {%@ PostCard post: post %} + {% end %} +
+ {% if paginator.previous_page %}
+
-
+ {% paginator.resources.each do |post| %}
+
- {%@ PostCard post: post %} + {% end %} +
+ {% if paginator.previous_page %}
+
+ +
+ + Children silhouette designed by Kjpargeter / Freepik + +
diff --git a/bridgetown-website/src/_pages/index.md b/bridgetown-website/src/_pages/index.md index b22c0e27c..15c4ad125 100644 --- a/bridgetown-website/src/_pages/index.md +++ b/bridgetown-website/src/_pages/index.md @@ -1,36 +1,291 @@ --- -layout: home +layout: default +exclude_from_search: true +page_class: homepage --- -## A Webpack-aware, Ruby-powered static site generatorfor the modern Jamstack era. -{:.mb-10.has-text-centered.title.is-4.has-text-primary} +
+ 
+
Bridgetown is so cool. It’s the most fun I’ve had outside of Rails in a long time.+ + [@_williamkennedy](https://twitter.com/_williamkennedy/status/1323023702502658049?s=21) + +-
Coherent, thought through, well-structured, yet powerful and efficient SSG. This is GREAT!+ + [@noam__shemesh](https://twitter.com/noam__shemesh/status/1362228411826069504?s=21) + +-
With Rails 7, Hotwire, Stimulus, Strada, Bridgetown, Render, and things like this, I believe Ruby is about to have a renaissance.+ + [@aviflombaum](https://twitter.com/aviflombaum/status/1470438543159930886?s=21) + +-
Within a very short period of time I went from a blank VSCode editor to fully designed and deployed website using Bridgetown! 👏+ + [@rabbigreenberg](https://twitter.com/rabbigreenberg/status/1462403305334788099?s=21) + +-
I made my Bridgetown site 'come alive' with automatic redeploys where the site's content is updated via an API. In lieu of a Frankenstein emoji… BRRAAAAAINS!! 🧟🧟🧟+ + [@fpsvogel](https://twitter.com/fpsvogel/status/1446469364874625025?s=21) + +-
If you need a static site generator and like Ruby, go for + Bridgetown. I'm using it on 3 projects right now and it's awesome.+ + [@stevediaconou](https://twitter.com/stevediaconou/status/1467124931729178625?s=20) + +-
I wish more new tools were doing this well out of the box. Congrats, and good luck!+ + [@slightlylate](https://twitter.com/slightlylate/status/1467293827245375492?s=21) + +-
Every time I turn around — something new from Bridgetown.+ + [@jeffreyguenther](https://twitter.com/jeffreyguenther/status/1464277154154254339?s=21) + +-
I just started my first project using Bridgetown today and I’m already loving it!+ + [@theluctus](https://twitter.com/theluctus/status/1459287487373877248?s=21) + +-
Bridgetown rules.+ + [@middlemanapp](https://twitter.com/middlemanapp/status/1264014892673069057?s=20) + + +
Bridgetown
- -Webpack-aware, Ruby-powered
static site generator for the
modern Jamstack era
- {{ page.data.title }}
- -
- Peruse our growing collection of official and third-party plugins which provide new capabilities to your Bridgetown site. If you've authored a plugin gem, add the bridgetown-plugin topic to your GitHub repo to include it here.
-
+ Peruse our growing collection of official and third-party plugins which provide new capabilities to your Bridgetown site. If you've authored a plugin gem, add the bridgetown-plugin topic to your GitHub repo to include it here.
+
-
{% page.data.plugins.each do |plugin| %}
-
+ + + {{ plugin.description }}
-- {{ plugin.description }} - ++ {% if plugin.gem_version %} +++ + {% end %} -v{{ plugin.gem_version }} +- - +- {{ plugin.owner.login }} -
+
{% end %}
-{% end %}
+
- {{ plugin.name }}
- {% if plugin.gem_version %}
- v{{ plugin.gem_version }}
- {% end %}
-
-
+ [We'd greatly appreciate it!](https://github.com/bridgetownrb/bridgetown/issues/new?assignees=&labels=documentation&template=documentation.md&title=docs%3A+{{ resource.relative_url | cgi_escape }}) 😃👍 +{% end %} \ No newline at end of file diff --git a/bridgetown-website/src/_components/docs/install/bridgetown.liquid b/bridgetown-website/src/_partials/docs/install/_bridgetown.serb similarity index 83% rename from bridgetown-website/src/_components/docs/install/bridgetown.liquid rename to bridgetown-website/src/_partials/docs/install/_bridgetown.serb index 12be95966..82842877f 100644 --- a/bridgetown-website/src/_components/docs/install/bridgetown.liquid +++ b/bridgetown-website/src/_partials/docs/install/_bridgetown.serb @@ -2,15 +2,15 @@ Now all that is left is to install Bridgetown! -{%- if edge_version %} +{%- if site.data.edge_version %} ``` -gem install bridgetown -N -v {{ version }} +gem install bridgetown -N -v {{ Bridgetown::VERSION }} ``` {%- else %} ``` gem install bridgetown -N ``` -{%- endif %} +{%- end %} Create a new Bridgetown site at `./mysite`, as well as run `bundle install` and `yarn install` automatically: @@ -27,4 +27,4 @@ Now you should be able to build the site and run a live-reload server: $ bin/bridgetown start ``` -Try opening the site up in [http://localhost:4000](http://localhost:4000){:target="_blank"}. See something? Awesome, you're ready to roll! If not, try revisiting your installation and setup steps, and if all else fails, [reach out to the Bridgetown community for support](/docs/community/). +Try opening the site up in [http://localhost:4000](http://localhost:4000){:target="_blank"}. See something? Awesome, you're ready to roll! If not, try revisiting your installation and setup steps, and if all else fails, [reach out to the Bridgetown community for support](/community/). diff --git a/bridgetown-website/src/_components/docs/install/node_on_linux.liquid b/bridgetown-website/src/_partials/docs/install/_node_on_linux.serb similarity index 100% rename from bridgetown-website/src/_components/docs/install/node_on_linux.liquid rename to bridgetown-website/src/_partials/docs/install/_node_on_linux.serb diff --git a/bridgetown-website/src/_posts/2020/2020-04-17-time-to-visit-bridgetown.md b/bridgetown-website/src/_posts/2020/2020-04-17-time-to-visit-bridgetown.md index 6db62ec0a..79770db75 100644 --- a/bridgetown-website/src/_posts/2020/2020-04-17-time-to-visit-bridgetown.md +++ b/bridgetown-website/src/_posts/2020/2020-04-17-time-to-visit-bridgetown.md @@ -75,6 +75,6 @@ Get started today. (or [find out how you can become a contributor](/docs/community/)…or perhaps join the Bridgetown core team!) {:.has-text-centered} -{% rendercontent "docs/note", extra_margin: true %} +{%@ Note do %} P. S. Let us know if you plan to build something awesome with Bridgetown! And be sure to use the hashtag [**#SpinUpBridgetown**](https://twitter.com/intent/tweet?url=https%3A%2F%2Fbridgetownrb.com&via=bridgetownrb&text=Check%20out%20this%20awesome%20new%20static%20site%20generator%20built%20in%20Ruby%21&hashtags=SpinUpBridgetown%2CJamstack) and spread the word! 😃 -{% endrendercontent %} +{% end %} diff --git a/bridgetown-website/src/_posts/2020/2020-05-05-supercharge-your-bridgetown-site-with-ruby-front-matter.md b/bridgetown-website/src/_posts/2020/2020-05-05-supercharge-your-bridgetown-site-with-ruby-front-matter.md index 2635bd5b7..1356b9255 100644 --- a/bridgetown-website/src/_posts/2020/2020-05-05-supercharge-your-bridgetown-site-with-ruby-front-matter.md +++ b/bridgetown-website/src/_posts/2020/2020-05-05-supercharge-your-bridgetown-site-with-ruby-front-matter.md @@ -1,24 +1,30 @@ ---- -title: Supercharge Your Bridgetown Site with Ruby Front Matter -subtitle: You can now write real Ruby code directly in your Front Matter! This feature is available for pages, posts, and other documents–as well as layouts for site-wide access to your Ruby return values. -author: jared -category: feature -calculation: !ruby/string:Rb | - [2 * 4, 5 + 2].min -title_fragment: Title of a Page -example_title: !ruby/string:Rb | - "This is the #{data["title_fragment"].sub("Title", "Name")}" -seo_tag_gem_version: !ruby/string:Rb | - url = "https://raw.githubusercontent.com/bridgetownrb/bridgetown-seo-tag/master/lib/bridgetown-seo-tag/version.rb" - result = Faraday.get(url).body - result.match(/VERSION = "(.*?)"/)[1] ---- +~~~{% +front_matter do + title "Supercharge Your Bridgetown Site with Ruby Front Matter" + subtitle "You can now write real Ruby code directly in your Front Matter! This feature is available for pages, posts, and other documents–as well as layouts for site-wide access to your Ruby return values." + author "jared" + category "feature" + calculation [2 * 4, 5 + 2].min + title_fragment "Title of a Page" + example_title "This is the #{title_fragment.sub("Title", "Name")}" + seo_tag_gem_version begin + url = "https://raw.githubusercontent.com/bridgetownrb/bridgetown-seo-tag/master/lib/bridgetown-seo-tag/version.rb" + result = Faraday.get(url).body + result.match(/VERSION = "(.*?)"/)[1] + end +end +%}~~~ + + +{%@ Note type: :warning do %} +This kind of Ruby front matter has been removed from Bridgetown in favor of a pure [Ruby front matter](/docs/front-matter#the-power-of-ruby-in-front-matter) format. This blog post is kept here only for historical reasons. +{% end %} Starting in Bridgetown v0.13, you can now write real Ruby code directly in your [Front Matter](/docs/front-matter/)! 🤯 This feature is available for pages, posts, and other documents–as well as layouts for site-wide access to your Ruby return values. -{% rendercontent "docs/note" %} +{%@ Note do %} This requires the environment variable `BRIDGETOWN_RUBY_IN_FRONT_MATTER` to be set to `"true"` in your development and deployment setups. Otherwise the code will not be executed and will be treated as a raw string. -{% endrendercontent %} +{% end %} Now you may be wondering, _how is this even possible?_ Front Matter is in YAML format, and the only place you can write actual code is in a custom plugin, right? _RIGHT??_ @@ -40,7 +46,7 @@ Calc Result: {{ page.calculation }} In this example, the value of the `calculation` variable is the return value of the Ruby code defined by the special string `!ruby/string:Rb`. The `|` symbol at the end just means all the indented code in the line(s) below are attached to that front matter variable. -The value printed out in the rendered page for the calculation will be **{{ page.calculation }}** (since 7 is less than 8 and thus the minimum integer in the array). In fact, on this very page you're reading, that number **{{ page.calculation }}** is actually being generated by Ruby Front Matter, not hard-coded in this article! Thus you know the system works. ☺️ +The value printed out in the rendered page for the calculation will be **{{ page.data.calculation }}** (since 7 is less than 8 and thus the minimum integer in the array). In fact, on this very page you're reading, that number **{{ page.data.calculation }}** is actually being generated by Ruby Front Matter, not hard-coded in this article! Thus you know the system works. ☺️ In Ruby Front Matter you can return any kind of value that is accessible from a Liquid template. So strings, numbers, arrays, hashes, integers: they all work. Even _objects_ can be returned if they are [implemented as a Liquid drop](https://github.com/Shopify/liquid/wiki/Introduction-to-Drops). @@ -54,7 +60,7 @@ title: !ruby/string:Rb | --- ``` -Now the page title will read: **{{ page.example_title }}** +Now the page title will read: **{{ page.data.example_title }}** ### Use Cases for Ruby Front Matter @@ -69,9 +75,9 @@ seo_tag_gem_version: !ruby/string:Rb | --- ``` -This will pull the current gem version of the master branch from [bridgetown-seo-tag](https://github.com/bridgetownrb/bridgetown-seo-tag) and output it via {% raw %}`{{ page.seo_tag_gem_version }}`{% endraw %} (it's **{{ page.seo_tag_gem_version }}**). +This will pull the current gem version of the master branch from [bridgetown-seo-tag](https://github.com/bridgetownrb/bridgetown-seo-tag) and output it via {% raw %}`{{ page.seo_tag_gem_version }}`{% endraw %} (it's **{{ page.data.seo_tag_gem_version }}**). -Another example is a feature we include on this very website's footer to show the average number of commits to the Bridgetown project on GitHub over the past month. (At the time this site was last built, that number is **{{ layout.github_participation }}**.) +Another example is a feature we include on this very website's footer to show the average number of commits to the Bridgetown project on GitHub over the past month. Here's the Ruby Front Matter we include in `_layouts/default.html`: @@ -105,9 +111,9 @@ But if you just need to add a little bit of dynamic functionality to a page or a And remember, this isn't a "lite" or stripped-down version of Ruby. **This is 100% full Ruby.** So you can process page or site data, instantiate objects, require gems, perform network requests, interact with the underlying filesystem, monkeypatch and metaprogram and do anything you'd ever need to do via Ruby. -{% rendercontent "docs/note", type: "warning" %} +{%@ Note type: :warning do %} For security reasons, please _do not allow_ untrusted content into your repository to be executed in an unsafe environment (aka outside of a Docker container or similar). Just like with custom plugins, a malicious content contributor could potentially introduce harmful code into your site and thus any computer system used to build that site. Enable Ruby Front Matter _only_ if you feel confident in your ability to control and monitor all on-going updates to repository files and data. -{% endrendercontent %} +{% end %} In summary, if you're excited to give Ruby Front Matter a try, all you have to do is [install Bridgetown v0.13 or later](/docs/), set `BRIDGETOWN_RUBY_IN_FRONT_MATTER` to `"true"` in your development environment, and go to town (Bridge…town 😋). And be sure to share your sweet solutions on Twitter with the hashtag [**\#SpinUpBridgetown**](https://twitter.com/search?q=%23SpinUpBridgetown) to let the community know what you've built with Ruby Front Matter! diff --git a/bridgetown-website/src/_posts/2020/2020-05-27-bridgetown-around-the-web-late-may-2020.md b/bridgetown-website/src/_posts/2020/2020-05-27-bridgetown-around-the-web-late-may-2020.md index a7e3f700e..59770a4f2 100644 --- a/bridgetown-website/src/_posts/2020/2020-05-27-bridgetown-around-the-web-late-may-2020.md +++ b/bridgetown-website/src/_posts/2020/2020-05-27-bridgetown-around-the-web-late-may-2020.md @@ -63,4 +63,4 @@ Finally, we [got a shoutout from Netlify](https://twitter.com/netlify/status/125 So that's it for this month's installment of **Bridgetown Around the Web**. Pop back in next month for more tweets, podcasts, links, tutorials, and all that jazz. 🎷 -And if you're interesting in trying out Bridgetown or using it fo your next project, [read the docs to get started](https://www.bridgetownrb.com/docs). \ No newline at end of file +And if you're interesting in trying out Bridgetown or using it for your next project, [read the docs to get started](https://www.bridgetownrb.com/docs). \ No newline at end of file diff --git a/bridgetown-website/src/_posts/2020/2020-06-18-major-workflow-advances-in-0.15-overlook.md b/bridgetown-website/src/_posts/2020/2020-06-18-major-workflow-advances-in-0.15-overlook.md index caf18747a..026778f11 100644 --- a/bridgetown-website/src/_posts/2020/2020-06-18-major-workflow-advances-in-0.15-overlook.md +++ b/bridgetown-website/src/_posts/2020/2020-06-18-major-workflow-advances-in-0.15-overlook.md @@ -13,8 +13,8 @@ It's time to unveil some of those initiatives today with the release of Bridgeto Before we get into the meat of the release, there's a brand-new overview video you can watch to learn more about Bridgetown! -
+ +
+ + +## Transcript _Automatic transcription by Happy Scribe, with light edits_ {:style="text-align:center"} diff --git a/bridgetown-website/src/_posts/2021/2021-12-03-progress-report-esbuild-aware.md b/bridgetown-website/src/_posts/2021/2021-12-03-progress-report-esbuild-aware.md index d3f55e938..c73c8c958 100644 --- a/bridgetown-website/src/_posts/2021/2021-12-03-progress-report-esbuild-aware.md +++ b/bridgetown-website/src/_posts/2021/2021-12-03-progress-report-esbuild-aware.md @@ -33,7 +33,7 @@ Developer time has slightly outpaced fundraising at this point, but that's not u There's also been a flurry of effort not included in this direct report to further ecosystem enhancements (plugins, methodologies, etc.) which tie into the overall 1.0 launch, such as our [Prismic CMS plugin](https://github.com/bridgetownrb/bridgetown-prismic), [CableCar/mrujs integration](https://github.com/bridgetownrb/bridgetown/pull/465), and seamless support for ActiveRecord (yes, [that ActiveRecord!](https://guides.rubyonrails.org/active_record_basics.html)) & databases. -### So, about that "esbuild" line item… +## So, about that "esbuild" line item… First, a little history lesson… @@ -65,7 +65,7 @@ In fact, we're so confident in our ability to iterate rapidly on this integratio Webpack will continue to be available _and_ supported. But with the release of Bridgetown 1.0, we're all in on esbuild—and PostCSS as well. We believe this is the right path forward for frontend bundling—not just for Bridgetown but for web frameworks across our industry. -### FAQ: Vite? Import maps? Migration strategy? +## FAQ: Vite? Import maps? Migration strategy? Three answers to likely questions before I close: diff --git a/bridgetown-website/src/_posts/_defaults.yml b/bridgetown-website/src/_posts/_defaults.yml index bf162af9f..9388f3d78 100644 --- a/bridgetown-website/src/_posts/_defaults.yml +++ b/bridgetown-website/src/_posts/_defaults.yml @@ -1,2 +1,3 @@ layout: post +author: jared category: news diff --git a/bridgetown-website/src/apple-touch-icon.png b/bridgetown-website/src/apple-touch-icon.png index 6058c93ed..58a694e60 100644 Binary files a/bridgetown-website/src/apple-touch-icon.png and b/bridgetown-website/src/apple-touch-icon.png differ diff --git a/bridgetown-website/src/authors/author.html b/bridgetown-website/src/authors/author.html deleted file mode 100644 index 4a3ad0f15..000000000 --- a/bridgetown-website/src/authors/author.html +++ /dev/null @@ -1,35 +0,0 @@ ---- -layout: default -title: Articles by :prototype-data-label -exclude_from_search: true -prototype: - collection: posts - term: author - data: authors - data_label: name ---- - -{% assign author = page.author_data %} -{% rendercontent "shared/page_layout" %} -Articles by - {{ author.name | split: " " | first }}
- -- Connect with - {{ author.name }} - on the - Web - or - {% if author.twitter %} - Twitter - {% elsif author.github %} - GitHub - {% endif %} -
- - {% for post in paginator.resources %} - {% render "content/news_item", post: post, authors: site.data.authors %} - {% endfor %} - - {% render "shared/pagination", paginator: paginator %} -{% endrendercontent %} diff --git a/bridgetown-website/src/categories/category.html b/bridgetown-website/src/categories/category.html deleted file mode 100644 index 5e2a8409f..000000000 --- a/bridgetown-website/src/categories/category.html +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: default -title: "Browse Category: :prototype-term-titleize" -exclude_from_search: true -prototype: - collection: posts - term: category ---- - -{% rendercontent "shared/page_layout" %} -{{ page.title }}
- - {% for post in paginator.resources %} - {% render "content/news_item", post: post, authors: site.data.authors %} - {% endfor %} - - {% render "shared/pagination", paginator: paginator %} -{% endrendercontent %} diff --git a/bridgetown-website/src/favicon-16x16.png b/bridgetown-website/src/favicon-16x16.png index 5a809f923..81dd8e81e 100644 Binary files a/bridgetown-website/src/favicon-16x16.png and b/bridgetown-website/src/favicon-16x16.png differ diff --git a/bridgetown-website/src/favicon-32x32.png b/bridgetown-website/src/favicon-32x32.png index 33938175c..eae4ad9e9 100644 Binary files a/bridgetown-website/src/favicon-32x32.png and b/bridgetown-website/src/favicon-32x32.png differ diff --git a/bridgetown-website/src/favicon.ico b/bridgetown-website/src/favicon.ico index 2edd171df..70d223c79 100644 Binary files a/bridgetown-website/src/favicon.ico and b/bridgetown-website/src/favicon.ico differ diff --git a/bridgetown-website/src/images/.keep b/bridgetown-website/src/images/.keep new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/bridgetown-website/src/images/.keep @@ -0,0 +1 @@ + diff --git a/bridgetown-website/src/images/Bridgetown-Logo-Squished.svg b/bridgetown-website/src/images/Bridgetown-Logo-Squished.svg deleted file mode 100644 index 953c96b81..000000000 --- a/bridgetown-website/src/images/Bridgetown-Logo-Squished.svg +++ /dev/null @@ -1,78 +0,0 @@ - - - diff --git a/bridgetown-website/src/images/Bridgetown-Logo.svg b/bridgetown-website/src/images/Bridgetown-Logo.svg deleted file mode 100644 index 2d5dacb2a..000000000 --- a/bridgetown-website/src/images/Bridgetown-Logo.svg +++ /dev/null @@ -1,76 +0,0 @@ - - - diff --git a/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.11.01 AM.png b/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.11.01 AM.png deleted file mode 100644 index efba47e13..000000000 Binary files a/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.11.01 AM.png and /dev/null differ diff --git a/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.13.31 AM.png b/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.13.31 AM.png deleted file mode 100644 index e39892da9..000000000 Binary files a/bridgetown-website/src/images/Screen Shot 2021-05-14 at 11.13.31 AM.png and /dev/null differ diff --git a/bridgetown-website/src/images/bridgetown-avatar.png b/bridgetown-website/src/images/bridgetown-avatar.png new file mode 100644 index 000000000..72f32bccd Binary files /dev/null and b/bridgetown-website/src/images/bridgetown-avatar.png differ diff --git a/bridgetown-website/src/images/bridgetown-background.jpg b/bridgetown-website/src/images/bridgetown-background.jpg new file mode 100644 index 000000000..73975a790 Binary files /dev/null and b/bridgetown-website/src/images/bridgetown-background.jpg differ diff --git a/bridgetown-website/src/images/bridgetown-logo-2022.svg b/bridgetown-website/src/images/bridgetown-logo-2022.svg new file mode 100644 index 000000000..3006b5ea4 --- /dev/null +++ b/bridgetown-website/src/images/bridgetown-logo-2022.svg @@ -0,0 +1,91 @@ + + + diff --git a/bridgetown-website/src/images/bridgetown-logo-twitter-card.jpg b/bridgetown-website/src/images/bridgetown-logo-twitter-card.jpg index d61b064a7..2426ce008 100644 Binary files a/bridgetown-website/src/images/bridgetown-logo-twitter-card.jpg and b/bridgetown-website/src/images/bridgetown-logo-twitter-card.jpg differ diff --git a/bridgetown-website/src/images/community.svg b/bridgetown-website/src/images/community.svg new file mode 100644 index 000000000..e1a9405f3 --- /dev/null +++ b/bridgetown-website/src/images/community.svg @@ -0,0 +1,9 @@ + \ No newline at end of file diff --git a/bridgetown-website/src/images/ruby-plain.svg b/bridgetown-website/src/images/ruby-plain.svg new file mode 100644 index 000000000..635286dd5 --- /dev/null +++ b/bridgetown-website/src/images/ruby-plain.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/bridgetown-website/src/images/waves/wave_1.svg b/bridgetown-website/src/images/waves/wave_1.svg new file mode 100644 index 000000000..4477d585b --- /dev/null +++ b/bridgetown-website/src/images/waves/wave_1.svg @@ -0,0 +1,7 @@ + + + diff --git a/bridgetown-website/src/images/waves/wave_2.svg b/bridgetown-website/src/images/waves/wave_2.svg new file mode 100644 index 000000000..47a8f0a48 --- /dev/null +++ b/bridgetown-website/src/images/waves/wave_2.svg @@ -0,0 +1,7 @@ + + + diff --git a/bridgetown-website/test/helper.rb b/bridgetown-website/test/helper.rb deleted file mode 100644 index 31f127786..000000000 --- a/bridgetown-website/test/helper.rb +++ /dev/null @@ -1,39 +0,0 @@ -# frozen_string_literal: true - -require "nokogiri" -require "minitest/autorun" -require "minitest/reporters" -require "minitest/profile" -require "shoulda" -require "rails-dom-testing" - -# Report with color. -Minitest::Reporters.use! [ - Minitest::Reporters::DefaultReporter.new( - color: true - ), -] - -Minitest::Test.class_eval do - include Rails::Dom::Testing::Assertions - - def site - @site ||= Bridgetown.sites.first - end - - def nokogiri(input) - input.respond_to?(:output) ? Nokogiri::HTML(input.output) : Nokogiri::HTML(input) - end - - def document_root(root) - @document_root = root.is_a?(Nokogiri::XML::Document) ? root : nokogiri(root) - end - - def document_root_element - if @document_root.nil? - raise "Call `document_root' with a Nokogiri document before testing your assertions" - end - - @document_root - end -end diff --git a/bridgetown-website/test/test_blog.rb b/bridgetown-website/test/test_blog.rb deleted file mode 100644 index 8efc9a590..000000000 --- a/bridgetown-website/test/test_blog.rb +++ /dev/null @@ -1,87 +0,0 @@ -# frozen_string_literal: true - -require_relative "./helper" - -class TestBlog < Minitest::Test - context "blog page" do - setup do - page = site.generated_pages.find { |doc| doc.url == "/blog/index.html" } - document_root page - end - - should "show authors" do - assert_select ".box .author img" do |imgs| - assert_dom_equal imgs.first.to_html, - '
'
- end
- end
-
- should "have correct microformat markup" do
- assert_select ".h-entry h2.p-name"
- assert_select ".h-entry article-content.p-summary"
- assert_select ".h-entry article-author.p-author"
- end
- end
-
- context "blog page" do
- setup do
- page = site.collections.docs.resources.find { |doc| doc.relative_url == "/docs/plugins" }
- document_root nokogiri(page)
- end
-
- should "have a formatted JSON code example" do
- assert_select "div.language-json pre.highlight", <<~JSON
- "dependencies": {
- "random-js-package": "2.4.6",
- "my-plugin": "../my-plugin"
- }
- JSON
- end
- end
-
- context "blog post" do
- setup do
- page = site.collections.posts.resources.find { |doc| doc.relative_url == "/release/whats-new-in-0.14-hazelwood/" }
- document_root nokogiri(page)
- end
-
- should "display a Builder code example" do
- assert_select ".box > article > h1" do |h1|
- assert_dom_equal h1.to_html, '