DEV Community: Curtis Zhang

Why MindMapAny Generates Markdown Before Building a Mind Map

Curtis Zhang — Tue, 15 Sep 2026 01:07:09 +0000

A mind map editor needs structured data: node IDs, parent IDs, sibling order and source references. That does not mean the language model needs to generate the editor's entire data structure.

MindMapAny uses an intermediate format: an indented Markdown outline. Application code turns that outline into nodes. The interesting part is the boundary between those two steps—especially what happens when the model produces something slightly wrong.

This article was drafted with AI assistance using the project's implementation as source material.

Give the model a smaller output contract

Here is an illustrative outline in the format the generation prompt requests:

# Battery Research
- Test conditions
  - Temperature: Cells were tested at room temperature. ^c3
  - Load: Each cell used the same discharge profile. ^c4
- Limitations
  - Sample size: The experiment used twelve cells. ^c8

The text describes the content, indentation expresses the hierarchy, and each leaf ends with a source chunk reference. The application assigns IDs and sibling order after parsing.

That keeps mechanical bookkeeping out of the generation task. The model chooses topics and groups facts. Code decides how those choices become a tree the editor can store.

The resulting representation still uses structured objects. Markdown is an intermediate language, not the persistence format.

The parser makes the recovery decisions

The parser scans the outline and maintains a stack of potential parents. When it reaches a node at the same or a shallower level, it removes deeper entries until it finds the appropriate parent.

This excerpt shows the parent-selection step from the implementation:

while (stack.length > 1 && level <= stack[stack.length - 1].level) {
  stack.pop();
}
const parent = stack[stack.length - 1];

Here, level has already been derived from indentation. The root starts at level -1, which gives top-level topics a parent without requiring a separate special case for each one.

The parser also has explicit policies for imperfect output. It skips unrecognized lines, drops duplicate sibling titles after lowercasing them, enforces a depth budget, and limits the number of parsed non-root nodes. It returns warnings for several of these cases.

Those choices deserve review. Dropping a malformed line may preserve the surrounding outline, but it can also discard information. A parsed tree should not automatically be presented as a complete account of the document.

For applications where missing a point matters, a useful next step is to turn selected warnings into visible incomplete-output states or regeneration triggers. That is an application policy, not something Markdown supplies for free.

One extra space can change the tree

The prompt asks for two spaces per level. The parser nevertheless allows some variation.

Before creating nodes, it collects the indentation widths used by bullet lines. It sorts those widths and groups neighboring values when the difference is at most one space. Tabs count as two spaces.

Consider this illustrative input:

- Test conditions
  - Temperature
   - Load

The two child lines use two and three spaces. This parser assigns them the same level. Without that normalization, an implementation that treats every indentation increase as a new level could make “Load” a child of “Temperature.”

There is a cost: genuinely distinct adjacent indentation widths can be merged. The grouping is also transitive across neighboring widths. If several widths differ by one space, they can collapse into the same level.

That is a tolerance decision tailored to this outline format. It is not a general-purpose Markdown parsing rule. A strict parser might reject the input instead; that would be a reasonable choice for a different product.

A chunk reference identifies a location, not a truth

The generation prompt asks for references such as ^c3. The parser looks that identifier up in an application-supplied chunk index:

const resolved = opts.chunkIndex?.get(ref[1]);
if (resolved) source = resolved;
else if (opts.chunkIndex) {
  warnings.push(`unknown chunk ref ^${ref[1]}`);
}

The application restores the source location from that lookup. It does not ask the model to invent the final page number.

An unknown reference generates a warning when an index is available. The node can still exist without a resolved source. The implementation also does not reject every leaf that lacks a reference, even though the prompt asks for one.

More fundamentally, a valid chunk ID does not prove that the chunk supports the claim. A model can cite an existing passage and summarize it incorrectly. Reference validation and factual verification are separate checks.

This distinction matters when writing interface copy. “Open the cited source” describes a capability. “Verified fact” would require additional evidence.

Markdown does not make streaming automatic

A line-oriented format suggests a convenient streaming approach: accumulate text until a newline arrives, parse completed lines, and hold the unfinished tail in a buffer.

But this parser first examines indentation across the supplied outline. Its final hierarchy can therefore depend on lines that have not arrived yet. The implementation discussed here parses a supplied string; it should not be described as proof of a stable incremental renderer.

A streaming implementation using this design would need an additional decision: enforce fixed indentation, accept provisional hierarchy and reconcile later, or delay final parent assignment until generation finishes.

JSON can also be streamed with suitable tooling. The relevant question is which partial results the application is prepared to interpret and revise.

Structured output is still a reasonable alternative

Schema-constrained generation can provide structured model responses. OpenAI's documentation describes schema adherence and supported recursive structures, so a tree is not inherently a reason to avoid that approach. Structured Outputs overview.

The choice here is about where complexity lives. An outline gives the application control over indentation recovery and node construction. A schema gives the model a more explicit object contract. Both still need application checks for useful grouping, missing content and unsupported claims.

