![\"\"](\"/images/2026/03/sourceSize.svg\")
This post is the fourth and last in a series comparing the same sample blog in Web Origami and Eleventy:
\nAs a very crude metric, the conciseness of legible code can roughly correlate with simplicity, so in this final post, let’s measure how large the projects are. That analysis is followed with an Appendix of other notes from this experiment.
\nI totaled the size of all source files in each project: configuration code, data, scripts, and templates. I did not count markdown content as source code, and in any event, both projects use the same markdown.
\nIn a code size comparison, Eleventy has latent advantages: its folder structure implicitly encodes behavior that Origami must spell out in code, and its use of configurable plugins should in theory require less code.
\nCounting source code in bytes (with wc -c) for Eleventy:
2836 base.njk\n 74 blog.11tydata.js\n 157 blog.njk\n 49 content.11tydata.js\n 4610 eleventy.config.js\n 475 eleventyDataSchema.js\n 1380 filters.js\n 54 home.njk\n 864 index.njk\n 294 metadata.js\n 1199 post.njk\n 528 postslist.njk\n 519 sitemap.xml.njk\n 608 tag-pages.njk\n 235 tags.njk\n 13882 total\nAnd for Origami:
\n 1613 base.ori.html\n 144 blogIndex.ori.html\n 603 feed.ori\n 310 images.ori\n 403 index.ori.html\n 243 metadata.yaml\n 851 post.ori.html\n 501 postList.ori.html\n 1463 posts.ori\n 502 readableDate.js\n 1328 site.ori\n 201 tag.ori.html\n 251 tagIndex.ori.html\n 159 tags.ori\n 8572 total\nThe Origami version, which is doing much of the work from scratch, is smaller!
\n
It seems Origami’s smaller size can be attributed in part to:
\nsite.ori (which defines the top-level structure of the site) is 30% the size of eleventy.config.js (which configures the main behavior of Eleventy’s static site generator).In the domain of site creation, code is more concise than configuration.
\nStatic site generators presume that sites are so complex that it’s better to generate a site with an engine whose behavior you configure. But sites just aren’t that complex! If you know how to write HTML and CSS, you can put together a site using zero magic. The code to do so is smaller than the configuration code required to influence a static site generator.
\nSpeaking of metrics, performance should probably be no more than a secondary concern for you when evaluating blogging tools. Most static site generators are quite fast, especially for personal sites.
\nThat said, I timed builds of both approaches via time npm run build on a 2024 MacBook Air M3. I threw the first (longest) time away, then averaged the real time of the next three builds.
Both Origami and Eleventy build this tiny blog project in less than a second:
\n![\"\"](\"/images/2026/03/buildTime.svg\")
While performance shouldn’t be your primary concern, in the case of this sample blog Origami comes out ahead. It’s entirely possible that Eleventy has higher startup costs as it digs through your project looking for files, so for all I know, once those startup tasks are accomplished it could process a larger blog faster. Regardless, the performance here shows that Origami’s fundamental approach is well-suited for this task.
\nSumming up this post series, I beleive this experiment shows that an explicit, code-oriented solution like Origami is easier to follow, more coherent, more expressive, and more concise than one predicated on configuration like Eleventy. I expect the same comparison holds true for the countless other static site generators that rely on a combination of configuration, naming conventions, and folder structure.
\nNot every person wants to code, or has the time or energy to learn to code. But I think configuration-based site generators cover up the complexity of code with a system that is ultimately just as hard to understand. If you’re capable of configuring a tool like Eleventy, you are just as capable of coding in Web Origami.
\nI don’t know the Eleventy team personally, but they seem like perfectly nice people who care deeply about their users and want to create good tools for them. They also have what looks (to an outsider like me) like a dynamic, supportive user community. If you pick Eleventy for your site, it’ll probably work out fine.
\nIf you’re interested in trying Origami for a blog, I think you’ll like it. You can start with the corresponding origami-blog-start template project. If you’re interested but want help or have questions, let me know.
Other posts in this series:
\nThe following are small points I noticed while studying the Eleventy blog; none are as important as the main points above.
\nI found three very minor possible issues in the sample eleventy-base-blog project. Although the issues are small and debatable, any bugs in a template project will be endlessly copied into new blogs, so their potential impact is magnified.
I want Eleventy to continue growing and their new users to have great experiences, so I reported these to Eleventy (issue, issue, issue).
\nTemplate languages like Nunjucks are common, but they become another language you need to learn. If you already know JavaScript, that’s enough to be able to do anything you want in a template in Origami.
\nAs a bonus, this means that you don’t have to do special things to invoke JavaScript from a template. When the Eleventy version wants to insert a timestamp onto a page, it registers a small JavaScript function as a shortcode:
\neleventyConfig.addShortcode("currentBuildDate", () => {\n return new Date().toISOString();\n});\nThis shortcode can then be called by name from a Nunjucks template:
\nbuilt on {% currentBuildDate %}\nIn Origami, a template is a JavaScript template literal stored in its own file, so you can skip all that registration complexity above and just inline the desired JavaScript into the template:
\nbuilt on ${ new Date().toISOString() }\nIf the code were longer, you could put it in its own JavaScript file and call that by file name. The Origami version uses that technique to implement the Eleventy readableDate function; Origami templates then call that function with
${ readableDate.js(post.date) }\nA number of the Nunjucks templates in the Eleventy blog include lines like this:
\n{% set postslist = collections.posts %}\n{% include "postslist.njk" %}\nAs I understand it, a Nunjucks include doesn’t let you pass data directly, so you have to pass data via what’s effectively a global variable. That approach is so fraught with the high potential for errors that it’s hard for me to recommend any system that requires it. (Eleventy allows the use of template engines other than Nunjucks; perhaps those are better.)
Origami templates are functions, so you can pass data to them directly:
\n${ postList.ori.html(posts) }\nBlogging tools like Eleventy use a project’s folder structure to determine the resulting site structure. That approach focuses on complete file resources, such as a page for an individual post.
\nBut blog posts in this project actually have three representations:
\nblog areablog/index.html, and tag pagesfeed/feed.xmlThe folder structure only gives you a way to conveniently express the first representation. The Origami code doesn’t have any particular focus on pages; all post representations can be defined in a variety of ways.
\nMeanwhile, using folder structure to represent site structure has limits. It took me a while to realize that the single file tag-pages.njk isn’t just a template for a tag page; an embedded block of JavaScript at the top of the file appears to also generate the collection of pages like tags/second-tag/index.html.
In contrast, the Origami site.ori file includes an explicit definition of the tags area.
The Eleventy blog inlines the main CSS stylesheet into every page instead of linking to it. Origami can easily do both, but as a matter of preference, I had the Origami version link to the main stylesheet. Among other things, that keeps each built page smaller and easier to read.
\nThe Eleventy version uses an Eleventy navigation plugin. I’m probably missing something, but in this project it looks like the plugin is used to add an aria-current attribute to three links.
Perhaps in other contexts the plugin saves time, but here it seems like overkill. I implemented this in the Origami version by adding conditions to the three links in question:
\n${ _.area === "Home" ? `aria-current="page"` : "" }\nThis does the job, and is a lot easier for me (someone familiar with JavaScript) to understand. This could be scaled up into a helper function if necessary.
\nI was baffled by this template fragment in the Eleventy version:
\nGo <a href="index.njk">home</a>.\nI just couldn’t figure out what this was doing — what would it even mean to navigate to a Nunjucks template? Looking at the running site, I could see that the link was magically being rewritten. But even closely reading the project’s source code couldn’t help me see how or why this was happening.
\nClaude Code identified this fragment as something handled by the Eleventy InputPath to URL plugin.
\nSome people love such magic; I’m not one of them.
\nThe original Eleventy project defined a sitemap.xml file so I implemented one for the Origami version. That said, a sitemap seems unnecessary for this blog; all the content is trivially discoverable by a search engine. The code to generate the sitemap ends up being both a distraction and a possible maintenance burden.
The original Eleventy blog uses a number of plugins to:
\nAll these tasks performed by the Eleventy plugins have one thing in common: the tasks have nothing to do with Eleventy. Every one of them is something you might want to do on any static site, regardless of which tool you’re using to make it.
\nIt’s in the nature of tools with proprietary interior workings to require tool-specific plugins. The lost opportunity is that, instead of sharing general-purpose code that can work with many tools, we collectively waste time rewriting the same ideas over and over for different tools.
\nExtensibility in Origami is provided by calling functions that can be written as generally as possible. There are no internal data structures that require proprietary plugins to manipulate. As the creator, your own code generates the requisite objects; you can pass those directly to third-party functions.
\nThe aforementioned Origami package for turning a data object into an RSS feed is a plain JavaScript function that has nothing to do with Origami at all. Other Origami packages are written around the use of the standard Map class as the basis for tree structures, an approach that’s at least theoretically adoptable by other tools.
\n", "date_published": "2026-03-20T08:00:00.000Z", "id": "https://jan.miksovsky.com/posts/2026/03-20-code-is-more-concise-than-configuration.html", "url": "https://jan.miksovsky.com/posts/2026/03-20-code-is-more-concise-than-configuration.html", "title": "Code is more concise than configuration: comparing a sample blog in Web Origami and Eleventy" }, { "content_html": "This post is the third in a series comparing the same sample blog in Web Origami and Eleventy:
\nThis post looks at another advantage of code over configuration: the degree to which you can easily express your ideas without limits.
\nAs one example, let’s look at the code required to give this blog a feed. The Eleventy version uses the Eleventy RSS plugin, which in this project is configured this way:
\neleventyConfig.addPlugin(feedPlugin, {\n type: "atom", // or "rss", "json"\n outputPath: "/feed/feed.xml",\n templateData: {\n eleventyNavigation: {\n key: "Feed",\n order: 4,\n },\n },\n collection: {\n name: "posts",\n limit: 10,\n },\n metadata: {\n language: "en",\n title: "Blog Title",\n subtitle: "This is a longer description about your blog.",\n base: "https://example.com/",\n author: {\n name: "Your Name",\n },\n },\n});\nIn contrast, the Origami project uses a function that generates an RSS feed from a data object created this way:
\n// The posts in JSON Feed format\n(posts) => {\n version: "https://jsonfeed.org/version/1.1"\n title: metadata.yaml/title\n description: metadata.yaml/description\n feed_url: `${ metadata.yaml/url }/feed.json`\n home_page_url: metadata.yaml/url\n \n // Map the post data to JSON Feed items\n items: Tree.values(Tree.map(posts, (post, slug) => {\n // Patch image URLs to be absolute\n content_html: post._body.replaceAll('src=".\\/', `src="${ metadata.yaml/url }/blog/${ slug }/`)\n date_published: post.date\n id: url\n title: post.title\n url: `${ metadata.yaml/url }/blog/${ slug }`\n }))\n}\nIn both projects, you build the feed with code — but in completely different ways:
\nThe expressiveness of code gives you the freedom to tackle things the way you want to — and the code required to make the change is proportional to the complexity of the change. If you want to change what the Origami feed uses as an item id, you change that part of the code.
A long-term benefit of coding things is that you learn transferrable knowledge. Your potential mastery of the Eleventy RSS plugin data schema won’t help you in a different blog tool, or even using a different Eleventy plugin. In contrast, learning an interchange format like RSS or (here) JSON Feed is knowledge you can apply elsewhere, as are the data manipulation techniques employed in the code above.
\n[As I was finishing this post series, I discovered that the Eleventy RSS plugin allows you to specify a feed template, giving you the same degree of expressiveness as Origami for a feed specifically although not as concisely. That only makes me wonder why the plugin has to exist at all — the feed template itself isn’t that much longer than the plugin configuration code. In any event, there’s no guarantee that other plugins will give you the same kind of escape hatch through code.]
\nThe expressiveness of code comes into play at every level of the Origami site. At the site’s highest level, I could readily use Origami to support the Eleventy sample blog’s preferred folder layout:
\ncontent folder, like content/firstpost.md.content/fourthpost/fourthpost.md) and associated images (content/fourthpost/possum.png).I’ve never used that particular layout for a project before, but it was straightforward to express in code.
\nI point this out because folder-based, configuration-focused tools impose very particular expectations about how you should organize your content and source files. I have no idea whether it would be possible to configure, say, Astro to work with the content layout of this Eleventy project, or for Eleventy to work with the content layout of Astro’s starter blog.
\nYou might not care about that, or you may care about that a lot. In an Origami project, there’s nothing special about the source file names or organization; structure them however makes sense to you.
\nTo be clear, both approaches require too much code! I hope someday you can make a great blog for yourself with much less coding — or none at all. So you can design whatever you want and retain complete control and avoid paying a monthly ransom on your own writings via a subscription.
\nBut we have to start somewhere. You’re either writing code to 1) configure an engine or 2) do the actual work. Think about what kind of code you want to learn, and whether it will let you create what you want without limits.
\nOther posts in this series:
\nThis post is the second in a series comparing the same sample blog in Web Origami and Eleventy:
\nToday let’s look at how both projects define the overall structure of the site and consider whether they can present a coherent picture of what you’re building.
\nLike most static site generators, Eleventy leverages the tree-like structure of a folder hierarchy to approximate the tree-like structure of a site. The good news is that the file system itself gives you the best picture you’re going to get of the resulting site. That’s also the bad news.
\nHere’s the folder structure of this Eleventy project, including the relevant source files:
\n_config/\n filters.js\n_data/\n eleventyDataSchema.js\n metadata.js\n_includes/\n layouts/\n base.njk\n home.njk\n post.njk\n postslist.njk\ncontent/\n blog/\n blog.11tydata.js\n blog.njk\n content.11tydata.js\n index.njk\n sitemap.xml.njk\n tag-pages.njk\n tags.njk\neleventy.config.js\nThe above organization alone may not mean much to the uninitiated, and sadly folders on their own can’t have comments. Nevertheless, experienced Eleventy developers can probably envision the resulting site, especially if they also scan the lengthy configuration file.
\nThere are also many little files that configure different parts of the site’s construction, like content/content.11tydata.js:
export default {\n layout: "layouts/home.njk",\n};\nMost of these configuration files have no explanatory comments, by which I only conclude that we’re not expected to look at them. But if the average user isn’t expected to look at these files, why not have comments for those users that do look at them?
\nThe above file sets a path to a Nunjucks layout, but I couldn’t see how it was used. As discussed last time, configuration-oriented tools tend toward “action at a distance” behavior that is hard to intuit. It’s also the case that there’s just not much to go on here when searching for answers.
\nI eventually learned that a file called content.11tydata.js is a directory-specific data file that implicitly associates its exported data with the containing folder. In this case, it defines a default layout property that will be applied as the base template for other templates in the content folder, like content/index.njk.
Most of the Eleventy configuration code feels like this. The site builds a blog as advertised, but it feels like substantial work to piece together the site’s construction to the point where you could change it.
\nIn contrast, the premise of a coding-focused approach like Origami is that you describe what you want in code. Given that freedom, most Origami users elect to define their site’s top-level tree of resources in a single file, providing a coherent map of the project. Here’s the whole site.ori file for the sample blog:
// This file defines the structure of the entire blog site\n{\n about: {\n // About page\n index.html: templates/base.ori.html(Origami.mdHtml(about.md))\n }\n\n // Static assets like stylesheets\n assets/\n\n // Blog area\n blog: {\n // Blog index page\n index.html = templates/blogIndex.ori.html(posts.ori)\n\n // Create a folder for each post\n ...Tree.map(posts.ori, {\n key: (post, key) => `${ key }/`\n value: (post, key, tree) => {\n // Index page for post folder\n index.html: templates/post.ori.html(post, key, tree)\n // Any associated images\n ...post.images\n }\n })\n }\n\n feed: {\n // Blog feed in RSS format\n feed.xml = Origami.rss(feed.ori(posts.ori))\n }\n\n // Home page\n index.html = templates/index.ori.html(posts.ori)\n\n // Tags area\n tags: {\n // Tag index page\n index.html: templates/tagIndex.ori.html(tags.ori)\n\n // Create a folder for each tag\n ...Tree.map(tags.ori, {\n key: (group, tag) => `${ Origami.slug(tag) }/`,\n value: (group, tag) => {\n index.html: templates/tag.ori.html(group, tag)\n }\n })\n }\n\n // Not Found page\n 404.html = templates/base.ori.html(Origami.mdHtml(404.md))\n}\n\n// Add a sitemap for all of that\n→ (site) => {\n ...site\n sitemap.xml = Origami.sitemap(site, { base: metadata.yaml/url })\n}\nEven if you don’t know Origami or JavaScript, you can probably squint and perceive the structure of the final site. All references here are explicit and by name.
\nFor example, at the top you can see that the about area contains a page called index.html. The formula for that page may be unclear to you, but it contains references to the files templates/base.ori.html and about.md, so you can look at those. Even if you don’t know what something does, you at least have a name to search for. Searching the Web Origami documentation for the remaining term in that formula finds the built-in function, Origami.mdHtml.
This single site.ori file pulls together the bulk of the logic behind the site. I think such a coherent, text-based map of the site is enormously helpful in understanding and remembering how the parts fit together. You can also ask Origami to draw a visual diagram of the running site to confirm your understanding.
Other posts in this series:
\nThis post series is for people who want to build or rebuild a site.
\nYou may have heard of Eleventy, a popular static site generator, and maybe heard it’s simple to use. To evaluate that simplicity, I’ll compare a sample blog in Eleventy to the same blog in Web Origami. This will be similar to my comparison last year of Astro and Origami.
\nIf you’re shopping for a site-building tool, I hope this series can help inform your decision. If you already use Eleventy, I’m happy you’ve found something that works for you. As I said last year, anything that makes people more likely to create a site is fantastic.
\nEleventy works like most static site generators: you run the tool, it searches inside your project for certain folders and files, then processes them to create an output directory with your site’s HTML pages and other resources. You influence this process through configuration, setting various parameters to adjust what Eleventy does. You generally set those parameters through JavaScript files, although the emphasis in those files is on defining parameterized objects or enabling plugins.
\nIn Web Origami you focus on defining the site you want with code. You do this in standard JavaScript or the smaller Origami dialect of JavaScript, which is essentially JavaScript expressions with embedded file paths. The code does whatever you tell it to do. In this case, it defines a blog site’s tree of resources, transforming the markdown posts into browsable HTML and a feed.
\nThis difference between configuration and coding is similar to the difference between working with numbers in Intuit QuickBooks and Microsoft Excel. The former is configured; the latter lets you calculate whatever you want.
\nConfiguration is generally sold as simpler than coding, and most people intuitively feel that should be the case. But I believe that, for making sites, coding is superior in four specific ways:
\nConfiguration can certainly let you achieve impressive results in complicated domains that you probably couldn’t code yourself, but sites just aren’t that complicated. It’s actually easier to code your own site from scratch than to create one by configuring a tool.
\nI copied Eleventy’s recommended starting point for new blogs, the eleventy-base-blog template project, studied that until I felt I understood its construction, then ported it to Web Origami. This gave me two versions of the same blog:
Both demos are about as close as I can easily make them. For a cleaner comparison, I made a few modifications to the original Eleventy project:
\nBeyond that I tried to port all observable behavior; some minor differences remain. For example, the Eleventy project uses PrismJS for syntax highlighting while the Origami solution uses the slightly different HighlightJS. With more work, the sites could be made even more identical, but I don’t think that would change the overall results of this experiment.
\nWith two versions of the same project in hand, let’s start evaluating them by considering which version is easier to follow. If you’re coming fresh to the project, can you answer the question: How does it work?
\nThat can be a hard question, so let’s start with a simpler one: What is calling what?
\nFor template projects like eleventy-base-blog, the README typically instructs you to build the site with a command like npm run build. That’s the main entry point to the build process. I tried to search forward from there and follow links to related files.
I got stuck.
\n![visual diagram of the running site](\"/images/2026/03/site.svg\"){kind=link}
eleventy-base-blog is npx @11ty/eleventy. That invokes Eleventy, but beyond that point it’s not obvious how Eleventy does what it does.eleventy.config.js file makes specific references to a folder called content and a file called filters.js, but there I hit a dead end.I constructed a partial map of what calls what:
\n![\"\"](\"/images/2026/03/eleventy.svg\")
The files floating in space aren’t directly referenced by any other files. Some of the file names suggest what roles those files play, but it was still mysterious to me how they actually played those roles.
\nI eventually found an Eleventy documentation page called Order of Operations providing an “advanced” description of most (but not all) of what was going on. I then had Claude Code guess/explain how the remaining files worked. This clarified that, e.g., Eleventy lets you register JavaScript functions as “filters” you can call from templates. I hadn’t been able to work out for myself that many of the .njk files were invoking code in filters.js.
I was then able to flesh out the above dependency diagram, adding what I understand to be the implicit connections as dashed lines:
\n![\"\"](\"/images/2026/03/eleventy2.svg\")
Many of the connections in this project are dashed lines representing “action at a distance” — if you don’t already know how the system works, such connections are hard to discover or intuit. This may be acceptable for something you will use all the time, but it certainly does make learning the system (or coming back to it) more difficult.
\nLet’s now try to answer the “What is calling what?” question for the Web Origami blog, again starting from the build command:
ori copy src/site.ori, clear files:build\nEven if the meaning of that command is unclear, you can still see an explicit reference to the file site.ori. If you open that file, you’ll see it contains references to all the files it calls.
You can repeat that process, following links from one file to another, to recover the entire graph of source file calls:
\n![\"\"](\"/images/2026/03/origami.svg\")
The Origami project has no hidden associations, so all the lines are solid. Everything happens because an explicit line of code makes it happen.
\nThis property of an Origami project makes it much easier to follow what the project does. When I read someone else’s Origami project, it doesn’t matter how they’ve written it. I can always start at the build command and work forward to find all the code. The project’s author also benefits from this same guarantee when they read their own project after some time away from it.
Other posts in this series:
\nI’m interested in helping to create a shared JavaScript library for letting Electron apps authenticate with Netlify (and potentially GitHub/GitLab pages) via OAuth for the purpose of creating new projects and uploading files to existing projects.
\nThe users in the web publishing ecosystem are benefiting from Electron becoming a de facto standard for user-facing tools. As Niki relates, Electron is winning because “native has nothing to offer”. Many developers are voting for Electron these days; I’m one of them.
\nOne task I want my Electron app to perform for end users is helping them select or create a site on a static site host and later deploy locally-built files to that site. Netlify is an attractive target because it supports OAuth; GitHub Pages and GitLab Pages are others.
\nAs it stands today, many tools that want to perform this task on the user’s behalf msut guide the user through creating an account with a host, obtaining a developer credential such as an access token, then copying the token and various other details into the tool. This is complex enough for a developer — and ridiculously complex for a non-developer. I think Publii’s walkthrough of this process is as clear as possible and it’s probably still daunting to many people that might want to create a site.
\nNetlify offers developers the possibility of an OAuth-based UI flow, but that’s a non-trivial thing to create from scratch:
\nEven with the help of AI, creating and maintaining this would be some work. But much of this work would be generic — so it could be implemented in a library shared by multiple tools.
\nA conceptual, back-of-the-envelope API sketch for a hypothetical NetlifyPublish library:
// Select the site or create a new one\nconst siteDetails = await NetlifyPublish.selectSite({ name: "My blog" });\n\nif (siteDetails) {\n // Successful, deploy build to site\n const files = await doTheBuild(); // However the tool wants to do that\n const success = await NetlifyPublish.deploySite(siteDetails, files);\n}\nThere are many details to hammer out — how is work split across the main Electron process and the renderer? To what extent can the server component be generalized and shared as a community service? On the renderer side, how is the UI made modal: a <dialog> or a separate BrowserWindow? How are the built files represented? How is the UI themed? etc.
If you work on a tool that would might benefit from such a shared library, or are interested in participating in its design and/or implementation, please get in touch!
\n", "date_published": "2026-03-05T08:00:00.000Z", "id": "https://jan.miksovsky.com/posts/2026/03-05-netlify-dialog-library.html", "url": "https://jan.miksovsky.com/posts/2026/03-05-netlify-dialog-library.html", "title": "Who else would use a shared Electron library to create and deploy Netlify sites?" }, { "content_html": "To increase awareness of cool features in Web Origami, I kicked off a weekly comic series with a Mastodon post:
\n\n![\"4](\"/images/2026/01/comicPost.png\")
\n\n\nEach 4-panel comic will deliver a short, standalone story. I thought a 4-panel comic would be a perfect format for Twitter-like sites that allow 4 images per post. The images should add visual interest to a user’s feed, and the user can read the comic right there. Each comic will also be available as regular HTML on the Origami site.
\nIt takes a couple of hours to rough out a little story, come up with code examples, ensure they work, and revise as necessary. I write the comic script in YAML, indicating who is talking, what they’re saying, and what should appear in the panel.
\nThe rest of the process is automated:
\nDev.changes builtin to test the site and flag any changes in code output.My top-line goals for 2025 were:
\n😐 Nurture a small, healthy, respectful user community. I’m happy that the small circle of existing Origami users seem happy with the system and continue using it. A number of new people tried Origami as well, although most of them fell into the “lurker” category; I have no idea whether they are still using it or, if not, why it didn’t meet their needs. So pragmatically speaking, I didn’t do as well on this goal as I’d hoped. One new Origami site, the documentation for the open-source WESL project, was interesting to me because it uses a GitHub wiki as the content management system.
\n😃 Make it easier for users to make sites they’re happy with through docs, bug fixes, and features. Most of the work I did this year was driven by user feedback. Some existing users moved additional projects of theirs from other systems to Origami, a good indication of user satisfaction.
\nThe big feature investments I aimed to make in 2025 were:
\n😃 Language Server Protocol implementation. I wanted to implement an LSP server so that development tools like Microsoft VS Code (and others) could provide code completion and inline error feedback. An LSP is a complex beast, and tackling this goal was a significant undertaking. The LSP is now part of the Origami VS Code extension and published in the VS Code marketplace.
\n😃 Screencast engine. I wanted a way of introducing new users to Origami through a media somewhere between a video and traditional documentation. A video is insanely time-consuming to produce and can’t be kept up to date; traditional docs are easier to maintain but less interesting to newcomers. I developed a system for creating comics and published an initial introductory comic. I’ve always loved comics and am delighted with how this turned out. I have more plans for the comics system in 2026.
\n😐 Feature complete for JavaScript expressions. I mostly accomplished what I wanted, which was feature parity with JavaScript expressions, but during the year I moved the goal posts. I ended up investing far more in this area than I’d expected; see below. There are still a few remaining unsupported JavaScript features in Origami that I’m looking forward to implementing.
\n☹️ Inspector/debugger. My plan was to create a browser-hosted tool that lets a user interactively inspect the call tree of an Origami file so they can more easily diagnose errors and better understand how their code works. I spent a month on this, but it proved to be a bigger job than I’d expected and I ultimately set it aside to pursue other priorities. I plan on trying this again in 2026.
\nThe Origami language has evolved in stages, growing closer and closer to JavaScript, but at the beginning of 2025 there were still distinct differences.
\nChief among them was that Origami required the / slash operator as a way of extracting a property from an object. Instead of writing post.title like in JavaScript, you had to write post/title. Origami used a slash to preserve the use of the . period as a valid character in file names like data.json.
Feedback from Origami users indicated that this difference in syntax presented a persistent stumbling block, and I eventually developed a file name heuristic that lets the Origami parser determine whether a . period represents part of a file name or a property access. The parser can handle expressions like data.yaml[0].name and generally do what users expect.
This change was a small but important step forward towards turning Origami into a dialect of JavaScript: “JavaScript with paths”. To that end, other important changes included:
\ntree:map became the JS-style call Tree.map().new. Old syntax: new:@js/Date("2025-12-31") is now new Date("2025-12-31"), just like JavaScript.Another significant foundational change this year was in the way Origami represents hierarchical tree-like structures. The higher levels of the Web Origami project rest on a foundational notion of a tree of nodes that may require asynchronous calls to traverse. For the past few years, these trees have been defined by a small proprietary interface, essentially a stripped-down version of the standard JavaScript Map class. Origami didn’t use the Map class itself because it was some quirks.
However, experiments suggested ways to work around those quirks, so I rewrote the foundations of Origami to use Map as a general interface.
Now most of the tree structures you work with in Origami, including those based on in-memory objects, the file system, and local data like JSON/YAML files, are represented with standard Map instances. Because Map doesn’t support async calls, Origami uses an async variation called AsyncMap to represent network resources.
These architectural changes also necessitated extensive revision of Origami’s documentation, including a completely rewritten pattern walkthrough discussing the use of Map-based trees to represent a wide variety of data sources and operations.
Along the way there were many other additions to Origami:
\nTree.filter builtin for filtering a tree based on a conditionTree.mask builtin for filtering a tree based on conditions defined in a second treeTree.globKeys builtin to support filtering based on Unix-style glob patterns like *.jpegTree.regExpKeys builtin to support filtering based on JavaScript regular expressionsOrigami.mdOutline builtin to extract the tree structure of markdown content, e.g., to generate navigation elementsDev.audit and Dev.crawl<path/to/file.txt> for unambiguous file referencesawait, in, instanceof, new, typeof, voidJavaScript has a Map class for holding key/value pairs, but it’s underused and underappreciated. If you fix the class’ limitations, you can use Map as a building block to create really interesting things.
![\"A](\"/images/2025/11/blocks.jpg\")
\nPhoto: Cun Mo, Unsplash
MapThe Map class lets you associate keys with values:
const m = new Map();\n\nm.add("a", 1);\nm.add("b", 2);\n\nm.get("a"); // 1\nm.get("b"); // 2\nm.get("c"); // undefined\n\nm.keys(); // "a", "b"\nm.values(); // 1, 2\nThe Map class has a number of advantages over plain objects for storing data, but JavaScript syntax makes it easier to create and work with objects so Map doesn’t get used as often as it should.
MapMap also has one key advantage over a plain object: Map is a class you can extend, so you can expose any key/value data store as a Map.
For example, we can write a FileMap class that makes the contents of a file system folder available as a Map. This ignores the map’s built-in storage, and instead gets the keys and values from the file system:
import * as fs from "node:fs";\nimport path from "node:path";\n\nexport default class FileMap extends Map {\n constructor(dirname) {\n super();\n this.dirname = path.resolve(process.cwd(), dirname);\n }\n\n get(key) {\n const filePath = path.resolve(this.dirname, key);\n let stats;\n try {\n stats = fs.statSync(filePath);\n } catch (error) {\n if (error.code === "ENOENT") {\n return undefined; // File not found\n }\n throw error;\n }\n\n return stats.isDirectory()\n ? new this.constructor(filePath) // Return subdirectory as a map\n : fs.readFileSync(filePath); // Return file contents\n }\n\n *keys() {\n try {\n yield* fs.readdirSync(this.dirname);\n } catch (error) {\n if (error.code === "ENOENT") {\n // Directory doesn't exist yet; treat as empty\n } else {\n throw error;\n }\n }\n }\n}\nThis is pretty amazing! You can easily work with files in code.
\nconst markdown = new FileMap("./markdown");\n\nmarkdown.keys(); // ["post1.md", "post2.md", …]\nmarkdown.get("post1.md"); // "This is **post 1**."\nMost of the time you work with files in code, you’re just reading a list of files and getting their contents, so something like this is much easier to work with than the full file system API.
\nBetter yet, you can immediately pass this kind of file system Map to any code that understands a Map. That provides a desired separation between data storage and code that works on data.
Sadly, the Map class is cumbersome to extend: its standard methods like clear(), entries(), and values() will ignore your get() and keys() methods.
markdown.entries(); // empty array ☹️\nFor comparison, the Python language provides a Mapping abstract base class that is much more helpful than JavaScript’s Map. When you inherit from Mapping, you only need to define a small set of core methods, and the base class uses your definitions to provide the remaining methods.
To compensate for this and other issues with Map, we can create our own base class that inherits from Map but provides all the expected methods:
export default class BetterMapBase extends Map {\n // Override entries() method to call overridden get() and keys()\n *entries() {\n for (const key of this.keys()) {\n const value = this.get(key);\n yield [key, value];\n }\n }\n …\n}\nIf we derive our FileMap class from this improved base class, the full set of Map methods work as expected:
markdown.entries(); // [["post1.md", <contents>], …] 🤩\nOnce your data is in Map form, you can manipulate it in interesting ways without having to worry about how the original data is defined. For example, you can transform a map of markdown to a map of HTML.
const html = new HtmlMap(markdown);\n\nhtml.keys(); // ["post1.html", "post2.html", …]\nhtml.get("post1.html"); // "<p>This is <strong>post 1</strong>.</p>\\n"\nTransforming the values of data often implies a transformation of the keys, so maps are ideal representations of such operations.
\nThis Map approach is a pattern you can explore in more detail. Because it’s a pattern, you can use it without taking on any new dependencies.
But you can take advantage of the Web Origami project’s async-tree library, which includes:
Map base class along these lines, called SyncMapAsyncMap that can represent network data sourcesFileMap class that supports write operationsYou can use this library to construct things like a build system for generating the static files for a site. A sample blog project uses the library to represent the various stages of the build process as Map-based trees:
Map objects.Map-based representation of the folder that will hold the build output.The entire build.js build process is very concise and boils down to a copy operation:
import { FileMap, Tree } from "@weborigami/async-tree";\nimport site from "./site.js";\n\n// Build process writes the site resources to the build folder\nconst buildTree = new FileMap(new URL("../build", import.meta.url).pathname);\nawait Tree.clear(buildTree); // Erase any existing files\nawait Tree.assign(buildTree, site); // Copy site to build folder\nBy using Map as the fundamental building block, this sample project generates the site’s static files using only two dependencies, the async-tree library and a markdown processor.
The AsyncMap variant lets you represent a network data source as an object that has the same methods as a Map but the methods are asynchronous. This lets you pull content from sources like Dropbox or Google Drive using a much simpler API, so you can incorporate content directly from the network into your build process.
I’ve extended my series of blog architecture comparison posts from earlier this year by porting the sample reference blog from Origami and plain JavaScript to create a Python version (source, demo).
\nThe occasion was reading about improvements in async features in today’s release of Python 3.14, which prompted me to write some Python code for the first time in a long while.
\nThe sample blog doesn’t actually need to make async network requests, so it ended up only using sync functions — but all those sync functions are still lazy and do work only when necessary. And with the improvements in Python 3.14, it might be possible to create an AsyncMapping abstract base class as a variation of Mapping to handle the sorts of async network operations that Origami can do, e.g., reading post content directly out of Dropbox or Google Drive.
Python’s audience has always included people who don’t think of themselves primarily as programmers. That aligns with what I’m trying to do in Origami, so it’s interesting to explore using Python as a possible substrate for Origami ideas.
\nI’m not familiar with Python static site generators, but they seem to generally take the same framework approach as their Node.js counterparts: impose a particular folder structure, provide a magic transformation of that structure to static files, and offer a degree of customization through configuration.
\nLike all the blog implementations in this series, this Python project rejects that approach entirely. Instead, the focus is on creating useful functions and abstractions for defining the site you want to create. It leaves you to put the parts together in a way that makes sense to you. You are always in control and can entirely satisfy your requirements.
\nLike the JavaScript versions of the sample blog, the Python version attempts to use native language constructions whenever possible. It makes heavy use of Python’s Mapping abstract base class to represent collections which are fundamentally lazy: they do essentially no work when constructed. Only when asked for their keys, or for a particular value for a key, will they do substantive work.
An example of this is the project’s Folder class, which wraps a file system folder as a lazy Mapping (specifically, a MutableMapping, which can be updated after it’s created).
Another example of this are the project’s operations that take one Mapping as input and return a new, transformed Mapping. For example, map_extensions, can convert a virtual collection of .md files into a corresponding collection of .html files.
post_html_docs = map_extensions(folder, ".md->.html", md_doc_to_html)\nWhen backed by a Folder containing post.md, the resulting map-of-a-map says that it contains a post.html – but it hasn’t done the real work for that yet. When you ask for post.html, it will ask the underlying Folder for post.md, translate the markdown content to HTML, then return that result. (The actual data pipeline is slightly more complex; see the ReadMe.)
You can use a debugger to inspect the value of a map like this at runtime with a command like:
\nlist(post_html_docs.items())\nThis lets you confirm that the map’s keys and values are what you expect.
\nThe beauty of working at this abstract Mapping level is that your code doesn’t need to care how a particular collection is defined – your code can handle real files or generated-on-demand files in exactly the same way.
At the project’s highest level, site_tree.py defines the root of the site’s tree of resources as a Mapping. Most of those top-level parts of the sites are also Mapping instances: some like assets and images are real folders; others are virtual collections like posts.
# from src/blog_demo/site_tree.py\n\n# The site tree is a tree with Mappings for interior nodes and the desired\n# resources as leaves. The top level of the tree can invoke functions to\n# generate the content on demand. Areas which are just Mappings are inherently\n# lazy and are defined directly.\nsite_tree = invoke_fns({\n "about.html": lambda: about_html(),\n "assets": Folder(here / "assets"),\n "feed.json": lambda: json.dumps(feed(), indent=2),\n "feed.xml": lambda: json_feed_to_rss(feed()),\n "images": Folder(here / ".." / ".." / "images"),\n "index.html": lambda: pages_area()["1.html"], # same as pages/1.html\n "pages": lambda: pages_area(),\n "posts": posts_area(),\n})\nThis programmatic approach lets you dictate precisely how you want to compose the parts of your site; you’re not trapped within the confines of a framework and someone else’s expectations.
\nAs in Origami, the site’s tree of resources is used in two very different ways.
\nFirst, a small web server that accepts any Mapping-based tree converts URL requests like /assets/styles.css into an array of keys ["assets", "styles.css"] that are used to traverse the tree. Given the site_tree.py code above, the first ”assets” key retrieves the Folder wrapper for the real assets folder; the second key retrieves the styles.css file in that folder. Because the site tries to be as lazy as possible, the site only does the work necessary to fulfill the specific request.
Second, building the static site files is simply a matter of copying the site’s virtual tree of resources into a real tree in the file system.
\n# from src/blog_demo/__main__.py\n\ndef build(m: Mapping):\n """\n Given a mapping representing the site structure, copy the entire tree into\n the build folder to create static files.\n """\n build_folder = Folder("build")\n build_folder.clear()\n build_folder.update(m)\nA MutableMapping is created for the build output folder; it’s mutable so that files can be written into it.
The site’s tree of resources is copied directly into it using the completely standard update() method to copy one map into another. That boils down the essence of a static site generator to the single line:
build_folder.update(m)\nThis walks through the source tree m, calling __getitem__ to get each resource. That will trigger the generation of said resource. The result will be passed to the build’ folder’s __setitem__ method to create the corresponding output file.
Let’s compare this Python blog port with the earlier Origami and JavaScript versions.
\nIn terms of source code size, the Python version is written as a demo application and a separate library for map manipulations. That makes it roughly comparable to the blog using Origami’s async-tree library. Accordingly, I’ll factor out the library portion of the code, and the reusable JSON feed-to-RSS translation to measure the non-reusable bytes in the demo application, including both Python (.py) files and Jinja (.j2) templates.
![\"\"](\"/images/2025/10/pythonSourceCode.png\")
The Python version comes in at 10021 bytes, just a bit more than the 9450 bytes for the async-tree version. For this blog application, at least, both Python and JavaScript are comparably expressive. (Origami is still more concise.)
\nPython and Node.js are completely different environments, so it’s not possible to make an apples-to-apples comparison of the weight of the project dependencies. And in any case, measuring dependencies by total file size can only give an extremely coarse approximation of potential complexity. Still, I thought it was interesting to measure the total size on disk of the Python project’s site-packages as an analogue for node_modules.
![\"\"](\"/images/2025/10/pythonDependencies.png\")
The Python version weighs more than the async-tree version. It’s less than Origami, but Origami is also doing a lot more. (Astro is still the most complex answer to the problem, and I don’t believe it’s actually doing enough interesting work to justify its size.)
Finally, let’s look at the time required to build the blog’s static files:
\n![\"\"](\"/images/2025/10/pythonBuildTime.png\")
Python comes in at 0.24s — a hair faster than the zero-dependency JavaScript version, making it the fastest of all the blog versions I’ve created so far.
\nThis was a really interesting experiment! It was a ton of fun to write Python code again.
\nIt seems completely feasible to serve and build a site in Python in a lightweight fashion using a library (under your control) instead of a big framework (that takes control from you). Python seems like a great substrate for Origami ideas. It’s well-designed and widely-used Mapping abstract base class is a natural way to represent your source content as a tree that you can transform into the tree of resources you want for your site.
Over this summer I’ve shifted the Origami expression language to be a closer dialect of JavaScript expressions. Feedback from early adopters indicated that some differences from JavaScript created trouble; eliminating those would improve the language.
\nOrigami is now essentially JavaScript expressions plus paths, with a few additional syntactic features that make it easier to define a site.
\n![\"\"](\"/images/2025/09/blogCode.png\")
The language supports a conceptual model called Content/Transformation you may find helpful in thinking about how to build a site.
\nThe syntax changes to the language included:
\n. syntax for accessing a property. This required developing a heuristic that could reliably tell that post.title is a property reference but image.jpg is a file name — even though both use the same period syntax.Tree for functions that work with trees and Origami for most everything else.new syntax. I’d tried hard to avoid having reserved words, but new is so ingrained in JavaScript developers’ minds that any other syntax is hard to remember.Origami is still missing some esoteric JavaScript expression features (e.g., function parameter destructuring), but those are all on the list tackle. The goal is that you should be able to copy any JavaScript expression and evaluate it as an Origami expression.
\nWhy introduce an alternative expression language to JavaScript?
\nasync, lets you load or fetch files and get data out of them more concisely than with JavaScript. The resulting expression can be 20-40% shorter, making the intent of code easier to see.Watch the motion comic introducing the language, or walk through how to create a basic blog.
\n", "date_published": "2025-09-15T08:00:00.000Z", "id": "https://jan.miksovsky.com/posts/2025/09-15-syntax-changes.html", "url": "https://jan.miksovsky.com/posts/2025/09-15-syntax-changes.html", "title": "Making Origami expressions easier to learn and use" } ] }