This script dynamically loads and displays a hierarchical list of subpages for the current page in Wiki.js (version 2.x). It utilizes the built-in GraphQL API to fetch child pages and builds a nested tree view up to a specified depth.

Auto-generate Subpage Tree for Wiki.js 2.x.md

📄 Auto-generate Subpage Tree for Wiki.js 2.x

Description:

This script dynamically loads and displays a hierarchical list of subpages in Wiki.js (version 2.x). It utilizes the built-in GraphQL API (pages.search for subpaths, pages.list for root-level) to fetch pages and builds a nested tree view up to a specified depth.

Usage:

The script can be included in two ways:

1. Globally via Administration → Theme → Head HTML Injection

Requirements:

A <div class="children-placeholder"> must be present on the page. Configure it with the following optional attributes:

Attribute	Default	Description
data-limit	100	Maximum number of subpages
data-depth	2	Maximum tree depth
data-sort	path:asc	Sorting field (path, title, description) and direction (asc, desc)
data-target-path	(current page)	Override target path. Supports locale prefix (e.g. de/projekte/project01). Set to locale only (e.g. de) to generate a full sitemap from root.
data-debug	false	Enable debug logs in the browser console

Examples:

Subpages of the current page:

<div class="children-placeholder" data-depth="2"></div>

Subpages of a specific path:

<div class="children-placeholder" data-target-path="de/projekte/project01" data-depth="3"></div>

Full sitemap (all pages):

<div class="children-placeholder" data-target-path="de" data-depth="5" data-limit="200"></div>

Result:

Once loaded, the script replaces the placeholder with a nested <ul> structure of links to all matching subpages.

script.html

