Eleventy Baseline
English Nederlands Français
|
Table of Contents
Page 6 of 6

Eleventy Base Blog

Rehome the per-page CSS

A loose end left behind by the deletions on the config page, and one that builds cleanly while being wrong.

The bundles carried message-box.css and prism-diff.css, neither of which is @imported by index.css, plus a raw <style> include of the Prism theme in post.njk that now emits unbundled into every post body. Group them into a file under src/assets/css/ and inline it with Baseline's filter, which does what the bundles did:

In home.njk, for the message box:

{%- set messageBoxPath = _baseline.paths.assets ~ "/css/message-box.css" %}
{{ messageBoxPath | inlinePostCSS | safe }}

In post.njk, for syntax highlighting:

{%- set prismPath = _baseline.paths.assets ~ "/css/prism.css" %}
{{ prismPath | inlinePostCSS | safe }}

prism.css is a new file, src/assets/css/prism.css, grouping the theme with the diff styles the starter already had:

/* Syntax highlighting, inlined on blog posts only via `inlinePostCSS`. */
@import "prismjs/themes/prism-okaidia.css";
@import "./prism-diff.css";

postcss-import resolves the bare node_modules specifier, so the theme is imported by name rather than copied in. The assets module covers the pipeline.

Tidy the content, then delete metadata.js

Input-path links. The starter demonstrates InputPathToUrlTransformPlugin by linking between posts with .md paths, and without it those ship as literal href="/blog/firstpost.md". Rather than restoring the plugin, use wikilinks:

[[firstpost|First post]]

The overlap is partial and worth understanding: wikilinks are a markdown-it inline rule, so they cover Markdown body content only, not Nunjucks templates or front matter. Template-to-template links stay plain paths. A wikilink that misses renders as literal [[slug]] text rather than breaking the build, so mistakes are visible on the page.

Descriptions. Give every page a description. Before this, five pages in the starter share the site description, and tag-pages.njk needs a computed one so each tag page differs. Nothing warns about this: Baseline's fallback chain ends at extracting the first paragraph, which is not reliable enough to depend on. Front matter is the only dependable route.

Then delete src/_data/metadata.js and remove @zachleat/heading-anchors. Every consumer has moved, and dependencies is now one package:

"dependencies": {
	"@apleasantview/eleventy-plugin-baseline": "0.1.0-next.45"
}

That is the conversion. What is left is finding out whether it worked, and the exit code will not tell you.

What a green build will not tell you

Start the dev server and walk the site first:

npm start

Every page, a post with a code block in it, the tag pages, the feed. You are looking for the things a person would notice: styling that is missing, a layout on the wrong page, a link that goes nowhere. Drafts render in this mode and images are served from a dev endpoint, so a clean walk here does not mean the built site is clean.

Then build it for production, with the origin you actually deploy to:

BASELINE_URL=https://www.example.com/ npm run build

It will pass. The most useful thing this conversion taught is that Eleventy exits zero on a site that is quietly broken, so go and look at dist/ rather than at the exit code:

  • Images. Real .avif and .webp files under dist/, not .11ty/image/ dev endpoints.
  • The stylesheet. dist/assets/css/index.css exists, is linked, and is minified on a production build.
  • Inlined CSS. Grep the output for /* Error processing CSS */. inlinePostCSS catches its own errors and emits that comment inside a <style> element rather than failing, so a wrong path is invisible.
  • Wikilinks. No literal [[ anywhere in dist/, and no .md hrefs.
  • Drafts. The draft post absent from dist/blog/, from the feed and from the sitemap.
  • BASELINE_URL. Nothing warns when it is unset, and a production build without it ships localhost in every canonical, og:url and JSON-LD node.

Not covered here

Subpath deploys. --pathprefix and Baseline do not currently agree: HtmlBasePlugin rewrites relative links so stylesheets and nav pick up the prefix, while canonical, og:url and the JSON-LD graph are composed from settings.url and come out claiming the origin root. On a subpath deploy that is the one tag you most need correct. It is a plugin issue rather than an integration one, and deploying under a subpath is where it will be answered.

The starter's deploy files. netlify.toml, vercel.json and the GitHub Pages workflow sample all still point at _site/. They are outside this guide's job, which ends at a correct build, but they will fail after a green one, so they are worth a look before you deploy.

See also