fixing gh-pages

site/content/posts/xslt-debugging-patterns.md

@@ -0,0 +1,33 @@
+---
+title: "XSLT debugging patterns that save hours"
+description: "Practical ways to trace, isolate, and fix transformations with minimal friction."
+date: 2025-03-01T00:00:00Z
+---
+
+XSLT bugs are rarely loud. More often, a template silently matches the wrong node, a predicate filters out a value you needed, or a namespace mismatch turns an element into a ghost. The fastest fix comes from a repeatable debugging workflow that keeps your assumptions visible. Over time you learn the same patterns appear in almost every real project, whether you are cleansing XML feeds, integrating partner payloads, or generating documents. This post walks through the techniques I use as an integration engineer to debug transforms quickly without losing context.
+
+Start by making the matching rules obvious. The majority of issues are caused by using `//` too freely or relying on default namespaces. Replace broad paths with anchored ones, and when in doubt, print out what the processor thinks the current node is. A simple `xsl:message` combined with `name()` and `namespace-uri()` can reveal a namespace mismatch in seconds. I also add short, temporary templates that match the suspected nodes and output minimal text, which is a fast way to confirm whether the selection is correct.
+
+Next, isolate the failing region by reducing input size. You rarely need the entire input document to debug a single mapping. Extract the smallest fragment that reproduces the issue and run the transform against that. This lets you simplify predicates and remove unrelated templates. When a transform uses `xsl:key`, add a temporary output that lists the key index for a given value so you can see if the key is being built correctly. The same idea works for variables: output them just once in a deterministic area of the result so you can verify their shape.
+
+A stable debug transform also benefits from deterministic ordering. When you iterate through nodes, add an explicit `xsl:sort` so the output is predictable. That makes diffs meaningful when you tweak a predicate or update a template priority. If you are mixing modes, ensure the call chain is explicit; a missing `mode` is a classic way to call a generic template by accident. A related trap is having a high-priority identity template that overrides a specialized one, so watch for priority values and make sure the most specific template wins.
+
+When handling multiple inputs, be clear about document boundaries. Use `document()` or `collection()` with explicit base URIs and add messages that show which document node you are iterating. If you are using XSLT 2.0 or 3.0, a quick `serialize()` to a short string can show you whether the tree is what you expect. If you stick to XSLT 1.0, the same idea works by writing `xsl:copy-of` into a separate debug result tree and inspecting it.
+
+Here is a short pattern I often add while troubleshooting:
+
+```xml
+<xsl:template match="*">
+  <xsl:message>
+    node=<xsl:value-of select="name()"/>
+    ns=<xsl:value-of select="namespace-uri()"/>
+  </xsl:message>
+  <xsl:apply-templates/>
+</xsl:template>
+```
+
+You can drop this at the top of the stylesheet, run a quick transform, and then remove it once the root cause is found. The idea is not to keep noise in production, but to have a fast way to make the invisible visible. For more focused tracing, add the template only for the nodes you suspect are wrong. Debugging gets faster the more you scope down the noise.
+
+Finally, keep a checklist of the classic XSLT footguns: missing namespaces, wrong context node, incorrect `@` in attribute selection, and predicates that use 1-based indexes when you thought they were 0-based. I also look for template import precedence issues and for unexpected whitespace handling when the output is textual. These are easy to miss because the transform still runs, it just runs incorrectly.
+
+If you want a fast place to test these patterns with real inputs, use the online editor at [https://xsltplayground.com](https://xsltplayground.com). It is built for rapid iteration with multiple inputs and parameters, which makes debugging much less painful and keeps your feedback loop tight.

site/content/posts/xslt-integration-architecture.md

@@ -0,0 +1,25 @@
+---
+title: "Architecting XSLT in integration pipelines"
+description: "Where XSLT fits in modern systems and how to keep transforms clean."
+date: 2025-03-06T00:00:00Z
+---
+
+XSLT is at its best when it is treated as a focused transformation component in a wider integration architecture. You can use it inside an ESB, as part of a serverless function, or embedded in a data processing pipeline. The key is to define its responsibility clearly: XSLT should transform shape and content, not contain hidden transport logic or business workflows. With that boundary in place, the stylesheet becomes easier to test, reuse, and evolve.
+
+A good architecture separates input acquisition, transformation, and delivery. The system that receives the payload should normalize and validate it before passing it to the XSLT step. After the transform, another component handles delivery or storage. This keeps the stylesheet focused and reduces the risk of it failing because of environment assumptions. It also makes it easier to swap processors or upgrade XSLT versions without touching unrelated logic.
+
+When integrating multiple sources, think of XSLT as a join and normalization engine. The stylesheet can combine a transaction payload with reference data, language resources, or configuration parameters. The calling system should provide those inputs explicitly rather than having the stylesheet reach out to remote systems. This makes the transform deterministic and reduces operational risk. It also improves security because the transform does not need to access external networks.
+
+Versioning is another important part of integration architecture. Treat stylesheets like code and version them alongside the application that uses them. Include an identifier in the stylesheet that indicates its version and expected input schema. If you have multiple partner versions, consider a dispatch layer that selects the correct stylesheet based on input metadata. This avoids cluttering a single stylesheet with dozens of conditionals and makes maintenance much easier.
+
+Pay attention to error handling. XSLT can fail when the input is malformed or missing required elements. Decide whether the transform should fail fast or produce a partial output with warnings. In critical integrations, I prefer to fail fast and let the pipeline route the message to an error queue. For non-critical outputs, you may choose to emit defaults and collect warnings. Either way, keep the error strategy consistent and visible in the stylesheet.
+
+Performance and scalability often depend on your processor configuration. If you run large transforms, use a streaming-capable processor where possible, and avoid functions that require the whole tree if you do not need it. In XSLT 3.0, streaming modes can reduce memory pressure significantly. If you are still on XSLT 1.0, the best strategy is to keep documents small and avoid deep scans.
+
+Documentation matters more than you think. A short diagram or README that shows inputs, parameters, and outputs can save days of debugging. Include a section that lists required inputs and optional ones, and document the default values for parameters. This makes it easy for new team members to use the stylesheet correctly and reduces integration errors.
+
+Security is another architectural concern. Treat external payloads as untrusted and validate them before the transform. Limit external entity expansion and disable features you do not need in the processor configuration. If you pass data between services, make sure you are not leaking sensitive fields in the output, and keep a clear mapping of which fields are retained or dropped.
+
+The final piece is tooling. You need a place to test, debug, and share transforms with the team. A browser-based editor is ideal for quick iteration, especially when you are coordinating across teams or validating partner payloads. It lowers the barrier to entry and speeds up the feedback loop during integration work.
+
+If you want a reliable place to iterate on transforms with multiple inputs and parameters, try the online editor at [https://xsltplayground.com](https://xsltplayground.com). It is a practical tool for integration engineers who need fast feedback without complex setup.

site/content/posts/xslt-parameters-and-multiple-inputs.md

@@ -0,0 +1,32 @@
+---
+title: "Designing XSLT transforms with parameters and multiple inputs"
+description: "How to structure stylesheets that consume several XML documents and stay maintainable."
+date: 2025-03-02T00:00:00Z
+---
+
+Many real-world transformations do not run on a single XML document. You often merge a primary payload with reference data, catalog lookups, or environment configuration. Done well, this results in a clean, predictable transform. Done poorly, it becomes a maze of `document()` calls and hidden dependencies. The difference is in how you model inputs and parameters from the start. As an integration engineer, I treat input selection and parameter design as first-class API design for the stylesheet.
+
+Start by naming every input. Instead of embedding `document('config.xml')` in multiple templates, load each external document once near the top of the stylesheet and bind it to a global variable. This makes dependencies explicit and keeps the rest of the code focused on mapping. It also helps with testing, because you can override the URI with a parameter. A clean pattern is to define `xsl:param` values for input URIs and then bind them to `xsl:variable` values that hold the parsed documents.
+
+The same clarity applies to parameters. Keep parameters primitive and predictable, and avoid passing in node sets unless you truly need them. A parameter should be an external knob: region, language, a feature flag, or an output format. If you have a complex decision tree, consider using a lookup XML or JSON input and then query it inside the stylesheet. This approach keeps the invocation interface stable while still letting you evolve business rules.
+
+A simple skeleton might look like this:
+
+```xml
+<xsl:param name="catalog-uri"/>
+<xsl:param name="region" select="'us'"/>
+
+<xsl:variable name="catalog" select="document($catalog-uri)"/>
+```
+
+From there, templates can reference `$catalog` without worrying about IO or base URIs. You can also define a named template that accepts a parameter for reuse across multiple modes. This is useful when the same output block is needed for several sections of the document but the selection context differs.
+
+When combining multiple inputs, always anchor your lookups to a clear key. If you can, define `xsl:key` on the external document so lookups are efficient and readable. In XSLT 2.0 or 3.0, `xsl:for-each-group` and the `map` types can reduce boilerplate, but the core idea remains: make your joins explicit and deterministic. If you rely on default order or on undocumented assumptions about uniqueness, you will eventually get a hard-to-reproduce bug.
+
+Another important integration pattern is separating parsing from formatting. For example, you might normalize all values from the various inputs into a canonical intermediate structure and then render that structure into the final output. This makes testing easier and supports future outputs such as CSV, JSON, or a secondary XML format. Even in XSLT 1.0, you can emulate this by creating result tree fragments, then processing them in a second pass if needed.
+
+Multiple inputs also raise questions about fallbacks. Decide how you want to behave when optional data is missing. I prefer to centralize defaults in a few named templates or functions and avoid sprinkling `xsl:choose` blocks everywhere. This keeps the stylesheet readable and makes it obvious how to override the defaults later. Document your fallbacks in the code with short, clear names so a future maintainer does not have to rediscover the rules by reading the entire stylesheet.
+
+Finally, create a small set of inputs that represent common scenarios and run them regularly. For example, have a baseline case, a case with missing reference data, and a case with unexpected elements. These are the cases that reveal poor assumptions about inputs. A fast way to iterate on these scenarios is to run the transform with a tool that lets you swap inputs and parameters quickly.
+
+If you want to try these patterns with real inputs and multiple documents, the online editor at [https://xsltplayground.com](https://xsltplayground.com) is built for that workflow. It lets you load multiple XML documents and parameters, see how they interact, and keep your integration logic transparent as it grows.

site/content/posts/xslt-performance-tuning.md

@@ -0,0 +1,25 @@
+---
+title: "XSLT performance tuning without losing readability"
+description: "A practical guide to faster transformations with keys, modes, and smarter selection."
+date: 2025-03-03T00:00:00Z
+---
+
+Performance problems in XSLT are sneaky. The stylesheet looks clean, the output is correct, but the transform slows down as the input grows. Most of the time this is caused by expensive selections that are repeated in loops, or by deep `//` searches that scan the entire tree more often than you expect. The good news is that you can usually fix these issues without turning the stylesheet into unreadable micro-optimizations.
+
+The first step is to examine where you are traversing the document. XSLT processors are optimized for template matching, so prefer `xsl:apply-templates` and specific match patterns over `xsl:for-each` with `//` in the select. When you do need a search, limit it to the smallest possible subtree. A single `//` at the top-level becomes a full-tree scan each time it runs. If it runs inside another loop, the cost can explode.
+
+Keys are the most important performance feature, and they also improve readability. When you define an `xsl:key`, you turn a repeated search into a fast lookup. This is especially critical for join-like operations where you match a reference value to another document or a secondary section of the same document. Build the key once, and then use `key('id', $value)` everywhere. The intent becomes clear: you are doing a lookup, not a scan. If you only use keys occasionally, it can feel like overkill, but it is often the biggest win.
+
+Modes are another useful tool. If you use the same templates in multiple contexts, you may end up doing extra work or firing templates that you do not need. A dedicated mode lets you create a focused processing pipeline that touches only the nodes relevant to that output section. This can reduce both runtime and mental overhead. It also makes it easier to reason about precedence: within a mode, you can define more specific templates without worrying about side effects on unrelated parts of the transform.
+
+Consider caching computed values in variables. XSLT variables are immutable, so they are safe to reuse without unintended side effects. If you are computing a complex string or a filtered node set repeatedly, store it once per relevant scope. Just be careful not to define a variable at the top of the stylesheet if it depends on the context; keep it as close as possible to where it is used to avoid confusion.
+
+If you are working in XSLT 2.0 or 3.0, you gain access to `xsl:for-each-group` and higher-order functions. These can be faster and clearer than manual grouping with keys. For XSLT 1.0, the Muenchian grouping pattern is still effective, and when combined with keys it remains a strong choice. Either way, focus on minimizing passes over large node sets.
+
+Also consider the output method. Serializing large outputs can be a significant part of the runtime. If you do not need pretty-printed XML, avoid indentation to reduce the amount of whitespace and processing time. Similarly, if you are generating text or JSON, use `method="text"` or structured XSLT 3.0 serialization options rather than building a text string node by node.
+
+I recommend using realistic test data when tuning performance. A transform that runs in 100 milliseconds on a tiny input may take seconds on real data. Use a handful of real documents and measure changes as you apply each improvement. This keeps the optimization process grounded and prevents you from making the code worse without a measurable gain.
+
+Finally, keep a balance between speed and clarity. The fastest stylesheet is useless if it is too hard to maintain. Use a few consistent patterns: keys for lookups, modes for pipelines, variables for repeated values, and limited selection scope. With those in place, the performance usually becomes acceptable without heroics.
+
+If you want a quick way to benchmark different approaches with the same input set, try the online editor at [https://xsltplayground.com](https://xsltplayground.com). It is a convenient place to experiment with keys, modes, and alternative match patterns while keeping your transform readable.

site/content/posts/xslt-testing-and-regression.md

@@ -0,0 +1,25 @@
+---
+title: "Testing XSLT transforms for regression safety"
+description: "How to build a lightweight test harness for reliable XSLT deployments."
+date: 2025-03-05T00:00:00Z
+---
+
+XSLT transformations often live at the heart of an integration flow. A small change can impact downstream systems, and because the output is just data, regressions can go unnoticed until a business process breaks. You do not need a massive testing framework to prevent this. A lightweight, repeatable testing approach with a few representative inputs can catch most issues and make changes far safer to deploy.
+
+Start by curating a compact test corpus. Choose a handful of XML inputs that represent the most important scenarios: a normal case, a case with missing optional elements, a case with unexpected or additional fields, and a case with edge values such as empty strings or special characters. Keep these documents small and focused so you can understand the expected output at a glance. Store them alongside the stylesheet to keep the transformation and tests tightly connected.
+
+Next, define expected outputs. This can be literal expected output files, or it can be key assertions. In XSLT 2.0 and 3.0, you can use `xsl:assert` to enforce invariants such as required elements or output ordering. In XSLT 1.0, you can still build a test harness by comparing the output to known-good files. The important thing is that the tests are deterministic and easy to run.
+
+A practical approach is to create a wrapper script that runs the transform against each input and diffs the output against the expected result. If you are using a CI pipeline, this is easy to automate. If you are running locally, you can use a simple shell script or a makefile target. The key is to reduce friction so you actually run the tests before shipping a change.
+
+Beyond output equality, consider adding structure checks. For example, if your output is XML, use an XML-aware diff or validate the output against a schema. For JSON outputs, parse and validate. For CSV, load into a parser and verify column count. These checks help catch cases where output is syntactically valid but structurally wrong. They also help maintain consistent ordering when you refactor templates.
+
+One effective pattern is to include a test-only mode in your stylesheet. In this mode, you can output debug traces or additional metadata that is useful for validation. You keep the production output clean while making it easier to assert internal behavior during tests. The mode can be controlled with a parameter, so you do not need a separate stylesheet.
+
+If your transform depends on external inputs, mock them. For example, if you read reference data from a lookup file, keep a small version of that file in your test fixtures. This makes the tests independent and fast. The smaller and more deterministic the inputs, the easier it is to interpret test failures.
+
+Finally, document the test scenarios. A short README with a one-line description of each fixture is enough. When new cases come in, add them to the test set and keep the suite small but representative. Over time, this becomes a powerful safety net that speeds up changes rather than slowing them down.
+
+One more tip: keep track of transformation time for each fixture. Even a simple timestamp around the transform can reveal regressions that functional tests do not catch. If a mapping suddenly takes twice as long, that is a signal to review recent changes or input growth. Performance is part of correctness in integration flows, and small slowdowns can turn into outages when volume spikes.
+
+If you want to iterate on tests and outputs quickly, the online editor at [https://xsltplayground.com](https://xsltplayground.com) is a convenient place to run your fixtures, compare outputs, and refine expectations before you bake them into your automated checks.

site/content/posts/xslt-xml-to-json-csv.md

@@ -0,0 +1,33 @@
+---
+title: "Transforming XML to JSON and CSV with XSLT"
+description: "Patterns for producing modern integration formats while staying in XSLT."
+date: 2025-03-04T00:00:00Z
+---
+
+XSLT is usually associated with XML-to-XML transformations, but in integration work you often need JSON or CSV. The good news is that XSLT is perfectly capable of producing non-XML outputs when you design the stylesheet for it. The key is to choose the right output method, control whitespace carefully, and build an intermediate structure if it helps clarify the mapping. This post covers practical patterns for generating JSON and CSV from XML while keeping the stylesheet maintainable.
+
+For JSON, the simplest method is to output text and build the JSON structure manually. This gives you precise control, but it also requires careful escaping and formatting. If you are on XSLT 3.0, use maps and arrays and let the processor serialize to JSON. This reduces string manipulation and makes your transform more robust. If you are on XSLT 1.0 or 2.0, you can still build JSON text safely by using templates that escape quotes, backslashes, and control characters.
+
+A clear pattern is to create a template that takes a string and outputs an escaped JSON string. Then, for each object, output the property names and values with explicit commas. Keep a template to handle comma placement so you do not end up with trailing commas in arrays. This is a good place to use position checks like `position() != last()` to decide when to emit a comma. While it can look verbose, the logic is deterministic and easy to debug.
+
+CSV output is simpler but comes with its own hazards. You need to wrap fields that contain commas, quotes, or line breaks. The common rule is to wrap the field in quotes and double any interior quotes. Again, a dedicated template to escape fields pays off. Define the column order explicitly and avoid depending on the source document order. This keeps the CSV consistent even if the XML input changes slightly. If you need multiple CSV sections, consider running two passes: one to compute the rows and one to serialize them.
+
+An example CSV field template can look like this in XSLT 1.0:
+
+```xml
+<xsl:template name="csv-field">
+  <xsl:param name="value"/>
+  <xsl:variable name="escaped" select="translate($value, '&quot;', '&quot;&quot;')"/>
+  <xsl:text>"</xsl:text>
+  <xsl:value-of select="$escaped"/>
+  <xsl:text>"</xsl:text>
+</xsl:template>
+```
+
+This gives you a reusable building block and keeps the main row template readable. You can also pair it with a `csv-row` template that inserts commas between fields. The result is a clear structure where you can change column order without touching the escaping logic.
+
+When moving between XML and JSON/CSV, consider creating a normalized intermediate structure. For example, if the input XML has a deep hierarchy but your output is a flat list, create a lightweight node set representing rows and columns first. Then serialize that representation into your target format. This approach makes the mapping more explicit and keeps string-heavy output logic confined to a small section of the stylesheet.
+
+Testing is crucial because formatting errors are easy to miss. Validate JSON output with a JSON parser and load CSV into a spreadsheet or a small parser to confirm columns align. This is also where you will notice if a newline or a stray comma slipped in. To keep iteration fast, run your transform with a tool that allows quick input swaps and immediate output inspection.
+
+If you want a quick way to experiment with JSON or CSV output, the online editor at [https://xsltplayground.com](https://xsltplayground.com) is a great option. It lets you run transforms with multiple inputs and see the serialized output instantly, which makes it easy to refine your JSON and CSV strategies.

site/hugo.toml

@@ -16,6 +16,9 @@ lead = "Run and debug XSLT online with multi-parameter inputs, timing hints, and
 client = "ca-pub-1549720748100858"
 inArticleSlot = ""
 
+[params.ethicalads]
+publisher = "xsltplaygroundcom"
+
 [menu]
   [[menu.main]]
   name = "Home"

site/layouts/_default/baseof.html

@@ -8,7 +8,9 @@
   {{ partial "adsense/head.html" . }}
   <link rel="stylesheet" href="{{ "css/main.css" | relURL }}">
 </head>
-<body>
+{{- $ethicalAds := and .Site.Params.ethicalads.publisher (ne hugo.Environment "development") -}}
+<body{{ if $ethicalAds }} class="has-ethicalads"{{ end }}>
+  {{ partial "ethicalads.html" . }}
   <header class="site-header">
     <div class="container header-grid">
       <div>

site/static/css/main.css

@@ -17,6 +17,11 @@ body {
   background: radial-gradient(circle at 20% 20%, #11223f, #0b1021 45%), radial-gradient(circle at 80% 0%, #182743, #0b1021 40%), var(--bg);
   color: var(--text);
   line-height: 1.6;
+  --header-offset: 0px;
+}
+
+body.has-ethicalads {
+  --header-offset: 64px;
 }
 
 a { color: var(--accent); text-decoration: none; }
@@ -27,10 +32,28 @@ a:hover { color: var(--accent-2); }
   margin: 0 auto;
 }
 
+.ad-bar {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  background: rgba(11, 16, 33, 0.95);
+  border-bottom: 1px solid var(--border);
+  min-height: 64px;
+  display: flex;
+  align-items: center;
+}
+
+.ad-bar-inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
 .site-header {
   border-bottom: 1px solid var(--border);
   position: sticky;
-  top: 0;
+  top: var(--header-offset);
   backdrop-filter: blur(8px);
   background: rgba(11, 16, 33, 0.9);
   z-index: 10;