<script type="application/javascript">
(async function() {
  // Wait until Wiki.js finishes rendering the page content
  function waitForContent(timeout = 10000) {
    return new Promise((resolve) => {
      const start = Date.now();
      const check = () => {
        const el = document.querySelector(".children-placeholder");
        if (el) return resolve(el);
        if (Date.now() - start > timeout) return resolve(null);
        requestAnimationFrame(check);
      };
      check();
    });
  }

  const placeholder = await waitForContent();
  if (!placeholder) {
    console.log("🛈 No .children-placeholder found (timeout reached).");
    return;
  }

  // Read configuration from data attributes
  const limit = parseInt(placeholder.getAttribute("data-limit") || "100", 10);
  const maxDepth = parseInt(placeholder.getAttribute("data-depth") || "1", 10);
  const sortAttr = placeholder.getAttribute("data-sort") || "path:asc";
  const debug = placeholder.getAttribute("data-debug") === "true";
  const targetPath = placeholder.getAttribute("data-target-path");

  // Validate sort field against allowed values
  const ALLOWED_SORT_FIELDS = ["path", "title", "description"];
  const [rawSortField, sortDirection] = sortAttr.split(":");
  const sortField = ALLOWED_SORT_FIELDS.includes(rawSortField) ? rawSortField : "path";
  const sortAsc = sortDirection !== "desc";

  const log = (...args) => debug && console.log(...args);

  if (sortField !== rawSortField) {
    log("⚠️ Invalid sort field:", rawSortField, "– falling back to 'path'");
  }

  // Parse current URL for locale and path
  let fullPath = window.location.pathname;
  let [, rawLocale, ...pathParts] = fullPath.split("/");

  // Validate locale: must be 2-3 letter language code (e.g. "en", "de", "deu")
  const locale = /^[a-z]{2,3}$/.test(rawLocale) ? rawLocale : "en";

  if (locale !== rawLocale) {
    log("⚠️ Invalid locale detected:", rawLocale, "– falling back to 'en'");
  }

  // Use targetPath if specified, otherwise use current path
  let path;
  if (targetPath) {
    path = targetPath.replace(/^\/+|\/+$/g, "");
    // Strip locale prefix if present (e.g. "de" → "" or "de/projekte/dana" → "projekte/dana")
    if (path === locale) {
      path = "";
    } else if (path.startsWith(locale + "/")) {
      path = path.slice(locale.length + 1);
    }
    log("🎯 Using target path:", path || "(root)");
  } else {
    path = pathParts.join("/").replace(/^\/+|\/+$/g, "");
    log("📍 Using current path:", path);
  }

  const isRoot = path === "";
  const basePath = isRoot ? "" : `${path}/`;

  log("🌍 Locale:", locale);
  log("🔍 Searching for subpages of path:", isRoot ? "(root)" : basePath);

  placeholder.textContent = "Loading subpages…";

  // Build GraphQL query: use pages.list for root level, pages.search for subpaths
  let gqlQuery;
  if (isRoot) {
    gqlQuery = {
      query: `
        query {
          pages {
            list(orderBy: PATH) {
              path
              title
              description
            }
          }
        }
      `
    };
    log("📋 Using pages.list (root level)");
  } else {
    gqlQuery = {
      query: `
        query ($query: String!, $locale: String!) {
          pages {
            search(query: $query, locale: $locale) {
              results {
                title
                path
                description
              }
            }
          }
        }
      `,
      variables: { query: basePath, locale: locale }
    };
    log("🔎 Using pages.search for:", basePath);
  }

  try {
    const response = await fetch("/graphql", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(gqlQuery)
    });

    const json = await response.json();

    if (!response.ok || json.errors) {
      throw new Error("GraphQL error: " + JSON.stringify(json.errors));
    }

    // Extract results depending on which query was used
    const results = isRoot
      ? (json?.data?.pages?.list ?? [])
      : (json?.data?.pages?.search?.results ?? []);

    log("📄 Found pages:", results.map(p => p.path));

    // Filter for children
    const children = results
      .filter(p => p.path !== path)
      .filter(p => isRoot || p.path.startsWith(path + "/"))
      .sort((a, b) => {
        const aVal = a[sortField]?.toLowerCase?.() || "";
        const bVal = b[sortField]?.toLowerCase?.() || "";
        if (aVal < bVal) return sortAsc ? -1 : 1;
        if (aVal > bVal) return sortAsc ? 1 : -1;
        return 0;
      })
      .slice(0, limit);

    log("✅ Filtered & sorted subpages:", children.map(p => p.path));

    if (children.length === 0) {
      placeholder.innerHTML = "<em>No subpages available.</em>";
      return;
    }

    // Build a tree
    const tree = {};
    children.forEach(page => {
      const relPath = isRoot
        ? page.path.replace(/^\/+|\/+$/g, "")
        : page.path.slice(basePath.length).replace(/^\/+|\/+$/g, "");
      const parts = relPath.split("/");
      let node = tree;
      parts.forEach((part, idx) => {
        if (!node[part]) node[part] = { __meta: null, __children: {} };
        if (idx === parts.length - 1) node[part].__meta = page;
        node = node[part].__children;
      });
    });

    function escapeHtml(str) {
      return str.replace(/[&<>"']/g, m =>
        ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#039;" }[m])
      );
    }

    function renderTree(treeObj, depth = 1) {
      if (depth > maxDepth) return null;
      const ul = document.createElement("ul");
      ul.className = `children-tree level-${depth}`;

      for (const key of Object.keys(treeObj)) {
        const node = treeObj[key];
        const hasChildren = Object.keys(node.__children).length > 0;
        const hasMeta = !!node.__meta;
        if (!hasMeta && !hasChildren) continue;

        const li = document.createElement("li");
        li.className = "children-item";

        if (hasMeta) {
          const p = node.__meta;
          li.innerHTML = `
            <a href="/${locale}/${p.path}">${escapeHtml(p.title)}</a>
            <br><small>${escapeHtml(p.description || "")}</small>
          `;
        } else {
          li.innerHTML = `<strong>${escapeHtml(key)}</strong>`;
        }

        const childList = renderTree(node.__children, depth + 1);
        if (childList) li.appendChild(childList);
        ul.appendChild(li);
      }

      return ul;
    }

    // Render final tree
    const wrapper = document.createElement("div");
    wrapper.className = "children-list";
    const treeHtml = renderTree(tree);
    if (treeHtml) wrapper.appendChild(treeHtml);

    // Safely replace content inside placeholder
    placeholder.innerHTML = "";
    placeholder.appendChild(wrapper);

    log("🌲 Tree structure successfully rendered.");
  } catch (err) {
    console.error("❌ Error loading subpages:", err);
    placeholder.innerHTML = "<em>Error loading subpages.</em>";
  }
})();
</script>

I forked this and made some changes so that the script waits for Wiki.js to render the page before replacing the contents of the div (instead of replacing the entire div), which means additional text on the page doesn’t interfere with the scripts functionality.

@mormorhaxa Nice - I took a look at it and will adopt it and embed something else as well.

@mormorhaxa Added another feature today

@psycho0verload Great! I’ll check it out!

I’ve actually got a newer version I’m using myself that’s easier for my users to use with the Visual Editor.