RubyGems - shoreditch - Versions diffs - 1.1.0 - Mend

shoreditch 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +148 -0
data/Gemfile +5 -0
data/LICENSE.md +9 -0
data/README.md +230 -0
data/bridgetown.automation.rb +277 -0
data/components/shoreditch/comments.erb +25 -0
data/components/shoreditch/comments.rb +49 -0
data/components/shoreditch/details.erb +52 -0
data/components/shoreditch/details.rb +83 -0
data/components/shoreditch/head_icons.erb +12 -0
data/components/shoreditch/head_icons.rb +48 -0
data/components/shoreditch/post_summary.erb +19 -0
data/components/shoreditch/post_summary.rb +37 -0
data/components/shoreditch/sidebar.erb +64 -0
data/components/shoreditch/sidebar.rb +67 -0
data/content/shoreditch/shoreditch.css +991 -0
data/content/shoreditch/shoreditch.js +102 -0
data/layouts/shoreditch/default.erb +89 -0
data/layouts/shoreditch/page.erb +27 -0
data/layouts/shoreditch/post.erb +72 -0
data/lib/shoreditch/icons.rb +32 -0
data/lib/shoreditch/version.rb +5 -0
data/lib/shoreditch.rb +70 -0
data/shoreditch.gemspec +41 -0
metadata +112 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2afe1ffff65e9ece59afc75378470a72fcafc495f74d1a9b3f25396c03452a70
+  data.tar.gz: 6990c1918011c9a5b60660e737e438964a52fe511180bbdbf0bc59ca30f50f21
+SHA512:
+  metadata.gz: 6a3f2dbac7af5e77dc3b06a55c79edca5b630201bee92d74240ae4a4f87522dcfafc1571f606ba765b1d532197dfb695f0dd93b2fabe2d0c5650efb5cd1130ca
+  data.tar.gz: 7e848819d28f74639dc9732f0f9211402ce4400c7f4d64c23b635392b48107fdf33c2bc954dbe798dbbe6ae0c2be4d30ee4428d9fb7f1fa72ddd8cbf8ad5cff9

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,148 @@
+# Changelog
+## 1.1.0
+First version published to RubyGems. Restores features the 1.0.0 rewrite
+dropped without recording, and fixes a set of defects that only showed up once
+the demo rendered the theme correctly.
+### Fixed
+- **The `accent` option did nothing.** `--sd-accent` was hardcoded in the
+  stylesheet and the configured value was never emitted. It is now applied from
+  the initializer, after the theme's CSS and before the site's own, and
+  validated so a site's config cannot inject CSS.
+- **Index listings reserved a thumbnail column whether or not there was a
+  thumbnail**, squeezing every title and excerpt of a post without one into a
+  128px ribbon.
+- **Syntax highlighting is now owned by the theme.** It sets the code
+  background, so a site shipping the light-only Rouge palette that
+  `bridgetown new` generates rendered keywords black on near-black in dark
+  mode.
+- `aria-current` was HTML-escaped, so the current nav item was never
+  highlighted.
+- `<body>` carried `HashWithDotAccess::Hash`, from `data.class` resolving to
+  Ruby's `Object#class` rather than the front-matter `class` key.
+- Excerpts were the first *source line*, so hard-wrapped markdown was cut
+  mid-sentence. `<!--more-->` is honoured, otherwise the first paragraph.
+- Every generated tag page shared one `<title>`.
+- Code blocks were padded twice, Rouge nesting `pre.highlight` inside
+  `div.highlight` and both matching the same rule.
+- Pagination rendered an empty nav, and its margin, when there was one page.
+- **An automation-installed site never rendered as the theme.** The scaffold's
+  starter layouts beat the theme's for every page whose front matter named
+  them — including the scaffold's own welcome post, whose explicit `layout:
+  post` also defeated the automation's `_defaults.yml` — and the starter
+  stylesheet trampled what remained. The automation now retires a starter
+  layout or stylesheet only when it is *exactly* the untouched scaffold
+  (whitespace aside), points the pages that named a retired layout at the
+  theme's — editing only their front matter, never a `layout:` line in body
+  text — and leaves anything a site has changed in place with a note.
+- **The automation could execute a prompt answer as code.** Answers were
+  interpolated into the generated `config/initializers.rb` verbatim, so an
+  answer such as `#{`…`}` ran as Ruby every time the site loaded, and one
+  containing a quote produced a file that would not parse. Answers carrying a
+  quote, a backslash, a newline or a Ruby interpolation are now rejected with
+  a note to set that option by hand — escaping was not enough, because
+  Bridgetown's initializer insertion rewrites backslashes.
+### Added
+- `--sd-rule-strong`, a heavier companion to `--sd-rule`. A hairline separator
+  can afford to be almost invisible; a border drawn around something so it reads
+  as one object cannot. Index entries use it.
+- **Comments**, off unless configured. Giscus ships as the default provider;
+  overriding `components/shoreditch/comments.erb` swaps in any other. Replaces
+  the Disqus support removed in 1.0.0, without the third-party trackers.
+- **The contact panel**, restored from the Jekyll `details.html` include. Brand
+  marks are vendored from Simple Icons (CC0) and inlined, rather than loading a
+  Font Awesome kit from a CDN on every page.
+- **Per-page sidebar overrides** — `include_sticky`, `include_details`,
+  `include_logo`, `logo_location`, `logo_shape`, `logo_legend_shape` and
+  `flashy_logo`, as the Jekyll version had them.
+- **CV styling**, opted into with `class: cv`. Not a layout: a CV is an
+  ordinary page whose front matter reshapes the sidebar and whose body class
+  tightens the type.
+- `.pullquote` and `.code-title` styling, both of which the documentation
+  demonstrated but the stylesheet never defined.
+- `.sd-archive` styling for a flat post archive — titles left, dates right in
+  tabular figures, a hairline rule between entries. The page supplies the
+  markup (the demo's Posts page groups by year); the theme ships the style.
+### Changed
+- **The sidebar becomes a compact header band on narrow screens.** Below 60rem
+  it had been the desktop column rendered at phone width with nothing resized —
+  a 128px logo, a centred stack, the theme toggle and the copyright all ahead of
+  the article. On a 390px phone that was 439px of chrome, putting a post's title
+  at 80% of the first screen and its copyright notice above the headline. The
+  logo now sits inline with the site title, the navigation runs beneath it, and
+  the toggle and copyright drop to the foot of the page: 137px, with the title
+  at 45%. No menu to open and no JavaScript — the parts are promoted to items of
+  the page shell with `display: contents` and reordered.
+- **Index entries are framed again**, as they were up to 0.9.0, rather than
+  separated by a hairline rule. The frame is what gives the listing a single
+  left edge: a post with no thumbnail began its title at the content edge while
+  its neighbours began an image-column in, so the stack read as ragged.
+  Thumbnails now sit flush to the frame and fill the card's height instead of
+  floating inside it with their own rounded corners, excerpts are clamped to
+  three lines at a line boundary, and the date moves above the title, set in the
+  mono face.
+- **Index excerpts are set as plain text** whatever block the post opens with.
+  A post beginning with `{:.message}` or a blockquote put a filled, accent-barred
+  box in the listing while its neighbours stayed plain.
+- **The sidebar splits top and bottom.** The logo, badge, site title and
+  tagline stay at the top of the column; the navigation and footer drop to the
+  bottom. Previously everything stacked from the top, leaving the empty space
+  below the nav with nothing to do.
+- **Node 22 is now required** for the frontend build. Bridgetown's esbuild
+  configuration calls `fs.globSync`, added in Node 22; on Node 20 the build
+  fails while the site still serves, so CSS changes silently never appear.
+  Pinned in `demo/.nvmrc`.
+## 1.0.0
+First Bridgetown release. Shoreditch was a Jekyll theme up to 0.9.0; this is a
+rewrite rather than a port, so nothing upgrades in place from the Jekyll
+version.
+### Changed
+- Distributed as a gem-based Bridgetown plugin. Previously the only way to use
+  it was to clone or fork the repo and edit in place; now `bundle add
+  shoreditch` and `init :shoreditch` is enough, and updates arrive through
+  `bundle update`.
+- Templates are ERB rather than Liquid, as components and layouts served
+  through a source manifest.
+- Stylesheet rewritten. The inherited `hyde.sass` and `poole.sass` layers are
+  gone, along with the Sass dependency; it is now one plain CSS file driven by
+  custom properties.
+- The sidebar is flexbox, finishing the rewrite announced but abandoned in the
+  Jekyll version's final week.
+- Fonts are the system stack. The Jekyll version loaded Roboto and Rosario from
+  Google Fonts over plain HTTP, which was both a privacy leak and mixed
+  content.
+- Favicon links are emitted only for files that exist. The Jekyll version
+  hard-coded seventeen icon links whether or not the site had them.
+### Added
+- Light and dark themes, from `prefers-color-scheme` plus a sidebar toggle that
+  remembers the reader's choice. Applied before first paint, so no flash.
+- Configuration through the initializer: `accent`, `sidebar_side`,
+  `logo_legend`, `logo_shape`.
+- `bridgetown.automation.rb`, so `bin/bridgetown apply` installs and configures
+  the theme in one step.
+- Open Graph and Twitter card metadata.
+- A skip link, `aria-current` on the active nav item, and visible focus rings.
+- `prefers-reduced-motion` support.
+### Removed
+- Disqus comments. Add them from your own layout override if you want them.
+- The Google Analytics hook. Use a privacy-preserving analytics script from
+  your site's own head if you need it.
+- The `jekyll-paginate-v2` and `classifier-reborn` dependencies — Bridgetown
+  paginates natively, and related-posts is a site concern rather than a theme
+  one.
+- The version badge in the sidebar.

data/Gemfile ADDED Viewed

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+gemspec

data/LICENSE.md ADDED Viewed

@@ -0,0 +1,9 @@
+# Released under MIT License
+Copyright (c) 2013 Mark Otto.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md ADDED Viewed

@@ -0,0 +1,230 @@
+# Shoreditch
+A two-column [Bridgetown](https://www.bridgetownrb.com) theme built for
+technical blogging: a fixed sidebar, optional cover images, and a content
+column deliberately wide enough that 80-character code samples do not wrap.
+See it at [shoreditch.mehcoleman.com](https://shoreditch.mehcoleman.com).
+Shoreditch is adapted from the excellent [Hyde](http://hyde.getpoole.com) theme
+by [@mdo](https://github.com/mdo), and was also inspired by [Flexible
+Jekyll](https://github.com/artemsheludko/flexible-jekyll) by Artem Sheludko.
+Both are worth a look.
+## Install
+```
+bin/bridgetown apply https://github.com/MEHColeman/shoreditch
+```
+The automation asks for an accent colour and a badge text, installs the gem,
+and points your posts and pages at the theme's layouts. On a fresh site it
+also retires the scaffold's starter stylesheet and layouts, which would
+otherwise override the theme — but only files that are *exactly* the untouched
+`bridgetown new` scaffold; anything you have edited is left alone with a note.
+An accent or badge answer that contains a quote, a backslash or a `#{…}` is
+declined rather than written into your config, since it would otherwise land
+in generated Ruby — set those options by hand if you need such characters.
+Or by hand:
+```
+bundle add shoreditch
+```
+then in `config/initializers.rb`:
+```ruby
+init :shoreditch
+```
+There is nothing to add to your esbuild entry points. The theme's stylesheet
+and script ship as static files through the gem's source manifest, so
+`bundle update shoreditch` is all it takes to move to a new version.
+## Options
+```ruby
+init :shoreditch do
+  accent "#c7254e"          # any CSS colour; drives links, tags, focus rings
+  sidebar_side "right"      # "left" (default) or "right"
+  logo_legend "For hire"    # badge under the logo; omit for none
+  logo_shape "square"       # "round" (default) or "square"
+  logo_legend_shape "straight"  # "round" (default) or "straight"
+end
+```
+`accent` is validated before it reaches the stylesheet — a value that is not a
+recognisable CSS colour falls back to the default rather than emitting broken
+CSS.
+## Comments
+Off unless configured. The theme ships [Giscus](https://giscus.app), which
+stores comments as GitHub Discussions:
+```ruby
+init :shoreditch do
+  comments({
+    repo: "you/your-repo", repo_id: "R_...",
+    category: "Comments",  category_id: "DIC_...",
+  })
+end
+```
+The four values come from giscus.app once Discussions is enabled on the
+repository. A single post opts out with `comments: false` in its front matter.
+For any other provider, override `components/shoreditch/comments.erb` in your
+own site — your files take precedence over the gem's, so there is no need to
+fork the theme or copy the post layout. The thread follows the reader's theme
+toggle, not just their OS setting.
+## Site metadata
+In `src/_data/site_metadata.yml`:
+```yaml
+title: Your Site
+tagline: Shown under the title in the sidebar
+description: Used for meta description and the feed
+logo: /images/you.png
+logo_link: /about/
+author:
+  name: Your Name
+  # All optional, and all used only by the contact panel — see below.
+  github: yourhandle
+  mastodon: https://example.social/@you   # a full URL, unlike the others
+  linkedin: yourhandle
+  twitter: yourhandle
+  instagram: yourhandle
+  reddit: yourhandle
+  youtube: https://youtube.com/@you       # a full URL
+  tiktok: yourhandle
+  lastfm: yourhandle
+  deviantart: yourhandle
+  artstation: yourhandle
+  phone: "+44 20 7946 0000"
+  file_url: /files/cv.pdf
+  file_link_text: Download as PDF
+  # Split in two on purpose. The halves are only joined in the browser, so the
+  # address never appears whole in the HTML for a crawler to lift.
+  email_1: hello@examp
+  email_2: le.com
+```
+## The contact panel
+A page opts in with `include_details: true`. It lists whichever of the author
+fields above are filled in, with an inline icon each — brand marks are vendored
+from [Simple Icons](https://simpleicons.org) (CC0), so the theme still loads
+nothing from a third party.
+It is off by default because a blog post has no use for a phone number; a CV or
+an about page does.
+## Layouts
+| Layout | Use |
+| --- | --- |
+| `shoreditch/default` | Wraps everything. Index pages use it directly. |
+| `shoreditch/post` | Posts. Adds dates, tags, related posts and image credits. |
+| `shoreditch/page` | Standalone pages. |
+## Front matter
+| Key | Effect |
+| --- | --- |
+| `cover` | Full-width image above the content |
+| `thumbnail` | Image in index listings |
+| `last_updated` | Shown in the post header |
+| `last_verified` | Shown in the post header — for saying how stale a technical post may be |
+| `credits` | List of `label` / `name` / `via` / `via_link` for image attribution |
+| `nav_order` | Puts a page in the sidebar nav, in this order |
+| `exclude` | Keeps a page out of the sidebar nav |
+| `noindex` | Emits `robots: noindex, nofollow` |
+| `class` | Extra CSS class on `<body>` — `class: cv` opts into the CV styling |
+| `comments` | `false` turns comments off for one post |
+These reshape the sidebar for a single page — useful when one page should
+introduce a person rather than the site:
+| Key | Effect |
+| --- | --- |
+| `include_sticky` | `false` drops the site title, tagline and navigation |
+| `include_details` | `true` shows the contact panel |
+| `include_logo` | `false` hides the logo entirely |
+| `logo_location` | A different logo image for this page |
+| `logo_shape` | `round` or `square`, overriding the site setting |
+| `logo_legend` | Overrides the badge; `false` hides it |
+| `logo_legend_shape` | `round` or `straight` — the badge, shaped independently |
+| `flashy_logo` | `true` gives the logo a pulsing accent glow |
+## Customising
+Every colour and dimension is a custom property on `:root`, and your site's own
+stylesheet loads after the theme's. To restyle, override what you need:
+```css
+:root {
+  --sd-accent: rebeccapurple;
+  --sd-measure: 52rem;
+  --sd-sidebar-width: 20rem;
+}
+```
+Syntax highlighting is one of those properties. The theme sets the code
+background, so it also sets the token colours — otherwise a light-only Rouge
+palette renders keywords black on near-black as soon as dark mode flips the
+background. Override `--sd-code-keyword`, `--sd-code-string`,
+`--sd-code-comment`, `--sd-code-number`, `--sd-code-fn`, `--sd-code-tag` and
+`--sd-code-punct` to use your own.
+Rules come in two weights. `--sd-rule` is the hairline used for separators and
+table borders; `--sd-rule-strong` is the heavier one used where a border encloses
+something that has to read as a single object, as an index entry does. Override
+them together if you are changing the palette.
+Do not style `body`, `main` or bare `a` from your site's stylesheet — those
+belong to the theme, and because your CSS loads last you will win by accident.
+Override custom properties instead.
+Light and dark both come from `prefers-color-scheme`, with a toggle in the
+sidebar that stores the reader's choice and wins over the OS setting. The
+choice is applied by an inline script before first paint, so there is no flash
+of the wrong scheme.
+Below 60rem the two columns stack, and the sidebar becomes a compact header
+band: the logo shrinks and sits inline with the site title, the navigation runs
+along under it, and the theme toggle and copyright move to the foot of the page
+so a reader arriving on a post meets the masthead rather than the small print.
+There is no menu to open — everything stays on screen, and no JavaScript is
+involved.
+The markdown classes the Jekyll version defined — `.message`, `.callout`,
+`.alert`, `.alarm` — still work, so posts carrying them keep rendering.
+## Development
+The `demo/` directory is a Bridgetown site that uses the theme from the parent
+directory. It is what gets published to
+[shoreditch.mehcoleman.com](https://shoreditch.mehcoleman.com), and it is the
+quickest way to see a change:
+```
+cd demo
+bundle install
+bin/bridgetown start
+```
+Ruby 3.3+ and **Node 22 or newer** — Bridgetown's esbuild configuration calls
+`fs.globSync`, which does not exist before Node 22. On an older Node the
+frontend build fails while the site itself still serves, so stylesheet changes
+silently never reach the browser. `demo/.nvmrc` pins it.
+## Licence
+MIT. See [LICENSE.md](LICENSE.md) — the original copyright is Mark Otto's and
+stays.

data/bridgetown.automation.rb ADDED Viewed

@@ -0,0 +1,277 @@
+# Installs Shoreditch into an existing Bridgetown site.
+#
+#   bin/bridgetown apply https://github.com/MEHColeman/shoreditch
+#
+# The theme's stylesheet and script ship as static files through the gem's
+# source manifest, so there is nothing to add to esbuild entry points and no
+# NPM package to install.
+#
+# This can run against a site with real content, so every destructive step is
+# gated on the file being *exactly* the untouched `bridgetown new` scaffold
+# (whitespace aside). Anything a site has edited is left alone with a note.
+# The gate is deliberately strict: a newer Bridgetown scaffold this does not
+# recognise is treated as "not ours to touch", so the automation degrades to
+# advice rather than deleting someone's work.
+add_gem "shoreditch"
+# Both answers are written into the generated initializer as Ruby string
+# literals (`accent "…"`). Reject any answer that could break out of the
+# literal or smuggle interpolation (`#{…}`, `#@…`, `#$…`) rather than trying
+# to escape it: Bridgetown's initializer insertion rewrites backslashes, so an
+# escaped answer can be un-escaped on its way into the file — but an answer
+# carrying none of these characters needs no escaping and cannot be reactived.
+# A colour and a short badge never need them; anything that does is set by hand.
+unsafe = ->(text) { text.match?(/["\\\r\n]|#[{@$]/) }
+accent = ask("Accent colour (hex, blank for the default slate blue)?").to_s.strip
+if unsafe.call(accent)
+  say "Ignoring the accent — it contained characters not allowed in a colour. " \
+      "Set `accent` by hand in config/initializers.rb.", :yellow
+  accent = ""
+end
+legend = ask("Badge text under the logo (blank for none)?").to_s.strip
+if unsafe.call(legend)
+  say "Ignoring the badge text — it contained characters that aren't allowed. " \
+      "Set `logo_legend` by hand in config/initializers.rb.", :yellow
+  legend = ""
+end
+add_initializer :shoreditch do
+  settings = []
+  settings << %(accent "#{accent}") unless accent.empty?
+  settings << %(logo_legend "#{legend}") unless legend.empty?
+  if settings.empty?
+    ""
+  else
+    <<~RUBY
+      do
+        #{settings.join("\n  ")}
+      end
+    RUBY
+  end
+end
+# Collapse whitespace so indentation and line-ending differences do not read
+# as edits; any real change to the content does.
+normalise = ->(text) { text.gsub(/\s+/, " ").strip }
+pristine_default = <<~'ERB'
+  <!doctype html>
+  <html lang="<%= site.locale %>">
+    <head>
+      <%= render "head", metadata: site.metadata, title: data.title %>
+    </head>
+    <body class="<%= data.layout %> <%= data.page_class %>">
+      <%= render Shared::Navbar.new(metadata: site.metadata, resource: resource) %>
+      <main>
+        <%= yield %>
+      </main>
+      <%= render "footer", metadata: site.metadata %>
+    </body>
+  </html>
+ERB
+# `bridgetown new` generates page.erb and post.erb identically.
+pristine_page_post = <<~'ERB'
+  ---
+  layout: default
+  ---
+  <h1><%= data.title %></h1>
+  <%= yield %>
+ERB
+pristine_css = <<~'CSS'
+  :root {
+    --body-background: #f2f2f2;
+    --body-color: #444;
+    --heading-color: black;
+    --action-color: #d64045;
+  }
+  body {
+    background: var(--body-background);
+    color: var(--body-color);
+    font-family: BlinkMacSystemFont, -apple-system, "Segoe UI", "Roboto", "Oxygen",
+      "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
+      "Helvetica", "Arial", sans-serif;
+    margin: 0 8px;
+    font-size: 108%;
+    line-height: 1.5;
+  }
+  a {
+    color: var(--action-color);
+    text-decoration: underline;
+    text-decoration-color: #ffb088;
+  }
+  h1 {
+    margin: 1rem 0 3rem;
+    text-align: center;
+    font-weight: 900;
+    font-size: 2.5rem;
+    color: var(--heading-color);
+    line-height: 1.2;
+  }
+  body > header {
+    margin: 1rem;
+    text-align: center;
+  }
+  body > header img {
+    display: inline-block;
+    width: 400px;
+    max-width: 100%;
+  }
+  body > nav ul {
+    margin: 2rem 0;
+    padding: 0;
+    list-style-type: none;
+    display: flex;
+    justify-content: center;
+    gap: 1.5rem;
+    font-size: 1.3rem;
+    font-weight: bold;
+  }
+  body > nav a {
+    text-decoration: none;
+  }
+  main {
+    margin: 2rem auto 4rem;
+    max-width: 65rem;
+    min-height: calc(100vh - 200px);
+    padding: 25px 25px 50px;
+    background: white;
+    box-shadow: 2px 3px 3px #ddd;
+    border-radius: 3px;
+    @media (max-width: 500px) {
+      padding: 16px 16px 50px;
+    }
+  }
+  footer {
+    text-align: center;
+    margin-bottom: 4rem;
+    font-size: 1em;
+  }
+  hr {
+    border: none;
+    border-top: 2px dotted #bbb;
+    margin: 3rem 0;
+  }
+CSS
+# The starter stylesheet styles body and main directly, and a site's own CSS
+# loads after the theme's — so left in place it pulls the theme apart (it once
+# cost the demo its entire appearance). Replace it only when it is exactly the
+# untouched starter.
+starter_css = "frontend/styles/index.css"
+if File.exist?(starter_css)
+  if normalise.call(File.read(starter_css)) == normalise.call(pristine_css)
+    say "Clearing the starter stylesheet — its body/main rules override the theme…", :green
+    create_file starter_css, <<~CSS, force: true
+      /* Your site's styles load after the theme's, so anything here overrides
+         Shoreditch. Prefer overriding the theme's custom properties (see the
+         README) to styling body, main, or bare a directly. */
+    CSS
+  else
+    say "Left frontend/styles/index.css alone — it differs from the starter. " \
+        "Your CSS loads after the theme's, so remove any rules on body, main " \
+        "or bare a that fight it.", :yellow
+  end
+end
+say "Pointing your layouts at the theme…", :green
+# The scaffold's own layouts beat the theme's for every page whose front
+# matter names them — including the scaffold's welcome post — so a fresh site
+# would not render as the theme anywhere. Retire each starter layout only when
+# it is exactly the untouched scaffold; an edited layout is the site's own and
+# stays, with a note.
+layouts = {
+  "default" => [pristine_default,   "shoreditch/default"],
+  "page"    => [pristine_page_post, "shoreditch/page"],
+  "post"    => [pristine_page_post, "shoreditch/post"],
+}
+retired = {}
+layouts.each do |name, (pristine, replacement)|
+  file = "src/_layouts/#{name}.erb"
+  next unless File.exist?(file)
+  if normalise.call(File.read(file)) == normalise.call(pristine)
+    remove_file file
+    retired[name] = replacement
+  else
+    say "Left src/_layouts/#{name}.erb alone — it differs from the starter. " \
+        "Point pages that use it at #{replacement} yourself.", :yellow
+  end
+end
+# Repoint the pages that named a retired layout — but only inside the leading
+# `---`…`---` front matter, so a `layout:` line in a post's body or a fenced
+# code block is never touched, and tolerant of quoted values (layout: "post").
+unless retired.empty?
+  Dir.glob("src/**/*.{md,markdown,erb,serb,liquid,html}").each do |page|
+    next unless File.file?(page)
+    text = File.read(page)
+    # A non-UTF-8 source would raise on the match below, aborting mid-way with
+    # layouts already removed; skip it so the pass is all-or-nothing.
+    next unless text.valid_encoding?
+    next unless text =~ /\A(---[ \t]*\r?\n)(.*?\r?\n)(---[ \t]*\r?\n)(.*)\z/m
+    open_fence, front, close_fence, body = $1, $2, $3, $4
+    changed = false
+    retired.each do |name, replacement|
+      # The `\r?` before the anchor keeps CRLF front matter matching, and the
+      # captured trailing group is re-emitted so the line ending is preserved.
+      front = front.sub(/^(layout:[ \t]*)["']?#{Regexp.escape(name)}["']?([ \t]*\r?)$/) do
+        changed = true
+        "#{$1}#{replacement}#{$2}"
+      end
+    end
+    File.write(page, open_fence + front + close_fence + body) if changed
+  end
+end
+# Posts and pages need to reference the theme's layouts. A site that already
+# has its own layouts keeps them; these defaults only apply where there is
+# nothing already.
+create_file "src/_posts/_defaults.yml", force: false do
+  <<~YAML
+    layout: shoreditch/post
+  YAML
+end
+say <<~TEXT, :green
+  Shoreditch installed.
+  Next steps:
+    1. Set `layout: shoreditch/page` on your standalone pages.
+    2. Add these to src/_data/site_metadata.yml:
+         logo: /images/your-logo.png
+         logo_link: /about/
+         tagline: Your tagline
+    3. Give pages a `nav_order:` to put them in the sidebar. Pages with
+       `exclude: true` never appear there.
+  The full option list is in the theme README.
+TEXT