Forem: Nicolas Hoizey

HTML and CSS based View Transitions are coming

Nicolas Hoizey — Fri, 19 May 2023 17:47:56 +0000

While same-document View Transitions have now been available for a while in Chromium browsers for Single Page Applications (SPA), they were requiring the use of a JavaScript API. Chrome Canary now allows us to develop and test View Transitions with HTML and CSS only, obviously targeting Multiple Pages Applications (aka Web sites 🤷‍♂️).

Let's experiment!

After following Jake Archibald's work for many months now, and sharing a few links about View Transitions, I wanted to try them, and decided my photography site would be a good playground.

Here's what I got with just a <meta> tag and a few CSS rules:

https://youtu.be/Z_MG97DzNPs

Thanks Dave Rupert for the very simple View Transitions tutorial!

There are a few improvements required for when we transition from a small and lightweight thumbnail to a very large and heavy photo (still no JPEG-XL…), so I tried to add a Low Quality Image Placeholder (I usually hate them… 😞) to limit the issue on slow networks. But I guess there should be a better solution if I could keep the thumbnail while the large image loads.

Ok for Chrome Canary, but elsewhere?

The documentation for the View Transitions API on MDN is already available, but focused on SPA.

Noam Rosenthal is currently leading the creation of a new explainer for "cross-document navigations" (MPA), a welcome step towards standardisation, and maybe implementation in other browsers.

There are also a lot of open issues in the CSS Working Group GitHub repository with ideas and questions.

Whatever the standardisation and cross-browser implementation status, a really nice thing about View Transitions is that they have been designed as a progressive enhancement, so you can use them right now, even if support is currently low (in terms of browser diversity).

I the mean time, I can only thank Jake Archibald A LOT for this nice improvement of the user experience! 🙏

Running CSS animations only if both the device and the user allow it

Nicolas Hoizey — Fri, 07 Apr 2023 17:49:14 +0000

Thanks to Chrome release notes, I discovered today that there is an update media feature which accepts values fast, slow and print, to set styles depending on the ability of the device to update the rendering and the speed of it.

As I'm already respecting the user's preference with the prefers-reduced-motion media feature, I wondered how I could progressively enhance this with the new media feature.

"Testing" media feature support without `@supports`

Amelia Bellamy-Royds had the answer with a clever trick. Thanks Amelia! 🙏

This is how you can apply styles only if a feature is supported by the browser:

@media (thing: one), not (thing: one) {
  …
}

Indeed:

either the browser doesn't understand thing: one and ignores both media queries
or the browser understands thing: one and this is either true or false, so combining both matches all supporting browsers/contexts

Running CSS animations only if both the device (either `update: fast` not supported or `true`) and the user allow it (`prefers-reduced-motion: no-preference`)

Combining this trick with my already existing media queries for the prefers-reduced-motion media feature requires a bit of code, but it's manageable.

Here's the code I got for the Ken Burns animations running on my photography site (with non relevant selectors cleaned up):

// Without @media update support
// Enable animations if no reduced motion preference
@media (prefers-reduced-motion: no-preference) {
  img {
    animation-play-state: running;
  }
}

// With @media update support
@media (update: fast), not (update: fast) {
  // If screen update is fast (neither slow nor print)
  @media (update: fast) {
    // Enable animations if no reduced motion preference
    @media (prefers-reduced-motion: no-preference) {
      img {
        animation-play-state: running;
      }
    }
  }

  // If screen update is NOT fast (either slow or print)
  // Disable animations
  @media not (update: fast) {
    img {
      animation-play-state: paused;
    }
  }
}

Being able to nest media queries is great!

Later update: a simpler solution thanks to Amelia

As Amelia noticed when I shared this (I ❤️ her comment “both awesome & awful” 😅), the code can be much simpler, without media queries inception. 😅

Here's what Amelia suggests to write, and I agree it's much better:

@media (prefers-reduced-motion: no-preference) {
  img {
    animation-play-state: running;
    /* turn animations on if user doesn't mind */
  }
}
@media not (update: fast) {
  img {
    animation-play-state: paused;
    /* except, turn them off again if the browser can't draw them effectively anyway */
  }
}

I feel so lucky to regularly get great feedback from people with such expertise as Amelia, on many topics. Once with Twitter, I now get this with Mastodon, and it feels even better.

Now… how can I test the different permutations of update support or not, and actual value? 🤔

How I built my own excerpt for Markdown content in Eleventy

Nicolas Hoizey — Thu, 30 Mar 2023 23:40:32 +0000

I was not really happy with Eleventy's native excerpt solution requiring just a separator and having the excerpt content preserved in the content, without any way to style it differently. So I tried different alternatives, and settled on a solution with some Markdown-it plugins and a bunch of regexes.

To be able to style the content lead whatever it contains, I'm using the great and simple markdown-it-container plugin for Markdown-it, with a lead container.

For exemple, I can write this in the begining of my Markdown file, after the YAML Front Matter:

::: lead
This paragraph is in the lead.

This other paragraph is also in the lead.
:::

This is no more part of the content lead…

With this really simple syntax, I can put whatever I want in the lead and style it in the content page.

And I can also extract it for the excerpt!

I could have used a Nunjucks filter, as I previously did, but it means the excerpt for the same content would have been computed multiple times (unless I did some memoization) for different content listings in the homepage, a category page, archives pages, Atom and JSON feeds, Algolia index, etc.

Fortunately, Eleventy provides the eleventyConfig.setFrontMatterParsingOptions() function which allows passing options to gray-matter, the npm package it relies on to parse front matter.

This is the function that allows setting a custom separator for the default excerpt feature with the excerpt_separator option, as shown in Eleventy documentation, but in addition to the simple true boolean shown here, the excerpt option can be a function, which gets the Markdown content and options as parameters.