MindMapAny itself uses a JSON object for a separate hierarchy-planning prompt. That task assigns existing node IDs to groups rather than regenerating all the document's content. Different stages can use different output contracts.

Questions this design raises

Does successful parsing mean the map is complete?

No. The parser can skip lines or drop nodes because of limits. Completion needs its own checks, including the generation result and any parsing warnings.

Can this parser accept arbitrary Markdown?

No. It recognizes a deliberately limited outline format. Its treatment of headings, indentation and fenced content belongs to that format.

Is Markdown cheaper or more accurate than JSON?

This article provides no benchmark establishing either claim. Compare formats using representative documents, the same quality criteria and the actual models used by the application.

Choose the boundary you can inspect

The useful part of this Markdown outline pipeline is that its recovery behavior is visible in code. It makes concrete decisions about malformed indentation, duplicate siblings, depth limits and unknown references.

For another AI application, start by writing down those failure decisions. Then choose an intermediate format that makes them manageable. A valid object is only the beginning of a usable result.

Implementation discussed: MindMapAny, an AI mind mapping application. The examples above are illustrative, not benchmark results.

Designing AI Mind Maps You Can Actually Verify

Curtis Zhang — Fri, 11 Sep 2026 12:37:48 +0000

AI can turn a long document into a neat hierarchy in seconds. The harder problem is knowing whether the hierarchy is faithful to the source.

A useful AI mind map should do more than summarize. It should preserve enough provenance for a reader to move from any important node back to the page, slide, chapter, or timestamp that supports it. This article lays out a practical architecture for building that behavior.

The real output is a structure, not a picture

A mind map is often treated as a visual export. For an AI system, however, the graphic should be the last step. The core output is a tree with explicit relationships:

type SourceRef = {
  kind: "page" | "slide" | "chapter" | "timestamp";
  value: string;
};

type MindMapNode = {
  id: string;
  label: string;
  children: MindMapNode[];
  sources: SourceRef[];
};

This model separates three concerns:

extraction: turning a source into ordered text blocks;
reasoning: grouping those blocks into topics and subtopics;
presentation: laying the resulting tree out on a canvas.

Keeping these stages separate makes the system easier to test. It also stops presentation choices from silently changing the meaning of the source.

Attach provenance before calling the model

Source references are most reliable when they enter the pipeline with the text. A PDF extractor should attach a page number to each block. A slide deck parser should retain the slide index. A video transcript should keep the start time of each caption passage.

type SourceBlock = {
  text: string;
  source: SourceRef;
};

Do not ask the model to reconstruct these locations after summarization. Once multiple passages have been compressed into a short statement, the original position may no longer be recoverable.

For long inputs, chunking should respect source boundaries where possible. If a chunk spans pages 12 and 13, keep both references. When the model creates a node from that chunk, copy those references into the node instead of inventing a cleaner-looking citation.

Make unsupported nodes visible

A generated hierarchy may include useful organizing labels such as “Implementation risks” or “Key themes.” Those labels can help readers navigate even when the exact phrase never appeared in the source.

The interface should not pretend that such a label has direct evidence. A simple rule works well:

nodes derived from source passages display their references;
organizational nodes may have no reference;
a reference-free node is visually distinguishable from a sourced claim.

This is more honest than assigning a nearby page number to every node. Provenance is valuable only when its absence is also meaningful.

Preserve references through editing

Users will rename nodes, merge branches, delete details, and ask AI to reorganize the map. Provenance should survive these edits.

For direct text edits, keep the existing references. For a merged node, combine and deduplicate the references of its inputs. For newly generated content, require the transformation to return the IDs of the source nodes it used.

function mergeSources(nodes: MindMapNode[]): SourceRef[] {
  const unique = new Map<string, SourceRef>();

  for (const node of nodes) {
    for (const source of node.sources) {
      unique.set(`${source.kind}:${source.value}`, source);
    }
  }

  return [...unique.values()];
}

If an edit cannot be traced to existing nodes, mark the result as unsourced. That constraint is better than displaying a confident but false citation.

Turn citations into navigation

A source marker should be an action, not decoration.

A PDF page reference can reopen the document at that page.
A slide reference can focus the corresponding slide.
A chapter reference can identify the section in an EPUB.
A video timestamp can open the video at that second.

This changes the review workflow. Readers can skim the map first, then verify only the branches that matter. The map becomes an index into the source rather than a replacement for it.

That is the approach used in MindMapAny: document nodes retain page, slide, or chapter locations, while YouTube-derived nodes can link back to timestamps. The product also keeps the generated tree editable so provenance remains useful after the first pass.

Test the pipeline at its boundaries

End-to-end output quality is subjective, but the provenance pipeline contains deterministic behavior that can be tested.

Useful checks include:

Every extracted block has a valid source reference.
Every cited node points to a reference that existed in its input chunks.
Merge operations preserve the union of their source references.
Deleting a node does not remove references from unrelated branches.
Timestamp links and page links open the intended location.

These tests will not tell you whether a summary is insightful. They will catch a more dangerous failure: presenting a plausible statement with evidence that does not support it.

