Help with organizing resources for a blog

[azangru]

Hi. Could you please help me set up a blog with Eleventy?

The Goal

1. As a personal preference, I would like to arrange articles in directories by year
2. I would also like to co-locate each article's assets (images, extra styles or scripts) with the article itself. So my source directory will look similar to this:

src/
├─ blog/
│  ├─ 2022/
│  │  ├─ article-one/
│  │  │  ├─ index.md
│  │  ├─ article-two/
│  │  │  ├─ index.md
│  │  │  ├─ assets/
│  │  │  │  ├─ images/
│  │  │  │  │  ├─ 1.webp
│  │  │  │  ├─ styles/
│  │  │  │  │  ├─ styles.css
│  ├─ 2023/
│  │  ├─ article-three/
│  │  │  ├─ index.md
|  ├─ blog.json

3. At the same time, I do not want the year to appear as a subpath in the pathname. I.e. I would prefer my urls to look like so:

/blog/article-one
/blog/article-two
/blog/article-three

My attempt to achieve the goal

Pathnames

I added a blog.json file defining the permalink template, similar to how it's done for 11ty website:

{
  "layout": "layouts/post.njk",
	"permalink": "/blog/{{ page.fileSlug }}/"
}

Assets

I added @11ty/eleventy-plugin-bundle to include links to css files used only in some of the articles. An article would then reference a style file like so:

{% html "styles" %}
<link href="./assets/styles.css" rel="stylesheet">
{% endhtml %}

I also added a pass-through copy rule for static assets:

eleventyConfig.addPassthroughCopy('src/**/assets/**/*.*');

Problems

As it turned out, I didn't quite think it through. The articles will get written to the build directory as follows:

├─ blog/
|  ├─ article-one/
|  ├─ article-two/
|  ├─ article-three/
|  ├─ 2022/   <--- this directory now contains the assets copied from the source

The passthrough copy, of course, respects the original directory structure of source files; and since I modified the output path in the blog.json template, the output path for the articles is now different from the output path of associated assets.

Questions

• Does my approach make sense overall? Is there an easy way to fix it?
• Is there a better and idiomatic way of co-locating articles with their resources (not just images, but also styles and scripts)?

UPDATE

After rummaging some more, I found this unresolved issue, which describes at least a part of my problem. So, there doesn't seem to be a decent solution, eh? 😞

[pdehaan]

Re: passthrough copy globbing, there might be an answer in https://www.11ty.dev/docs/copy/#advanced-options
Seems to wrap https://github.com/timkendrick/recursive-copy#usage options.

I haven't tried hacking that level in a long time, but options.filter sounds promising if we can figure out the API. https://github.com/timkendrick/recursive-copy#advanced-options seems to imply it might just be:

	rename: function(filePath) {
		return filePath + '.orig';
	},

So you might be able to parse the filePath and use RegExp or parse the path to remove the four digit date directory. 🤷

[azangru]

Thank you! It looks much hackier than what I was hoping for; but at the same time it's great to know that this is one possible solution to get this working.

[pdehaan]

We can get worse if you want!

Instead of blog.json, you could use a JavaScript directory data file which mirrors the logic in eleventy.config.js:

