DEV Community: Fedor

1.5KB Single-File Wiki

Fedor — Sat, 01 Mar 2025 19:32:26 +0000

Imagine having a personal wiki that fits in a single HTML file — no databases, no servers, just a self-contained knowledge base you can store in Dropbox, email to yourself, or even host on a static file server. Sounds familiar? Inspired by the legendary TiddlyWiki, I set out to create a minimalist wiki that’s lightweight and works even without JavaScript.

TiddlyWiki is a robust and feature-rich tool, but it comes with a cost: it’s a JavaScript-heavy application, often weighing several megabytes. What if we could peel away the complexity and distill it down to its purest form? The result is a lean, fast, and no-frills — a wiki that:

Works without JavaScript: Thanks to pure CSS routing, you can view pages even if JS is disabled.
Edits with ease: Markdown lets you write and format content effortlessly.
Saves instantly: Changes are saved by downloading a new HTML file, making it perfect for offline use.
Fits in 1.5 KB: Minified and gzipped, it’s smaller than most favicons.

In this article, I’ll walk you through the key ideas and hacks that made this project possible. Whether you’re a fan of TiddlyWiki, a minimalist at heart, or just curious about building lightweight web apps, there’s something here for you. Let’s dive in!

Pure CSS Routing: Navigation Without JavaScript

The secret sauce lies in the :target pseudo-class, which applies styles to an element whose ID matches the part of the URL after the # (hash). For example, if the URL is #my-page, the element with id="my-page" becomes the "target", and you can style it accordingly.

In our wiki, each page is represented by an <article> element with a unique ID. The CSS rule below ensures that only the target article (or the index page, if no hash is present) is displayed:

article:not(.index, :target, :has(:target)),
:root:has(:target) article.index:not(:has(:target)) {
  display: none;
}

If the URL hash is #my-page, the <article id="my-page"> becomes visible. If the URL has no hash, the .index article is shown by default. If the hash is #my-photo and some article contains <img id="my-photo">, this article will be displayed.

Hash-based routing works purely with CSS, making it incredibly lightweight and reliable.

Markdown Editing and Prerendering

If JavaScript is enabled, the wiki can progressively enhance the experience with features like Markdown editing. The editor is toggled by double-clicking anywhere on the page. Pages are created on the fly when a new hash is encountered.

At first I expected to find a plethora of minimalist Markdown libraries that could handle basic formatting without external dependencies. To my surprise, a relativley popular option — Snarkdown — doesn't support paragraphs. That’s right — no <p> tags!

That led to creating a compact, self-contained Markdown-to-HTML converter. Here’s the core of it:

