From 09cecb770b4e3fe764c634509c23867ef4f71b7b Mon Sep 17 00:00:00 2001 From: Jared White Date: Thu, 11 Nov 2021 15:39:39 -0800 Subject: [PATCH] Integrate Serbea 1.0 into Bridgetown (#440) * Integrate Serbea 1.0 into Bridgetown * Add additional Serbea documentation * don't italicize erb/serbea syntax * serbea formatting --- bridgetown-core/.rubocop.yml | 1 + bridgetown-core/bridgetown-core.gemspec | 1 + .../converters/serbea_templates.rb | 71 ++++++++++++++++ .../test/resources/src/_pages/i-am-ruby.rb | 12 +++ .../test/source/src/_components/nested.erb | 2 +- .../source/src/_components/nested_serb.rb | 12 +++ .../source/src/_components/nested_serb.serb | 5 ++ .../test/source/src/_layouts/serblayout.serb | 15 ++++ .../src/_partials/testing/_partials.serb | 1 + .../test/source/src/page_using_serb.serb | 49 +++++++++++ bridgetown-core/test/test_filters.rb | 2 + bridgetown-core/test/test_layout_reader.rb | 1 + bridgetown-core/test/test_resource.rb | 16 ++++ bridgetown-core/test/test_serbea.rb | 58 +++++++++++++ bridgetown-core/test/test_site.rb | 1 + .../frontend/styles/syntax.scss | 2 +- .../src/_docs/erb-and-beyond.md | 85 +++++++++++++++++-- .../src/_docs/template-engines.md | 16 ++-- .../_pages/{plugins.liquid => plugins.serb} | 16 ++-- 19 files changed, 343 insertions(+), 23 deletions(-) create mode 100644 bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb create mode 100644 bridgetown-core/test/resources/src/_pages/i-am-ruby.rb create mode 100644 bridgetown-core/test/source/src/_components/nested_serb.rb create mode 100644 bridgetown-core/test/source/src/_components/nested_serb.serb create mode 100644 bridgetown-core/test/source/src/_layouts/serblayout.serb create mode 100644 bridgetown-core/test/source/src/_partials/testing/_partials.serb create mode 100644 bridgetown-core/test/source/src/page_using_serb.serb create mode 100644 bridgetown-core/test/test_serbea.rb rename bridgetown-website/src/_pages/{plugins.liquid => plugins.serb} (92%) diff --git a/bridgetown-core/.rubocop.yml b/bridgetown-core/.rubocop.yml index a518b8c97..a4fc51053 100644 --- a/bridgetown-core/.rubocop.yml +++ b/bridgetown-core/.rubocop.yml @@ -11,6 +11,7 @@ AllCops: - vendor/**/* - tmp/**/* - test/source/**/* + - test/resources/src/_pages/*.rb - lib/site_template/Rakefile - lib/site_template/config.ru - lib/site_template/config/**/* diff --git a/bridgetown-core/bridgetown-core.gemspec b/bridgetown-core/bridgetown-core.gemspec index bf5a0c578..288af5dbe 100644 --- a/bridgetown-core/bridgetown-core.gemspec +++ b/bridgetown-core/bridgetown-core.gemspec @@ -49,6 +49,7 @@ Gem::Specification.new do |s| s.add_runtime_dependency("rake", ">= 13.0") s.add_runtime_dependency("roda", "~> 3.46") s.add_runtime_dependency("rouge", "~> 3.0") + s.add_runtime_dependency("serbea", "~> 1.0") s.add_runtime_dependency("terminal-table", "~> 1.8") s.add_runtime_dependency("thor", "~> 1.1") s.add_runtime_dependency("tilt", "~> 2.0") diff --git a/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb b/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb new file mode 100644 index 000000000..991d85135 --- /dev/null +++ b/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb @@ -0,0 +1,71 @@ +# frozen_string_literal: true + +require "serbea" +require "rouge/lexers/serbea" + +module Bridgetown + class SerbeaView < ERBView + include Serbea::Helpers + + def partial(partial_name, options = {}, &block) + options.merge!(options[:locals]) if options[:locals] + options[:content] = capture(&block) if block + + partial_segments = partial_name.split("/") + partial_segments.last.sub!(%r!^!, "_") + partial_name = partial_segments.join("/") + + Tilt::SerbeaTemplate.new( + site.in_source_dir(site.config[:partials_dir], "#{partial_name}.serb") + ).render(self, options) + end + end + + module Converters + class SerbeaTemplates < Converter + priority :highest + input :serb + + # Logic to do the Serbea content conversion. + # + # @param content [String] Content of the file (without front matter). + # @param convertible [ + # Bridgetown::GeneratedPage, Bridgetown::Resource::Base, Bridgetown::Layout] + # The instantiated object which is processing the file. + # + # @return [String] The converted content. + def convert(content, convertible) + return content if convertible.data[:template_engine].to_s != "serbea" + + serb_view = Bridgetown::SerbeaView.new(convertible) + + serb_renderer = Tilt::SerbeaTemplate.new(convertible.relative_path) { content } + + if convertible.is_a?(Bridgetown::Layout) + serb_renderer.render(serb_view) do + convertible.current_document_output + end + else + serb_renderer.render(serb_view) + end + end + + def matches(ext, convertible) + if convertible.data[:template_engine].to_s == "serbea" || + (convertible.data[:template_engine].nil? && + @config[:template_engine].to_s == "serbea") + convertible.data[:template_engine] = "serbea" + return true + end + + super(ext).tap do |ext_matches| + convertible.data[:template_engine] = "serbea" if ext_matches + end + end + + def output_ext(ext) + ext == ".serb" ? ".html" : ext + end + end + end +end diff --git a/bridgetown-core/test/resources/src/_pages/i-am-ruby.rb b/bridgetown-core/test/resources/src/_pages/i-am-ruby.rb new file mode 100644 index 000000000..5ef5b3805 --- /dev/null +++ b/bridgetown-core/test/resources/src/_pages/i-am-ruby.rb @@ -0,0 +1,12 @@ +###ruby +front_matter do + layout :default + title "I am Ruby. Here me roar!" +end +### + +markdownify <<~MARKDOWN + + > Well, _this_ is quite interesting! =) + +MARKDOWN diff --git a/bridgetown-core/test/source/src/_components/nested.erb b/bridgetown-core/test/source/src/_components/nested.erb index 3b17f3e51..2e48b4a80 100644 --- a/bridgetown-core/test/source/src/_components/nested.erb +++ b/bridgetown-core/test/source/src/_components/nested.erb @@ -1,5 +1,5 @@ <%= @level %>: <%= content %> <%= render (Nested.new(level: @level + 1)) do %>Level <%= @level + 1 %><% end %> <% if @level == 4 %> - <%= markdownify("**#{site.config.level} 4!!**") %> + <%= markdownify("**#{site.config.level} 4!!**\n") %> <% end %> \ No newline at end of file diff --git a/bridgetown-core/test/source/src/_components/nested_serb.rb b/bridgetown-core/test/source/src/_components/nested_serb.rb new file mode 100644 index 000000000..bf1985467 --- /dev/null +++ b/bridgetown-core/test/source/src/_components/nested_serb.rb @@ -0,0 +1,12 @@ +# frozen_string_literal: true + +class NestedSerb < Bridgetown::Component + def initialize(level:) + @level = level + @site = Bridgetown::Current.site + end + + def render? + @level < 5 + end +end diff --git a/bridgetown-core/test/source/src/_components/nested_serb.serb b/bridgetown-core/test/source/src/_components/nested_serb.serb new file mode 100644 index 000000000..280c3ff17 --- /dev/null +++ b/bridgetown-core/test/source/src/_components/nested_serb.serb @@ -0,0 +1,5 @@ +{{ @level }}: {{ content }} +{%@ Nested level: @level + 1 do %}Level {{ @level + 1 }}{% end %} +{% if @level == 4 %} + {{ "**#{site.config.level} 4!!**" | markdownify }} +{% end %} \ No newline at end of file diff --git a/bridgetown-core/test/source/src/_layouts/serblayout.serb b/bridgetown-core/test/source/src/_layouts/serblayout.serb new file mode 100644 index 000000000..4ec8f2dfc --- /dev/null +++ b/bridgetown-core/test/source/src/_layouts/serblayout.serb @@ -0,0 +1,15 @@ +--- +layout_var: + - test +--- + +
Test? {%= layout[:layout_var].first %}
+ +

{{ page.data.title }}

+ +{%= yield %} + +{%= partial "testing/partials", locals: { yes: "yes." } %} +{%= render "testing/partials", yes: "YES!!" %} + + \ No newline at end of file diff --git a/bridgetown-core/test/source/src/_partials/testing/_partials.serb b/bridgetown-core/test/source/src/_partials/testing/_partials.serb new file mode 100644 index 000000000..84b2c734b --- /dev/null +++ b/bridgetown-core/test/source/src/_partials/testing/_partials.serb @@ -0,0 +1 @@ +A partial success? {{ yes }} \ No newline at end of file diff --git a/bridgetown-core/test/source/src/page_using_serb.serb b/bridgetown-core/test/source/src/page_using_serb.serb new file mode 100644 index 000000000..0a66393ae --- /dev/null +++ b/bridgetown-core/test/source/src/page_using_serb.serb @@ -0,0 +1,49 @@ +--- +layout: serblayout +title: I'm an Serbea Page +page_var: 123 +--- + +One two three: {%= page.data[:page_var] * 10 %} + +{%= liquid_render "test_component", param: "Liquid FTW!" %} + +Oats, {{ ["peas", "beans", "barley"] | array_to_sentence_string }} grow. + + {%= markdownify do %} + ## I'm a header! + + * Yay! + {%= "* Nifty!" %} + {% end %} + +{% test_capturing = capture do %} + This is how {%= "#{"cap"}turing" %} works! +{% end %} + +{{ test_capturing | reverse }} + +

classes!

+ +{%@ RubyComponent %} + +{%= render(Card.new(title: "I'm a card", footer: "I'm a footer")) do |c| %} + {% c.image do %} + + {% end %} +

I'm the body of the {%= c.kind %}

+{% end %} + +{%@ Card title: "Nope", footer: "CANCEL!" do %} + Canceled! +{% end %} + +{%= render (NestedSerb.new(level: 1)) do %}Level 1{% end %} + +{%= render Example::OverrideComponent.new %} + +=== +{%= test_block_helpers do |item| %} +{%= item[:value] %} +{% end %} +--- diff --git a/bridgetown-core/test/test_filters.rb b/bridgetown-core/test/test_filters.rb index eeff03a4b..e95fff403 100644 --- a/bridgetown-core/test/test_filters.rb +++ b/bridgetown-core/test/test_filters.rb @@ -849,6 +849,7 @@ def to_liquid assert( ["default", "erblayout", + "serblayout", "example/test_layout", "example/overridden_layout", "nil", @@ -1143,6 +1144,7 @@ def to_liquid assert( ["DEFAULT", "ERBLAYOUT", + "SERBLAYOUT", "EXAMPLE/TEST_LAYOUT", "EXAMPLE/OVERRIDDEN_LAYOUT", "NIL", diff --git a/bridgetown-core/test/test_layout_reader.rb b/bridgetown-core/test/test_layout_reader.rb index e8689e495..5c1a7410f 100644 --- a/bridgetown-core/test/test_layout_reader.rb +++ b/bridgetown-core/test/test_layout_reader.rb @@ -12,6 +12,7 @@ class TestLayoutReader < BridgetownUnitTest layouts = LayoutReader.new(@site).read assert_equal ["default", "erblayout", + "serblayout", "example/overridden_layout", "example/test_layout", "simple", diff --git a/bridgetown-core/test/test_resource.rb b/bridgetown-core/test/test_resource.rb index be2b33881..e26486766 100644 --- a/bridgetown-core/test/test_resource.rb +++ b/bridgetown-core/test/test_resource.rb @@ -311,6 +311,22 @@ class TestResource < BridgetownUnitTest end end + context "a PORT (Plain Ol' Ruby Template)" do + should "render out as HTML" do + @site = resources_site + @site.process + @dest_file = File.read(dest_dir("i-am-ruby/index.html")) + + assert_includes @dest_file, <<~HTML + +
+

Well, this is quite interesting! =)

+
+ + HTML + end + end + context "dotfile permalink" do should "get saved to destination" do @site = resources_site diff --git a/bridgetown-core/test/test_serbea.rb b/bridgetown-core/test/test_serbea.rb new file mode 100644 index 000000000..b2eada175 --- /dev/null +++ b/bridgetown-core/test/test_serbea.rb @@ -0,0 +1,58 @@ +# frozen_string_literal: true + +require "helper" + +class TestSerbea < BridgetownUnitTest + def setup + @site = fixture_site + @site.process + @serb_page = @site.resources.find { |p| p.data[:title] == "I'm an Serbea Page" } + end + + context "Serbea page" do + should "render page vars" do + assert_includes @serb_page.output, "One two three: 1230" + end + + should "render Liquid components" do + assert_includes @serb_page.output, "Liquid FTW!" + end + + should "render Ruby/Serbea components" do + assert_includes @serb_page.output, "1: Level 1" + assert_includes @serb_page.output, "

** 4!!**

" + end + + should "provide full suite of Liquid filters" do + assert_includes @serb_page.output, "Oats, peas, beans, and barley grow." + end + + should "allow Markdown content via a helper" do + assert_includes @serb_page.output, "

I’m a header!

" + assert_includes @serb_page.output, "
  • Yay!
    • " + assert_includes @serb_page.output, "
  • Nifty!
    • " + end + + should "allow capturing into a variable" do + assert_includes @serb_page.output, "This is how capturing works!".reverse + end + + should "properly handle block expressions" do + assert_includes @serb_page.output, "\n===\n+Value: value+\n---\n" + end + end + + context "Serbea layout" do + should "render layout vars" do + assert_includes @serb_page.output, "Test? test" + assert_includes @serb_page.output, "

    I'm an Serbea Page

    " + + assert_includes @serb_page.output, "" + end + + should "render partials" do + assert_includes @serb_page.output, "A partial success? yes." + assert_includes @serb_page.output, "A partial success? YES!!" + end + end +end diff --git a/bridgetown-core/test/test_site.rb b/bridgetown-core/test/test_site.rb index e77c3983c..5e5d38e79 100644 --- a/bridgetown-core/test/test_site.rb +++ b/bridgetown-core/test/test_site.rb @@ -166,6 +166,7 @@ class TestSite < BridgetownUnitTest main.scss page_from_a_plugin.html page_using_erb.erb + page_using_serb.serb properties.html sitemap.xml static_files.html diff --git a/bridgetown-website/frontend/styles/syntax.scss b/bridgetown-website/frontend/styles/syntax.scss index b1ac76382..0415b1b87 100644 --- a/bridgetown-website/frontend/styles/syntax.scss +++ b/bridgetown-website/frontend/styles/syntax.scss @@ -15,7 +15,7 @@ $base-code-text-color: #403030; .highlight .x { color: $base-code-text-color } /* Other */ .highlight .p { color: $base-code-text-color; font-weight: 500 } /* Punctuation */ .highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */ +.highlight .cp { color: #8f5902; } /* Comment.Preproc */ .highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ .highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ .highlight .gd { color: #a40000 } /* Generic.Deleted */ diff --git a/bridgetown-website/src/_docs/erb-and-beyond.md b/bridgetown-website/src/_docs/erb-and-beyond.md index 315634c10..9b6f30614 100644 --- a/bridgetown-website/src/_docs/erb-and-beyond.md +++ b/bridgetown-website/src/_docs/erb-and-beyond.md @@ -10,15 +10,15 @@ Bridgetown's primary template language is [**Liquid**](/docs/liquid), due to his However, Bridgetown's implementation language, Ruby, has a rich history of providing [ERB (Embedded RuBy)](https://docs.ruby-lang.org/en/2.7.0/ERB.html) for templates and view layers across a wide variety of tools and frameworks. Other Ruby-based template languages such as [Haml](https://haml.info), [Slim](http://slim-lang.com), and [Serbea](https://www.serbea.dev) garner enthusiastic usage as well. -Bridgetown makes it easy to add ERB-based templates and components to any site. In additional, there are plugins you can easily install for Haml, Slim, and Serbea support. Under the hood, Bridgetown uses the [Tilt gem](https://github.com/rtomayko/tilt) to load and process these Ruby templates. +Bridgetown makes it easy to add both ERB-based and Serbea-based templates and components to any site. In additional, there are plugins you can easily install for Haml and Slim support. Under the hood, Bridgetown uses the [Tilt gem](https://github.com/rtomayko/tilt) to load and process these Ruby templates. -Interested in switching your entire site to use ERB by default? [It's possible to do that too!](/docs/template-engines) +Interested in switching your entire site to use ERB or Serbea by default? [It's possible to do that too!](/docs/template-engines) <%= toc %> ## Usage -Simply define a page/document with an `.erb` extension, rather than `.html`. You'll still need to add front matter to the top of the file (or at the very least two lines of triple dashes `---`) for the file to get processed. In the Ruby code you embed, you'll be interacting with the underlying Ruby API for Bridgetown objects (aka `Bridgetown::Page`, `Bridgetown::Site`, etc.). Here's an example: +For ERB, simply define a page/document with an `.erb` extension, rather than `.html`. You'll still need to add front matter to the top of the file (or at the very least two lines of triple dashes `---`) for the file to get processed. In the Ruby code you embed, you'll be interacting with the underlying Ruby API for Bridgetown objects (aka `Bridgetown::Page`, `Bridgetown::Site`, etc.). Here's an example: ```eruby --- @@ -54,14 +54,67 @@ You can easily loop through resources in a collection: <%% end %> ``` -Or using the [paginator](/docs/content/pagination): +Or using the [paginator](/docs/content/pagination), along with the `link_to` helper: ```eruby <%% paginator.resources.each do |post| %> -
  • <%%= post.data.title %>
    • +
  • <%%= link_to post.data.title, post %>
    • <%% end %> ``` +### Serbea + +Serbea is a "superset" of ERB which provides the same benefits as ERB but uses curly braces like Liquid `{% %}` or `{{ }}` and adds support for filters and render directives. Use the file extension `.serb`. Here's an example of the above ERB code rewritten in Serbea: + +```serb +{% collections.posts.resources.each do |post| %} +
  • {{ post.data.title }}
    • +{% end %} + +---- + +{% paginator.resources.each do |post| %} +
  • {{ post.data.title | link_to: post }}
    • +{% end %} +``` + +Notice this is using the Liquid-like filter syntax for `link_to`. You can use this kind of syntax with _any_ helpers available in all Ruby templates, as well as methods on objects themselves. Examples: + +```serb +{{ resource.data.description | markdownify }} + +{{ resource.data.title | titleize }} + +{{ resource.data.tags | array_to_sentence_string: "or" }} + +{{ resource.data.upcase_me | upcase }} +``` + +(Under the hood, a Ruby method's first argument will be supplied with the value of the left-side of the pipe `|` operator, and subsequent arguments continue after that as you write the filter syntax.) + +For Serbea code samples in Markdown, use the `serb` tag. And like ERB, you can escape using two percent signs: + +~~~md +Here's·my·**Markdown**·file. + +```serb +And·my·{%%= "ERB·code·sample" %} +``` +~~~ + +Serbea also provides a `raw` helper just like Liquid for escaping Serbea code: + +```serb + +Process me! {% do_something %} + +Don't process me! {% raw %}{% do_something %}{% endraw %} +``` + +There's a [VS Code extension available for Serbea](https://marketplace.visualstudio.com/items?itemName=whitefusion.serbea) which includes syntax highlighting as well as commands to convert selected ERB syntax to Serbea, and even a Serbea + Markdown highlighter. + +For details on HTML output safety, see below (Serbea and ERB differ slightly on how escaping is accomplished). + ## Dot Access Hashes Data hashes support standard hash key access, but most of the time you can use "dot access" instead for a more familar look. For example: @@ -350,7 +403,7 @@ Usage is pretty straightforward: ## Escaping and HTML Safety -Starting in Bridgetown v0.21, the ERB template engine has switched to using a safe output buffer—[the same one used in Rails](https://guides.rubyonrails.org/active_support_core_extensions.html#output-safety). +The ERB template engine uses a safe output buffer—[the same one used in Rails](https://guides.rubyonrails.org/active_support_core_extensions.html#output-safety). That means that you'll sometimes find that if you simply output a front matter variable or some other string value that contains HTML tags and entities, the string will be "escaped" so that the actual angle brackets and so forth are displayed in the website content (rather than being interpreted as valid HTML tags). @@ -370,6 +423,26 @@ Note that using `html_safe` directly _requires_ the value to be a string already If you find a particular use case where escaping occurs (or doesn't occur) in an unexpected manner, [please file a bug report in the Bridgetown GitHub repo](https://github.com/bridgetownrb/bridgetown/issues/new?assignees=&labels=bug&template=bug_report.md&title=). +### When Using Serbea + +Serbea only escapes values by default when using the double-braces syntax `{{ }}`. When using `{%= %}`, escaping does _not_ occur by default. + +```serb +str = "

    Escape me!

    " + +{{ str }} +{%= str %} +``` + +To explicitly escape a value when using percent signs, use the `escape` or `h` helper. To explicitly mark a value as safe when using double-braces, use the `safe` or `raw` filter: + +```serb +str = "

    Escape me!

    " + +{{ str | safe }} +{%= escape(str) %} +``` + ## Haml and Slim Bridgetown comes with ERB support out-of-the-box, but you can easily add support for either Haml or Slim by installing our officially supported plugins. diff --git a/bridgetown-website/src/_docs/template-engines.md b/bridgetown-website/src/_docs/template-engines.md index 3b5733820..aa63ed403 100644 --- a/bridgetown-website/src/_docs/template-engines.md +++ b/bridgetown-website/src/_docs/template-engines.md @@ -8,15 +8,17 @@ category: engines Bridgetown's primary template language is [**Liquid**](/docs/liquid), due to historical reasons (its heritage coming from Jekyll) and well as Liquid's simple syntax and safe execution context making it ideal for designer-led template creation. -However, starting in v0.18, you can configure Bridgetown to use [ERB](/docs/erb-and-beyond) as its primary template engine, and in addition you can specify your preferred template engine (including even Haml or Slim) on a per-file basis. +However, you're welcome to use a variety of different template engines within Bridgetown simply by using the appropriate file extension (aka `.erb`), or by specifying the template engine in your resource's front matter. You can also configure Bridgetown to use a language other than Liquid as the "default" template engine regardless of file extension. -## But Why? +Out of the box, Bridgetown provides support for both [ERB and Serbea](/docs/erb-and-beyond) and you can also use Haml or Slim by installing additional plugins. + +## Why Switch from Liquid? Liquid is a great way to start out if you're not that familiar with Ruby, because it feels more akin to template engines like Mustache, Jinja, Nunjucks, Twig, and so forth. Simple tags and filters, along with loops and conditional statements, let you construct templates quickly and easily. But if you need more power (especially when writing [components](/docs/components)) or you're already familiar with Ruby and engines such as ERB, then the cognitive overhead to learn and stick with Liquid can actually become a hindrance. In addition, it's an important goal for Bridgetown to integrate well with a development workflow which already incorporates the [Ruby on Rails framework](https://rubyonrails.org){:rel="noopener"}. Or perhaps you're looking to switch from [Middleman](https://middlemanapp.com){:rel="noopener"} which uses ERB by default. -In any case, the ability to "pick your flavor" of template engines on a site-by-site or file-by-file basis is now one of Bridgetown's core strengths as a web framework. +In any case, the ability to "pick your flavor" of template engines on a site-by-site or file-by-file basis is one of Bridgetown's core strengths as a web framework. {% rendercontent "docs/note" %} For more information on how to use Ruby-based templates in general, take a look at [ERB and Beyond](/docs/erb-and-beyond). @@ -36,14 +38,14 @@ Besides adding `template_engine` directly in your file's front matter, you could ## Site-wide Configuration -Most likely, however, you'll want to switch your site wholesale from one engine to another. That's where `bridgetown.config.yml` comes in. Simply add `template_engine: erb` right in your config, and suddenly *everything* will get processed through ERB regardless of file extension. Write HTML, XML, Markdown, JSON, CSV, whatever you like—and _still_ access the full power of your Ruby template language of choice. You don't even need to give up on Liquid completely—just save files with `.liquid` or use `template_engine: liquid` front matter. +Most likely, however, you'll want to switch your site wholesale from one engine to another. That's where `bridgetown.config.yml` comes in. Simply add `template_engine: erb` right in your config, and suddenly *everything* will get processed through ERB regardless of file extension. Serbea works in the same manner: `template_engine: serbea`. Write HTML, XML, Markdown, JSON, CSV, whatever you like—and _still_ access the full power of your Ruby template language of choice. You don't even need to give up on Liquid completely—just save files with `.liquid` or use `template_engine: liquid` front matter. -It's worth noting that by combining Markdown, ERB, components, and frontend JavaScript "sprinkles" (or "spices" as we like to say), you can author extremely sophisticated documents which boast stunning performance and SEO scores while at the same time providing impressive interactivity in the browser. This is quickly becoming a "best practice" in the web development industry, and Bridgetown will help get you there. +It's worth noting that by combining Markdown, ERB/Serbea, components, and frontend JavaScript "sprinkles" (or "spices" as we like to say), you can author extremely sophisticated documents which boast stunning performance and SEO scores while at the same time providing impressive interactivity in the browser. This is quickly becoming a "best practice" in the web development industry, and Bridgetown will help get you there. {% rendercontent "docs/note", type: "warning", extra_margin: true %} -While it's true you can use ERB site-wide, the [Haml](https://github.com/bridgetownrb/bridgetown-haml){:rel="noopener"} and [Slim](https://github.com/bridgetownrb/bridgetown-slim){:rel="noopener"} plugins do _not_ allow site-wide configuration. That's because both Haml and Slim start with pure HTML/XML output using special syntax, and if you want to do something else like write Markdown or JSON, you'll have to use their "embedded" language support. Read their documentation for further details. +While it's true you can use ERB or Serbea site-wide, the [Haml](https://github.com/bridgetownrb/bridgetown-haml){:rel="noopener"} and [Slim](https://github.com/bridgetownrb/bridgetown-slim){:rel="noopener"} plugins do _not_ allow site-wide configuration. That's because both Haml and Slim start with pure HTML/XML output using special syntax, and if you want to do something else like write Markdown or JSON, you'll have to use their "embedded" language support. Read their documentation for further details. {% endrendercontent %} ## It's Up to You -Regardless of which template engine you pick, whether it's [Liquid](/docs/liquid) or [ERB](/docs/erb-and-beyond) or something else, Bridgetown has got you covered. We continue to look for ways to make switching engines easier while reducing the number of "sharp edges" that can arise to differences in how various template engines process content, so please don't hesitate to [let us know](/docs/community) if you run in to any issues. \ No newline at end of file +Regardless of which template engine you pick, whether it's [Liquid](/docs/liquid), [ERB, Serbea](/docs/erb-and-beyond), or something else, Bridgetown has got you covered. We continue to look for ways to make switching engines easier while reducing the number of "sharp edges" that can arise to differences in how various template engines process content, so please don't hesitate to [let us know](/docs/community) if you run in to any issues. \ No newline at end of file diff --git a/bridgetown-website/src/_pages/plugins.liquid b/bridgetown-website/src/_pages/plugins.serb similarity index 92% rename from bridgetown-website/src/_pages/plugins.liquid rename to bridgetown-website/src/_pages/plugins.serb index c2a7c0165..fbbac6957 100644 --- a/bridgetown-website/src/_pages/plugins.liquid +++ b/bridgetown-website/src/_pages/plugins.serb @@ -1,4 +1,4 @@ ----ruby +~~~{% { layout: :default, title: "Jazz Up Your Site with Themes & Plugins", @@ -33,23 +33,23 @@ items end } ---- +%}~~~ -{% rendercontent "shared/page_layout" %} -

    {{ page.title }}

    +{%= liquid_render "shared/page_layout" do %} +

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

    - {% for plugin in page.plugins %} + {% page.data.plugins.each do |plugin| %}

    {{ plugin.name }} {% if plugin.gem_version %} v{{ plugin.gem_version }} - {% endif %} + {% end %}

    @@ -62,5 +62,5 @@ {{ plugin.owner.login }}
    - {% endfor %} -{% endrendercontent %} + {% end %} +{% end %}