Trying Just the Docs theme #204

ultraq · Apr 19, 2020 · 64cbb6c · 64cbb6c
1 parent 92da953
commit 64cbb6c
Show file tree

Hide file tree

Showing 11 changed files with 781 additions and 117 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,2 +1,2 @@
-/.jekyll-cache
+/.sass-cache
 _site
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -1,7 +1,4 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "/~https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
 
 gem "jekyll"
+gem "just-the-docs"
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -4,64 +4,66 @@ GEM
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
     colorator (1.1.0)
-    concurrent-ruby (1.1.5)
+    concurrent-ruby (1.1.6)
     em-websocket (0.5.1)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0.6.0)
     eventmachine (1.2.7)
-    ffi (1.11.1)
+    ffi (1.12.2)
     forwardable-extended (2.6.0)
     http_parser.rb (0.6.0)
-    i18n (1.6.0)
+    i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jekyll (4.0.0)
+    jekyll (3.8.6)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
-      i18n (>= 0.9.5, < 2)
-      jekyll-sass-converter (~> 2.0)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
       jekyll-watch (~> 2.0)
-      kramdown (~> 2.1)
-      kramdown-parser-gfm (~> 1.0)
+      kramdown (~> 1.14)
       liquid (~> 4.0)
       mercenary (~> 0.3.3)
       pathutil (~> 0.9)
-      rouge (~> 3.0)
+      rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
-      terminal-table (~> 1.8)
-    jekyll-sass-converter (2.0.0)
-      sassc (> 2.0.1, < 3.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.6.1)
+      jekyll (>= 3.3, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.1.0)
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
+    just-the-docs (0.2.7)
+      jekyll (~> 3.8.5)
+      jekyll-seo-tag (~> 2.0)
+      rake (~> 12.3.1)
+    kramdown (1.17.0)
     liquid (4.0.3)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