Here's the function I built to generate my own excerpt:


const markdownItPlainText = require('markdown-it-plain-text');
const excerptMd = new markdownIt().use(markdownItPlainText);

function grayMatterExcerpt(file, options) {
  const regex = /^.*::: lead(((?!(:::)).|\n)+):::.*$/gm;
  let excerpt = '';
  let leadFound = false;

  if ((leadMatches = regex.exec(file.content)) !== null) {
    lead = leadMatches[1];
    leadFound = true;
    excerptMd.render(lead);
  } else {
    excerptMd.render(file.content);
  }
  excerpt = excerptMd.plainText
    .trim()
    .replace(/{%(((?!(%})).|\n)+)%}/gm, '') // remove short codes
    .replace(/{{(((?!(}})).|\n)+)}}/gm, '') // remove nunjucks variables
    .replace(/{#(((?!(#})).|\n)+)#}/gm, '') // remove nunjucks comments
    .replace(/<style>(((?!(<\/style>)).|\n)+)<\/style>/gm, '') // remove inline CSS
    .replace(
      /<script type="application\/ld\+json">(((?!(<\/script>)).|\n)+)<\/script>/gm,
      ''
    ) // remove JSON+LD
    .replace(/(<\/h[1-6]>)/gm, '. $1') // add a dot at the end of headings
    .replace(/<\/?([a-z][a-z0-9]*)\b[^>]*>|<!--[\s\S]*?-->/gm, '') // remove HTML tags
    .replace(/(\[\^[^\]]+\])/gm, '') // remove Markdown footnotes
    .replace(/\[([^\]]+)\]\(\)/gm, '$1') // remove Markdown links without URL (from {% link_to %} for example)
    .replace(/ +(\.|,)/gm, '$1'); // remove space before punctuation

  if (!leadFound && excerpt.length > 150) {
    // Keep only 145 characters and an ellipsis if there was no declared lead
    excerpt = excerpt.replace(/^(.{145}[^\s]*).*/gm, '$1') + '…';
  }
  file.excerpt = excerpt;
}

eleventyConfig.setFrontMatterParsingOptions({
  excerpt: grayMatterExcerpt,
});

It first looks for a ::: lead container to use directly, or takes the full content.

It then parses the result with Markdown-it and the markdown-it-plain-text plugin, and then removes some parts that are really not useful in an excerpt: Nunjucks short codes/variables/comments, inline CSS rules, JSON/LD metadata, remaining HTML tags, footnotes, etc.

Finally, if the full content was used (no ::: lead found), it limits the result length.

A bookmarklet to create a new link content Markdown on GitHub

Nicolas Hoizey — Wed, 08 Feb 2023 09:42:51 +0000

When I was building my site on my local computer, I had a shell script to initialize a new Markdown file for sharing a link. When I moved to Cloudflare Pages 6 months ago, it opened a new opportunity to share links more easily in my Eleventy content, directly from the page I wanted to share. Bookmarklets are still an awesome invention!

The main features of my bookmarklet are:

get the page title, ask for any change in a window.prompt()
get some content
- the selection made on current page,
- or the page's meta description,
- or the first paragraph of the first main element,
- or the first paragraph of the first article element,
- or the first paragraph of the page
compute the slug based on the title
compute the file path for my links content type (/links/YYYY/MM/DD/slug/index.md)
create the Markdown file content, with YAML Front Matter
open a new file editor on GitHub, so I can add some content and metadata

I can then commit the file, push it directly to my main branch or open a pull request.

And then the build runs on Cloudflare Pages, and the new link is online. It is also available in the feeds, to it soon becomes a toot on Mastodon, thanks to my GitHub Action!

The JavaScript source code is here on GitHub:

// ==Bookmarklet==
// @name +🔗
// @description New link for nicolas-hoizey.com
// @version 1.0
// ==/Bookmarklet==

// Adapted from https://gist.github.com/codeguy/6684588#gistcomment-3361909
const slugify = (str) => {
  let slug = str.toString();
  console.log(`1: ${slug}`);
  slug = slug.replaceAll('/', ' ');
  console.log(`2: ${slug}`);
  slug = slug.normalize('NFD');
  console.log(`3: ${slug}`);
  slug = slug.replace(/[\u0300-\u036f]/g, '');
  console.log(`4: ${slug}`);
  slug = slug.toLowerCase();
  console.log(`5: ${slug}`);
  slug = slug.replace(/\s+/g, ' ');
  console.log(`6: ${slug}`);
  slug = slug.replace(/[^\w]+/g, ' ');
  console.log(`7: ${slug}`);
  slug = slug.trim();
  console.log(`8: ${slug}`);
  slug = slug.replace(/ +/g, '-');
  console.log(`9: ${slug}`);

  return slug;
};