FAQ

Does every mind-map node need a citation?

No. Organizational labels may be useful without representing a sourced claim. The important rule is to distinguish them clearly from nodes that do carry evidence.

Should the model generate page numbers or timestamps?

No. Extractors should attach location metadata before model processing. The model should select from known references, not invent new ones.

What happens when several passages support one node?

Keep all relevant references and deduplicate exact matches. The interface can show the first reference by default and reveal the rest on demand.

Can provenance prevent hallucinations?

It cannot prevent every unsupported statement. It makes unsupported or incorrectly sourced output easier to detect and review.

Conclusion

The most important design decision in a verifiable AI mind map is to treat provenance as part of the data model. Attach source locations during extraction, carry them through generation and editing, and turn them into navigation in the interface. The result is still a fast visual summary, but it remains connected to the material it represents.

Building an Award Flight Finder: What I Learned Turning 365 Date Checks Into One Search

Curtis Zhang — Tue, 08 Sep 2026 05:53:58 +0000

Reward flights are one of those problems that look simple until you try to build a useful search experience around them.

A traveller usually starts with a straightforward question:

“Which dates can I fly this route using miles?”

But airline websites often make people check one date at a time. Availability changes frequently, different cabins behave differently, and a seat that appears today may be gone tomorrow. The user does not really want another booking form. They want a fast way to understand a large, changing set of dates.

While building MileSeat, I learned that the best interface for this problem is not a conventional list of search results. It is a calendar, supported by filters and alerts.

Start with the real user job

The obvious product brief is “build an award flight search tool.” That description is too broad to guide many design decisions.

The actual job is closer to this:

Check a route across a wide date range.
See which dates have seats in the desired cabin.
Compare nearby dates without repeating the search.
Return later when availability changes.
Complete the redemption on the relevant airline or loyalty-program website.

This framing matters. MileSeat is not an airline or a travel agent, and it does not complete bookings. Its job is to reduce the discovery work before booking.

A year is a better unit than a single date

Most flight forms begin with a departure date. That works well when cash fares are widely available and the user is optimizing price or schedule.

Award travel is different. Availability itself is often the constraint.

If someone wants two Business Class award seats between London and New York, asking for one exact date too early can hide the useful answer: there may be no seats on Friday, but there may be seats on Thursday or Sunday.

That led us toward a 365-day calendar view. A calendar changes the interaction from repeated querying into visual scanning. Users can identify clusters, gaps, and nearby alternatives without submitting dozens of nearly identical searches.

The broader product lesson is simple:

When flexibility is part of the user's strategy, show the whole decision space before asking them to narrow it.

Availability and price are different questions

Another important distinction is the difference between award-seat availability and the final redemption price.

A seat can be available while the number of points, taxes, fees, or booking rules vary by program. Partner-airline access can differ as well. Trying to compress all of that into a single “best deal” number creates false certainty.

A clearer flow is:

Find dates with award seats.
Filter by airline, route, cabin, and number of seats.
Confirm the current points price and fees with the program used for booking.
Complete the redemption on the official site.

Keeping these stages separate makes the product easier to explain and reduces the risk of users treating an availability signal as a guaranteed booking quote.

Filters should reflect traveller decisions

A technically impressive filter is not necessarily a useful filter. The highest-value controls are the ones that map directly to decisions travellers already make:

Origin and destination
One-way or return
Economy, Premium Economy, Business, or First Class
Number of seats
Airline or loyalty-program context
Flexible date range

The number-of-seats filter is especially important. Showing a date with one seat is not useful to a couple looking for two. The calendar should reflect the party's actual requirement rather than presenting any positive inventory as a match.

Alerts complete the workflow

A search only answers “what is available now.” For popular premium cabins, that is often not enough.

Availability can return after cancellations or inventory updates, so the product needs a second mode: monitoring. A traveller specifies the route, cabin, date range, and seat count, then receives an alert when a matching result appears.

This is more than a notification feature. It changes the product from a one-time query tool into an asynchronous workflow:

Search now → no suitable dates → save criteria → monitor changes → notify when a match appears.

For products built around volatile data, the same pattern can be useful in many domains: appointments, event tickets, rentals, inventory, and pricing.

What I would measure

A search product can easily optimize the wrong metric. Page views alone do not tell you whether people found a usable result.

The more meaningful signals are:

Percentage of searches that return at least one matching date
Time from landing to the first calendar result
Filter changes after results appear
Alert creation following a search with no suitable result
Return visits from an alert
Outbound clicks to continue the booking process

These metrics follow the user's progress rather than the site's content volume.

The main takeaway

The biggest lesson from building MileSeat is that search UX should match the shape of the underlying decision.

For award travel, the user is not choosing from a stable list. They are exploring sparse availability across time. A full-year calendar makes that structure visible, while cabin and seat-count filters make it relevant. Alerts handle the fact that the answer can change after the user leaves.

If you are building any product around limited, changing availability, begin by asking whether users really want a better search box—or a better view of the entire opportunity space.

You can see the current implementation at MileSeat.