22.0 RC1

[til]
- full fledged implementation of TILs, using old writeups base
- two initial entries: pdf-count, eleventy-package
- supporting js scripts and sass styles

[styles]
- split files for global styles
- use highlight.js for code syntax highlighting
- other minor style changes

[templates]
- phase out `css` and `js` magic tags
- allow HTML content in titles and subtitles
- other base template changes
- new til template

[.eleventy.js]
- use `pkg` data value to import `package.json` values (and dependant changes)

Author: miermontoto

.eleventy.js

@@ -6,8 +6,10 @@ const Nunjucks = require("nunjucks");
 const buildBreadcrumbs = require('./src/static/js/building/breadcrumbs.js');
 const buildTreemap = require('./src/static/js/building/treemap.js');
 const buildChangelog = require('./src/static/js/building/changelog.js');
+const { buildTagWall, getRecents, getRelated, buildTimestamps } = require('./src/static/js/building/tilling.js');
 const addAsset = require('./src/static/js/building/linking.js');
 const { qka, quizButtons, quizQuestions } = require('./src/static/js/building/quizzing.js');
+const { buildVersionTag, buildKeywords } = require("./src/static/js/building/package.js");
 
 module.exports = function (eleventyConfig) {
     eleventyConfig.addPlugin(EleventyRenderPlugin);
@@ -20,31 +22,24 @@ module.exports = function (eleventyConfig) {
     eleventyConfig.setQuietMode(true);
     eleventyConfig.setServerOptions({ watch: ["src/static/css/**"], port: 8088 });
 
+    eleventyConfig.addShortcode("breadcrumbs", function (navPages) { return buildBreadcrumbs(navPages, this.page) });
+    eleventyConfig.addShortcode("treemap", function (navPages) { return buildTreemap(navPages) });
+    eleventyConfig.addShortcode("changelog", (data, pkg) => buildChangelog(data, pkg));
+
+    eleventyConfig.addShortcode("tilTags", (data) => buildTagWall(data));
+    eleventyConfig.addShortcode("tilRecents", (data) => getRecents(data));
+    eleventyConfig.addShortcode("tilRelated", (data, current) => getRelated(data, current));
+    eleventyConfig.addShortcode("tilTimestamps", (element) => buildTimestamps(element) );
 
-    eleventyConfig.addShortcode("breadcrumbs", function(navPages) { return buildBreadcrumbs(navPages, this.page) });
-    eleventyConfig.addShortcode("treemap", function(navPages) { return buildTreemap(navPages) });
-    eleventyConfig.addShortcode("changelog", (data) => buildChangelog(data));
     eleventyConfig.addShortcode("qka", (data) => qka(data));
     eleventyConfig.addShortcode("quizButtons", (json) => quizButtons(json));
     eleventyConfig.addShortcode("quizQuestions", (json) => quizQuestions(json));
+
     eleventyConfig.addShortcode("addScript", (filename) => addAsset("script", filename));
     eleventyConfig.addShortcode("addStyle", (filename) => addAsset("style", filename));
 
-    eleventyConfig.addShortcode("keywords", () => {
-        let json = require('./package.json');
-        if (!json.keywords) {
-            console.log('keywords not found in package.json');
-            return '';
-        }
-        return `<meta name="keywords" content="${json.keywords.join(', ')}">`;
-    });
-
-    eleventyConfig.addShortcode("version", () => {
-        let json = require('./package.json');
-        let version = json.version;
-        let channel = json.channel && json.channel !== 'RTW' ? ` (${json.channel})` : '';
-        return `<a id="version-tag" href="/changelog/">${version}${channel}</a>`;
-    });
+    eleventyConfig.addShortcode("keywords", (pkg) => buildKeywords(pkg));
+    eleventyConfig.addShortcode("version", (pkg) => buildVersionTag(pkg));
 
 
     eleventyConfig.setLibrary("njk", new Nunjucks.Environment(

.gitattributes

@@ -4,3 +4,4 @@ assets/** linguist-generated
 src/content/data/changelog.json linguist-generated
 pnpm-lock.yaml linguist-generated
 *.svg linguist-generated
+*.umd.js linguist-generated

package.json

@@ -7,5 +7,5 @@ eleventyNavigation:
 ---
 
 {% addStyle "changelog" %}
-{% changelog changelog %}
+{% changelog changelog, pkg %}
 {% include 'src/templates/snippets/top.njk' %}

src/content/changelog.njk

@@ -0,0 +1,24 @@
+---
+title: til
+emoji: ❔
+desc: collection of general questions I've asked myself over time
+subtitle: inspired by <a href="https://til.simonwillison.net/" target="_blank">Simon Willison's TIL</a>
+icons: [eleventy, markdown]
+permalink: /til/
+eleventyNavigation:
+  key: til
+---
+
+{% addStyle 'til' %}
+
+<div id="til-tags">
+	<h2>tags</h2>
+	{% tilTags collections.til %}
+</div>
+
+<hr>
+
+<div id="til-recents">
+	<h2>recent TILs</h2>
+	{% tilRecents collections.til %}
+</div>

src/content/collections/projects/til.njk

@@ -0,0 +1,56 @@
+---
+title: "accessing <code>package.json</code> in Eleventy shortcodes"
+tags: ["eleventy"]
+eleventyNavigation:
+  key: "eleventy-package"
+keywords: ["eleventy", "package.json", "shortcodes", "package", "json"]
+---
+
+For a long time now, I've been using a custom shortcode in Eleventy through the
+configuration file (`.eleventy.js`) to access the `package.json` file. This is
+useful for various reasons, such as displaying the version number of the package
+or the using the package's keywords in the metadata of the website.
+
+Because I was directly accessing the `package.json` file, I had to import it
+using `require`:
+
+```js
+let json = require('./package.json');
+```
+
+This works fine, but restricts the definition of the shortcode to the config
+file itself, which is not ideal. I wanted to separate the shortcode from the
+config file so that it's easier to manage and maintain.
+
+```js
+eleventyConfig.addShortcode("version", () => {
+    let json = require('./package.json');
+    let version = json.version;
+    let channel = json.channel && json.channel !== 'RTW' ? ` (${json.channel})` : '';
+    return `<a id="version-tag" href="/changelog/">${version}${channel}</a>`;
+});
+```
+
+While browsing the Eleventy documentation, I came across the
+*Eleventy Supplied Data*. In it, I found that the content of the `package.json`
+file is available through the `pkg` data value in the template files. This
+means that I can access the `package.json` file directly in the template files
+without having to import it in the configuration file:
+
+```
+{% raw %}{% pkg.version %}{% endraw %}
+```
+
+This is a much cleaner way to access the version number of the package, and as
+such I can migrate the function for the shortcode to a separate script file:
+
+```js
+const { buildVersionTag, buildKeywords } = require("./src/static/js/building/package.js");
+
+module.exports = function(eleventyConfig) {
+  // ...
+  eleventyConfig.addShortcode("version", (pkg) => buildVersionTag(pkg));
+  eleventyConfig.addShortcode("keywords", (pkg) => buildKeywords(pkg));
+  // ...
+};
+```

src/content/collections/projects/writeups.njk

@@ -0,0 +1,46 @@
+---
+title: "puppeteer: getting the number of pages in a PDF"
+tags: ["puppeteer", "pdf"]
+eleventyNavigation:
+  key: "pdf-count"
+keywords: ["puppeteer", "pdf", "page count", "number of pages", "chromium", "wkhtmltopdf"]
+---
+
+In Okticket, we are building a serverless service that generates PDF from HTML.
+This feature was previously implemented using `wkhtmltopdf`,
+but we are migrating to Puppeteer for better performance and stability, as
+the previous engine is severely outdated and clogs up the API when under heavy
+load.
+
+the first step of this transition is using Puppeteer to render the PDF from the
+HTML content generated by the API using Blade templates. In this process, some
+specific features are required, such as the ability to get the number of pages
+in the generated PDF.
+
+[After a quick search](https://github.com/puppeteer/puppeteer/issues/9550),
+the seemingly most straightforward way to get the number of pages in a PDF
+generated by Puppeteer is to use a pdf library to read the file and count the
+pages. However, this approach is far from ideal, as we would need to render the
+PDF twice: once to get the number of pages and once to generate the final PDF
+with the page count.
+
+```typescript
+const pdfBuffer = await page.pdf({ ... });
+
+const pdfDoc = await PDFDocument.load(pdfBuffer);
+const pageCount = pdfDoc.getPages().length;
+this.logger.debug(`PDF has ${pageCount} pages`);
+```
+
+However, [Puppeteer has built-in style classes](https://github.com/puppeteer/puppeteer/issues/5345)
+that inject certain information in the PDF, including the page count:
+
+- <b><code>pageNumber</code></b>: current page number.
+- <b><code>totalPages</code></b>: total number of pages in the PDF.
+- <code>date</code>: current date.
+- <code>title</code>: title of the document.
+- <code>url</code>: URL of the document.
+
+Replacing the built-in classes of `wkhtmltopdf` with Puppeteer's classes in the
+blade templates allows us to get the page count directly from the PDF without
+the need to render it twice, cutting the processing time in half!

src/content/collections/til/eleventy-package.md

@@ -0,0 +1,6 @@
+{
+    "eleventyNavigation": {"parent": "til"},
+    "layout": "til.njk",
+    "permalink": "/til/{{ page.fileSlug }}/",
+    "tags": ["til"]
+}

src/content/collections/til/pdf-count.md

@@ -7,16 +7,16 @@ eleventyNavigation:
 ---
 
 <div>
-	<div id="uuid-options">
-		<span class="label">version</span>
-		<select id="uuid-version">
-			<option value="v1">v1</option>
-			<option value="v4" selected>v4</option>
-			<option value="v7">v7</option>
-			<option value="guid">guid</option>
-		</select>
-	</div>
-	<span class=button id="uuid-generate">generate</span>
-	<span class=button id="uuid-copy">copy</span>
-	<span class="output" id="uuid-output"></span>
+  <div id="uuid-options">
+    <span class="label">version</span>
+    <select id="uuid-version">
+      <option value="v1">v1</option>
+      <option value="v4" selected>v4</option>
+      <option value="v7">v7</option>
+      <option value="guid">guid</option>
+    </select>
+  </div>
+  <span class=button id="uuid-generate">generate</span>
+  <span class=button id="uuid-copy">copy</span>
+  <span class="output" id="uuid-output"></span>
 </div>