/* **********************************************************************************
/* Get data from the page
/* ********************************************************************************* /
let pageTitle = window.document.title;
let linkSelection =
  'getSelection' in window ? window.getSelection().toString().trim() : '';
let linkContent =
  linkSelection ||
  window.document
    .querySelector('head meta[name=description i]')
    ?.content.trim() ||
  window.document.querySelector('main p')?.textContent.trim() ||
  window.document.querySelector('article p')?.textContent.trim() ||
  window.document.querySelector('p')?.textContent.trim();
let linkUrl = window.location.href;

/* **********************************************************************************
/* Ask the user to confirm/modify the title
/* ********************************************************************************* /
let title = window.prompt('Title of the link?', pageTitle);

if (title !== null) {
  let slug = window.prompt('Slug of the link?', slugify(title));

  if (slug !== null) {
    /* **********************************************************************************
    /* Build the content
    /* ********************************************************************************* /
    const today = new Date();
    const dateString = today
      .toISOString()
      .replace('T', ' ')
      .replace(/\.[0-9]{3}Z/, ' +00:00');

    let value = `---
date: ${dateString}
title: "${title}"
lang: en
link: ${linkUrl}
authors:
  - ""
tags: []
---
\n
${linkContent ? `> ${linkContent.replaceAll('\n', '\n> ')}` : ''}
`;

    /* **********************************************************************************
    /* Build the URL
    /* ********************************************************************************* /
    const pathDate = dateString.slice(0, 10).replaceAll('-', '/');
    const filename = `src/links/${pathDate}/${slug}/index.md`;

    let newFileUrl = `https://github.com/nhoizey/nicolas-hoizey.com/new/main/?filename=${filename}&value=${encodeURIComponent(
      value
    )}`;

    window.open(newFileUrl);
  }
}

The metadata in the comment on top of this script is used by bookmarklet, the npm package I use to transform my source JS into a proper bookmarklet, with a page from which I can drag the link to my bookmarks bar:

bookmarklet --demo assets/js/bookmarklets/new-link.js src/tools/bookmarklets/new-link.html

Good old bookmarklets are still great in 2023! 🥰

Updating webmentions on a static site

Nicolas Hoizey — Sun, 05 Feb 2023 19:27:38 +0000

When I started using Webmention on this site (more than 5 years ago!), I was building the site on my local computer, and uploading the build result on my hosting with rsync. I've moved to Cloudflare Pages 6 months ago, which means webmentions where updated only when I pushed new content to GitHub. Here's how I fixed that.

I chose to fetch new webmentions directly on GitHub with an Action, so that new webmentions are immediately added to the repository, and future calls to the webmention.io API only ask for new mentions.

Most of my Webmention implementation is based on two great inspiration sources:

Here's the workflow of my GitHub Action:

name: Check Webmentions
on:
  schedule:
    # Runs at every 15th minute from 0 through 59
    # https://crontab.guru/#0/15_*_*_*_*
    - cron: '0/15 * * * *'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  webmentions:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout the project
        uses: actions/checkout@v2

      - name: Select Node.js version
        uses: actions/setup-node@v1
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Run webmention script
        env:
          WEBMENTION_IO_TOKEN: ${{ secrets.WEBMENTION_IO_TOKEN }}
        run: npm run webmention >> $GITHUB_STEP_SUMMARY

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v3
        with:
          token: ${{ secrets.PAT }}
          branch: webmentions
          delete-branch: true
          commit-message: Update Webmentions
          title: Update Webmentions
          labels: automerge 🤞

It uses the WEBMENTION_IO_TOKEN and PAT (Personal Access Token) secrets I've defined in my GitHub secrets for Actions.

And here's the Node.js script that it runs:

const fetch = require('node-fetch');
const unionBy = require('lodash/unionBy');
const sanitizeHTML = require('sanitize-html');
const domain = new URL(require('../package.json').homepage).hostname;
const { writeToCache, readFromCache } = require('../src/_utils/cache');

// Load .env variables with dotenv
require('dotenv').config();

// Define Cache Location and API Endpoint
const WEBMENTION_URL = 'https://webmention.io/api';
const WEBMENTION_CACHE = '_cache/webmentions.json';
const WEBMENTION_TOKEN = process.env.WEBMENTION_IO_TOKEN;

async function fetchWebmentions(since, perPage = 10000) {
  // If we dont have a domain name or token, abort
  if (!domain || !WEBMENTION_TOKEN) {
    console.warn('>>> unable to fetch webmentions: missing domain or token');
    return false;
  }

  let url = `${WEBMENTION_URL}/mentions.jf2?domain=${domain}&token=${WEBMENTION_TOKEN}&per-page=${perPage}`;
  if (since) url += `&since=${since}`; // only fetch new mentions

  const response = await fetch(url);
  if (!response.ok) {
    return null;
  }
  const feed = await response.json();
  const webmentions = feed.children;
  let cleanedWebmentions = cleanWebmentions(webmentions);
  if (cleanedWebmentions.length === 0) {
    console.log('[Webmention] No new webmention');
    return null;
  } else {
    console.log(`[Webmention] ${cleanedWebmentions.length} new webmentions`);
    return cleanedWebmentions;
  }
}

function cleanWebmentions(webmentions) {
  // https://mxb.dev/blog/using-webmentions-on-static-sites/#h-parsing-and-filtering
  const sanitize = (entry) => {
    // Sanitize HTML content
    const { content } = entry;
    if (content && content['content-type'] === 'text/html') {
      let html = content.html;
      html = html
        .replace(/<a [^>]+><\/a>/gm, '')
        .trim()
        .replace(/\n/g, '<br />');
      html = sanitizeHTML(html, {
        allowedTags: [
          'b',
          'i',
          'em',
          'strong',
          'a',
          'blockquote',
          'ul',
          'ol',
          'li',
          'code',
          'pre',
          'br',
        ],
        allowedAttributes: {
          a: ['href', 'rel'],
          img: ['src', 'alt'],
        },
        allowedIframeHostnames: [],
      });
      content.html = html;
    }

    // Fix missing publication date
    if (!entry.published && entry['wm-received']) {
      entry.published = entry['wm-received'];
    }

    return entry;
  };

  return webmentions.map(sanitize);
}

// Merge fresh webmentions with cached entries, unique per id
function mergeWebmentions(a, b) {
  if (b.length === 0) {
    return a;
  }
  let union = unionBy(a, b, 'wm-id');
  union.sort((a, b) => {
    let aDate = new Date(a.published || a['wm-received']);
    let bDate = new Date(b.published || b['wm-received']);
    return aDate - bDate;
  });
  return union;
}

const updateWebmention = async function () {
  const cached = readFromCache(WEBMENTION_CACHE) || {
    lastFetched: null,
    webmentions: [],
  };

  // Only fetch new mentions in production
  const fetchedAt = new Date().toISOString();
  const newWebmentions = await fetchWebmentions(cached.lastFetched);
  if (newWebmentions) {
    const webmentions = {
      lastFetched: fetchedAt,
      webmentions: mergeWebmentions(cached.webmentions, newWebmentions),
    };

    writeToCache(webmentions, WEBMENTION_CACHE);
  }
};

updateWebmention();

Whenever the workflow updates the repository with new webmentions, it triggers a Cloudflare Pages build (could be Netlify), and the site is updated.

It means I don't have to run a full build of the site periodically "just" to check if there are new webmentions, and the check can be more frequent, as it is really light and fast.

Let's POSSE to Mastodon with a Feed and a GitHub Action

Nicolas Hoizey — Sat, 07 Jan 2023 12:49:09 +0000

After building a Node script for my own POSSE needs, I thought it would be good if other people could also use it. I knew not many people would be able to use the script as-is, so I built a GitHub Action that is much simpler to use, without losing any feature, even gaining some!

You should already know that I'm a true believer of IndieWeb and POSSE, as many contents I already published show.

You could for example replace "Medium" with many other services, including Twitter and Mastodon, in Medium is only an edge server of your POSSE CDN, your own blog is the origin.

I also gave a talk (in French) about IndieWeb and POSSE 3 years ago: Ne vous laissez plus déPOSSEder de vos contenus !.

Did you see Heydon Pickering's “Why The IndieWeb?” episode of the Webbed Briefs?

You should!

Every time I talk about IndieWeb and POSSE, a lot of people reply with “but it's not easy”… and they are right!

As Max Böck recently said:

Owning your content on the web should not require extensive technical knowledge or special skills. It should be just as easy as signing up for a cellphone plan.

So…

I've developed a GitHub Action for anyone to POSSE their content to Mastodon as easily as possible : GitHub Action: Any feed to Mastoson

It currently requires a JSON Feed for input, so you might still have to build this one, if you "only" have a RSS or Atom feed. I hope to support these also in the future as they're often available out of the box in content management tools/platforms (even on Mastodon), but there are multiple variants so it's not easy to deal with.

I know there are already other ways to push content from RSS/Atom feeds to Mastodon, but I didn't want to rely on a third party service like IFTTT or Zapier. Ok, GitHub is also a 3rd party, but my code and content are already there anyway^[1]. 🤷‍♂️

I won't paraphrase the Action's documentation, so go read it, use it, and tell me if it's useful:

GitHub Action: Any feed to Mastoson

If you have some ideas, bugs or anything to discuss about this action, GitHub issues are the right place.

Also, I know my code is not state of the art, so feel free to open issues, or even better pull requests, if you think you help improve it.

HTH.

and 99% of the Action is a Node script, so I can move anywhere else if necessary. ↩︎

Accessible anchor links with Markdown-it and Eleventy

Nicolas Hoizey — Thu, 25 Feb 2021 21:08:34 +0000

I like to be able to link directly to a section in a long content. I wish every site provided anchor links associated to headings, even if Text Fragments might be a cross browser thing sometimes in the future. Here's how I made the anchor links of my Eleventy based site accessible.

I've been using the markdown-it-anchors plugin in my Eleventy configuration for a while, but even if I applied some settings different from the defaults (which heading levels to consider, how to generate a slug, which visual symbol to use, etc.), I never tried to change the rendering function, as I thought the default one was enough.

Were my Anchor Links Accessible?

But a few weeks ago, I read this great detailed post where Amber Wilson explains how she figured out how to make such anchor links really accessible: Are your Anchor Links Accessible?

My anchor links were not accessible at all… 😱

Enhancing `markdown-it-anchor`'s rendering

Amber also uses Eleventy and shared a new plugin to automate such accessible anchor links, but I wanted to keep the features I'm already using in markdown-it-anchor and enhance it with better accessibility.

Fortunately, markdown-it-anchor provides a large set of options, including a way to provide our own rendering function with the renderPermalink option. After a while diving into markdown-it and markdown-it-anchor documentation and code, I've been able to create a rendering function that generates accessible anchor links, which you should be able to use in any Eleventy project! 🎉

The code is primarily based on markdown-it-anchor's default renderPermalink function.

Here is my version:

renderPermalink: (slug, opts, state, idx) => {
  // based on fifth version in
  // https://amberwilson.co.uk/blog/are-your-anchor-links-accessible/
  const linkContent = state.tokens[idx + 1].children[0].content;

  // Create the openning <div> for the wrapper
  const headingWrapperTokenOpen = Object.assign(
    new state.Token('div_open', 'div', 1),
    {
      attrs: [['class', 'heading-wrapper']],
    }
  );
  // Create the closing </div> for the wrapper
  const headingWrapperTokenClose = Object.assign(
    new state.Token('div_close', 'div', -1),
    {
      attrs: [['class', 'heading-wrapper']],
    }
  );

  // Create the tokens for the full accessible anchor link
  // <a class="deeplink" href="#your-own-platform-is-the-nearest-you-can-get-help-to-setup">
  // <span aria-hidden="true">
  // ${opts.permalinkSymbol}
  // </span>
  // <span class="visually-hidden">
  // Section titled Your "own" platform is the nearest you can(get help to) setup
  // </span>
  // </a >
  const anchorTokens = [
    Object.assign(new state.Token('link_open', 'a', 1), {
      attrs: [
        ...(opts.permalinkClass ? [['class', opts.permalinkClass]] : []),
        ['href', opts.permalinkHref(slug, state)],
        ...Object.entries(opts.permalinkAttrs(slug, state)),
      ],
    }),
    Object.assign(new state.Token('span_open', 'span', 1), {
      attrs: [['aria-hidden', 'true']],
    }),
    Object.assign(new state.Token('html_block', '', 0), {
      content: opts.permalinkSymbol,
    }),
    Object.assign(new state.Token('span_close', 'span', -1), {}),
    Object.assign(new state.Token('span_open', 'span', 1), {
      attrs: [['class', 'visually-hidden']],
    }),
    Object.assign(new state.Token('html_block', '', 0), {
      content: `Section titled ${linkContent}`,
    }),
    Object.assign(new state.Token('span_close', 'span', -1), {}),
    new state.Token('link_close', 'a', -1),
  ];

  // idx is the index of the heading's first token
  // insert the wrapper opening before the heading
  state.tokens.splice(idx, 0, headingWrapperTokenOpen);
  // insert the anchor link tokens after the wrapper opening and the 3 tokens of the heading
  state.tokens.splice(idx + 3 + 1, 0, ...anchorTokens);
  // insert the wrapper closing after all these
  state.tokens.splice(
    idx + 3 + 1 + anchorTokens.length,
    0,
    headingWrapperTokenClose
  );
},

I hope there are enough comments in the code to understand how it works. The main markdown-it behavior I had to understand is that it uses an array of tokens to represent HTML nodes, instead of a more traditional Abstract Syntax Tree.

Adapting the CSS to the new HTML structure

If you're already using markdown-it-anchor, the anchor link is inside the heading:

<h3 id="were-my-anchor-links-accessible">
  Were my Anchor Links Accessible?
  <a class="deeplink" href="#were-my-anchor-links-accessible">#</a>
</h3>

With my new code, following Amber advice, it is now:

<div class="heading-wrapper">
  <h2 id="were-my-anchor-links-accessible">Were my Anchor Links Accessible?</h2>
  <a class="deeplink" href="#were-my-anchor-links-accessible">
    <span aria-hidden="true">#</span>
    <span class="visually-hidden">Section titled Were my Anchor Links Accessible?</span>
  </a>
</div>

My actual code is a little more complex as I use a SVG for the anchor symbol, but the HTML structure is the same, so you can take some inspiration from my CSS code, which is heavily inspired from Stephanie Eckles' Smol Article Anchors:

// Anchor links
// Based on https://smolcss.dev/#smol-article-anchors
.heading-wrapper {
  display: grid;
  // anchor link on the far right for long wrapping headings
  grid-template-columns: minmax(auto, max-content) min-content;
  align-items: stretch;
  gap: 0.5rem;
}

.deeplink {
  display: grid;
  justify-content: center;
  align-content: center;

  &:link,
  &:visited {
    padding: 0 0.25rem;
    border-radius: 0.3em;
    color: var(--color-meta);
    text-decoration: none;

    svg {
      fill: none;
      stroke: currentColor;
      stroke-width: 2px;
      stroke-linecap: round;
      stroke-linejoin: round;
    }
  }

  .heading-wrapper:hover &,
  &:hover,
  &:focus {
    color: var(--color-link-hover);
    background-color: var(--color-link-hover-bg);
  }
}

@media (min-width: 65rem) {
  .heading-wrapper {
    // Anchor link in the left margin on larger viewports
    grid-template-columns: min-content auto;
    margin-left: -2rem; // 1rem width + .25rem * 2 paddings + 0.5rem gap
  }

  .deeplink {
    grid-row-start: 1;
  }
}

On viewports < 65rem, the anchor link is inside the content container, at the right of the heading. If a long heading wraps on multiple lines, the anchor link is located on the far right, but if the heading is short, the anchor link follows it directly. I'm not sure setting grid-template-columns: minmax(auto, max-content) min-content; is the best way to do it, feel free to suggest an enhancement.

On viewports >= 65rem, there is space around the content, so I move the anchor link in the margin on the left.

Enhancing `markdown-it-anchor` for everyone

I asked Valérian Galliat, maintainer of markdown-it-anchor, if he would be open to merge a pull request providing this enhancement: https://github.com/valeriangalliat/markdown-it-anchor/issues/82

But I think this would break (at least visually) all current uses of the plugin, so I believe it would require a new option to activate it. We'll discuss this before I provide the PR.

Enhancing archives navigation, step 2

Nicolas Hoizey — Sun, 01 Nov 2020 22:55:51 +0000

In my previous article Enhancing archives navigation, step 1, I promised further archives navigation enhancements. Here they are!

Remember how UX of navigation in archives by year and month where already enhanced with a single Eleventy layout:

This new awesome layout made my build time go from 40 seconds to 300 seconds, a 650 % increase, not so awesome… 😅

Now, imagine you want to see content from two — or more — types (articles and notes for example), or mix not only one type and a date, but also the language, or tags, even multiple of them.

Generating all possible filter combination as static pages with one single Eleventy build would probably take more than one hour. I obviously don't want that, even if this would provide users with an even better UX.

Time to enhance the already nice server-side rendering with awesome client-side features!

Here's what is now available for navigating the archives, if you activated JavaScript in your browser:

There is a search input field, to search for any content, with live "as you type" results, and live updated filtering facets. 🤯

If you search for something specific, the results highlight why they're here in the list:

All of this would not be possible without Algolia, the awesome search service I've been using for multiple years.

I inject all my contents in an Algolia index, and a single JavaScript script uses Algolia's InstantSearch.js UI library to build the user interface and synchronize the search term and facets values to the URL (and back).

What I really like here is that this is not the only way to browse the archives, it is "only" a (great) enhancement of what's available to anyone with the server-side rendering.

I hope you'll enjoy this new feature!

Enhancing archives navigation, step 1

Nicolas Hoizey — Mon, 26 Oct 2020 14:16:23 +0000

I decided years ago to remove paged navigation (aka "pagination"), because I find it not user friendly at all, and a nightmare for SEO with new content pushing one tenth of contents to another page (for a 10 items per page pagination). Now, I improved the UX even further.

Here's how the month by month navigation was presented earlier, in the page bottom:

While it was OK for the year by year navigation, such a full months list was really not user friendly, so I intended to enhance it a little.

Instead of "just" a little, I finaly chose to present this navigation with facets in a search engine, with the possibility to combine a filter for the content type, and another for the year or month of publication:

For example, you can navigate to the links I published in March 2019: /links/2019/03/.

I find it so easy to navigate, I wonder why I didn't have this idea earlier!

I already had the required Eleventy collections, so almost everything was done in a single shared Nunjucks template. Not the easiest one, I recon.

Now, I wonder if it's useful to keep the main navigation items for "articles", "links", etc., or if the "archives" navigation item is enough, which would obviously help on mobile.

As you might have guessed from this article's title, I'm working on further archives navigation enhancements, we'll see that soon online, and I'll explain in a dedicated article. Stay tuned!

How I build my SVG sprites

Nicolas Hoizey — Wed, 14 Oct 2020 22:02:19 +0000

I'm using an SVG sprite on this site to make sure I don't repeat SVG code for icons that are used multiple times, and I inline it so the rendering doesn't depend on another resource loading. Here's how I build this sprite from individual SVG icons.

I'm using the very nice and open source Feather icons. Feather provides multiples ways to use the icons, including a sprite, but it contains all icons and weights almost 60 KB (minified, not compressed), so it's really not a good option for me as I need only 9 of them. Feather also provides a way to load icons with JavaScript, obviously not the best choice either for performance in a statically generated site.

It's nice anyway that there's feather-icons on npm, as adding it to my dev dependencies is enough to make sure I'll will always have the latest versions.

Here's own these icons are used on this site:

In pages listing multiple contents such as the home page, these icons are used multiple times, so it's best having each only once in the HTML, hence the use of a sprite. For the whole site, I use only 9 different icons, so the sprite is light, at only 3 KB (minified, not compressed).

To build this sprite, I use svgstore in the following Node.js script, where comments should be enough to understand how it works:

const svgstore = require('svgstore');
const fs = require('fs');
const path = require('path');

// Where are Feather icons available from the npm package?
const ICONS_FOLDER = 'node_modules/feather-icons/dist/icons/';

// Which icons do I need for the sprite?
// icon filename + title for accessibility
const ICONS_LIST = {
  calendar: 'Date',
  info: 'Info',
  link: 'Link',
  wifi: 'Online',
  'wifi-off': 'Offline',
  search: 'Search',
  tag: 'Tag',
  twitter: 'Twitter',
  'message-circle': 'Webmention',
};

// Initiate the sprite with svgstore
let sprite = svgstore({
  // Add these attributes to the sprite SVG
  svgAttrs: { style: 'display: none;', 'aria-hidden': 'true' },
  // Copy these attributes from the icon source SVG to the symbol in the sprite
  copyAttrs: ['width', 'height'],
});

// Loop through each icon in the list
Object.entries(ICONS_LIST).forEach(([icon, title]) => {
  // Log the name of the icon and its title to the console
  console.log(`${icon}.svg -> ${title}`);
  const svgFile = fs
    // Load the content of the icon SVG file
    .readFileSync(path.join(ICONS_FOLDER, `${icon}.svg`), 'utf8')
    // Make its dimensions relative to the surounding text
    .replace(' width="24" height="24"', ' width="1em" height="1em"')
    // Remove useless attributes (for my usage) and add a title for accessibility
    .replace(
      / fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-[^"]+">/,
      ` ><title id="${icon}-icon">${title}</title>`
    );
  // Add the new symbol to the sprite
  sprite.add(`symbol-${icon}`, svgFile, {
    // Add attributes for accessibility
    symbolAttrs: {
      'aria-labelledby': `${icon}-icon`,
      role: 'img',
    },
  });
});
// Finally, store the sprite in a file Eleventy will be able to include
fs.writeFileSync(
  'src/_includes/svg-sprite.svg',
  sprite.toString({ inline: true })
);

This script is located in the src/_utils/ folder of my Eleventy project, with other scripts I run with npm, like my Webmention update script.

This script was previously part of my site build, but it made no sense, as the list of icons doesn't change much, and each icons are not often updated in the source. I just have to run npm run svg when I feel it useful, and my build is a little faster.

JAMstack is fast only if you make it so

Nicolas Hoizey — Wed, 07 Oct 2020 11:02:15 +0000

JAMstack often promotes itself as an excellent way to provide performant sites. It's even the first listed benefit on jamstack.wtf, a "guide [which] gathers the concept of JAMstack in a straight-forward guide to encourage other developers to adopt the workflow". But too many JAMstack sites are very slow.

Vous pouvez aussi lire la version française, merci Arnaud pour la traduction.

You may have seen Alex Russell's frequent rants about Gatsby:

Alex Russell

@slightlylate

@matthewcp @justinfagnani @gatsbyjs @kylemathews @addyosmani Looking across the full set of traces, modern Gatsby seems to produce pages that take 2-3x as long as they should to become interactive.

This is not OK. Gatsby/NPM/React regressively tax access to content.

In less generous moments, I'd go as far as to say it's unethical.

22:30 PM - 17 Oct 2019

3 17

Gatsby is an easy target (among many others) because it is currently not optimized for performance out of the box, despite what's promoted. It is possible to fix it, for example with this plugin, and I believe good React developers can make it shine, but it should be the default, not an afterthought.

Eleventy is very different, as Zach Leatherman reminds us in Eleventy’s New Performance Leaderboard:

Eleventy doesn’t do any special optimizations out of the box to make your sites fast. It doesn’t protect you from making a slow site. But importantly it also doesn’t add anything extra either.

The issue with most slow JAMstack sites is that they load a loooot of JavaScript. Remember that any added JavaScript has to be sent to the browser, which also needs more computation for it. It quickly impacts performance.

Sometimes, using the server-side build is enough to get data from an API and serve HTML to all visitors, which is much better for performance.

For example, swyx wrote Clientside Webmentions about implementing Webmention with Svelte. Any article promoting Webmention and easing its adoption is welcome! But even if it's nice for a demo of Webmention and Svelte, I wouldn't recommend doing it client-side.

Server-side first

I prefer doing it on the server.

It allows to:

call webmentio.io API only when building the site, which should be less often than visitors viewing pages.
cache the result of requests to webmention.io and the timestamp of the latest, so that the next one only asks for new webmentions.

It puts less pressure on webmention.io, with one single request per build, when a client implementation makes a much larger request (or even several, with pagination) for each page view.

For example:

my website received 75 webmentions in April 2020. I have probably built it a hundred times during the same period, so let's say 100 requests to webmention.io with small responses.
in the same period, my website had 3,746 page views (underestimated, I still use Google Analytics 🤷‍♂️), which would have made 3,746 requests to webmention.io with large responses.

Using the server-side build to get the webmentions provides multiple benefits:

The performance for the users is much better, with HTML already computed on the server and statically served.
Much fewer API calls, requiring much less computing time and power.
Everyone should know that Aaron Parecki provides the awesome webmention.io service for free, and most Webmention users seem to use it nowadays, so being nice with its API feels better.

Enhance client-side, if really needed

If you know you receive a lot of very useful webmentions that you have to show to your visitors, you can enhance the server-side generated list with a bit of client-side.

But remember every JavaScript added to the page has a cost, so the few additional webmentions have to be really useful.

So, instead of doing this for every page view, at least:

First, try to wait for some time after the site build before making client-side API calls. Keep the build timestamp available to client-side JavaScript, and wait for an hour, a day, or more, depending on the frequency of webmentions. You could even use the page's "age" to query webmention.io less for older content that probably receives less webmentions, as Aaron Gustafson did even for server-side call in his Jekyll plugin.

Then, keep track of a user's calls to the API, in localStorage or IndexedDB, so that you don't make these calls again a short while after. You could even use a Service Worker to cache requests and their timestamp.

Client-side only API calls sometimes make more sense

I agree Webmentions are not the most complex use case to explain that most of the time you should call APIs from the server at build time rather than from the client:

Webmentions to show are the same for all visitors.
Missing a few of the latest ones is probably not an issue.

So yes, many other use cases make client-side API calls necessary, or better than server-side ones, I understand that.

I say it should not be the default.

Promoting the AJMstack Mstack

That's also something I don't really like in current JAMstack trend, promoting JavaScript and APIs much more than Markup.

Here's for example what you can see on jamstack.wtf (simplified):

As suggested by Yann, I would like to start by using this better presentation¹:

It makes more obvious there is a pile of things, quite useful for a "stack".

But I would like to suggest this modification:

Of course, it reads as AJMstack instead of JAMstack, so I bet I won't be successful promoting it… 🤷‍♂️

But at least it feels more accurate, it shows JavaScript is the link between APIs and Markup.

It even allows to present this as a great progressive enhancement platform, as we can start with plain old (did I hear "boring"?) Markup…

Here's the Mstack:

Make sure this "stack" is great, and then enhance with JavaScript and APIs.

CSS Grid and Flexbox are so fun to use, it took me just a few minutes to get this for the original post! 💪 ↩

Identify which Apache rewrite rules are used

Nicolas Hoizey — Fri, 29 May 2020 10:13:01 +0000

I have many rewrite rules in my Apache configuration for redirections, some dating from more than 15 years ago. So I wanted to know which ones are really useful, because there's maybe some cleaning to do. I'll explain here how I got the list.

Get some logs

First, I had to tell Apache's mod_rewrite module^[1] to log more information than it usually does, but not too much either.

Here's what I added to my Apache configuration^[2] with the LogLevel directive:

LogLevel warn rewrite:trace2

warn is Apache's default log level, and trace2 is much more verbose, so I add it only for the rewrite module.

Filter the logs for useful informations

The logs I get with this are really verbose, and contain messages from Apache and all the active modules.

Here is just a small extract for one single request to articles/2018/06/users-do-change-font-size/.

This is an old URL format where I didn't put the day as I do now, so there's a redirection:

[Thu May 28 23:28:29.299495 2020] [rewrite:trace2] [pid 1241533:tid 140624745461504] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7104af0a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] rewrite 'articles/2018/06/users-do-change-font-size/' -> 'https://nicolas-hoizey.com/articles/2018/06/15/users-do-change-font-size/'
[Thu May 28 23:28:29.299518 2020] [rewrite:trace2] [pid 1241533:tid 140624745461504] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7104af0a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] explicitly forcing redirect with https://nicolas-hoizey.com/articles/2018/06/15/users-do-change-font-size/
[Thu May 28 23:28:29.299528 2020] [rewrite:trace2] [pid 1241533:tid 140624745461504] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7104af0a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] trying to replace prefix /home/nhoizey/www/nicolas-hoizey.com/www/ with /
[Thu May 28 23:28:29.299531 2020] [rewrite:trace1] [pid 1241533:tid 140624745461504] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7104af0a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] escaping https://nicolas-hoizey.com/articles/2018/06/15/users-do-change-font-size/ for redirect
[Thu May 28 23:28:29.299534 2020] [rewrite:trace1] [pid 1241533:tid 140624745461504] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7104af0a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] redirect to https://nicolas-hoizey.com/articles/2018/06/15/users-do-change-font-size/ [REDIRECT/301]
[Thu May 28 23:28:29.327806 2020] [rewrite:trace1] [pid 1241533:tid 140624871286528] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe7100390a0/initial] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] pass through /home/nhoizey/www/nicolas-hoizey.com/www/articles/2018/06/15/users-do-change-font-size/
[Thu May 28 23:28:29.327852 2020] [rewrite:trace1] [pid 1241533:tid 140624871286528] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe6e47970a0/subreq] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] pass through /home/nhoizey/www/nicolas-hoizey.com/www/articles/2018/06/15/users-do-change-font-size/index.php
[Thu May 28 23:28:29.327872 2020] [rewrite:trace1] [pid 1241533:tid 140624871286528] mod_rewrite.c(483): [client 92.169.204.166:0] 92.169.204.166 - - [nicolas-hoizey.com/sid#7fe7132989d8][rid#7fe6e479d0a0/subreq] [perdir /home/nhoizey/www/nicolas-hoizey.com/www/] pass through /home/nhoizey/www/nicolas-hoizey.com/www/articles/2018/06/15/users-do-change-font-size/index.html

The log file contains many lines like this, for all requests, on multiple domains sharing the same host. I had more than 4000 log lines per day , even before adding the detailed logs for the rewrite module, so it's impossible to navigate in these to get the information.

Only the first of the eight lines above is useful to identify the redirection.

So I chose to use simple shell tools^[3] to filter the raw data and get only the useful lines.

cat apache.log | grep 'nicolas-hoizey.com' | grep "] rewrite '"

cat prints the content of the log file on the standard output, and then grep filters lines containing three strings:

nicolas-hoizey.com to get only logs for my domain^[4]
] rewrite ' to make sure I get the rewrite instruction, not the others (explicitly forcing redirect, trying to replace prefix, escaping, etc.)

So with that, I get all lines for redirections, great first step.

But the useful data is "hidden" at the end of the line, after many things that can probably be useful sometimes, but not for my current use case.

Extract the useful value from the remaining logs

Here is the full line broken into pieces (I won't explain it, just split the parts):

[Thu May 28 23:28:29.299495 2020]
[rewrite:trace2]
[pid 1241533:tid 140624745461504]
mod_rewrite.c(483):
[client 92.169.204.166:0]
92.169.204.166
- -
[nicolas-hoizey.com/sid#7fe7132989d8]
[rid#7fe7104af0a0/initial]
[perdir /home/nhoizey/www/nicolas-hoizey.com/www/]
rewrite 'articles/2018/06/users-do-change-font-size/' -> 'https://nicolas-hoizey.com/articles/2018/06/15/users-do-change-font-size/'

The only useful part is the last one. I can remove everything before.

I chose to use sed^[5] to replace everything from the beginning of the line to the ] rewrite string:

cat apache.log | grep 'nicolas-hoizey.com' | grep "] rewrite '" | sed 's/^.*\] rewrite //'

I then chose to get the list as a CSV file, so I also replaced the arrow in the middle (->) with a semi-colon, and I removed the domain from the second part to ease reading it:

cat apache.log | grep 'nicolas-hoizey.com' | grep "] rewrite '" | sed 's/^.*\] rewrite //' | sed 's/ -> /;/' | sed 's/https:\/\/nicolas-hoizey.com\///'

Here's what I now get:

'articles/2018/06/users-do-change-font-size/';'articles/2018/06/15/users-do-change-font-size/'

But with logs for multiple days, I get some identical redirections many times, so I chose to sort them, keep only one of each, and count their number:

cat apache.log | grep 'nicolas-hoizey.com' | grep "] rewrite '" | sed 's/^.*\] rewrite //' | sed 's/ -> /;/' | sed 's/https:\/\/nicolas-hoizey.com\///' | sort | uniq -c | sort -nr

Finally, I chose to put all this in a file for later use:

cat apache.log | grep 'nicolas-hoizey.com' | grep "] rewrite '" | sed 's/^.*\] rewrite //' | sed 's/ -> /;/' | sed 's/https:\/\/nicolas-hoizey.com\///' | sort | uniq -c | sort -nr > ~/rewrites.csv

I can now run this script, open the .csv file in a spreadsheet, and see which of my redirections are still useful.

After less than one single day with the log directive, I already have 181 different redirections performed. I will wait for a few days (24 hours later, I have 839 different redirections ), and I'll have to understand which ones are legitimate, and which others I can safely remove.

For some of these redirections, the log also contains the referer, so I might be able to fix the URL at the source, like I just did in the IndieWeb wiki.

I use mod_rewrite for redirections because I need advanced URL manipulations mod_alias doesn't allow. ↩︎
Unfortunately, this can not be set in an .htaccess file in your DOCUMENT_ROOT, so you have to be able to change your Apache configuration, like my hosting AlwaysData allows. ↩︎
I'm sure there are better tools, more powerful, but these ones allowed me to get the result I wanted. ↩︎
you might have a log file dedicated to one single domain, which would be easier to parse. ↩︎
I know awk is more powerful, but I always forget the syntax, so sed is fine. KISS. ↩︎