+    listen (3.2.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (4.0.1)
+    public_suffix (4.0.4)
+    rake (12.3.3)
     rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
+    rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rouge (3.10.0)
-    ruby_dep (1.5.0)
+    rouge (3.18.0)
     safe_yaml (1.0.5)
-    sassc (2.2.0)
-      ffi (~> 1.9)
-    terminal-table (1.8.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    unicode-display_width (1.6.0)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   jekyll
+  just-the-docs
 
 BUNDLED WITH
-   2.0.2
+   2.1.4
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,4 @@
+title: "Thymeleaf Layout Dialect"
+description: "A dialect for Thymeleaf that lets you build layouts and reusable templates in order to improve code reuse"
+baseurl: "/thymeleaf-layout-dialect"
+theme: "just-the-docs"
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,185 @@
+---
+layout: default
+title: Configuration
+nav_order: 5
+---
+
+Configuration
+=============
+
+
+`<head>` element merging
+------------------------
+
+When decorating the `<head>` sections of the content and layout templates, the
+default behaviour is to place all content elements after the layout ones, eg:
+
+```html
+Content.html
+
+<head>
+  <title>Hello!</title>
+  <link rel="stylesheet" href="content-stylesheet.css"/>
+  <script src="content-script.js"></script>
+</head>
+```
+
+```html
+Layout.html
+
+<head>
+  <title>Goodbye!</title>
+  <link rel="stylesheet" href="layout-stylesheet.css"/>
+  <script src="layout-script.js"></script>
+</head>
+```
+
+Result:
+
+```html
+<head>
+  <title>Hello!</title>
+  <link rel="stylesheet" href="layout-stylesheet.css"/>
+  <script src="layout-script.js"></script>
+  <link rel="stylesheet" href="content-stylesheet.css"/>
+  <script src="content-script.js"></script>
+</head>
+```
+
+However, sometimes we need a smarter merging of elements, such as grouping like
+elements together (having scripts with scripts and stylesheets with stylesheets).
+
+```html
+Content.html
+
+<head>
+  <title>Hello!</title>
+  <link rel="stylesheet" href="content-stylesheet.css"/>
+  <script src="content-script.js"></script>
+</head>
+```
+
+```html
+Layout.html
+
+<head>
+  <title>Goodbye!</title>
+  <link rel="stylesheet" href="layout-stylesheet.css"/>
+  <script src="layout-script.js"></script>
+</head>
+```
+
+Result:
+
+```html
+<head>
+  <title>Hello!</title>
+  <link rel="stylesheet" href="layout-stylesheet.css"/>
+  <link rel="stylesheet" href="content-stylesheet.css"/>
+  <script src="layout-script.js"></script>
+  <script src="content-script.js"></script>
+</head>
+```
+
+The Layout dialect can be configured to support either use case, with the
+ability for developers to define their own sorting.
+
+This sorting is exposed by the `nz.net.ultraq.thymeleaf.decorators.SortingStrategy`
+interface and the layout dialect provides 4 implementations to choose from:
+
+ - `nz.net.ultraq.thymeleaf.decorators.strategies.AppendingStrategy`, the
+   default, appends content `<head>` elements after layout ones.  Deprecated.
+ - `nz.net.ultraq.thymeleaf.decorators.strategies.GroupingStrategy`, groups like
+   elements together.  Deprecated.
+ - `nz.net.ultraq.thymeleaf.decorators.strategies.AppendingRespectLayoutTitleStrategy`,
+   a new variant of the `AppendingStrategy` which respects the position of the
+   `<title>` element based on its position in the layout template.
+ - `nz.net.ultraq.thymeleaf.decorators.strategies.GroupingRespectLayoutTitleStrategy`,
+   a new variant of the `GroupingStrategy` which respects the position of the
+   `<title>` element based on its position in the layout template.
+
+> The default behaviour of the layout dialect has historically been to place the
+> `<title>` element at the beginning of the `<head>` element during the
+> decoration process; an arbitrary design decision which made development of
+> this library easier.  However, this runs against the expectations of
+> developers who wished to control the order of elements, most notably the
+> practice of putting `<meta charset...>` as the first element in the `<head>`.
+> The new strategies (ones with `RespectLayoutTitle` in their name) instead keep
+> `<title>`s wherever they exist within the target/layout template being
+> decorated, and then work on everything else as normal.
+> 
+> The `RespectLayoutTitle` strategies were introduced in version 2.4.0 and will
+> become the default strategies from version 3.x.  The existing strategies are
+> now deprecated but retain the historic behaviour, maintaining backwards
+> compatibility with the 2.x versions.
+
+To change to the grouping strategy, configure the Layout dialect using one of
+the methods below.
+
+For those who are configuring their own Thymeleaf template engine:
+
+```java
+TemplateEngine templateEngine = new TemplateEngine();  // Or SpringTemplateEngine for Spring
+templateEngine.addDialect(new LayoutDialect(new GroupingRespectLayoutTitleStrategy()));
+```
+
+For those using XML config in Spring:
+
+```xml
+<bean id="groupingStrategy" class="nz.net.ultraq.thymeleaf.decorators.strategies.GroupingRespectLayoutTitleStrategy"/>
+
+<bean id="templateEngine" class="org.thymeleaf.spring4.SpringTemplateEngine">
+  <property name="additionalDialects">
+    <set>
+      <bean class="nz.net.ultraq.thymeleaf.LayoutDialect">
+        <constructor-arg ref="groupingStrategy"/>
+      </bean>
+    </set>
+  </property>
+</bean>
+```
+
+For those using Spring Boot and Java configuration:
+
+```java
+@Bean
+public LayoutDialect layoutDialect() {
+	return new LayoutDialect(new GroupingRespectLayoutTitleStrategy());
+}
+```
+
+If neither strategy suits your needs, you can implement your own `SortingStrategy`
+and pass it along to the layout dialect like above.
+
+
+Bypassing `<head>` element merging altogether
+---------------------------------------------
+
+From version 2.4.0, an experimental option was added to skip the special `<head>`
+merging entirely.  Reasons for this might be that you wish to manage that
+section yourself so are using things like Thymeleaf's `th:replace` to fill that
+special part of your HTML document in.
+
+To bypass the layout dialect's `<head>` element merging, a second parameter to
+the `LayoutDialect` constructor should be set to `false`.  (The first parameter
+can be set to `null` as a merging strategy isn't really relevant when `<head>`
+element merging is disabled.)
+
+For those who are configuring their own Thymeleaf template engine:
+
+```java
+TemplateEngine templateEngine = new TemplateEngine();  // Or SpringTemplateEngine for Spring
+templateEngine.addDialect(new LayoutDialect(null, false));
+```
+
+For those using Spring Boot and Java configuration:
+
+```java
+@Bean
+public LayoutDialect layoutDialect() {
+	return new LayoutDialect(null, false);
+}
+```
+
+When disabled, the `<head>` element will be whatever it was in the content
+template, so the `<head>` from the layout is not applied.