function md2html(str) {
  const enchtml = (str) => str.replaceAll("<", "&lt;");
  const inlines = [
    [
      /(\*{1,2}|~~|`)(.+?)\1/g,
      (_, c, txt) =>
        c == "*"
          ? `<i>${txt}</i>`
          : c == "**"
          ? `<b>${txt}</b>`
          : c == "~~"
          ? `<s>${txt}</s>`
          : `<code>${enchtml(txt)}</code>`,
    ],
    // ... (other inline patterns)
  ];
  const blocks = [
    [
      /\n(#+)([^\n]+)/g,
      (_, h, txt) => `\n<h${h.length}>${txt.trim()}</h${h.length}>`,
    ],
    [
      /\n(\n *\-[^\n]+)+/g,
      (txt) =>
        `\n<ul><li>${replaceInlines(txt)
          .split(/\n+ *\- */)
          .filter(Boolean)
          .join("</li><li>")}</li></ul>`,
    ],
    // ... (other block patterns)
  ];
  return blocks.reduce((md, rule) => md.replace(...rule), `\n${str}\n`);
}

The md2html function follows a specific sequence to ensure Markdown is parsed correctly:

Process Block-Level Elements First: The function starts by identifying and transforming block-level Markdown syntax (like code blocks, headings, lists, and paragraphs) into their corresponding HTML structures.
Process Inline Elements Within Blocks: Inline formatting rules (like bold, italics, and links) are applied only where appropriate (e.g., inside paragraphs or list items).
Escape HTML Only Where Necessary: HTML escaping is applied selectively, primarily within code blocks and inline code snippets. It's not a security feature here.

The rules are easy to modify or extend, allowing you to add support for additional formatting features. But remember that Markdown is not a replacement for HTML!

When you save a wiki page, the content is prerendered into HTML and dynamically appended to the DOM. It’s essentially like a static site generator, but it operates entirely within the browser resulting in a single, self-contained HTML file.

Saving Wiki: File Download

Since this is a single-file wiki, saving works by downloading the entire HTML file with the updated content. This is achieved using the Blob API:

function download() {
  const doc = document.documentElement.cloneNode(true);
  const html = "<!DOCTYPE html>\n" + doc.outerHTML;
  const blob = new Blob([html], { type: "text/html" });
  const link = document.createElement("a");
  link.href = URL.createObjectURL(blob);
  link.download = "wiki" + Date.now() + ".html";
  link.click();
}

This function creates a new HTML file containing the current state of the wiki and triggers a download. It’s a simple yet effective way to persist changes without a backend.

Conclusion: 1.5KB Single-File Wiki

By combining pure CSS routing, a custom Markdown parser, and a simple offline-first saving method, you can create a functional and lightweight wiki that works even without JavaScript. Whether you're building a personal knowledge base or a portable documentation tool, this approach strikes a nice balance between simplicity and practicality. It’s not perfect, but it gets the job done in a way that’s both elegant and efficient.

Feel free to take the code, tweak it, and make it your own. After all, the best tools are the ones you build yourself.

1KB Frontend Library: Final Bytes

Fedor — Sun, 16 Feb 2025 22:23:49 +0000

Recap: The Journey to a 1KB Frontend Library

In the previous article, we set out to build a 1KB frontend library — a lean, no-frills toolkit that fits in just a few functions without any dependencies. Here’s what we covered:

signal: For creating reactive state.
effect: For running side effects when state changes.
computed: For deriving reactive values.
html: For declarative DOM rendering.

These four functions gave us a solid foundation for building dynamic, efficient UIs without the need for build tools. But today, we’re introducing the fifth and final function — each — to unlock efficient list rendering. Let’s dive into how each works and why it’s the perfect finishing touch!

The Problem with Brute-Force Re-Rendering

Signals allow us to pinpoint exactly which parts of the DOM depend on specific data changes, enabling us to rerender only the affected nodes or attributes.

However, when it comes to dynamic lists, the story changes. Lists often involve complex updates — adding, removing, or reordering items — that can’t be handled by simply updating individual nodes.

Let’s start with the basic way of rendering lists. Typically, we might use a .map() to iterate over an array and generate DOM elements. For example:

html`<ul>
  ${() => todos().map(
    (todo) => html`<li>${todo.text}</li>`
  )}
</ul>`;

While this approach is straightforward, it has a significant downside: every update to the list results in a full re-render. Even if only one item in the list changes, the entire list is torn down and rebuilt. This can lead to unnecessary DOM manipulations, reflows, and degraded performance — especially as the list grows in size.

A Smarter Way to Render Lists with `each`

The each function is designed to solve this problem by introducing a diffing algorithm. Instead of re-rendering the entire list, each compares the current state of the list with the new state and only updates the parts of the DOM that have changed. This approach minimizes DOM operations and preserves critical DOM states like user focus, text selection, and scroll position.

To implement the each function, we’re dusting off a decade-old algorithm by Simon Friis Vindum, the creator of the widely respected snabbdom library. The resulting code is compact yet performant:

function each(val, getKey, tpl) {
  let a = [];
  let aNodes = [];
  return () => {
    const items = val?.call ? val() : val;
    const b = items.map(getKey);
    const aIdx = new Map(a.map((...kv) => kv));
    const bIdx = new Map(b.map((...kv) => kv));
    const bNodes = [];
    for (let i = 0, j = 0; i != a.length || j != b.length; ) {
      let aElm = a[i],
        bElm = b[j];
      if (aElm === null) i++;
      else if (b.length <= j) aNodes[i++].remove();
      else if (a.length <= i) bNodes.push(tpl(items[j], j++)[0]);
      else if (aElm === bElm) bNodes[j++] = aNodes[i++];
      else {
        let oldIdx = aIdx.get(bElm);
        if (bIdx.get(aElm) === undefined) aNodes[i++].remove();
        else if (oldIdx === undefined) {
          bNodes[j] = tpl(items[j], j)[0];
          aNodes[i].before(bNodes[j++]);
        } else {
          bNodes[j++] = aNodes[oldIdx];
          aNodes[i].before(aNodes[oldIdx]);
          a[oldIdx] = null;
          if (oldIdx > i + 1) i++;
        }
      }
    }
    a = b;
    aNodes = bNodes;
    return [...aNodes];
  };
}

Here’s how it works:

html`<ul>
  ${each(
    todos,
    (todo) => todo.id,
    (todo) => html`<li>${todo.text}</li>`
  )}
</ul>`;

The second argument to each is a function that returns a unique key for each item (e.g., item.id). These keys allow us to track which items have been added, removed, or moved, enabling precise updates to the DOM.

When the list updates, each creates a map of the old and new items using their keys. It then iterates through both lists simultaneously, comparing items based on their keys. The algorithm ensures that the DOM reflects the new list state with the fewest possible changes.

Unlike some old diffing algorithms, each allows you to use the entire item object as a key. This is possible because each leverages JavaScript’s Map under the hood, which can use objects as keys. For example:

html`<ul>
  ${each(
    todos,
    (todo) => todo, // Use the whole object as a key
    (todo) => html`<li>${todo.text}</li>`
  )}
</ul>`;

An Updated Example: A Todo App

To showcase the power of the each function, here is an updated version of our Todo App example. Check out how it preserves DOM state like text selection.

Conclusion: A Complete 1KB Frontend Library

Our journey to build a 1KB frontend library is now complete! With just five functions — signal, effect, computed, html, and each — we’ve created a powerful, lightweight toolkit for building dynamic, efficient UIs. Clocking in at 972 bytes minified and gzipped, this library proves that you don’t need megabytes of dependencies or complex build tools to create modern web applications.

And the best part? The entire code is provided below — ready for you to copy, paste, and start using right away.

Full Code

{
  const effects = [Function.prototype];
  const disposed = new WeakSet();

  function signal(value) {
    const subs = new Set();
    return (newVal) => {
      if (newVal === undefined) {
        subs.add(effects.at(-1));
        return value;
      }
      if (newVal !== value) {
        value = newVal?.call ? newVal(value) : newVal;
        for (let eff of subs) disposed.has(eff) ? subs.delete(eff) : eff();
      }
    };
  }

  function effect(fn) {
    effects.push(fn);
    try {
      fn();
      return () => disposed.add(fn);
    } finally {
      effects.pop();
    }
  }
}

function computed(fn) {
  const s = signal();
  s.dispose = effect(() => s(fn()));
  return s;
}

{
  function html(tpl, ...data) {
    const marker = "\ufeff";
    const t = document.createElement("template");
    t.innerHTML = tpl.join(marker);
    if (tpl.length > 1) {
      const iter = document.createNodeIterator(t.content, 1 | 4);
      let n,
        idx = 0;
      while ((n = iter.nextNode())) {
        if (n.attributes) {
          if (n.attributes.length)
            for (let attr of [...n.attributes])
              if (attr.value == marker) render(n, attr.name, data[idx++]);
        } else {
          if (n.nodeValue.includes(marker)) {
            let tmp = document.createElement("template");
            tmp.innerHTML = n.nodeValue.replaceAll(marker, "<!>");
            for (let child of tmp.content.childNodes)
              if (child.nodeType == 8) render(child, null, data[idx++]);
            n.replaceWith(tmp.content);
          }
        }
      }
    }
    return [...t.content.childNodes];
  }

  const render = (node, attr, value) => {
    const run = value?.call
      ? (fn) => {
          let dispose;
          dispose = effect(() =>
            dispose && !node.isConnected ? dispose() : fn(value())
          );
        }
      : (fn) => fn(value);
    if (attr) {
      node.removeAttribute(attr);
      if (attr.startsWith("on")) node[attr] = value;
      else
        run((val) => {
          if (attr == "value" || attr == "checked") node[attr] = val;
          else
            val === false
              ? node.removeAttribute(attr)
              : node.setAttribute(attr, val);
        });
    } else {
      const key = Symbol();
      run((val) => {
        const upd = Array.isArray(val)
          ? val.flat()
          : val !== undefined
          ? [document.createTextNode(val)]
          : [];
        for (let n of upd) n[key] = true;
        let a = node,
          b;
        while ((a = a.nextSibling) && a[key]) {
          b = upd.shift();
          if (a !== b) {
            if (b) a.replaceWith(b);
            else {
              b = a.previousSibling;
              a.remove();
            }
            a = b;
          }
        }
        if (upd.length) (b || node).after(...upd);
      });
    }
  };
}

function each(val, getKey, tpl) {
  let a = [];
  let aNodes = [];
  return () => {
    const items = val?.call ? val() : val;
    const b = items.map(getKey);
    const aIdx = new Map(a.map((...kv) => kv));
    const bIdx = new Map(b.map((...kv) => kv));
    const bNodes = [];
    for (let i = 0, j = 0; i != a.length || j != b.length; ) {
      let aElm = a[i],
        bElm = b[j];
      if (aElm === null) i++;
      else if (b.length <= j) aNodes[i++].remove();
      else if (a.length <= i) bNodes.push(tpl(items[j], j++)[0]);
      else if (aElm === bElm) bNodes[j++] = aNodes[i++];
      else {
        let oldIdx = aIdx.get(bElm);
        if (bIdx.get(aElm) === undefined) aNodes[i++].remove();
        else if (oldIdx === undefined) {
          bNodes[j] = tpl(items[j], j)[0];
          aNodes[i].before(bNodes[j++]);
        } else {
          bNodes[j++] = aNodes[oldIdx];
          aNodes[i].before(aNodes[oldIdx]);
          a[oldIdx] = null;
          if (oldIdx > i + 1) i++;
        }
      }
    }
    a = b;
    aNodes = bNodes;
    return [...aNodes];
  };
}

1KB Frontend Library

Fedor — Sat, 08 Feb 2025 23:19:29 +0000

Today’s Challenge: Build a 1KB Frontend Library

Let’s tackle an exciting challenge today: creating a frontend library that’s just 1 kilobyte in size. I’m talking about a "disappearing framework" — not like Svelte, which only "disappears" after compilation. No build tools, no bloated node_modules folder hogging your SSD. Just a few lightweight JavaScript functions you can copy, paste, and use right away.

Buckle up!

Reactivity with Signals

By 2025, the frontend world has largely agreed on one thing: signals for reactivity. Almost every major framework has its own version of signals — like Vue’s ref() or Svelte’s $state rune.

If you’re new to signals, don’t worry. Just remember two key concepts:

Signals: Reactive values that can be read and updated.
Effects: Functions that depend on signals. When a signal changes, its dependent effects automatically re-run.

A Tiny Signals Implementation

Our compact signals implementation is inspired by Andrea Giammarchi’s excellent article on signals. If you’re curious about the nitty-gritty, I highly recommend giving it a read.

{

const effects = [Function.prototype];
const disposed = new WeakSet();

function signal(value) {
  const subs = new Set();
  return (newVal) => {
    if (newVal === undefined) {
      subs.add(effects.at(-1));
      return value;
    }
    if (newVal !== value) {
      value = newVal?.call ? newVal(value) : newVal;
      for (let eff of subs) disposed.has(eff) ? subs.delete(eff) : eff();
    }
  };
}

function effect(fn) {
  effects.push(fn);
  try {
    fn();
    return () => disposed.add(fn);
  } finally {
    effects.pop();
  }
}

}

function computed(fn) {
  const s = signal();
  s.dispose = effect(() => s(fn()));
  return s;
}

How It Works:

We use a block scope ({}) to keep our variables out of the global namespace. This is handy when modules aren’t an option.
The signal function creates a reactive value. It returns a function that acts as both a getter and setter:
- If called without arguments, it returns the current value and subscribes the active effect to the signal.
- If called with a new value, it updates the signal and triggers all subscribed effects (unless they’re disposed).
The effect function registers a callback that runs immediately and re-runs whenever any of its dependent signals change.
The computed function creates a derived signal — a reactive value that is recalculated every time it's dependencies change.

Example Usage:

const count = signal(0); // Create a signal with initial value 0

effect(() => {
  console.log(`Count is: ${count()}`); // Log the current value of the signal
});

count(1); // Update the signal, which triggers the effect and logs "Count is: 1"
count(2); // Update again, logs "Count is: 2"

Reactive HTML Templates

Now, let’s add some templating and rendering magic. We’ll create a tagged template function, html, that parses HTML strings and dynamically binds reactive values to the DOM.

{

function html(tpl, ...data) {
  const marker = "\ufeff";
  const t = document.createElement("template");
  t.innerHTML = tpl.join(marker);
  if (tpl.length > 1) {
    const iter = document.createNodeIterator(t.content, 1 | 4);
    let n,
      idx = 0;
    while ((n = iter.nextNode())) {
      if (n.attributes) {
        if (n.attributes.length)
          for (let attr of [...n.attributes])
            if (attr.value == marker) render(n, attr.name, data[idx++]);
      } else {
        if (n.nodeValue.includes(marker)) {
          let tmp = document.createElement("template");
          tmp.innerHTML = n.nodeValue.replaceAll(marker, "<!>");
          for (let child of tmp.content.childNodes)
            if (child.nodeType == 8) render(child, null, data[idx++]);
          n.replaceWith(tmp.content);
        }
      }
    }
  }
  return [...t.content.childNodes];
}

const render = (node, attr, value) => {
  const run = value?.call
    ? (fn) => {
        let dispose;
        dispose = effect(() =>
          dispose && !node.isConnected ? dispose() : fn(value())
        );
      }
    : (fn) => fn(value);
  if (attr) {
    node.removeAttribute(attr);
    if (attr.startsWith("on")) node[attr] = value;
    else
      run((val) => {
        if (attr == "value" || attr == "checked") node[attr] = val;
        else
          val === false
            ? node.removeAttribute(attr)
            : node.setAttribute(attr, val);
      });
  } else {
    const key = Symbol();
    run((val) => {
      const upd = Array.isArray(val)
        ? val.flat()
        : val !== undefined
        ? [document.createTextNode(val)]
        : [];
      for (let n of upd) n[key] = true;
      let a = node,
        b;
      while ((a = a.nextSibling) && a[key]) {
        b = upd.shift();
        if (a !== b) {
          if (b) a.replaceWith(b);
          else {
            b = a.previousSibling;
            a.remove();
          }
          a = b;
        }
      }
      if (upd.length) (b || node).after(...upd);
    });
  }
}

}

Key Features:

The html function returns an array of DOM nodes.
It supports dynamic attributes, text content, child nodes, and event listeners using the on* syntax.
If the provided value is a function (or a signal itself) it sets up an effect which is re-run to update the DOM.

Example Usage:


  // Reactive state
  const count = signal(0);

  // Render the app
  const app = html`<div>
      <h1>Counter: ${count}</h1>
      <button onclick=${() => count((val) => val + 1)}>Increment</button>
      <button onclick=${() => count((val) => val - 1)}>Decrement</button>
    </div>`;

  // Mount the app to the DOM
  document.body.append(...app);

A More Complex Example: A Todo App

Check out this interactive Todo app built with our tiny library. It’s a great example of what you can achieve with just a few lines of code.

What’s Next?

In the next installment, we’ll add efficient list re-rendering with just one function. Stay tuned! 🚀

DEV Community: Fedor

1.5KB Single-File Wiki

Pure CSS Routing: Navigation Without JavaScript

Markdown Editing and Prerendering

Saving Wiki: File Download

Conclusion: 1.5KB Single-File Wiki

1KB Frontend Library: Final Bytes

Recap: The Journey to a 1KB Frontend Library

The Problem with Brute-Force Re-Rendering

A Smarter Way to Render Lists with each

An Updated Example: A Todo App

Conclusion: A Complete 1KB Frontend Library

1KB Frontend Library

Today’s Challenge: Build a 1KB Frontend Library

Reactivity with Signals

A Tiny Signals Implementation

How It Works:

Example Usage:

Reactive HTML Templates

Key Features:

Example Usage:

A More Complex Example: A Todo App

What’s Next?

A Smarter Way to Render Lists with `each`