Markdown to Knowledge Graph Pipeline

Personal experiment—not a production client project.

What it does

A document already has a structure: a main topic, sections, and the text inside them. This experiment makes those connections explicit in Neo4j, a database that stores connected information.

It turns Markdown headings into a connected map of topics and sections. You can then follow a connection from a topic to its sections, or from a section back to its topic.

The question behind this work is simple: how can software use the structure already present in documentation? This is a small exploration of that question, not a finished AI assistant.

A small example

Here is a made-up support document, processed by the real parser. It is not client material, and the policy is only an illustration.

# Customer support
Information for the support team.

## Returns policy
Customers can request a return within 30 days.

## Shipping questions
The support team checks delivery updates.

From document to connected map

Customer support
├── Returns policy
└── Shipping questions

Illustration of the expected graph structure—not a live database capture. The importer defines connections from the topic to each section and back again. It does not discover new relationships beyond this document structure.

Running the parser on this example produced one topic and two sections, keeping the text under each heading:

• Topic: Customer support, with the description “Information for the support team.”
• Section: Returns policy, with the text “Customers can request a return within 30 days.”
• Section: Shipping questions, with the text “The support team checks delivery updates.”

You can inspect the input Markdown file and the actual parser output (JSON). These are the files behind this example; the JSON is parser output, not a database export.

What this demonstrates—and its limits

What is demonstrated: the parser separates the main topic, sections, and their text. The Neo4j import code defines how to store them and connect each section to its topic.

What is not demonstrated: a finished assistant, better search accuracy, time saved by a business, or results from a client deployment. This example checks parsing; it does not test a running Neo4j database.

There are also practical limits:

• The parser expects a simple format: one main heading (#) and section headings (##). It is not a general-purpose Markdown parser.
• Entries use IDs derived from their headings. Sections with the same name in different documents can share an entry in Neo4j. That needs addressing before using varied company documents.
• File references are stored as properties on sections, not as separate graph connections.
• Building useful search or an assistant on top would require additional work and evaluation. A graph is not automatically better than simpler search.

Technical details

The pipeline uses Node.js, TypeScript, and Neo4j:

1. Read Markdown files and extract the main topic and sections.
2. Save the parsed content as JSON.
3. Pass that content to the Neo4j importer.

In the database model, a topic is called a Concept and a section is called a Chunk. The import code defines these relationships:

(Concept)-[:HAS]->(Chunk)
(Chunk)-[:PART_OF]->(Concept)

The example was checked against the parser and the Neo4j importer at revision dc2ffa5.

Explore the ds-parse source code on GitHub.

Could this relate to your business?

Exploring how AI could use your company’s documentation?

I can help assess the problem and whether a simple search system, a graph, or another approach makes sense. The starting point is what your team needs—not choosing a database first.

Discuss your use case →

You can also see my consulting services or read about my work on Ketzai, a separate example of my production work.