module.exports = {
  permalink(data) {
    return data.page.filePathStem.replace(/^(\/?blog\/)[0-9]{4}\//, "$1") + "/";
  },
};

versus

      rename(filename) {
        return filename.replace(/^(\/?blog\/)[0-9]{4}\//, "$1");
      },

There might be a way to extract that into a shared function which takes a file path string and returns the new path, so it can be shared between the passthrough copy and the permalink generation.
The RegExp might be uglier than needed, but I was trying to protect against the edge case of maybe you having a file named 1984.md and that possibly also getting replaced.

[pdehaan]

Also, now that we know the correct flags/config for recursive-copy, there might be a way to backport that to the Eleventy passthrough copy config.

[pdehaan]

Look on my Solutions, ye Mighty, and despair!

I ended up going with a custom filter solution since it seems like the filter is available in the this. scope when inside a directory data file. Seemed slightly more convenient than creating a ./helpers.js file that is imported in multiple files. 🤷

eleventy.config.js

/**
 * @param {import("@11ty/eleventy/src/UserConfig")} eleventyConfig
 * @returns {ReturnType<import("@11ty/eleventy/src/defaultConfig")>}
 */
module.exports = function (eleventyConfig) {
  eleventyConfig.addFilter("blogPermalink", function (filename = "") {
    return filename.replace(/^(\/?blog\/)[0-9]{4}\//, "$1");
  });

  eleventyConfig.addPassthroughCopy("src", {
    // debug: true,
    filter: ["**/assets/**"],
    rename(filename) {
      const fn = eleventyConfig.getFilter("blogPermalink");
      return fn(filename);
    },
  });

  return {
    dir: {
      input: "src",
      output: "www",
    }
  };
};

src/blog/blog.11tydata.js

module.exports = {
  permalink(data) {
    return `${this.blogPermalink(data.page.filePathStem)}/`;
  },
};

OUTPUT

> eleventy

[11ty] Writing www/blog/post2/index.html from ./src/blog/2022/post2.md (liquid)
[11ty] Writing www/blog/post1/index.html from ./src/blog/2023/post1.md (liquid)
[11ty] Writing www/aboot/index.html from ./src/blog/2022/post3.md (liquid)
[11ty] Copied 4 files / Wrote 3 files in 0.05 seconds (v2.0.1)

With extra template passthrough debugging:

DEBUG=Eleventy:TemplatePassthrough* npm run build

> [email protected] prebuild
> rm -rf www


> [email protected] build
> eleventy

  Eleventy:TemplatePassthroughManager Resetting counts to 0 +0ms
  Eleventy:TemplatePassthroughManager TemplatePassthrough copy started. +9ms
  Eleventy:TemplatePassthroughManager `addPassthroughCopy` config API paths: { src: { outputPath: true, copyOptions: { filter: [Array], rename: [Function: rename] } } } +0ms
  Eleventy:TemplatePassthroughManager `addPassthroughCopy` config API normalized paths: [ { inputPath: './src', outputPath: true, copyOptions: { filter: [Array], rename: [Function: rename] } } ] +1ms
  Eleventy:TemplatePassthroughManager TemplatePassthrough copying from config: { inputPath: './src', outputPath: true, copyOptions: { filter: [ '**/assets/**' ], rename: [Function: rename] } } +0ms
  Eleventy:TemplatePassthrough Copying './src' +0ms
  Eleventy:TemplatePassthrough Copying individual file 'src/blog/2023/post1/assets/img-1.webp' +38ms
  Eleventy:TemplatePassthrough Copying individual file 'src/blog/2023/post1/assets/img-2.webp' +1ms
  Eleventy:TemplatePassthrough Copying individual file 'src/blog/2023/post1/assets/img-3.webp' +0ms
  Eleventy:TemplatePassthrough Copying individual file 'src/blog/2023/post1/assets/styles.css' +0ms
  Eleventy:TemplatePassthroughManager Copied './src' (4 files) +41ms
  Eleventy:TemplatePassthroughManager TemplatePassthrough copy finished. Current count: 4 +0ms
[11ty] Copied 4 files / Wrote 3 files in 0.05 seconds (v2.0.1)

Probably quite gross and overbuilt, but a fun exercise. Not sure it needs the complexity as I can't imagine you'll change the permalink pattern often enough to warrant everything. And maybe it will fail pretty quickly in real world scenario that has marginally more complexity than my 3 template playground. :yolo:

[azangru]

@pdehaan This is me, back several months later, to report that the solution in your last comment seems to work great! Well, at least in absence of a native solution from Eleventy, it is the next best thing.

There were two minor hurdles I encountered during the implementation.

One is that data.page.filePathStem ends in index; so the blogPermalink filter above for the index.md file below:

src/
├─ blog/
│  ├─ 2022/
│  │  ├─ article-one/
│  │  │  ├─ index.md

will return /blog/article-one/index/ with an index.html file inside that superfluous index directory. So I had to make the filter function slightly uglier:

  eleventyConfig.addFilter('blogPermalink', function (filePath = '') {
    const withoutFileName = filePath.split('/').slice(0, -1).join('/');
    const yearRegex = /([0-9]{4})\//;

    return withoutFileName.replace(yearRegex, "$1-"); // to get /blog/2023-article-one/
  });

This also meant that the rename function in the addPassthroughCopy first needs to separate the file name from the rest of the path, then modify the directory path to get the desired target path, and then recombine it with the file name:

  eleventyConfig.addPassthroughCopy('src/blog', {
    filter: ['**/*.!(md|njk|html|json)'],
    rename: (filePath) => {
      const fn = eleventyConfig.getFilter('blogPermalink');
      const fileName = filePath.split('/').pop();
      if (!fileName) {
        return filePath;
      }
      const targetDir = fn(filePath);
      return `${targetDir}/${fileName}`;
    }
  });

Which is also yucky. But it works; and the fact that it is reusing the same filter function as the permalink generator, is brilliant!

The other annoyance is that Eleventy dev server doesn't seem to correctly emulate the passthrough behavior as the docs suggest it should be able to. So, the eleventyConfig.setServerPassthroughCopyBehavior("passthrough") instruction does not work; but the default server behavior, when the files are actually copied to the destination even in development, works. Annoying; it would have been much more elegant if the asset files could be read from the source directory directly, without actually being copied to the build destination; but I can live with that. I think I'll open an issue in the dev server repo.

In any case, incredibly, this seems to be working fine and doing what I wanted Eleventy to do. Thank you for your suggestions!